[ALIGNMENT]: AQI Display and Calculation standards for improved air quality telemetry project

[garthvh]

Area of Alignment

A clear and concise description of what part of the application needs to be aligned.

Sub-tasks

• Create Android alignment issue.
• Create iOS alignment issue.
• Create Web alignment issue.

[oscgonfer]

Let's unpack AQI first. I'll add sources as I go along. AQI is "complex" but it can be very simple for us.

TL;DR
Let's use NowCast* with PM2.5 if there is enough data for making the calculation. 
Otherwise, don't report an AQI, just the raw readings.

Official AQIs

AQI is designed as an easy method to provide outdoor air quality feedback to people wanting to know the AQ in their area. There are many scales (practically each country or area defines their own) and its influenced by health impact reports, also being a political tool (i.e. countries with very poor AQ often tend to define it in a more lax way).

Here you have an explanation of the pollutants used to calculate AQI on different regions of the world. As you'll see, meshtastic devices only measure PM2.5 and PM10 from that list. Other sensor systems could measure NO2, O3, SO2 and so on, but those are very complex sensors, that nobody except advanced users will use.

So first conclusion we need to calculate AQI with either PM2.5 or PM10.

Now, most PM sensors of the kind we will use in mesthastic are nephelometers. These sensors tend to undersestimate PM10 in many cases, mostly because their little fan can't push enough flow through the sensor to make a good estimate of PM10. If you are interested about this, you can read the Smart Citizen Knowledge on PM sensors.

So second conclusion we will use PM2.5 for making AQI estimates.

Next, is the AQI algorithm itself. This algorithm heavily depends on the country we look at. For the US AQI algorithm (that I wouldn't use), the problem with the official calculation is that the calculation requires 24h of data for the calculation. The reason for that is because it's defined by the EPA, and most studies on health impact are conducted on 24h averages. This is explained here, the argument being very clear against it's use in a general sense, as AQ can be very dynamic, specially during wildfires. Similarly, in Europe, the EU AQI index also requires a significant amount of data to be used (see https://aqihub.info/indices/eu), which renders it very difficult to use because we need at least 18h of 24h to calculate the index. Note that if we were to use NO2, SO2 or O3, we could do 1h, but that's not the case.

So third conclusion we need another algorithm that is not the official AQI (even if we use the color scales).

Alternative algorithms

There are two options to handle AQI then.

• InstantCast: We could completely ignore the averaging (what some people call InstantCast), and just map AQ to an index and to a colorscale. I do not recommend this at all, because it's not the same to have a bad AQ just at this moment, than to be exposed to bad AQ for an amount of time that makes it unhealthy. I would be very weary of saying AQ is unhealthy, if it can be misleading.
• NowCast: this is a more relaxed approach to AQI that considers 12h instead of 24h for PM2.5 (from the US EPA). The idea behind it is that more recent readings have more weight than older readings. If we have a decent amount of readings (with defaults, it would be 2 readings per hour, for 12h) this would be my suggested. This is explained here and in a much more affordable way here.

The NowCast is computed from the most recent 12 hours of PM monitoring data, but the NowCast weights the most recent hours of data more heavily than an ordinary 12-hour average when pollutant levels are changing. The NowCast is used in lieu of a 24-hour average PM concentration in the calculation of the AQI until an entire calendar day of hourly concentrations has been monitored.

There could be some tweaks to the algorithm however. The index is calculated with US data, but it may not be applicable everywhere:

The NowCast formula, as it is defined nowadays, is the fruit of the research based on Air Quality levels in America. While for USA it gives an accurate reporting of the current conditions, it might not be the case of Asia where the dynamic of Air Quality is much stronger. For this reason, we do believe that the NowCast formula should be adapted for each continents.

However, I think this is for now too much, and my final conclusion would be: let's use PM2.5 data and the NowCast algorithm as is.

[oscgonfer]

I'll add CO2 on #53

[garthvh]

Current state

Per @oscgonfer's analysis above, the agreed algorithm is: NowCast on PM2.5 (12h EPA-weighted rolling average), falling back to raw readings only (no computed AQI) when there isn't enough history yet. Neither platform implements NowCast today — but they're missing different halves of it.

iOS — doesn't ingest PM2.5/PM10 at all yet

The firmware's AirQualityMetrics telemetry variant (pm25_standard, pm10_standard, pm100_standard, etc. — a separate message from EnvironmentMetrics) is received but immediately discarded: DiscoveryScanEngine.swift:668 only counts/logs it (case .airQualityMetrics: discoveredNode?.sensorPacketCount += 1). TelemetryEntity (Model/TelemetryEntity.swift) has no pm25/pm10 fields at all — only iaq (the Bosch BME680's on-device Indoor Air Quality index, a different metric from outdoor PM-based AQI).

Interestingly, the display half already exists and is unused: Views/Helpers/Weather/AirQualityIndex.swift + the Aqi enum (Enums/TelemetryEnums.swift) already implement the EPA 0-500 AQI scale with the standard color categories (good/moderate/sensitive/unhealthy/very unhealthy/hazardous) and a gauge/dot/text/gradient display — but there are zero real call sites; it only appears in its own SwiftUI previews. It's built for the right output shape, just never fed a real computed value.

Android — ingests and displays raw PM values, but never computes an index

Android fully persists AirQualityMetrics per node (NodeEntity.kt, Node.kt, TelemetryPacketHandlerImpl.kt) and has a dedicated info-card display (feature/node/.../component/AirQualityMetrics.kt, AirQualityInfoCards) showing PM1.0/PM2.5/PM10/CO₂ as raw µg/m³ values. This already satisfies design#54's fallback rule ("not enough data → just raw readings") — permanently, since there's no NowCast calculation and no AQI category/color scale (Android has Co2Severity color-coding for CO₂ specifically, but nothing PM-based).

Path forward

Both platforms need a NowCast (12h PM2.5-weighted) calculator feeding an EPA AQI category display — that part doesn't exist on either platform yet. Beyond that the gap is asymmetric:

• iOS needs the PM2.5/PM10 ingestion + persistence built from scratch (Android already has this), then NowCast, then wire the result into the already-built AirQualityIndex/Aqi display. Given that's a bigger lift, we're moving forward in stages: land ingestion + raw-reading display first (satisfying [ALIGNMENT]: AQI Display and Calculation standards for improved air quality telemetry project #54's own "not enough data" fallback in the interim), then layer NowCast on top rather than blocking the whole thing on a full implementation up front.
• Android already has ingestion + raw display; it needs the NowCast calculator and a PM-based AQI category/color component (mirroring the Co2Severity pattern it already has for CO₂).

Opening an issue on each platform.

(Web not checked in this pass.)

[garthvh]

Implementation issues opened: meshtastic/Meshtastic-Apple#2040 (iOS) · meshtastic/Meshtastic-Android#6092 (Android)