Home

Awesome

air-gradient-pro-rs

Firmware and tools for the AirGradient PRO kit with some modifications.

The firmware is written in Rust and uses the RTIC framework.

dashboard startup display.jpg prototype.jpg agp_renode.png

Overview

I've modified an AirGradient PRO kit (PCB Version 3.7) mainly so I can have a wired ethernet connection.

Significant differences from stock:

Features

Configuration

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:

FOTA Updating

Update files (agp_images.cpio) are generated by a custom linker (see its README) as part of the build process (cargo build --release).

air-gradient device update --address 192.168.1.38 path/to/agp_images.cpio

Flashing

Initial 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.

Using a github release artifact

  1. Install probe-rs-cli
cargo install probe-rs-cli
  1. 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

Building from source

  1. Install cargo-embed and flip-link
cargo install cargo-embed flip-link
  1. Build the bootloader and flash the target
cd bootloader/
cargo embed --release
  1. Build the firmware and flash the target
cd firmware/
cargo embed --release

Log 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 <<<

Renode Emulation

The default Cargo runner for the bootloader and firmware is set to renode-run.

  1. Install Renode (currently requires nightly, tested against 1.14.0+20231008gitebcb1b6b)
  2. Install renode-run
cargo install renode-run
  1. Setup TAP device and networking on the host (requires root)
sudo ./renode/setup-network.sh
  1. Configure the environment per the configuration section. AIR_GRADIENT_MAC_ADDRESS is 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
  1. Run the bootloader or the firmware
cd firmware/
cargo run --release
  1. 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 console

Robot Framework Tests

The system-level integration tests are written in Robot Framework and use Renode's integration to drive it.

  1. Install Renode (currently requires nightly, tested against 1.14.0+20231008gitebcb1b6b)
  2. Install Robot Framework
pip install robotframework==6.0.2
  1. Setup TAP device and networking on the host (requires root)
sudo ./renode/setup-network.sh
  1. Run the tests
renode-test agp.robot

System Architecture

system_architecture.png

RTIC Task and System Timings

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.

timing.png

pms_timing.png

Hardware

Pins

PinPeripheralBoard D1 Mini Header PinDescription
PA11USART6 TxTXConsole/logger/panic-handler output
PA12USART6 RxRXConsole input (not used currenlty)
PA9USART1 TxD3senseAir S8 Rx
PA10USART1 RxD4senseAir S8 Tx
PA2USART2 TxD6PMS5003 Rx
PA3USART2 RxD5PMS5003 Tx
PB3I2C2 SDAD1Shared I2C SCL : SH1106, SHT31, SGP41
PB10I2C2 SCLD2Shared I2C SDA : SH1106, SHT31, SGP41
PB13SPI2 SCKNCENC28J60 Eth SCK
PB14SPI2 MISONCENC28J60 Eth MISO
PB15SPI2 MOSINCENC28J60 Eth MOSI
PB12GPIO OutputNCENC28J60 Eth CS
PA8GPIO InputNCENC28J60 Eth INT
PB1GPIO OutputNCENC28J60 Eth RESET
PC13GPIO OutputNCOn-board LED

License

Licensed under either of

at your option.

Contribution

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.