ESP32-S3 firmware for a campus classroom sensor node: CO2/temperature/humidity
(SCD41), occupancy (mmWave presence, optional door counter), and power/energy
(Modbus-RTU meter over RS485). Reports to visualization-server's sensors
service — see docs/wire-contract.md.
Builds clean with ESP-IDF v5.3.2 (
idf.py set-target esp32s3 && idf.py build). Not yet run against real hardware — expect to adjust the sensor drivers once you have boards wired up.
- ESP-IDF v5.x
- An ESP32-S3 board with at least 8MB flash.
idf.py set-target esp32s3
idf.py build
idf.py -p <PORT> flash monitorWi-Fi credentials, server address, and device id/API key are read from NVS
at boot (components/device_config) — the firmware image itself has none
of this hardcoded, so the same build works for every node.
- In the dashboard, create a device under
/devices/newand copy the returned device id and API key (shown once). - Copy
provisioning/device_config.csv.exampletoprovisioning/device_config.csvand fill in Wi-Fi,server_host/server_port, and the id/key from step 1. - Generate and flash the NVS partition:
python $IDF_PATH/components/nvs_flash/nvs_partition_generator/nvs_partition_gen.py \
generate provisioning/device_config.csv provisioning/device_config.bin 0x6000
esptool.py -p <PORT> write_flash 0x9000 provisioning/device_config.binPin assignments are in main/sensor_common_pins.h.
| Signal | Interface | Pins (default) |
|---|---|---|
| SCD41 | I2C | SDA=8, SCL=9 |
| SSD1306 OLED (optional) | I2C, shared bus | SDA=8, SCL=9 |
| mmWave presence | GPIO in | 4 |
| Door A/B (optional) | GPIO in, interrupt | 5, 6 |
| RS485 energy meter | UART + DE/RE | TX=17, RX=18, RTS=15 |
| microSD (optional) | SPI | MOSI=11, MISO=13, SCLK=12, CS=10 |
| CO2 status LEDs | GPIO out | 1, 2, 3 |
| Waste LED | GPIO out | 21 |
| Fan relay | GPIO out | 14 |
The energy meter's register map and scale factors (main/app_main.c) are
meter-model-specific placeholders — set them from your meter's datasheet.
main/ boot sequence, pin map
components/device_config NVS-backed configuration
components/sensor_common shared reading struct and latest-values state
components/sensor_scd41 CO2/temperature/humidity driver
components/sensor_presence mmWave + door counter driver
components/sensor_power Modbus-RTU energy meter driver
components/analysis CO2 average/rate, waste detection, CO2e
components/storage_sd pending-readings buffer, optional SD-backed
components/net_client Wi-Fi, SNTP, HTTP reporting
components/display_status optional SSD1306 status readout