# 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

```bash
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`.

```bash
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

```bash
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/`.

```bash
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.