Skip to content

Fix air quality telemetry propagation and sensor labels#156

Open
isdennu wants to merge 1 commit into
meshtastic:mainfrom
isdennu:fix/air-quality-telemetry-sensors
Open

Fix air quality telemetry propagation and sensor labels#156
isdennu wants to merge 1 commit into
meshtastic:mainfrom
isdennu:fix/air-quality-telemetry-sensors

Conversation

@isdennu

@isdennu isdennu commented Mar 9, 2026

Copy link
Copy Markdown

Summary

This fixes two related issues around Meshtastic air quality metrics in Home Assistant:

  1. air_quality_metrics packets were decoded by the integration, but never forwarded through the API/coordinator event pipeline, so the coordinator never stored them under airQualityMetrics.
  2. Once air quality entities were created, several of them appeared in HA with generic or misleading names because the entity descriptions did not define explicit names, and a few metrics also had incorrect labels/units.

Problem

I reproduced this with a node returning valid airQualityMetrics over the HA TCP proxy. Direct requests and proxy requests both returned correct payloads, but Home Assistant did not surface the air quality values correctly.

Observed behavior before this patch:

  • air_quality_metrics responses were received, but HA did not update coordinator state for them.
  • Some air quality entities appeared as the device name instead of metric names.
  • pm10Standard / pm10Environmental were presented like PM10 even though Meshtastic maps those fields to PM1.0.
  • gasResistance was exposed as hPa even though the protobuf describes it as MOhm.
  • particles* counters were exposed as μg/m³, even though they are particle counts, not mass concentration.

Root cause

MeshtasticApiClient._on_telemetry() handled:

  • deviceMetrics
  • localStats
  • environmentMetrics
  • powerMetrics

but not airQualityMetrics.

MeshtasticDataUpdateCoordinator._api_telemetry() also did not recognize an air_quality_metrics event type, so even if the event existed it would have been dropped as unsupported.

Separately, the air quality/environment sensor builders relied on translation_key only. For metrics without a Home Assistant-generated friendly fallback, HA ended up displaying the device name or overly generic names instead of the specific metric.

Changes

  • Add AIR_QUALITY_METRICS to EventMeshtasticApiTelemetryType
  • Forward telemetry["airQualityMetrics"] as EVENT_MESHTASTIC_API_TELEMETRY
  • Map that event in the coordinator to airQualityMetrics
  • Add explicit names for environment and air quality sensor entities
  • Correct metric naming for Meshtastic PM buckets:
    • pm10* -> PM1.0 *
    • pm25* -> PM2.5 *
    • pm100* -> PM10 *
  • Correct gasResistance unit from hPa to MOhm
  • Expose particles* values as particles/dL instead of μg/m³

Testing

Local verification performed:

  • python -m py_compile custom_components/meshtastic/api.py custom_components/meshtastic/coordinator.py custom_components/meshtastic/sensor.py
  • git diff --check -- custom_components/meshtastic/api.py custom_components/meshtastic/coordinator.py custom_components/meshtastic/sensor.py
  • Live telemetry request against the user's HA TCP proxy and target node, confirming payload contents:
Telemetry received:
airQualityMetrics:
  pm10Standard: 9
  pm25Standard: 15
  pm100Standard: 20
  pm10Environmental: 9
  pm25Environmental: 15
  pm100Environmental: 20
  particles03um: 605
  particles05um: 534
  particles10um: 54
  particles25um: 0
  particles50um: 0
  particles100um: 0

I could not run scripts/lint in this environment because ruff is not installed locally, but the patch was kept small and py_compile / git diff --check passed.

Notes

  • No documentation changes are needed for this bug fix.
  • This patch intentionally stays limited to the existing telemetry/sensor plumbing and sensor metadata.

@CLAassistant

CLAassistant commented Mar 9, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants