Initial Flashing Guides

The Initial Flashing Guides provide technical procedures for replacing the discontinued cloud-dependent firmware on Awair Glow C and Awair Element devices with the OpenAwair local-first firmware. This transition enables offline operation, data privacy, and integration with local smart home systems like Home Assistant.

The project targets the Laird Sterling-EWB module, which utilizes an STM32F412 ARM Cortex-M4 MCU. Flashing involves interacting with the MCU's bootloader region, managing Device Firmware Update (DFU) sessions, and ensuring data integrity through CRC32 validation.

Sources: CLAUDE.md:1-10, README.md:1-5

Hardware Interface and Preparation

Initial access to the device hardware is required for the first flash, as the original cloud support has been discontinued. The MCU may be read-protected but can be erased to install custom firmware.

Debug Interface

For a reliable initial flash, the Serial Wire Debug (SWD) interface is recommended. This requires opening the device to access specific test pads:

• SWD Pins: SWDIO, SWDCLK, NRST, GND, 3.3V.
• Board Label: "AWAIR-LITE-MAIN V2.0" (Element).
• Programmers: ST-Link or J-Link.

Sources: CLAUDE.md:14-25

Bootloader Logic

The system uses a specific bootloader region (64-128KB) to manage the transition between DFU mode and application execution. The bootloader decides whether to enter DFU mode based on hardware triggers or software flags stored in flash.

The diagram shows the decision logic used by the bootloader during the initial boot sequence.
Sources: CLAUDE.md:52-54, host/src/firmware/bootloader/bootloader.ts:25-28

DFU Protocol and Firmware Upload

Once the device is in DFU mode, firmware is uploaded in chunks. The DfuClient on the host side manages the transmission, while the DfuSession on the device handles reception and assembly.

Transmission Flow

1. Transport: Firmware is streamed in chunks (default 128 bytes, up to 512 bytes) via a DfuTransport (e.g., BLE).
2. Assembly: The DfuSession accepts these chunks and writes them to a buffer, tracking the total bytes received.
3. Validation: A CRC32 checksum is calculated for the entire image once the expected size is reached.

Sources: host/src/firmware/bootloader/dfu.ts:20-56, host/src/loader/ble/dfuClient.ts:18-35

Sequence of Operation

This sequence illustrates the interaction between the host tooling and the device bootloader during a firmware update.
Sources: CLAUDE.md:65-74, host/src/firmware/bootloader/dfu.ts:31-48

Technical Implementation Details

Flash Metadata

The bootloader relies on specific keys stored in the device's persistent storage to manage the firmware state and DFU requests.

• dfuFlagKey: A string flag ('1' for DFU mode, '0' for application mode).
• firmwareCrcKey: Stores the CRC32 string of the valid firmware image.
• firmwareSizeKey: Stores the total byte count of the firmware.

Sources: host/src/firmware/bootloader/bootloader.ts:8-12, host/src/firmware/bootloader/bootloader.ts:40-44

CRC32 Algorithm

The project uses a standard 32-bit Cyclic Redundancy Check with the polynomial 0xedb88320 to ensure no data corruption occurs during the wireless transfer.

// Sources: host/src/shared/crc32.ts:15-21
export const crc32 = (data: Uint8Array): number => {
  let crc = 0xffffffff;
  for (const byte of data) {
    const index = (crc ^ byte) & 0xff;
    crc = (crc >>> 8) ^ CRC_TABLE[index];
  }
  return (crc ^ 0xffffffff) >>> 0;
};

Summary

The initial flashing process transitions Awair devices to the OpenAwair ecosystem by utilizing the STM32F412's SWD interface for the primary bootloader installation, followed by a robust BLE-based DFU protocol for application updates. By maintaining strict CRC32 validation and a dedicated bootloader region, the system ensures that devices can be recovered even in the event of a failed firmware transmission.