Environment

Environment

Scope and data

Work from the device's declared environment capability and the measurements actually present. Do not require a camera, microphone, emotion marker, or a particular sensor model. If the capability is absent, skip environmental checks; ordinary room questions and room-feeling reports use the fixed unavailable reply in reference/room-comfort.md. Personal symptoms without a room question retain wellbeing support without sensor-error commentary. Do not enable hardware or edit its declaration.

For a direct room question or room-feeling report (even without a question), a requested current comparison, or a non-urgent wellbeing concern when the capability is declared, read the OS environment status API once (reuse a supplied current status snapshot when available):

curl --fail --silent --show-error --max-time 5 http://127.0.0.1:5000/api/environment/status

This read-only route admits local device callers and checks the environment capability. It returns the OS envelope {"status":1,"data":{...HAL snapshot...},"message":null}; inspect data. A non-2xx response or status:0 means unavailable. Do not bypass a denial through HAL or fetch credentials for the browser's authenticated hardware proxy.

Use the existing snapshot in an automatic event unless it is stale or the user explicitly requests a fresh check. Do not run a polling loop, start a cron job, invent a history endpoint, or promise a timed follow-up: OS owns polling, thresholds, sustained-change detection and cooldowns.

A usable snapshot has enabled: true, state: "ready", stale: false, and at least one fresh numeric measurement in sample. The shared status sample always contains nine nullable metric keys; an object of null values is not usable data. Check age_s and sample.timestamp before describing it as current. Disabled, starting, stopped, error, missing or stale data is unavailable, not zero pollution. Say so briefly on an explicit room-data question; stay silent on an unusable automatic event. For a personal wellbeing concern without a room question, silently skip unavailable environmental data and continue support without sensor-error commentary. Ordinary room questions/reports use the unavailable reply in reference/room-comfort.md. Individual null or absent measurements are unknown: retain the other valid readings. For a multi-component snapshot, sources[metric] identifies its entry in components; check that component's state, age and stale flag, plus metric_timestamps[metric]. The aggregate timestamp may belong to another sensor and does not establish freshness for every field. One failed component does not invalidate another healthy component.

Interpret the available metric, independently of the component model. Unsupported metrics are null, just like currently unavailable readings; use component state and sources for diagnostics, not the null alone. A healthy component without VOC/NOx is normal and does not require waiting for those indices or reporting a fault. Missing CO₂ does not prevent using valid PM, temperature or humidity. CO₂ is distinct from CO and O₂; the supported measurements do not include those gases. Use CO₂ only when its own reading is fresh, never estimate it from VOC/NOx. Do not infer oxygen shortage, impaired cognition, a gas leak, a fire or a medical condition from environmental readings.

VOC Index adapts to recent history (roughly 24 hours, baseline 100); NOx Index uses a different baseline (1). Neither baseline certifies safe air. Do not identify a chemical, smell or pollution source from either index. Describe an increase relative to previous readings. Do not convert indices into ppm or apply concentration guidelines to them. Instantaneous PM readings cannot establish compliance with 24-hour or annual WHO exposure guidelines. Sensor temperature may be affected by the enclosure and nearby electronics; do not present it as body temperature or a guaranteed room-wide measurement.

Event contract

[environment:update] is followed by an OS-generated JSON object containing observed_at (Unix seconds), sample (measurements and timestamp), changes (keyed by metric, each with previous, previous_at, current, current_at, delta and optional source), sustained_s, and per-metric sources / metric_timestamps. Older events may omit the added provenance fields. Use the numeric change facts rather than guessing a trend from one raw sample. Do not assume the event has the full status envelope or all metrics. A delayed event describes its observation time, not necessarily the current room; obtain current status before giving time-sensitive advice. previous is the detector's previous acknowledged baseline and previous_at is its Unix timestamp; current_at is that metric's observation time; observed_at is the newest valid reading in the snapshot and may belong to a different component. For older single-sensor events without current_at, use observed_at. current is the latest sample, not a rolling average. sustained_s describes consecutive qualifying readings, not a health exposure assessment. Missing context does not justify invented thresholds, durations, health classifications or user activity.

A normal update can also contain a comfort map for sustained room conditions. Each metric carries state (high, low or recovered), previous_state, current, current_at, threshold, sustained_s and optional source. An event with changes: {} and nonempty comfort is a valid sustained-condition event, not an initial report or a missing trend. Its per-metric duration is evidence of a persistent condition, not an exposure average. Use its measured state and the room-comfort reference to choose one useful, short observation and at most one action; no numbers, sensor names or spoken tags by default. Do not diagnose symptoms, claim WHO/AQI exceedance, or equate recovered with safe air or the person's recovery. A recovery acknowledgment is useful mainly after a relevant concern/action; otherwise silence may be appropriate. The OS owns persistence, hysteresis and repeat suppression; do not add timers.

An initial report has reason: "initial", changes: {}, and only the metrics that have passed OS freshness and warm-up checks. It is either embedded in the startup greeting under [environment:initial], or sent after the greeting as [environment:update]. It is a first observation, not a significant-change alert: empty changes is expected. Other metrics may still be warming up.

Discomfort and ventilation context

For ordinary room-feeling reports or room questions, first apply reference/room-comfort.md, including when the user says it is hot, cold, stuffy, dry or smoky. Actual breathing difficulty or reported smoke/exposure follows the urgent guidance in wellbeing's discomfort reference; do not wait for sensors or dismiss symptoms based on normal values.

When the user says they feel tired, headachy, dizzy, stuffy or unable to focus, consult skills/wellbeing/reference/discomfort.md for the response. Apply it here without handing the turn back through the wellbeing activity router. Do not inspect sensors before responding to an already apparent urgent symptom or reported exposure. Otherwise, when the capability is declared, you MUST use a supplied current status snapshot or one bounded status read before completing the reply. The check is required; the room-comfort branch controls its short reply. For personal symptoms without a room question, a failed read, all-null sample, stale data or absent metric means omit that environmental explanation, not invent a substitute.

Separate three facts: how the user says they feel, what the sensor measured, and which action might improve comfort. An increase is not itself a high or harmful concentration. Two event endpoints or sustained_s do not establish a long-term concentration average. For context only, HSE workplace guidance flags CO₂ consistently above 1500 ppm in occupied rooms as a reason to improve ventilation. This is not a symptom-causation threshold, universal home safety boundary, or a new OS alarm rule; do not claim consistency from one sample. See HSE: using CO₂ monitors (reviewed 2026-09-14). Treat a lone value as a current observation, not a trend, and use available context before suggesting action. Readings can be affected by placement, nearby breath and calibration; do not label the room safe from a low CO₂ value or diagnose poisoning from a high one.

For rising measured CO₂ with a useful ventilation opportunity, suggest one practical option: an outside-facing opening when outdoor air/weather allow, a fresh-air ventilation setting, or moving to a more comfortable ventilated space. An interior door alone may not bring in outdoor air. Do not invent outdoor air quality from indoor PM or fetch unrelated services to manufacture certainty. If outdoor smoke/pollution or unsafe access makes opening a window unsuitable, choose another option. Recirculation/HEPA is not CO₂ removal. HSE: improving ventilation.