Airy

Airy – Air Quality Monitoring Ecosystem

Airy is a from-scratch air quality monitor built around the Seeed Studio XIAO ESP32-C6. This embedded project covers the full chain end to end: component selection, schematic and PCB design, a custom 3D-printed enclosure, fault-tolerant FreeRTOS-based firmware, a rich BLE protocol, Matter smart-home integration, on-device history storage, and a native SwiftUI iOS companion app.

The device continuously measures PM1.0, PM2.5, PM4.0, PM10, CO2, VOC, NOx, temperature, and humidity using a Sensirion SEN66 sensor. In its default BLE mode, Airy streams live readings to the iOS app, syncs the RTC, exposes device maintenance commands, and buffers approximately 24 hours of offline history in external EEPROM for later download. The app merges live and historical samples into a 24-hour trend and computes the Air Quality Index from the raw measurements based on the EPA (Environmental Protection Agency) guidelines.

For smart-home integration, Airy can be switched into Matter mode and commissioned into Matter-compatible ecosystems such as Apple Home or Home Assistant.

Table of contents

1. System overview
2. Hardware
   • Microcontroller: XIAO ESP32-C6
   • Sensor: Sensirion SEN66
   • Real-time clock: PCF8523
   • History storage: 24AA64 EEPROM
   • User interface: button and LED
   • PCB
   • Enclosure
3. Firmware architecture
   • Boot sequence
   • Task and RTOS model
   • The I2C bus abstraction
   • SEN66 sensor driver
   • Data manager: averaging, buffering, dispatch
   • EEPROM driver and the circular history log
   • RTC driver and the dual-clock strategy
   • Communications manager
   • BLE stack and GATT structure
   • History transfer protocol
   • Matter integration
   • Button gestures and device commands
   • LED status patterns
   • CRC integrity
4. Fault management
   • Design goals
   • Reporting and the fault log
   • Severity classes and recovery policy
   • Escalation of transient failures
   • Restart budget, cooldown, and crash capture
   • Health check and the watchdog
   • Error code reference
5. iOS application
   • App architecture
   • State machine
   • BLE layer
   • Packet decoding and scaling
   • AQI computation
   • Persistence and history merge
   • Settings and commands
6. Tooling and build system
   • run.sh
   • Partition table
   • sdkconfig profiles
   • Serial capture
   • RTOS Tracing (SystemView)
7. Project structure
8. Building and flashing
9. Licenses
10. Resources

System overview

The project began with a clear definition of requirements and objectives, mapped out below. Based on these objectives, the appropriate hardware and software were selected.

At its core, the Airy project consists of two primary components: ESP32-C6 firmware and a custom iOS BLE application. The high-level system architecture is illustrated below:

The device supports two mutually exclusive connectivity modes. The active mode is selected at boot and can be toggled using a button gesture:

• BLE mode (default) – talks to the custom Airy iOS app. This is the preferred feature-rich mode: live-streaming, on-device history download, error-log retrieval, RTC sync and maintenance commands, all over a proprietary GATT profile.
• Matter mode – commissions the device into a standard smart-home fabric (Apple Home / Home Assistant) over Wi-Fi. This trades the proprietary features for interoperability.

The rough RTOS-level architectural overview is defined in rtos-architecture.puml, and displayed in the image below.

Hardware

Microcontroller: XIAO ESP32-C6

The brain is a Seeed Studio XIAO ESP32-C6 module. The ESP32-C6 is a 32-bit RISC-V SoC that, importantly for this project, carries the two radios Airy needs and natively supports the Matter protocol:

• Wi-Fi 6 (2.4 GHz) – required for Matter-over-Wi-Fi.
• Bluetooth 5 LE – used for the custom app protocol and for Matter commissioning.

The XIAO form factor was chosen because it is tiny, easy to solder on the carrier PCB, and exposes enough GPIO for this design while keeping the BOM trivial. On top of that, the module has an on-board ceramic antenna which removes the need to use an external antenna. The signal strength with the ceramic antenna is quite mediocre, but good enough for the in-house use case.

Sensor: Sensirion SEN66

The SEN66 is the heart of the device. Choosing this particular module, despite its high price point, was guided by the fact that it combines PM, NDIR CO2, and metal-oxide gas sensors all in one factory-calibrated I2C package:

Additionally, the sensor package provides:

