A real-time Linux Air Quality (AQI) monitoring stack featuring a kernel driver (CCS811), Python WebSocket gateway, and a modern web dashboard. Built for high-performance telemetry and safe virtualization on macOS.

Run the setup script to provision the Lima VM with necessary kernel headers and I2C tools:

./scripts/setup-lima-vm.sh

Compile and load the kernel module inside the VM:

limactl shell aqi-dev -- make -C kernel
limactl shell aqi-dev -- sudo insmod kernel/aqi_sensor.ko

Launch the real-time simulation and backend:

# Start backend gateway (Host)
uv run backend/src/sensor_stream.py

# Open Dashboard
open frontend/index.html

We use i2c-stub inside the Lima VM to simulate a CCS811 sensor, enabling safe, host-independent driver verification.

The aqi_sensor module binds to the virtual I2C bus, exposing a character device at /dev/aqi_sensor. It handles SMbus reads and provides an IOCTL interface for hardware control.

The aqi_reader (C) fetches data from the kernel and outputs structured JSON. The Python backend then bridges this telemetry to the Host using limactl shell.

Data is streamed via WebSockets to a modern frontend dashboard with live graphing and threshold alerting.

Real-time sensor data visualized on the dashboard.

Dashboard showing disconnected status when the backend is offline.

• Character Device Interface with IOCTL support.
• Automated VM isolation for safe kernel development.
• High-frequency real-time dashboard updates.
• PEP 723 inline dependency management via uv.