ladill-care/docs/devices.md

Care clinical devices

Ladill Care supports two realistic hardware paths:

Device	Connection	Plan
USB barcode / QR scanner	Browser keyboard wedge — scan into Patients or Lab	All plans
Badge / label printer	Browser print CSS (patient ID label)	All plans
Thermometer, BP monitor, pulse ox, scale, lab analyzer	Care Device Agent (local machine)	Pro / Enterprise
Queue kiosk	Public /kiosk/d/{token} tablet URL — walk-up ticket issue	Pro / Enterprise
Queue display	Registers a waiting-room TV board (/display/{token})	Pro / Enterprise

Browser pages cannot open serial ports or most BLE clinical devices without a local helper. The agent holds the vendor/serial connection and posts readings to Care with a device token.

Queue devices

Devices → Add kiosk / Add display (or Queue board shortcuts):

1. Kiosk — assign service queues, optional name/phone collection. Open the public kiosk URL on a locked tablet.
2. Display — creates a linked waiting display screen for the selected queues. Open the board URL on a TV/tablet.

Waiting displays can also be managed under Displays in the sidebar / Settings.

Device registry

Settings → Devices (hospital admin):

1. Register a device (branch-scoped).
2. For agent types and queue devices, Care shows a plaintext token once (create / regenerate). The DB stores device_token_hash (queue devices also keep metadata.access_token so the public URL can be reopened).
3. Status updates from agent/kiosk heartbeats (active + last_seen_at).

Browser wedge (patients)

1. Open Patients.
2. Focus the scan field (or scan while not typing in another input).
3. Scan a patient ID label (patient_number) → Care opens the patient record.
4. From the patient page, Print ID label for browser print.

Lab Collect sample accepts a scanned sample_barcode before submit.

Agent API

Base URL: {APP_URL}/api/v1/device-agent

Auth (any one):

• Header X-Care-Device-Token: <plaintext token>
• Header Authorization: Bearer <plaintext token>
• Header X-Device-Token: <plaintext token> (compat)

Rate limit: 60 requests / minute / token.

Heartbeat

curl -sS -X POST "$CARE_URL/api/v1/device-agent/heartbeat" \
  -H "X-Care-Device-Token: $DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"agent_version":"0.1.0","hostname":"nurse-station-1"}'

Post vitals

Provide consultation_uuid or visit_uuid (latest consultation on that visit). Readings create a care_vital_signs row with source=device and device_id.

curl -sS -X POST "$CARE_URL/api/v1/device-agent/vitals" \
  -H "X-Care-Device-Token: $DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "consultation_uuid":"'"$CONSULTATION_UUID"'",
    "vitals":{"temperature":36.8,"pulse":72,"spo2":98},
    "raw":{"driver":"stub","unit":"C"}
  }'

Typed consultation vitals remain the source of truth for clinicians; agent posts append provenance-aware rows.

Collect sample barcode

curl -sS -X POST "$CARE_URL/api/v1/device-agent/samples/collect" \
  -H "X-Care-Device-Token: $DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"investigation_uuid":"'"$INVESTIGATION_UUID"'","sample_barcode":"SMP-001"}'

Minimal agent (demo)

See deployment/care-device-agent/.

cd deployment/care-device-agent
cp .env.example .env   # set CARE_URL + DEVICE_TOKEN
npm install            # optional; Node 18+ has fetch built-in
FAKE_READING=1 npm start

With FAKE_READING=1 the agent heartbeats and posts a stub temperature every interval (no serial hardware). Point CONSULTATION_UUID at an open consultation for a live demo.