• Optical PM with a fan. The particulate channel uses a laser-scattering cell with an internal fan and supports an automated fan cleaning cycle. Dust accumulation on the optical path is the typical failure mode of long-running PM sensors, so its firmware exposes a "fan clean" command.
• Sensirion's data protocol. Every 16-bit word on the wire is followed by a CRC-8 byte. The driver validates each frame, which makes bus glitches detectable, preventing silent data corruption.

Real-time clock: PCF8523

Every stored sample needs a timestamp, otherwise a 24-hour history chart is meaningless after a power cycle. An NXP PCF8523 I2C RTC breakout (Adafruit PCF8523) fills this role. A CR1220 coin cell on the breakout board keeps the clock running when the device loses main power, so timestamps remain accurate across reboots.

History storage: 24AA64 EEPROM

When the device is running unconnected, its readings need persistent storage. A Microchip 24AA64 serial EEPROM (64 Kbit = 8 KiB) provides that buffer.

The chip is organized as 256 pages of 32 bytes each, which fits one packed sensor sample per page (sen66_sample_s is 24 bytes, leaving 8 bytes unused). It is a simple, low-cost, low-power serial memory that needs no wear-leveling driver (the circular-log strategy in the firmware handles endurance at a higher level).

User interface: button and LED

The device has a deliberately minimal physical UI: one tactile pushbutton and one red indicator LED.

• Button – active-low using the ESP32's internal pull-up. The pin triggers an interrupt on the falling (press) edge, which is used for multi-click gesture detection (handled entirely in firmware – see Button gestures).
• LED – communicates all device states (mode, operation progress, errors) through distinct blink patterns (see LED status patterns).

PCB

The "carrier" board was designed in KiCad. It is intentionally simple — the XIAO module carries the MCU and radios, so the carrier board only has to route the shared I2C bus, the pull-ups, the button, the indicator LED, and the sensor/RTC/EEPROM connections.

KiCad project files, including schematic and layout, are under pcb/. PCB manufacturing service was ordered from JLCPCB; the received board is shown below:

Enclosure

The enclosure was designed in Autodesk Fusion 360 and 3D-printed using a Creality Ender-3 S1 printer. I imported the .step files of the PCB (generated from KiCad) and the SEN66 sensor (from the Senserion website) to aid the design. See the snapshot below.

The final 3D model consists of three parts: base of the enclosure, the lid, and the knob. The box is 76.7 x 73.0 mm in size, with a height of approx 33 mm. The hole for the knob has tight tolerance, in combination with barely protruding from the case and the way it grabs the stem / actuator of the button, it produces an accurate and satisfying click every time.

STEP file of the enclosure is placed under enclosure/.

Firmware architecture

The firmware is an ESP-IDF application built on FreeRTOS, structured into clean layers: low-level drivers (i2c, sen66, eeprom, rtc, button, led), managers that own policy (data_mngr, comm_mngr, history, fault, health_check), and communication interfaces (ble_*, matter_interface). Every module exposes a small *_init() plus a focused API, and inter-module coupling goes through these headers rather than shared globals.

Boot sequence

app_main() (src/app_main.c) initializes subsystems in strict dependency order, because later modules assume earlier ones exist:

fault_init            -> fault log + restart bookkeeping (RAM only, no NVS yet)
led_init              -> indicator available for the rest of boot
nvs_flash_init        -> init NVS (auto-erase + retry on error)
fault_restore_log     -> pull persisted fault records back into RAM
i2c_master_init       -> shared bus + mutex
rtc_init              -> probe PCF8523, else fall back to software clock
eeprom_init           -> add 24AA64, recover write pointer from NVS
sen66_init            -> add SEN66, start measurement and spawn task
data_mngr_init        -> queue + data-processing task
comm_mngr_init        -> configure antenna, init BLE/Matter layer, bring up radio
button_init           -> GPIO ISR + click timer (non-fatal if it fails)
health_check_init     -> watchdog + periodic monitor

In debug builds a 5-sec delay is inserted right after NVS to give time to attach a serial monitor.

Task and RTOS model

Stack sizes and priorities live in one place, src/tasks.h. Note that when running in RTOS debug mode (see sdkconfig profiles), the system stacks (ISR, Idle, Timer) are automatically increased to accommodate the tracing overhead.

