# Nurse call & bed exit — integration guide

CarePulse does not replace the nurse call system. It receives its events (and bed / chair exit pads, call buttons) and adds a
live board with timers, presence answering, escalation and response-time analytics.

## Call types
`normal` (patient call), `bathroom`, `staff_assist`, `code_blue`, `bed_exit`, `pain`, `other`.

| Type | Alert | Notes |
|---|---|---|
| code_blue | critical | goes to *Who is told about nurse calls* + escalation trees |
| bathroom, bed_exit, staff_assist | warning | |
| normal, pain, other | none (board only) | tick *Treat ordinary patient calls as warnings* to alert |

One open call per bed (or room) and type — repeated presses do not create new calls.

## Ways to connect
1. **API** — the nurse call server (Ascom, Hill-Rom, Rauland, Indian systems with a REST/webhook option) or a middleware posts to
   `POST /api/v1/nurse-calls` (gateway token):
   ```json
   {"location": {"ward_code": "W3", "bed_code": "W3-4"}, "type": "bathroom", "state": "call", "source": "Ascom", "at": "2026-11-18T10:15:02+05:30"}
   ```
   `state`: `call` (raise) · `presence` (nurse at the bedside – answered) · `cancel` (reset at the bed – cleared). Without `type`,
   presence / cancel close every open call at that bed. Room-only systems send `{"location": {"zone": "Room 12"}}` (zone name from the floor map).
   Batch: `{"events": [ ... up to 200 ... ]}` → `{"ok": true, "results": [...]}`.
2. **Relay / dry-contact outputs** (most panels, bed-exit pads, pull cords) → a **Modbus I/O module** (e.g. Waveshare / USR / Advantech
   ADAM-6050) on the network, polled by the CarePulse Edge gateway. In `edge.json` under the Modbus device:
   ```json
   {"register": 0, "type": "uint16", "mask": 1, "param": "nc",  "nurse_call": {"ward_code": "W3", "bed_code": "W3-4", "type": "normal"}},
   {"register": 0, "type": "uint16", "mask": 2, "param": "be",  "nurse_call": {"ward_code": "W3", "bed_code": "W3-4", "type": "bed_exit"}}
   ```
   The edge sends a `call` when the masked bit turns on and a `cancel` when it turns off (edge-triggered; the first poll after
   start only learns the state). Poll every 1 s for nurse call inputs.
3. **BLE call buttons** heard by RTLS gateways — map the button tag to a room; the button raises a staff-help alert (see `RTLS_SETUP.md`).

## Presence answering
When a staff badge enters a room (RTLS) that has an open call — matched by the room's linked bed or the room itself — the call is
marked *answered by presence* with that nurse's name. Switch off in Settings → Operations if badges are not worn consistently.

## Board and analytics
* **Nurse call** page: dark live board (refresh 3 s), timer per call turning red past the target (default 120 s), Attend / clear,
  recent calls with response and who answered, 1 / 7 / 30-day stats, filter by ward.
* **Analytics**: calls, bed exits, median and 90th percentile response, % within target, by ward and per day; scheduled
  e-mail report type *Nurse call*.

## Checks before go-live
* Confirm with the nurse call vendor which events and reset/presence signals are available; many panels only expose "call" and "reset".
* Walk test every bed button, bathroom pull cord and bed-exit pad; verify the right bed lights up on the board.
* The nurse call panel, corridor lights and bedside annunciators remain the primary system.
