Firmware and tools for the AirGradient PRO kit with some modifications.
The firmware is written in Rust and uses the RTIC framework.
I've modified an AirGradient PRO kit (PCB Version 3.7) mainly so I can have a wired ethernet connection.
Significant differences from stock:
- Replace the Wemos D1 Mini v4 with an stm32f411 "black pill" board
- Add a ENC28J60 Ethernet board
- Custom bootloader and firmware, written in Rust
- Bootloader with firmware update and failover rollback mechanisms
- update manager task handles the update protocol in-application
- see the bootloader README
- TCP/IP stack (smoltcp), comes with these protocols:
- a lightweight broadcast protocol for influx/etc integration
- a device protocol for FOTA updates, device info, and device control
- CLI with command-line tools and InfluxDB relaying, see the air-gradient-cli README
- Configuration for network and device settings
- OLED display
- Emulation support via Renode
The build.rs file handles generating build-time configuration values based on the github repository and host environment variables.
The following environment variables can be set:
AIR_GRADIENT_IP_ADDRESS: The device's IP address, default is192.168.1.38AIR_GRADIENT_MAC_ADDRESS: The device's MAC address, default is02:00:04:03:07:02AIR_GRADIENT_DEVICE_ID: An arbitrary 16-bit identifier, default is0xFFFF(DeviceId::DEFAULT)AIR_GRADIENT_BROADCAST_PORT: The port number to send the broadcast protocol data on, default is32100AIR_GRADIENT_BROADCAST_ADDRESS: The IP address to send the broadcast protocol data to, default is255.255.255.255AIR_GRADIENT_DEVICE_PORT: The port number the device protocol socket listens on, default is32101AIR_GRADIENT_LOG: The max log level filter to use, default isINFO
Update files (agp_images.cpio) are generated by a custom linker (see its README)
as part of the build process (cargo build --release).
- See the device update section of the CLI for more information on using the CLI.
- See the Firmware Update Sequence section of the bootloader for more information on performing FOTA updates.
- See the Design section of the bootloader for more information on how the update protocol and failover mechanism works.
- See the Example Update Log section of the bootloader for example output from the bootloader and firmware throughout the update process.
air-gradient device update --address 192.168.1.38 path/to/agp_images.cpioInitial flashing of the bootloader and firmware onto the board is currently done via SWD and an st-link.
The default memory.x file is setup to use firmware slot 0 in flash, which is also the default slot picked by the bootloader on initial setup.
You can use the Development Artifacts github action to build a custom-configured bootloader and firmware image in CI (click "Run workflow" and set the configuration fields) or grab the latest release with the default configuration from the Releases page.
- Install probe-rs-cli
cargo install probe-rs-cli- Flash the target using the ELF files
probe-rs-cli run --chip STM32F411CEUx --protocol swd path/to/bootloader
probe-rs-cli run --chip STM32F411CEUx --protocol swd path/to/air-gradient-pro- Install cargo-embed and flip-link
cargo install cargo-embed flip-link- Build the bootloader and flash the target
cd bootloader/
cargo embed --release- Build the firmware and flash the target
cd firmware/
cargo embed --releaseLog messages are available on pin PA11 (USART6 Tx), you should see output like the following:
************************************************************
agp-bootloader 0.1.0 (release)
Build date: Mon, 24 Apr 2023 14:28:38 +0000
Compiler: rustc 1.69.0 (84c898d65 2023-04-16)
Commit: 3023a001f2ab011406a3e58dd8e328cb4502737a
Reset reason: Software reset
Boot config slot: SLOT0
Update pending: false
Update valid: false
************************************************************
############################################################
air-gradient-pro-rs 0.2.0 (release)
Build date: Mon, 24 Apr 2023 14:35:08 +0000
Compiler: rustc 1.69.0 (84c898d65 2023-04-16)
Commit: 3023a001f2ab011406a3e58dd8e328cb4502737a
Serial number: 303233313036517042018
Device ID: 0x1 (1)
IP address: 192.168.1.38
MAC address: 02-00-04-03-07-02
Broadcast protocol port: 32100
Broadcast protocol address: 255.255.255.255
Device protocol port: 32101
Reset reason: Software reset
Update pending: false
############################################################
Setup: startup delay 5 seconds
Setup: boot config
Setup: S8 LP
Setup: PMS5003
Setup: I2C2
Setup: SH1106
Setup: SHT31
Setup: SGP41
Setup: ETH
Setup: TCP/IP
Setup: net clock timer
Setup: net poll timer
>>> Initialized <<<
The default Cargo runner for the bootloader and firmware is set to
renode-run.
- Install Renode (currently requires nightly, tested against
1.14.0+20231008gitebcb1b6b) - Install renode-run
cargo install renode-run- Setup TAP device and networking on the host (requires root)
sudo ./renode/setup-network.sh- Configure the environment per the configuration section.
AIR_GRADIENT_MAC_ADDRESSis required to match the renode-run configuration in Cargo.toml
export AIR_GRADIENT_MAC_ADDRESS=02:00:04:03:07:04
export AIR_GRADIENT_IP_ADDRESS=192.0.2.80- Run the bootloader or the firmware
cd firmware/
cargo run --release- Use the air-gradient CLI to interact with the system
Alternatively, there's also a agp.resc script that can be used to emulate the full system with the bootloader and the firmware, which can be used to test the firmware update procedure.
# Assumes the bootloader and firmware ELF files have already been built
renode renode/agp.resc
# Run the 'start' command in the renode consoleThe system-level integration tests are written in Robot Framework and use Renode's integration to drive it.
- Install Renode (currently requires nightly, tested against
1.14.0+20231008gitebcb1b6b) - Install Robot Framework
pip install robotframework==6.0.2- Setup TAP device and networking on the host (requires root)
sudo ./renode/setup-network.sh- Run the tests
renode-test agp.robot
NOTE: some of the measurement periods are inaccurate (like the S8 LP), need to read the docs again. Also, the relative start times are not accurate.
- STM32F411 "black pill"
- ENC28J60 Ethernet board
- AirGradient PRO V3.7 kit
- SH1106 OLED
- Sensirion SHT31 (temperature/humidity sensor)
- Senseair S8 LP (CO2 sensor)
- PMS5003 (particle concentration sensor)
- Sensirion SGP41 (TVOC/NOx sensor)
- AMS1117-3.3 regulator
| Pin | Peripheral | Board D1 Mini Header Pin | Description |
|---|---|---|---|
| PA11 | USART6 Tx | TX | Console/logger/panic-handler output |
| PA12 | USART6 Rx | RX | Console input (not used currenlty) |
| PA9 | USART1 Tx | D3 | senseAir S8 Rx |
| PA10 | USART1 Rx | D4 | senseAir S8 Tx |
| PA2 | USART2 Tx | D6 | PMS5003 Rx |
| PA3 | USART2 Rx | D5 | PMS5003 Tx |
| PB3 | I2C2 SDA | D1 | Shared I2C SCL : SH1106, SHT31, SGP41 |
| PB10 | I2C2 SCL | D2 | Shared I2C SDA : SH1106, SHT31, SGP41 |
| PB13 | SPI2 SCK | NC | ENC28J60 Eth SCK |
| PB14 | SPI2 MISO | NC | ENC28J60 Eth MISO |
| PB15 | SPI2 MOSI | NC | ENC28J60 Eth MOSI |
| PB12 | GPIO Output | NC | ENC28J60 Eth CS |
| PA8 | GPIO Input | NC | ENC28J60 Eth INT |
| PB1 | GPIO Output | NC | ENC28J60 Eth RESET |
| PC13 | GPIO Output | NC | On-board LED |
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.