HVAC Filter Monitor & Air Quality Sensor

This project is a comprehensive monitoring system for a home HVAC (Heating, Ventilation, and Air Conditioning) unit. It combines an ESP32-based touch display with an Arduino Nano sensor hub to provide real-time data on HVAC performance and indoor air quality. All data is integrated into Home Assistant via MQTT for easy monitoring and automation.

Overview

The system is composed of two main components:

1. ESP32 Display Controller: An ESP32-2432S022C board runs a rich user interface built with LVGL. It handles WiFi connectivity, communicates with the sensor hub through uart, and pushes all data to a Home Assistant instance via MQTT. It also supports Over-the-Air (OTA) updates via both ArduinoOTA and a web interface.

2. Arduino Nano Sensor Hub: An Arduino Nano (ATmega168P) acts as a dedicated I2C and analog sensor hub. It gathers data from a suite of sensors and sends it to the ESP32 over a robust serial protocol. It runs a custom non-blocking firmware and uses the Urboot bootloader for maximum code space availability and seemless LTO optimized firmware binary.

Features

• HVAC Monitoring:

  • Measures differential pressure across the air filter to determine its condition.
  • Monitors the fan's electrical current using a CT clamp to detect its operational state (Off, Normal, Alert).
  • Provides a "High Pressure" alert, indicating a clogged filter that needs replacement.

• Air Quality Sensing:

  • Particulate Matter: Sensirion SPS30 for PM1.0, PM2.5, PM4.0, and PM10 readings.
  • CO₂ Levels: Sensirion SCD30 for Carbon Dioxide concentration.
  • VOC Index: Sensirion SGP41 for a Volatile Organic Compounds index value.
  • Temperature & Humidity: Provided by the Sensirion SCD30.

• Environmental Sensing:

  • Radiation: A Geiger counter measures background radiation in Counts Per Minute (CPM) and calculates the dose in µSv/h.

• User Interface:

  • A 2.2" color touch screen powered by LVGL.
  • Multiple swipeable tiles to display different categories of data (Air Quality, HVAC Status, System Info).
  • Status icons for WiFi, Home Assistant connection, sensor hub connection, and alerts.

• Home Assistant Integration:

  • Automatic discovery of all sensors and controls via MQTT.
  • Entities include sensors for all measured values, binary sensors for alerts, and buttons for system control.
  • Diagnostic sensors for Nano SensorStack subsystem's uptime, free RAM, and last reset cause.

• System & Diagnostics:

  • Uart/Serial communication between ESP32 and Nano with checksum validation.
  • Remote logging to a Syslog server with an offline message queue.
  • OTA updates for the ESP32.

Hardware

Main Components

