Skip to content

Rust bootloader, firmware and CLI tools for the AirGradient PRO

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT
Notifications You must be signed in to change notification settings

jonlamb-gh/air-gradient-pro-rs

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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:

  • Replace the Wemos D1 Mini v4 with an stm32f411 "black pill" board
  • Add a ENC28J60 Ethernet board
  • Custom bootloader and firmware, written in Rust

Features

  • 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:
  • 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

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:

  • AIR_GRADIENT_IP_ADDRESS : The device's IP address, default is 192.168.1.38
  • AIR_GRADIENT_MAC_ADDRESS : The device's MAC address, default is 02:00:04:03:07:02
  • AIR_GRADIENT_DEVICE_ID : An arbitrary 16-bit identifier, default is 0xFFFF (DeviceId::DEFAULT)
  • AIR_GRADIENT_BROADCAST_PORT : The port number to send the broadcast protocol data on, default is 32100
  • AIR_GRADIENT_BROADCAST_ADDRESS : The IP address to send the broadcast protocol data to, default is 255.255.255.255
  • AIR_GRADIENT_DEVICE_PORT : The port number the device protocol socket listens on, default is 32101
  • AIR_GRADIENT_LOG : The max log level filter to use, default is INFO

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

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

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

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.