Wi-Fi Provisioning & Management

Wi-Fi Provisioning & Management in the OpenAwair project provides the mechanism for connecting Awair Glow C and Awair Element devices to local wireless networks. Since these devices operate as "local-first" hardware following the discontinuation of original cloud services, provisioning is a critical step to enable MQTT telemetry and REST API access for Home Assistant integration.

The system is split between host-side tooling (TypeScript) which handles the credentials and flow logic, and the embedded firmware (C/C++) which manages the physical Wi-Fi connection. During the initial setup, devices are designed to advertise a provisioning service—typically via BLE—to receive network credentials from a loader application.

Sources: CLAUDE.md:7-12, CLAUDE.md:120-125, README.md:1-5

Provisioning Architecture

The provisioning process follows a specific lifecycle managed by the ProvisioningFlow and WifiManager classes. The host tool acts as a client that sends WifiCredentials to a WifiProvisioner interface.

State Management

The device maintains a state machine to track the progress of the Wi-Fi connection.

The diagram shows the transitions between different provisioning states as defined in the host-side manager.
Sources: host/src/firmware/networking/wifi.ts:1-7

Component Definitions

Sources: host/src/loader/wifi/provisioning.ts:1-20, host/src/firmware/networking/wifi.ts:9-28

Provisioning Flow Logic

The provisioning flow ensures that required fields are present before attempting to transmit sensitive data to the device.

Sequence of Operation

1. The user provides SSID and Password.
2. The ProvisioningFlow validates that the SSID is not empty.
3. Credentials are sent via the WifiProvisioner (typically over a BLE transport).
4. The WifiManager updates its state to provisioning.

This sequence illustrates the validation and transmission steps during credential setup.
Sources: host/src/loader/wifi/provisioning.ts:15-24, host/src/firmware/networking/wifi.ts:17-20

Firmware Integration

The embedded firmware implementation uses the Laird Sterling-EWB module, which contains a Cypress CYW4343W Wi-Fi/BLE chipset. The project utilizes the WICED SDK or ModusToolbox to interface with these hardware drivers.

Hardware Indicators

The firmware uses the RGB LED to indicate the current networking status:

• Blinking Blue: Device is waiting for Wi-Fi provisioning.
• Solid Green: Device is connected and operating normally.
• Red: Networking or system error.

Sources: CLAUDE.md:14-16, CLAUDE.md:131-133

Data Models

// From host/src/firmware/networking/wifi.ts:1-6
export type WifiProvisioningState =
  | { status: 'idle' }
  | { status: 'provisioning'; ssid: string }
  | { status: 'connected'; ssid: string; ip: string }
  | { status: 'error'; reason: string };

// From host/src/loader/wifi/provisioning.ts:1-4
export interface WifiCredentials {
  readonly ssid: string;
  readonly password: string;
}

Sources: host/src/firmware/networking/wifi.ts:1-6, host/src/loader/wifi/provisioning.ts:1-4

Summary

Wi-Fi Provisioning & Management is a foundational component of the OpenAwair system, enabling disconnected hardware to regain network utility. By leveraging a structured state machine and a dedicated provisioning flow, the project ensures reliable credential handoff from the loader application to the device firmware, ultimately allowing the devices to communicate sensor data via MQTT and REST.

Sources: CLAUDE.md:27-38, host/src/index.ts:1-20