SGP30 TVOC Sensor Handling
Relevant source files
The following files were used as context for generating this wiki page:
The SGP30 TVOC Sensor Handling module manages the Sensirion SGP30 gas sensor, which is a key component in both the Awair Glow C and Awair Element devices. Its primary responsibility is to measure Total Volatile Organic Compounds (TVOC) and provide estimated CO₂ (eCO₂) values for air quality monitoring.
Within the OpenAwair architecture, the SGP30 is integrated as a standard sensor driver. It operates via the I²C interface and requires specific handling for calibration, including the management of baseline values to maintain accuracy over time.
Sources: CLAUDE.md:12-25, host/src/firmware/sensors/sgp30.ts:4-20
Architecture and Implementation
Sensor Driver Interface
The Sgp30Sensor class implements the SensorDriver interface, ensuring it can be managed by the system's SensorScheduler. This interface requires the sensor to provide a name, a sampling interval, and an asynchronous read method.
Calibration and Baselines
The SGP30 requires a baseline value for accurate operation. In the host-side implementation, this baseline can be set manually. If no baseline is provided, the sensor defaults to a standard value (e.g., 150 ppb). In the physical firmware implementation, it is noted that the sensor requires approximately 24 hours to auto-calibrate, and the baseline must be persisted to flash storage every ~12 hours to survive reboots.
| Property | Value / Requirement | Description |
|---|---|---|
| Sample Interval | 10,000 ms (10 seconds) | Frequency at which the sensor is polled. |
| Auto-calibration | ~24 hours | Time required for the sensor to stabilize. |
| Baseline Persistence | ~12 hours | Frequency for saving baseline values to flash storage. |
| Default TVOC | 150 ppb | Fallback value used if no baseline is established. |
Sources: host/src/firmware/sensors/sgp30.ts:7-16, CLAUDE.md:78-78
Data Flow and Telemetry
When the read() method is invoked, the Sgp30Sensor returns a SensorReading object. This object contains a timestamp and the measured vocPpb (Volatile Organic Compounds in parts per billion).
Telemetry Data Structure
The sensor's output is mapped to the SensorReading interface, which is a subset of the overall DeviceMetrics.
export interface SensorReading {
readonly timestamp: Date;
readonly vocPpb?: VolatileOrganicCompounds; // Targeted by SGP30
// ... other fields (temp, humidity, etc)
}
Sources: host/src/firmware/sensors/sgp30.ts:14-20, host/src/shared/telemetry.ts:8-15
Integration with Device Hardware
The SGP30 is utilized across different hardware revisions supported by OpenAwair:
- Awair Glow C: Uses SGP30 for both TVOC and eCO₂ estimation via the I²C bus.
- Awair Element: Uses SGP30 specifically for TVOC monitoring, while relying on a dedicated Telaire T6703 for NDIR CO₂ measurements.
The AwairDevice controller initializes these sensors through the SensorScheduler, which iterates through all registered drivers to collect environment data.
Summary
The SGP30 handling in OpenAwair provides a standardized way to ingest air quality data into the system. By implementing the SensorDriver interface, the SGP30 integrates seamlessly with the host-side telemetry and MQTT discovery systems. Crucially, the implementation acknowledges the hardware-specific requirement for long-term baseline management and calibration to ensure data integrity over the life of the device.