Add a sensor
A sensor is a driver in rohi-hal managed by a generic Runner; the board crate supplies the bus, the firmware
spawns one task. Drivers know nothing about networks or serialization. Background: Sensor HAL,
Sensors.
- Model the observation (portable,
rohi-hal). Add the sensor toSensorKindand give it a typed update inMeasurementUpdate(units fromunits.rs:Celsius,Ppm, …). Measurements are grouped by the physical sensor; never merge readings of different sensors. Give the sensor a freshness policy (FreshnessPolicy::default_for) that outlasts its worst healthy cadence: a test insensors/mod.rsenforces it. - Write the driver in
crates/rohi-hal/src/sensors/<name>.rsand implementSensorDriver:init(probe and configure; called again to recover),sample(wait for and read the next observation,Ok(None)= no data yet),poll_interval_ms, optionallyinitial_delay_ms, plusKINDandWARMS_UP. Map the bus error intoDriverError(code, andis_absentfor “does not answer”, which makes the stateNotDetectedinstead ofError). - Test on the host. In the driver module, drive the driver with
MockI2c/ a fake UART from the crate-internaltestutil(crates/rohi-hal/src/testutil.rs), and the runner with a recording delay. Cover detection, a failing bus, recovery, warm-up and the exact decoding of datasheet examples. See Host testing. - Wire the bus (platform). If the sensor needs pins or a new peripheral, add them to the board module in
rohi-hal-esp(see Add a board); drivers never name pins. - Spawn a task in
firmwares/altruist-urban/src/tasks/sensors.rs: build the driver, wrap it inRunner::new(driver, reporter(SensorKind::X), Delay, RunnerConfig::DEFAULT)andrunner.run().await; start it inmain.rswith the other sensor tasks. I²C sensors share one bus throughi2c_handle. - Expose it to the control plane if it should be visible: extend the mapping from the typed snapshot to the
protobuf
Sensorlist inrohi-controland the canonical unit table in Control plane (see Add a control operation for schema rules). - Add a hardware example in
examples/src/bin/if useful, and record the validation in Hardware testing. - Update the docs (policy): the sensor’s page section in Sensors and any new limit in Resource limits.
Rules to respect: the runner owns the driver (one task per sensor); do not call step in a select unless you accept
that a bus transaction may be cut short (cancellation); do not allocate.