Only the LED, sensor, data, comm, and health tasks are permanent. The restart, factory-reset, and history-sync tasks are created and destroyed at runtime, which keeps RAM usage low. History sync gets the largest stack and the highest priority because it is a data-transfer-heavy, latency-sensitive BLE operation that must not be starved by the slower sensor / data manager loop.

Communication between tasks is explicit:

• sample queue (depth=3) from the sensor task to the data manager,
• event group in the comm manager for mode-switch signaling,
• binary semaphore in the BLE layer for indication flow control,
• I2C mutex guarding the shared bus,
• command queue feeding the LED task.

The I2C bus abstraction

src/i2c.c wraps ESP-IDF's new i2c_master driver and adds a bus-level mutex needed for this design. The ESP-IDF driver is thread-safe per call, but a sequence like "write a register address, wait, then read N bytes" must be atomic against other tasks. i2c_bus_lock() / i2c_bus_unlock() bracket every such sequence. The module also offers convenience helpers (i2c_master_write16, i2c_master_write16_then_read) and an i2c_probe_device() used to detect whether the device is actually present.

SEN66 sensor driver

src/sen66.c is the largest driver and encapsulates all sensor-specific logic:

• Command protocol. SEN66 commands are 16-bit codes (e.g., 0x0021 start measurement, 0x0300 read values, 0x5607 fan cleaning). The driver writes a command, waits the datasheet's execution time, then reads the response.
• Frame decoding. Raw measurement bytes arrive as 3-byte frames (MSB, LSB, CRC-8). sen66_process_frame() validates the CRC and byte-swaps big-endian wire order into the little-endian sen66_sample_s.
• The sample struct. Each reading is packed into a 24-byte sen66_sample_s: a 4-byte UNIX timestamp (from the RTC), nine 16-bit metric fields, and a trailing CRC-16 computed over the whole record.
• The read loop. Periodically, the task checks the sensor's data-ready flag, reads and validates the frame, range-checks the values, timestamps it, and pushes it onto the data queue.
• Resilience. Read failures, out-of-range values, and "not ready" conditions each have their own consecutive-failure counter and only escalate to a real fault after a threshold (see Escalation).

Maintenance operations – device reset, fan cleaning, reading the device status register – are exposed as public functions used by the command handler and the health monitor.

Data manager: averaging, buffering, dispatch

src/data_mngr.c is the traffic controller. Its task pulls samples off the queue and does one of two things depending on whether a live link is up:

• Live link ready: forward the sample to comm_mngr (flushing any partially accumulated average first so ordering is preserved).
• No live link: fold the sample into a running average (average_with_pending_sample()) and, once 16 samples have accumulated, commit the averaged record to the EEPROM circular log.

The running average is computed incrementally to avoid storing 16 full samples, and a fresh CRC-16 is computed for the averaged record before it is written. If the EEPROM is unavailable or a history transfer is in progress, the record is dropped and the failure is escalated. Queue statistics (received / dropped / depth) are tracked by the health monitor.

EEPROM driver and the circular history log

src/eeprom.c implements a circular log of averaged samples for the 24AA64 EEPROM IC:

