UART PM2.5 driver: crash, wrong publish tag, empty payload, missing ENV, single-read-per-cycle

[tyeth]

Component

UART / drvUartPm25 (PM2.5 AQI driver)

Summary

drvUartPm25::begin() dereferences _pm25 without ever allocating it, causing a null-pointer dereference the first time a PM2.5 (PMS5003 / PM1006) sensor is added over UART. On ESP32-C5 this manifests as a Guru Meditation Error: Load access fault (MCAUSE=5, A0=0x0, MTVAL=0x8) roughly 3 s after the UART Add (immediately after the driver's boot delay), which then boot-loops the device.

Details

In src/components/uart/drivers/drvUartPm25.h, the member is declared but never constructed:

bool begin() override {
  delay(3 * ONE_SECOND_IN_MS);            // wait for the sensor to boot
  return _pm25->begin_UART(_hw_serial);   // _pm25 is still nullptr here
}
// ...
Adafruit_PM25AQI *_pm25 = nullptr;        // never assigned via new

The sibling I2C driver src/components/i2c/drivers/drvPm25.h does the allocation correctly (_pm25 = new Adafruit_PM25AQI(); at the top of begin()); the UART driver was simply missing that line. The existing destructor already deletes _pm25, so it always expected a heap instance.

Steps to reproduce

1. Flash a build that includes the UART component.
2. Send a UART Add with cfg_device.pm25aqi (e.g. a PMS5003, PID 3686).
3. Device prints [uart] Added PM2.5 AQI device!, then panics ~3 s later.

Reproduced on HIL with a LilyGO T-Dongle C5 (ESP32-C5) and a PMS5003 on the UART0 pads:

[uart] Added PM2.5 AQI device!
Guru Meditation Error: Core  0 panic'ed (Load access fault). Exception was unhandled.
MCAUSE : 0x00000005  MTVAL : 0x00000008   A0 : 0x00000000

Fix

Allocate _pm25 in begin() before use, mirroring the I2C driver.

• Fix commit: 8ef2b4b
• Included in api-v2: use string pin names for i2c bus and uart rx/tx pins #943 (base api-v2-pins-as-strings)
• Carried by add(board): LilyGO T-Dongle C5 (ESP32-C5) + ST7735 SPI display driver #949 (LilyGO T-Dongle C5 board PR, rebased onto api-v2: use string pin names for i2c bus and uart rx/tx pins #943)

[tyeth]

Reflashing with the null-_pm25 fix stopped the crash and the PMS5003 streamed PM*_STD values over UART — but the same HIL run surfaced two more UART bugs on this branch, both now fixed alongside the original.

Bug 2 — UART events published with the wrong signal tag (data never reaches IO)

UARTController::update() in src/components/uart/controller.cpp passed ws_signal_BrokerToDevice_uart_tag (= 37) to PublishD2b(), but PublishD2b() switches on DeviceToBroker payload tags (ws_signal_DeviceToBroker_uart_tag = 33). The tag never matched, so every publish fell through to the default case ("ERROR: Invalid signal payload type, bailing out!") and returned false:

=> Publishing DeviceToBroker signal message...
[uart] ERROR: Unable to publish UartInputEvent to IO!

Every other component controller (analogIn, digitalIO, ds18x20, gps, i2c) correctly passes its DeviceToBroker_* tag; only UART used the BrokerToDevice one. Fix: use ws_signal_DeviceToBroker_uart_tag.

• Fix commit: 8e71f208

Bug 3 — PM2.5 environmental (ENV) subcomponents unimplemented

The PMS5003 component advertises pm10/pm25/pm100 -env subcomponents (and IO / the protomq test script request them), but drvUartPm25 and the drvUartBase::SensorEventHandlers map only implemented the three -std getters. Every ENV read returned false:

[uart] ERROR: Failed to read sensor!   (x3 per cycle — the ENV types)

Fix: add getEventPM10_ENV / getEventPM25_ENV / getEventPM100_ENV (reading PM25_AQI_Data's *_env fields into the matching sensors_event_t.*_env), plus the base virtuals and T_PM10_ENV / T_PM25_ENV / T_PM100_ENV handler-map entries.

• Fix commit: 164a521a

Status

All three fixes are on #943 (api-v2-pins-as-strings) and carried by #949 (rebased). Bug 1 HIL-verified after reflash; bugs 2 & 3 pending a re-flash to confirm.

(Minor, not fixed: each getEvent* calls _pm25->read() independently, so N sensor types = N frame reads per cycle — works with the sensor's active-mode streaming but is wasteful; left as-is to match the existing per-getter pattern.)

[tyeth]

After reflashing with the tag fix (bug 2), publishing succeeded (Published!, broker received on ws-d2b) — but the received payload decoded to an empty uart message, which exposed two more issues. Both now fixed on #943 / #949.

Bug 4 — published UART payload is empty (type mismatch)

PublishD2b() reinterprets the uart payload as a ws_uart_D2B, but UARTController::update() passed the raw ws_uart_Event* returned by GetUartInputEventMsg(). Reinterpreting an Event as a D2B left the D2B oneof unset, so the broker received a zero-length uart submessage — no sensor data reached IO despite Published!:

publish (io-wipper-...): tyeth/ws-d2b/lilygo-t-dongle-c5...
  raw: 8a0200          # field 33 (uart), length 0
  decoded: { "uart": {} }

The I2C model handles this correctly by keeping a ws_i2c_D2B (which_payload = probed_tag) and returning it from GetI2cD2B(). Fix: give the UART model a ws_uart_D2B envelope (which_payload = event_tag, payload.event = <input event>) via a new GetUartD2B(), and publish that.

• Fix commit: ec7f8235

Bug 5 — only the first SI sub-sensor reads per cycle

Each getEventPM* called _pm25->read() independently. The PMS5003 emits ~one frame per second, so reading once per sub-sensor (up to six per cycle) exhausted the buffer and every read after the first failed:

PM10STD: 190.00
PM25STD: 455.00
PM100STD: 540.00
Failed to read PM10ENV data
Failed to read PM25ENV data
Failed to read PM100ENV data

Fix: a refreshData() helper reads at most one fresh frame per 1 s window and serves all std/env sub-sensors from the cached frame, so a single sensor read populates all six SI values per update cycle.

• Fix commit: 437c5c26

Status

All five fixes are on #943 (api-v2-pins-as-strings) and carried by #949 (rebased). Bugs 1–3 verified on HIL; bugs 4 & 5 pending a re-flash to confirm the broker now receives a fully-populated six-value event.