• Display Controller: Sunton ESP32-2432S022C (ESP32-WROOM-32, 2.2" ST7789 TFT, CST820 Touch)
• Sensor Hub: Arduino Nano (ATmega168P @ 16MHz)

Sensors

• Differential Pressure: Custom 4-20mA current loop sensor.
• Particulate Matter: Sensirion SPS30
• CO₂, Temp, Humidity: Sensirion SCD30
• VOC: Sensirion SGP41
• Fan Current: SCT-013-010 Non-invasive AC Current Sensor (CT Clamp)
• Radiation: Generic Geiger-Müller tube with a pulse output.

Software & Libraries

This project is built using PlatformIO.

ESP32 (Display Controller)

• Framework: Arduino for ESP32
• UI: LVGL (Light and Versatile Graphics Library)
• Display Driver: LovyanGFX
• Home Assistant: ArduinoHA
• Logging: Syslog, ESP32Ping
• Updates: ArduinoOTA, WebServer

Arduino Nano (Sensor Hub)

• Core: MiniCore
• Bootloader: Urboot. Refer to urboot Github page for more information.
• Sensor Libraries: Official Sensirion libraries for SPS30, SCD30, and SGP41.

Communication Protocol (ESP32 <-> Nano)

Communication occurs over a simple, packet-based serial protocol at 19200 baud.

• Packet Format: <DATA,CHECKSUM>
• Checksum: A custom 8-bit CRC (polynomial 0x07) ensures data integrity.
• Commands: The ESP32 sends single-character commands to the Nano to request data or actions (e.g., H for health, V for version, R for reboot).
• Responses: The Nano responds with data packets prefixed with a character identifying the payload type (e.g., S for sensor broadcast, h for health response).

Setup & Installation

1. Prerequisites

• PlatformIO Core installed in your IDE (e.g., VSCode).
• An ISP programmer for the initial bootloader flash on the Arduino Nano (e.g., USBasp, another Arduino as ISP).

2. Configuration

Copy the include/secrets.h.example file to include/secrets.h and fill in your credentials:

// include/secrets.h

#define WIFI_SSID "YourWiFi_SSID"
#define WIFI_PASSWORD "YourWiFi_Password"

#define MQTT_HOST "192.168.1.100" // IP or hostname of your MQTT broker
#define MQTT_USER "mqtt_username"
#define MQTT_PASSWORD "mqtt_password"

3. Building and Uploading

This project contains two separate PlatformIO environments: one for the ESP32 and one for the Nano.

Arduino Nano (Sensor Hub)

The Nano requires a one-time setup to install the Urboot bootloader.

1. Burn Bootloader (First Time Only):

   • Connect your ISP programmer to the Nano's ICSP header.
   • Program urboot compiled bootloader to your device
     • urboot_m168p_2s_autobaud_uart0_rxd0_txd1_led+b5_hw.hex was used for this project.
   • Program fuses
     • For ATMega168PA with 256bytes urboot bootloader with hw reset vector

       lfuse: 0xf7
       hfuse: 0xd4
       efuse: 0xfe
       

2. Upload Firmware:

   • After the bootloader is installed, you can upload the firmware over the regular USB serial connection.
   • Use the Upload_UART environment.

     pio run -e Upload_UART -t upload

ESP32 (Display Controller)

Uploading to the ESP32 is straightforward.

1. Upload Firmware:

   • Connect the ESP32 board via USB.
   • Run the standard PlatformIO upload command.

     pio run -t upload

2. OTA Updates:

   • Once the initial firmware is flashed on ESP32, subsequent updates can be done over the network using either the PlatformIO OTA command or the built-in web updater.
   • The Arduino Nano (SensorStack) firmware can also be updated from the web updater (.hex file, flashed over UART by the ESP32). This requires the custom urboot bootloader to be installed once over ISP; see HVAC_NanoSensorHub/BOOTLOADER.md.

4. MicroSD Failsafe Recovery & Configuration

The Sunton ESP32-2432S022C includes an onboard MicroSD (TF) card slot. To guarantee that the device can never be permanently locked out by a runtime crash, buggy firmware, or network misconfiguration, an early boot-time failsafe check runs immediately on power-on.

This check executes before the LVGL UI, FreeRTOS tasks, Task Watchdog, WiFi stack, or Serial communication with the Arduino Nano initialize. The SPI bus and SD card are active only during this boot check; they are completely unmounted and shut down (pins placed in high-impedance mode) before the UI loads to guarantee zero impact on LVGL rendering performance.

To use this feature, format a MicroSD card with FAT/FAT32 and place either or both of the following files in the card's root directory:

1. Failsafe Firmware Flashing (firmware.bin)

• File Name: firmware.bin (or FIRMWARE.BIN)
• Behavior:
  • The boot routine performs integrity validation: checks minimum size (>= 64 KB), partition limit (<= ~1.98 MB), the ESP32 binary header magic byte (0xE9), and the target chip ID (ESP32).
  • If valid, the image is written directly to the next OTA partition and verified.
  • Upon successful flash, firmware.bin is automatically deleted from the card (or renamed to .done if deletion fails) to prevent boot loops.
  • The device immediately restarts into the newly flashed firmware.
  • If validation or flashing fails, the file is renamed to firmware.bin.bad or .failed to prevent repetitive boot loops.

2. Configuration Injection (config.txt)

• File Name: config.txt (or CONFIG.TXT, wifi.txt)
• Behavior:
  • Injects new Wi-Fi credentials and optional MQTT overrides into non-volatile storage (NVS hvac-config namespace).
  • Persisted settings override compiled defaults (secrets.h) without requiring a reflash.
  • Once written to NVS, config.txt is automatically deleted from the card (or renamed to .done) so plain-text credentials are not left on the card.
  • Normal boot continues and uses the new credentials immediately.

Configuration Syntax Example (config.txt):

# Wi-Fi Credentials
ssid=MyHomeWiFi
password=MySecretPassword

# Facultative / Optional: MQTT Broker & Device Overrides
mqtt_host=192.168.1.100
mqtt_port=1883
mqtt_user=homeassistant
mqtt_password=mqttsecret
mqtt_device_id=hvac_diff_pressure_sensor_01
mqtt_device_name=HVAC Sensor Display

Note: Both keys and values support whitespace around = and quotes around values (e.g. ssid = "My Network"). Comment lines starting with #, ;, or // are ignored.

Home Assistant Integration

Once the device is connected to your network and MQTT broker, it will automatically appear in Home Assistant under the "HVAC Sensor Display" device.

Entities Created:

• Sensors: Differential Pressure, Temperature, Humidity, Fan Current, CO₂, VOC Index, PM1.0, PM2.5, PM4.0, PM10.0, Geiger CPM, Geiger Dose Rate.
• Diagnostic Sensors: WiFi RSSI, Sensor Stack Uptime, Sensor Stack Free RAM, Sensor Stack Firmware Version, Sensor Stack Reset Cause.
• Binary Sensors: Fan Status, High Pressure Alert, Sensor Stack Connection.
• Controls:
  • A HALight entity to control the display backlight brightness.
  • A HAButton to reboot the ESP32 display.
  • A HAButton to remotely reboot the Nano sensor stack.
  • A HAButton to request detailed diagnostic info from the SPS30 sensor.
  • A HAButton to trigger the SGP41 self-test.

---

This project is a work in progress. Contributions and suggestions are welcome!