• Each stored record is one sen66_sample_s (24 bytes, fitting in a single 32-byte page), written by eeprom_write_page() with the page-aligned address prepended to the I2C write.
• The write pointer (s_eeprom_addr_ptr) advances by one page per write and wraps at the end of the chip, so the newest ~256 records always overwrite the oldest (mimics a ring buffer).
• The write pointer and page count are mirrored to NVS (MCU's internal flash), not to the EEPROM itself. NVS has wear-leveling, so persisting the bookkeeping there avoids writing to a single EEPROM cell. The sync is throttled to every EEPROM_NVS_SYNC_EVERY_N_PAGES (4) writes.
• On boot, nvs_recover_eeprom_state() restores the saved address pointer and validates it (must be page-aligned and within the chip boundary), falling back to zero if the stored value is corrupt.
• eeprom_read_page() is used exclusively by the history transfer task and enforces the same page-alignment and range constraints.

The sampling and averaging constants are designed together: the sensor task runs at 21.6 s, and the data manager averages 16 samples before committing. That gives 16 x 21.6 s ~ 5.76 min per stored entry, which is 250 entries per day – fitting within 8KB EEPROM for one full day of buffered history.

RTC driver and the dual-clock strategy

src/rtc.c initializes the PCF8523 hardware and provides the time abstraction for the rest of the firmware. Some design details are worth mentioning:

• Configured battery switchover. The backup coincell takes over when VDD is removed.
• BCD conversion. The PCF8523 stores time fields as BCD. bcd_to_bin() and bin_to_bcd() convert to/from native integers, and the full register set is converted to a UNIX timestamp using standard mktime / gmtime_r with the process timezone pinned to UTC.
• Range validation. After BCD-to-binary conversion, every register is checked for plausibility (month 1–12, day 1–31, hours 0–23, etc.) so a corrupt transfer can't produce an incorrect timestamp.

The architectural highlight is that the external RTC is optional. rtc_init() first probes for the PCF8523. If the chip is not present (or later becomes unreadable), the firmware falls back to a boot-relative software clock:

software time = RTC_BOOT_EPOCH_UNIX + seconds_since_boot + user_adjustment

RTC_BOOT_EPOCH_UNIX is a fixed epoch (2026-07-01). When the phone syncs the real time over BLE, rtc_set_unix_time() both writes the hardware RTC (if present) and updates the software offset, so timestamps stay consistent even if a later hardware read fails. rtc_is_external_valid() lets the health monitor report which clock source is actually in use.

Communications manager

src/comm_mngr.c presents a single, transport-agnostic API to the rest of the firmware. It handles switching between BLE and Matter protocols and abstracts the wireless communication logic so that the rest of the system does not care which radio is active.

• Mode is persisted in NVS and validated on read to survive corruption. Defaults to BLE.
• Only one stack is initialized per boot – BLE or Matter. That keeps RAM usage manageable given how heavy the Matter stack is, on top of being more reliable (in terms of connection stability). Note: during Matter device commissioning, the esp-matter SDK temporarily init its own BLE stack and clears it afterward.
• Switching modes is a deliberate, durable operation: a button gesture sets an event-group bit, the comm task writes the new mode to NVS, plays the mode-switch LED pattern, and reboots so the other stack comes up cleanly from a known state.

BLE stack and GATT structure

BLE is implemented on NimBLE and split across several files for clarity: setup (ble_setup.c), advertising (ble_adv.c), GAP event handling (ble_event_handler.c), the GATT server (ble_gatt_server.c), and a transport-facing interface (ble_interface.c).

All services use a custom 128-bit base UUID with a 16-bit selector spliced in (denoted by XXXX):

93e2XXXX-bce5-443f-a0b1-3462083b0323

All the available services and characteristics, along with their properties, are documented in ble-gatt.puml, shown below.

Design choices worth noting:

• Indications for data. Live and history data use indications so every packet is acknowledged. A binary semaphore (ble_wait_for_indication_done) enables one-in-flight flow control.
• Security. The device advertises as an Air Quality Sensor and requires bonding with LE Secure Connections (straightforward pairing). The event handler self-heals stale bonds: if the peer requests repeat-pairing (genuine bond mismatch, e.g., after NVS wipe), it deletes the broken peer record and re-initiates pairing. Transient encryption failures are logged but preserved so the bond survives intermittent connection drops.
• Reconnection. Advertising restarts automatically on a disconnect or failed connection attempt, so the device is always discoverable again without intervention.

History transfer protocol

History download (src/history.c) is a small state machine (IDLE -> REQUESTED -> IN_PROGRESS -> IDLE/ERROR) driven by the phone:

1. The phone subscribes to History Data and writes the History Request characteristic to move the state to requested, which spawns the history task.
2. The task refuses to start unless the link is subscribed and the negotiated MTU is at least 244 bytes (otherwise a 10-sample batch wouldn't fit in one BLE packet).
3. It walks the EEPROM backwards from the newest record, reading pages with retry, validating each record's CRC-16 and silently dropping corrupt ones.
4. Valid records are packed into batches of 10 and sent as indications, each awaited before the next.
5. When all pages are sent, a 4-byte EOF sentinel FF EF 00 00 is transmitted so the app knows the stream is complete. The EEPROM page counter is then reset on clean completion.

The full handshake is diagrammed in ble-history.puml.

Matter integration

src/matter_interface.cpp is the only C++ in the firmware and wraps esp-matter. It builds a node with 3 endpoints shown on the graph below.

Raw SEN66 values are mapped to Matter semantics: concentration clusters get numeric values plus level indications (Low/Medium/High/Critical), and the overall Air Quality attribute is derived as the worst category across all pollutants. The module manages the commissioning window, attribute updates, tracks Wi-Fi/commission status for the health monitor, and supports a Matter fabric factory reset.

The choice to use three endpoints instead of one was due to Matter interoperability between platforms – Apple Home was not displaying all the clusters correctly if these were grouped under a single Air Quality Sensor endpoint. The code still contains an option for a single endpoint, but it is commented out. The current implementation provides a consistent display for both Apple Home and Home Assistant ecosystems.

For commissioning, the default developer certificate was used. The QR code for this certificate is shown below.

Here are screenshots of the Airy device commissioned in Home Assistant, where all metrics are grouped under one device:

Apple Home app displays metrics per endpoint on the main screen with concentration clusters located under Air Quality Sensor. Here is a video demo of the Airy device commissioned in Apple Home ecosystem:

https://github.com/user-attachments/assets/b454da02-5396-45ba-bc8d-8c492ae9b64d

Button gestures and device commands

A single button drives several actions through click counting (src/button.c). The ISR debounces and increments an atomic counter; 2 sec after the last press a timer callback interprets the total:

The same actions (plus more) are reachable over BLE via the Device Command characteristic, dispatched by src/device_cmd.c:

Destructive/long operations (factory reset, restart) run in dedicated one-shot tasks so the BLE callback returns promptly and the operation gets a clean stack.

LED status patterns

src/led.c turns the single LED into a status channel. Each action maps to a distinct on/off sequence. A queue lets a newer pattern preempt one that is mid-playback, and only the halt pattern loops forever. This gives the device meaningful feedback if no debug interface is connected.

CRC integrity

Two CRC algorithms are used (src/crc.c), each fit for purpose:

• Sensirion CRC-8: validates every 16-bit word coming off the SEN66's I2C bus.
• CRC-16/IBM-3740: protects the whole sen66_sample_s record end-to-end, so corruption in the EEPROM or over the air is caught at both the firmware (history read) and app (packet decode) sides.

Fault management

Implemented in src/fault.c and complemented by the health monitor.

Design goals

An air quality monitor is expected to sit in a corner for weeks. The fault system was built around three goals:

1. Survive transient hiccups (an occasional I2C NAK, a momentarily unresponsive sensor) without rebooting.
2. Recover automatically from actual faults.
3. Remember errors across reboots, so the app can retrieve the failure later.

Reporting and the fault log

Every fault is reported through one call:

fault_report(sys_fault_e subsystem, error_e error, esp_err_t esp_err);

Reports are timestamped (via the RTC) and stored in a 20-entry ring buffer in RAM, guarded by a mutex. Faults are categorized by subsystem (e.g., SEN66, EEPROM, COMM, etc.) and by a specific error code. The ring buffer is persisted to NVS just before any restart and restored on the next boot, so the log is continuous across power cycles. The most recent five records are exposed over the BLE Error Log characteristic for the app to display.

Severity classes and recovery policy

The key idea is that severity is a static property of the error code, decided in one switch in fault_report(). Such an approach has some tradeoffs compared to inspecting live subsystem state at report time, but it is much simpler to implement.

Errors fall into three classes:

• Log-only: transient error like a single failed BLE indication – recorded, no action.
• Restart with degraded fallback: the subsystem is important but the device can still run (e.g., EEPROM I2C init or a persistent storage failure) – triggers a bounded restart. If restarts are exhausted, the device keeps running in a degraded state rather than halting.
• Restart with halt-on-exhaustion: no viable operation path (e.g., I2C bus init failed or an RTOS task couldn't be created) – triggers a bounded restart. If restarts are exhausted, the device enters a safe infinite loop with a distinctive LED pattern.

Escalation of transient failures

Single glitches must not cause reboots. The FAULT_ESCALATE macro implements consecutive-failure counting: each caller keeps a small counter, increments it on failure, and only reports failure once the count crosses a threshold, then resets it. A single success resets the counter to zero. This is used across drivers (e.g., SEN66 reads, RTC reads/writes, BLE indications, etc.), so, for example, the sensor has to fail three reads in a row before it is treated as faulted.

Restart budget, cooldown, and crash capture

The restart mechanism uses RTC_NOINIT_ATTR variables, which survive esp_restart() (they live in RTC RAM that is not zeroed on soft reset):

• A restart counter allows at most 3 automatic restarts.
• A 60 sec stability timer – if the device runs cleanly for a minute, the counter is cleared, so unrelated faults far apart in time don't accumulate.
• On exhausting the budget, the device enters a 5-minute cooldown (during which restarts are suppressed) or, for critical faults, the halt loop.
• A crash-info block (also in RTC RAM) can capture the program counter, return address, exception cause, and timestamp of a panic, so the app can report exactly why the firmware crashed on the next boot.

Health check and the watchdog

src/health_check.c is the periodic conscience of the system. Its task subscribes to the Task Watchdog and feeds it every 3 sec, and every 60 sec it runs a full sweep:

• last reset reason (and any captured crash context),
• heap free / minimum-free, plus a full heap integrity check,
• per-task stack high-water marks (warns when a task is close to overflow),
• BLE / Matter status,
• peripheral status (EEPROM pages, RTC validity, SEN66 device-status register, and out-of-range count),
• data-queue statistics (received / dropped / depth),
• optional per-task CPU runtime stats,
• and a forced EEPROM → NVS state flush.

The health monitor also participates in fault reporting (e.g., heap corruption or low memory).

Error code reference

Error codes are grouped by subsystem, mirrored exactly in the iOS FirmwareError model so the app can decode the Error Log characteristic:

iOS application

The companion app (ios-app/) is a native SwiftUI application (Swift 6, iOS 17+) that receives raw BLE stream and presents a dashboard with an Air Quality Index, historical charts, and device maintenance. Take a look at the demo below:

https://github.com/user-attachments/assets/417c0d9c-ef65-4417-9c84-ebc311fbdae2

App architecture

The app follows a service-oriented architecture. A handful of observable singletons own state and views react to them:

• AppStateManager – the high-level app state machine.
• BLEManager – CoreBluetooth orchestration and the owner of three service handlers.
• BLELiveDataServiceHandler, BLEHistoryServiceHandler, BLESettingsHandler – one handler per GATT service, so each concern (live stream, history download, settings/commands) is isolated.
• DataRepository – converts raw packets into scaled, AQI-scored storage entries.
• StorageManager – on-device persistent storage of metrics' history data.

State machine

AppState drives which screen RootContentView shows. The rough overview of the app's state flow can be found in ios-app-state-flow.puml and is rendered below.

The exact states are:

• waitingForBluetooth that covers the Bluetooth being off;
• autoConnect that silently reconnects to the last device (stored UUID) with a 9 sec timeout;
• autoConnectFailed that prompts user to retry or forget the device (erase stored UUID);
• readyToConnect that waits for user to start device discovery and select the found airy device;
• syncingHistory that initiates History transfer protocol and shows the download progress;
• streamingLive that listens to the live samples and displays the dashboard with metrics;
• error state is currently unused.

BLE layer

BLEManager is a CBCentralManager/CBPeripheralDelegate. It scans for peripherals whose name contains airy, connects, discovers services, and lazily instantiates the three handlers once their characteristics are found. It uses the exact same UUIDs as the firmware (base 93e2XXXX-bce5-443f-a0b1-3462083b0323). The last-connected peripheral's UUID is remembered for auto-reconnect, and cleared on factory reset / forget. Incoming values are routed by characteristic UUID to the right handler.

The history handler kicks off a transfer by writing 0x01 to the History Request characteristic, collects indication batches, and recognises the FF EF 00 00 EOF sentinel to finish (after which it transitions to live streaming). Pairing edge cases (peerRemovedPairingInformation, encryptionTimedOut) route back to a clean connect flow rather than an infinite retry.

Packet decoding and scaling

AirQualityPacket mirrors the firmware's sen66_sample_s byte-for-byte and is decoded straight from the received Data via MemoryLayout. DataRepository then applies the same scaling factors as the SEN66 table to produce actual values.

AQI computation

The firmware deliberately ships raw metrics; the app computes the Air Quality Index using the 2024 US EPA breakpoints. For each of PM2.5, PM10, VOC, and NOx it performs the standard EPA piecewise linear interpolation:

AQI = (AQI_high − AQI_low) / (C_high − C_low) x (C − C_low) + AQI_low

with EPA-mandated rounding (PM2.5 to one decimal, PM10 to an integer). The overall index is the maximum of the four sub-indices (exactly how government agencies report a single AQI number). Each metric additionally has its own color indicators (Good → Hazardous) used for the gauges and charts.

Persistence and history merge

StorageManager persists the trend as a JSON file (aq_history.json), loaded into memory at launch and written atomically on a background task. Both the live handler and the history handler funnel packets through the same DataRepository, and timestamp acts as a unique storage id, discarding the duplicate samples. A 24-hour retention window trims older entries, matching the device's ~1-day EEPROM buffer.

Settings and commands

The Settings screen issues the same maintenance commands the firmware understands (described in Device commands), each as a single-byte write to the Device Command characteristic:

• Time sync is handled automatically once the settings handler comes up: it writes the phone's current UTC UNIX time as 4 little-endian bytes to the Time Sync characteristic, giving the device a correct clock reference.
• The Device Info and Error Log characteristics are read upon the Settings menu entry to show the firmware metadata and recent faults.

Tooling and build system

run.sh

run.sh is the developer entry point. It wraps idf.py but adds the things this project needs on every invocation:

• Environment sourcing: sources both the ESP-IDF and ESP-Matter export.sh scripts.
• Build profiles: --release and --rtos-debug flags swap the sdkconfig overlay between the debug, release, and heavy-RTOS-debug profiles.
• Commands: build, flash, monitor, openocd, clean (fullclean + remove sdkconfig), erase (erase flash), and check (static analysis).

sh run.sh build               # debug build + size report
sh run.sh build --release     # optimized, log-stripped build
sh run.sh build --rtos-debug  # heavy RTOS debug build
sh run.sh flash               # build + flash (debug)
sh run.sh monitor             # serial monitor
sh run.sh openocd             # start OpenOCD for debugging/tracing
sh run.sh check               # cppcheck + HTML report

Partition table

The custom partitions.csv is sized for a 4 MB flash. The 24 KB NVS partition size is left unchanged, holding the wireless-mode preference, the persisted fault log, the EEPROM bookkeeping, BLE bonding keys, and Matter fabric data. The app is expanded to 2 MB, leaving headroom for the Matter stack.

sdkconfig profiles

• sdkconfig.defaults – always applied: target esp32c6, 4 MB flash, the custom partition table, NimBLE enabled with NVS-persisted bonds and a preferred MTU of 256, and the mbedTLS/LWIP/mDNS options Matter needs.
• sdkconfig.debug – -Og, verbose logging.
• sdkconfig.debug_rtos – SystemView tracing enabled, increased system stacks, and FreeRTOS runtime stats.
• sdkconfig.release – -Os, all logs and assertions stripped, newlib-nano, trimmed NimBLE roles and Matter clusters (all unused clusters are disabled).

Serial capture

tools/capture_log.sh starts a screen session against the USB serial port and streams everything to build/screen_output.log. Note: this only works on macOS.

RTOS Tracing (SystemView)

For deep RTOS analysis, Airy supports SEGGER SystemView via ESP-IDF's app-trace feature.

1. Build and flash with the --rtos-debug flag.
2. Start OpenOCD in one terminal: sh run.sh openocd.
3. In another terminal, trigger the trace capture:

   echo "esp sysview start file://airy.svdat" | nc localhost 4444

4. Stop capture after enough data is collected:

   echo "esp sysview stop" | nc localhost 4444

5. Import the generated airy.svdat into the SystemView application.

Here is an example RTOS trace analysis:

From the Total Runtime view, the device spends most of its time in the Idle task. All application tasks account for less than 1% of the total runtime, which suggests the system has plenty of CPU headroom.

The trace also shows multiple additional tasks created by the tracing/debug tooling (goes beyond this screenshot) likely because the RTOS debug configuration changes task behavior and disables certain optimizations. For this analysis, that overhead is acceptable.

The next graph shows an RTOS timeline with a selected subset of tasks, making it easier to observe system behavior over time. The numbered markers highlight the following events:

1. The NimBLE stack periodically wakes up for short advertising intervals while the phone is not connected.
2. The Health Check task runs at regular, longer intervals.
3. The SEN66 task wakes up to collect a sensor sample. We can see activity in the Data Manager and the ESP-IDF spawned I2C_EXT0 task, which handles thread-safe I2C transactions.
4. When the phone connects, BLE activity increases significantly. The device begins history synchronization, involving the History, I2C, and BLE-related tasks as records are read from EEPROM and transferred to the app.
5. The Health Check task reads and clears the SEN66 status register to verify sensor health.

Project structure

airy/
├── src/                     # ESP-IDF firmware (C, + one C++ file)
│   ├── app_main.c           # Entry point / boot sequence
│   ├── tasks.{c,h}          # Central task stack sizes & priorities
│   ├── i2c.{c,h}            # Shared I2C master + bus mutex
│   ├── sen66.{c,h}          # SEN66 sensor driver & sampling task
│   ├── eeprom.{c,h}         # 24AA64 circular history log
│   ├── rtc.{c,h}            # PCF8523 + software-clock fallback
│   ├── button.{c,h}         # Multi-click gesture detection
│   ├── led.{c,h}            # LED status patterns
│   ├── crc.{c,h}            # Sensirion CRC-8 + CRC-16
│   ├── data_mngr.{c,h}      # Averaging, buffering, dispatch
│   ├── comm_mngr.{c,h}      # BLE/Matter selection & routing
│   ├── history.{c,h}        # EEPROM -> BLE history transfer task
│   ├── fault.{c,h}          # Fault log, severity, restart policy
│   ├── health_check.{c,h}   # Watchdog + periodic diagnostics
│   ├── device_cmd.{c,h}     # Maintenance command handlers
│   ├── ble_*.{c,h}          # NimBLE setup, adv, GAP, GATT, interface
│   └── matter_interface.cpp # esp-matter integration
├── ios-app/Airy/            # SwiftUI companion app
│   ├── Models/              # BLE Packet, AQI, EPA breakpoints, errors
│   ├── Services/            # BLE handlers, repository, storage, state
│   ├── Views/               # Dashboard, gauge, charts, settings, setup
│   └── Utilities/           # Design system & theme

Building and flashing

Prerequisites

• ESP-IDF v5.4.1 at ~/Developer/esp/esp-idf (or edit the paths in run.sh).
• ESP-Matter v1.4.2 at ~/Developer/esp/esp-matter.
• XIAO ESP32-C6 based Airy board over USB-C.
• Xcode 16+ for the iOS app.

Firmware

sh run.sh build --release     # optimized build
sh run.sh flash --release     # flash optimized build

The device boots into BLE mode by default. Double-click the button to switch to Matter mode (it will reboot). In Matter mode, commission it with your hub using the standard Espressif test credentials – Apple Home accepts developer-mode devices with a warning; Home Assistant needs "Test Net DCL" enabled in the Matter integration.

iOS app

Open ios-app/Airy.xcodeproj in Xcode, then build and run it on a physical device (CoreBluetooth is unavailable in the simulator). Grant the Bluetooth permission, tap to discover Airy devices, and the app will connect, sync history, and start streaming.

Licenses

The firmware in this repository is licensed under the Apache License 2.0. The SwiftUI app is licensed under the Mozilla Public License 2.0 (MPL-2.0).

For Developers & Commercial Users

You are free to use, modify, and distribute this software in personal, educational, or commercial products under the terms of the Apache 2.0 License.

If you use or distribute this code (or modified versions of it), you must:

1. Retain the original copyright notices and license text.
2. Provide attribution to this repository in your project documentation or "About" screens.

Resources

Component datasheets (bundled in docs/spec/):

• Sensirion SEN6x – docs/specs/SEN6x_datasheet.pdf
• NXP PCF8523 RTC – docs/specs/PCF8523_datasheet.pdf
• Microchip 24xx64 EEPROM – docs/specs/24xx64_eeprom_datasheet.pdf

Specifications:

• Matter 1.4.2 Application Cluster and Device Library specifications (Matter clusters and device types used by the Matter interface).
• Bluetooth assigned numbers and spec supplement (GATT appearance, characteristic conventions).

Architecture diagrams (PlantUML sources in docs/arch/):

• rtos-architecture.puml – tasks, queues, mutex, button ISR path.
• ble-gatt.puml – services, characteristics, packet layout.
• ble-history.puml – history download sequence.

Frameworks and SDKs:

• ESP-IDF
• ESP-Matter
• Apache NimBLE (check this link for Bluetooth API tutorials/examples from Espressif)