screentinker/Examples/PIP-Air-Quality

PiP Air-Quality Widget

A persistent corner air-quality widget for ScreenTinker screens, driven by the Open-Meteo Air Quality API — no API key, no signup. Shows the current US AQI (color-coded by EPA band) plus the component pollutants (PM2.5 / PM10 / O₃ / NO₂) and refreshes itself in place.

Open-Meteo Air Quality  ──poll──▶  aqi.js  ──POST /api/pip──▶  ScreenTinker  ──ws──▶  player
   (us_aqi, pm2.5, …)              (normalise + color)         (web overlay)        (corner widget)

It pushes a type: web overlay with duration: 0 (stays up until cleared) and re-pushes each poll; the player keeps a single overlay slot (last-show-wins) so the widget just updates. On Ctrl-C it clears the overlay.

How it works

• aqi.js — polls Open-Meteo, normalises the response, maps the US AQI to an EPA category
  • color, and pushes/refreshes the overlay. Pure helpers (aqiCategory, normalise, aqiUrl, overlayUri) are exported for the test.
• aqi-overlay.html + aqi-overlay.js — the overlay page rendered in the player's iframe. All data comes from the URL query string; the JS is external (no inline script) so it passes the signage server's CSP (scriptSrc 'self').

US EPA AQI bands

US AQI	Category	Color
0–50	Good	#1f9d55
51–100	Moderate	#F2C200
101–150	Unhealthy (Sensitive)	#E8730C
151–200	Unhealthy	#CC0000
201–300	Very Unhealthy	#7B0000
301+	Hazardous	#5B0000

Setup

1. Host the overlay page. Copy both aqi-overlay.html and aqi-overlay.js into your signage server's frontend directory so they're served same-origin as the player (required by the CSP). They'll be reachable at https://<your-server>/aqi-overlay.html.

2. Get a full-scope API token (st_…) from the dashboard.

3. Configure. Copy config.example.json → config.json and fill in:

   • api_base — your ScreenTinker server, e.g. https://signage.example.com
   • api_token — the st_… token
   • overlay_base_url — https://<your-server>/aqi-overlay.html
   • device_id — a device or group id
   • lat / lon / location_name — the location to report
   • optional: poll_interval_sec (default 900), position (default top-right), width/height, border_radius

4. Run:

   node aqi.js
   

   Leave it running; it refreshes every poll_interval_sec. Ctrl-C clears the overlay.

Test (offline, no network)

npm test

Checks the EPA band boundaries, the category→color map, and the normaliser against fixture-aqi.json. Prints RESULT: PASS ✅.

Local quick-start (this machine)

The local dev instance serves the player over self-signed HTTPS, so disable TLS verification:

# 1. copy the overlay assets into the local server's frontend dir, e.g.:
cp aqi-overlay.html aqi-overlay.js /home/owner/Downloads/remote_display/frontend/

# 2. config.json for the local "testing" player:
#   api_base         https://localhost:3443/
#   api_token        st_REPLACE_WITH_A_FULL_SCOPE_TOKEN
#   overlay_base_url https://localhost:3443/aqi-overlay.html
#   device_id        DEVICE_OR_GROUP_ID

NODE_TLS_REJECT_UNAUTHORIZED=0 node aqi.js

Notes

• Open-Meteo's us_aqi is the overall US AQI (max of the per-pollutant sub-indices).
• The free Open-Meteo API is rate-limited; a 900s (15 min) poll is plenty for air quality.
• config.json is gitignored (it holds your token).