screentinker/Examples/PIP-CAP-AU-Alert-Monitor/README.md

CAP-AU → ScreenTinker PiP alert monitor (example)

Watches a CAP-AU emergency feed (default: the NSW RFS majorIncidentsCAP feed) and, when a qualifying alert covers a screen's location, pushes a PiP web overlay to that screen — then clears it when the alert expires, is cancelled, or leaves the feed.

It uses the existing ScreenTinker PiP API (POST /api/pip, POST /api/pip/clear). No server changes required.

How it works

CAP-AU feed ──poll──▶ parse (EDXL unwrap) ──▶ gate (AlertLevel + geofence) ──▶ POST /api/pip
                                                                              ◀─ clear on expiry/cancel/gone

Three non-obvious things this example gets right, learned from the real feed:

1. It's EDXL-DE wrapped. The feed is not a flat list of CAP alerts — each <alert> is embedded under EDXLDistribution > contentObject > xmlContent > embeddedXMLContent. cap-parse.js unwraps that.
2. Gate on AlertLevel, not CAP <severity>. RFS leaves <severity>/<urgency> as Unknown for routine incidents. The real urgency lives in a <parameter> named AlertLevel (Planned Burn / Advice / Watch and Act / Emergency Warning). Default threshold shows only Watch and Act and Emergency Warning, so routine hazard-reduction burns never hit a screen.
3. CAP coordinates are lat,lon — the reverse of GeoJSON's lon,lat. The geofence keeps that flip in one place; feeding raw CAP coords into a lon,lat library is the classic "matches on the wrong side of the planet" bug.

Setup

npm install
cp config.example.json config.json   # then edit it

In config.json:

• api_base — your ScreenTinker server URL.
• api_token — an st_ API token with the full scope (PiP is fleet-affecting and full-trust, so the route requires it). Create one in the dashboard's API-token section.
• overlay_base_url — where alert-overlay.html is hosted, reachable by the player (the player fetches the overlay URL directly). Drop the file on the ScreenTinker host or any static host.
• screens — each screen's lat/lon (its physical location, used for the geofence) and the device_id (a device or group id) to push the overlay to.
• alert_levels — the AlertLevel threshold (default ["Watch and Act","Emergency Warning"]).

Run

npm start            # uses ./config.json
# or
node monitor.js /path/to/config.json

On Ctrl-C it clears any overlays it put up, so a screen never keeps a stale alert.

Test the parser (no server needed)

npm test

Runs the EDXL/gate/geofence logic against fixture-feed.xml (two real RFS planned burns plus a synthetic Emergency Warning and a distant Watch-and-Act) and asserts that only the in-area Emergency Warning would fire.

Files

File	Purpose
monitor.js	Poll loop + PiP show/clear lifecycle (dedup by CAP identifier).
cap-parse.js	EDXL unwrap, AlertLevel/field extraction, polygon+circle geofence, gate.
alert-overlay.html	The web overlay the PiP points at; renders from ?level=&headline=&area=….
config.example.json	Copy to config.json and fill in.
fixture-feed.xml / test-parse.js	Offline test of the parser/gate.

Notes / next steps

• Targeting model: one screen → one device_id here. For many screens you'd likely drive screens from your device inventory (each device's stored location) rather than hand-listing them.
• msgType Update: currently an Update re-shows only if the identifier changed; if RFS reuses an identifier on update you may want to force a re-push (clear + show) to refresh the overlay content.
• Other states/agencies: point feed_url at other CAP-AU sources (state SES/fire services). Field names in <parameter> are RFS-specific; other agencies differ, so the AlertLevel mapping may need adjusting per source.
• This is an example/reference, not a life-safety system. Don't make it the only way people are warned.