# Floor maps & location tracking (RTLS) — set-up guide

CarePulse RTLS is **room-level BLE tracking**: one BLE gateway per room/corridor hears small BLE tags; CarePulse puts each tag in
the room whose gateway hears it best. It covers equipment (asset tags), staff badges (duress + nurse-call presence), infant and
mother tags (infant protection) and, optionally, patient wristbands.

## 1. What to buy (per floor)

| Item | Guidance |
|---|---|
| BLE gateways | 1 per room, ward bay, nursery, store and corridor segment; **1 inside every exit / lift lobby** you want to guard. Must forward scans as JSON over HTTP POST or MQTT with tag MAC + RSSI (Minew G1/MG3, KKM, April Brother, Ingics, Kontakt.io Portal Beam, Aruba/Cisco APs with BLE radio via their IoT/location connector). |
| Asset tags | Long-life BLE beacons (3–5 yr battery, adhesive or strap). Advertise every 1–2 s. |
| Staff badges | BLE card badges **with a button** (for duress). |
| Infant tags | Soft-strap infant BLE tags with **tamper / strap-cut** flag in the advertisement, 1 s interval. Mother tag = wristband. |
| Edge PC | Existing CarePulse Edge gateway (one per site is enough), or gateways post directly to the API. |

Ask the vendor for: scan JSON format, how *button* and *tamper* are reported, and the MAC prefix of your tag batch
(used as `tag_prefixes` so phones and other Bluetooth devices are not uploaded).

## 2. Draw the floor (Floor maps & tracking → + Floor)
1. Upload the floor plan (PNG/JPG/WEBP/SVG, ≤ 8 MB). SVGs with scripts are rejected.
2. **Draw room**: click the corners, double-click to finish. Set the kind: room, ward, ICU, OT, nursery, maternity, store,
   corridor, **exit**, **restricted**. Link a room to its **bed** (nurse calls + presence match on bed) or ward.
3. **Place gateway**: click where it is mounted and enter its ID exactly as the gateway reports it (MAC or name). MACs in any
   form (`AC233F001122`, `ac-23-3f-…`, `AC:23:3F:…`) are normalised.
4. **Save layout**.

## 3. Register tags (Floor maps → Tags)
Add each tag code (MAC) with its kind and link: equipment → device record; staff → user; infant / mother → patient. Pair the
infant tag with the mother's tag. At discharge use **Release at discharge** on the tag page — it closes the tag's alerts.

## 4. Connect gateways
**Through the edge gateway (recommended)** — `edge.json`:
```json
"rtls": { "interval": 2, "http_port": 8088, "topics": ["ble/gw/#"], "tag_prefixes": ["AC:23:3F"] }
```
* HTTP: point each gateway to `http://<edge-ip>:8088/?gw=<gateway-id>` (or include `"gateway"` in the JSON).
* MQTT: gateways publish to `ble/gw/<gateway-id>`; the edge subscribes on its MQTT broker connection.
* Accepted bodies: `[{"mac":..,"rssi":..}, ...]` or `{"gateway":..,"devices"|"beacons"|"obj"|"items"|"tags":[{"mac"|"dmac"|"tag":..,"rssi":..,"battery":..,"button":..,"tamper":..}]}`.
* The edge keeps the strongest RSSI per tag + gateway in each interval, keeps button/tamper flags, drops batches older than 60 s
  after an outage (location is live data) and posts to `/api/v1/rtls/sightings`.

**Direct** — `POST /api/v1/rtls/sightings` with a gateway token (see `DEVICE_ADAPTER_API.md`).

## 5. How positions are decided
* Strongest gateway wins the room; the current room is kept unless another gateway is **≥ 6 dB stronger** (stops tags flickering
  between neighbouring rooms).
* The map dot is an RSSI-weighted mix of the top 3 gateways on the same floor, pulled 60 % to the strongest; the room is the
  drawn polygon containing the dot (else the strongest gateway's room).
* Every room change writes a location-history row (who/what was where, from–to) — used for equipment trails and infection-control tracing.
  History is purged after `RTLS history (days)` (default 90).

## 6. Alerts (Settings → Operations)
| Event | Severity | Notes |
|---|---|---|
| Infant tag in **exit / restricted** zone | critical | + door lockdown webhook |
| Infant tag **tamper** | critical | + door lockdown webhook |
| Infant tag **not heard** for N s (default 120) | critical | closes automatically when heard again |
| Staff / mother / patient **button** | critical | "STAFF NEEDS HELP: name at room" |
| Equipment in **exit** zone | warning | switchable |
| Tag battery below N % (default 20) | info (infant: warning) | once per tag |

All go through the normal alert routing, escalation trees and voice calls. Recipients: *Who is told about infant security / staff help alerts*.

**Door lockdown webhook:** `POST <your URL>` with header `Authorization: Bearer <key>` and body
`{"event":"infant_exit"|"infant_tamper","tag":"AC:23:3F:..","zone_id":12,"alert_id":345}`. Your access-control integrator
maps it to the maternity / NICU door controllers.

## 7. Accuracy, testing and limits
* Room-level only. For bed-level or sub-room accuracy use more gateways per room or UWB (quote separately).
* Walk test before go-live: carry one tag of each kind through every room and exit; check the map and alerts.
* Glass walls and open bays reduce separation — lower gateway TX power, place gateways away from shared walls.
* Infant protection here is monitoring + alerts on BLE tags. It is **not** a certified hardware-interlocked infant protection
  system; where one exists, integrate it instead of replacing it, and keep security procedures (exit checks, ID bands) in place.
* Demo/training: `php tools/rtls_sim.php --client=DEMO` keeps tags heard and walks staff badges between rooms. Never run it on a site with real tags.
