Compact CO2, temperature and humidity sensor for Home Assistant: ESP32-C3, Sensirion SCD41, 2" display, 3D-printed enclosure for flush wall boxes or desks. Browser installer, OTA updates, parametric Fusion CAD.
Taken from the repository README
README
Loading the full README. The saved excerpt is shown below.
A compact CO2, temperature and humidity monitor for Home Assistant.
It covers a flush wall box or stands on your desk.
English | Deutsch | Project page and browser installer
Flash it from your browser. Connect the ESP32-C3 via USB, click Install on the project page, enter your WiFi. Home Assistant finds the device and offers new releases as a firmware update.
Real CO2 measurement with the Sensirion SCD41 (photoacoustic NDIR), plus temperature and humidity.
2" IPS colour display with everything at a glance: traffic light status, large CO2 value, 3 hour trend, clock, indoor and outdoor temperature and humidity.
Window hint. The display tells you when opening the window cools the room or dries the air, using an outdoor sensor or simply your Home Assistant weather forecast.
Window contacts. With your contacts from Home Assistant the window symbol shows grey (shut), blue (airing), green (fresh air, close it) or orange (the room cools down), and the blueprint only reminds you to ventilate while the windows are shut.
Everything adjustable in Home Assistant. Measuring interval, smoothing, trend arrow, night schedule (dim or off), night brightness, warnings at night, temperature correction, altitude and every hint threshold, no reflashing needed. Step by step: Home Assistant guide.
One device, two mounts. A dovetail rail slides onto the wall plate (two M4 screws with wall plugs, or the screws of a 68 mm flush wall box) or the desk stand.
Cable from the back or from below with the same housing: a 90° USB-C adapter leads the cable straight into the wall, or a straight cable leaves through the slot in the bottom. The opening you do not use is closed by a clean printed part.
One screw type, nothing glued. 10 heat-set inserts M2 × 3 and 10 button head screws M2 × 4. The SCD41 and the ESP32-C3 slide into rails and click behind spring hooks, the display cable stays plugged in and runs under a printed bridge.
Thought-through thermals. The sensor lives in its own chamber below the electronics, fresh air enters from below, the front stays closed.
Fully parametric CAD. Every dimension is a Fusion user parameter. Change a value, run the script, get new STL, STEP, print plates and drawing.
Bilingual. Firmware, documentation, drawings and project page in English and German.
Every 30 seconds (adjustable from 5 to 60 s) the SCD41 delivers a new reading. The ESP32-C3 updates the display, classifies the air quality against two thresholds (default 1000 and 1400 ppm) and reports everything to Home Assistant.
Specifications
Device
79.6 × 69.8 × 24 mm (+ 3 mm rail)
Wall plate
89.2 × 82 × 7 mm, slots for M4 screws 60 mm apart, also fits flush wall boxes Ø 68 mm
Display window
41.8 × 31.6 mm, 320 × 240 px IPS
Sensor
Sensirion SCD41, 400 to 5000 ppm, ±(50 ppm + 5 % of reading)
Room size
one sensor per room; in open spaces up to about 500 m² (FAQ)
Power
5 V via USB-C, about 0.5 W
Cable exit
back (90° USB-C adapter) or bottom (straight plug), same parts
Fasteners
10 heat-set inserts M2 × 3 (OD 3.0 to 3.2), 10 screws M2 × 4 ISO 7380, 2 screws M4 for the wall
² Shops often show a different board than the one they send. Measure it on arrival and print the matching carrier.
SCD41 boards come in different sizes. Only the small sensor carrier depends on the board: there is one for the 13.5 × 21.75 mm and one for the 15 × 20 mm board, for others enter six measurements in the online configurator and download the carrier. See measure your sensor.
Machine-readable: hardware/bom.yaml. This file is the only place for parts, prices and shop links; the table above and the project page are generated from it.
Wire the modules according to docs/wiring.md and assemble them as described in docs/assembly.md. The 3D assembly guide shows every step: turn the device, take it apart, hide single parts (double-click) and see which part comes next.
Flash the firmware from your browser on the project page. To build it yourself: copy esphome/secrets.yaml.example to secrets.yaml, fill it in and install esphome/co2-wall-sensor.yaml with the ESPHome Builder (German interface: co2-wall-sensor-de.yaml).
Home Assistant discovers the device automatically.
Home Assistant
Entity
Type
Purpose
CO2, Temperature, Humidity
sensor
measurements every 30 s
Measuring interval, Smoothing
number, switch
5 to 60 s (default 30 s), mean of two readings (default on)
Trend arrow from
number
change per hour that turns the arrow up or down (default 100 ppm/h)
Open the window, Airing dries the air, Keep it shut, None; with a window contact: Airing for x min, Fresh air: close the window, Close the window: room cools down
CO2 threshold yellow / red
number
traffic light limits (default 1000 / 1400 ppm)
Display brightness
light
dim or switch off the display by hand
Night mode, Night from, Night until
switch, time
night schedule (default 22:00 to 06:00)
Display at night, Night brightness
select, number
dim (default 8 %) or switch off
Red warning at night
switch
the display wakes up while the CO2 level is red (not while a window is open)
Window hint on the display, Window symbol on the display, Outdoor value on the display
switch
show or hide them
Display upside down
switch
turns the picture by 180° if it stands on its head
Window hint from indoor temperature, Window hint: cooler outside by
number
default 24 °C and 3 °C
Fresh air below, Window warning below
number
with an open window: fresh air (default 700 ppm), room cools down (default 19 °C)
Temperature correction
number
self-heating at your wall: compare with a reference thermometer
Altitude above sea level
All settings are kept after a power cut. Nothing has to be built yourself: the browser installer firmware has every setting.
Outdoor values
The display shows the outdoor temperature under OUT, and the window hint compares inside and outside.
Without anything to set up the device takes weather.forecast_home, the weather entity Home Assistant creates for your home location (integration Meteorologisk institutt (Met.no)).
A real outdoor sensor wins. Pair it as usual (Zigbee, Homematic IP, Shelly, ...), open it under Settings > Devices & services > Entities, click the gear and set the entity ID to sensor.outdoor_temperature (humidity: sensor.outdoor_humidity). A few seconds later the display shows it. No new firmware needed.
Window contacts
With a window contact the device knows when you are airing. The window symbol at the top is grey while the windows are shut. Open one and it turns blue, the hint line counts the minutes (Airing for 6 min), green tells you the air is fresh again (Fresh air: close the window, below 700 ppm) and orange that the room cools down too much (Close the window: room cools down, below 19 °C). While a window is open the red pill says Airing instead of Ventilate! and the red warning does not wake the display at night. Both thresholds are settings in Home Assistant, a switch hides the symbol. Every step with pictures: Home Assistant guide.
In Home Assistant open Settings > Devices & services > Helpers > Create helper > Group > Binary sensor group, name it CO2 Wall Sensor Window (German firmware: CO2 Wandsensor Fenster) and add the window contacts of the room. The entity ID becomes binary_sensor.co2_wall_sensor_window (binary_sensor.co2_wandsensor_fenster), exactly what the firmware listens to.
The group is on as soon as one window is open. A second window later? Just add it to the group, no new firmware needed.
Several devices in different rooms: give each device its own group and set window_entity in its device file.
Ventilation reminder: a ready blueprint notifies your phone when the CO2 level stays high and the windows are shut, when the air is fresh again with the window open and when the room cools down. It takes the thresholds straight from the device.
More examples (automations, dashboard card) are in homeassistant/.
Repository structure
co2-wall-sensor/
├── cad/
│ ├── fusion/generate_enclosure/ Fusion script, the single source of truth for all geometry
│ ├── fusion/co2_wall_sensor.f3d Fusion archive of the assembly (with slider joint)
│ ├── 3mf/ print-ready plates
│ ├── step/ STEP of the full assembly
│ ├── stl/ single print files
│ └── build_info.json fingerprint of the parameters the print files were made from
├── docs/ assembly, wiring, Home Assistant guide, design notes, FAQ (German in docs/de)
│ ├── drawing/ technical drawing, PDF + PNG, EN and DE
│ └── images/ renders, animation, wiring diagram, display preview
├── esphome/
│ ├── co2-wall-sensor*.yaml device files: own build and browser installer, EN and DE
│ └── common/ shared firmware logic and network variants
├── hardware/bom.yaml bill of materials with shop links
├── homeassistant/ blueprint, automations and dashboard card (German in homeassistant/de)
├── site/ template of the project page
└── tools/ generators for drawing, wiring, preview, print plates, project page, checks
Customising the enclosure
Every dimension is a Fusion user parameter.
In Fusion open Utilities > Scripts and Add-Ins, click + and add the folder cad/fusion/generate_enclosure. Run the script once.
Open Modify > Change Parameters and adjust values, for example FIT for tighter or looser fits, the SCD_* values for a different sensor board (measure your sensor) or INSERT_HOLE_D for other inserts.
Run the script again. It takes over your parameters, rebuilds every part and checks wall and desk assembly for interference. With EXPORT = True it writes new STL and STEP files and cad/build_info.json.
Regenerate drawing, print plates and the other generated files:
The CI repeats all of this, compiles four firmware variants and checks that the print files belong to the committed parameters. More background: design notes and FAQ.
Before your first print
Versions: the release number (e.g. 1.9.0) counts every change, firmware and docs included. The enclosure version (badge at the top, engraved on every printed part) only changes when the printed parts change. Parts with the same enclosure version fit together, whatever release they came from.
Display: all dimensions of the Waveshare 2inch LCD Module are measured with a caliper (PCB 58.2 × 35.3 × 1.62 mm, glass 47.7 × 34.6 mm, PCB and glass 4.43 mm thick). Other batches may differ slightly: check LCD_* and GLASS_*.
Hardware status: enclosure 2.5 contains the lessons of the first printed device and is verified in CAD and CI. Compared with 2.3 only the sensor carrier changed (every wire is soldered from below, with room behind the boards, 1 mm of air behind the whole SCD41), all other parts of 2.3 fit. The 90° USB-C adapter is measured, pocket and hole fit it with 1 mm play. Photos and measurements of a printed device are welcome.
Roadmap
Sensor carrier profiles for different SCD41 boards (#7, v1.4)
Enclosure 2.0 after the first print: display cable stays plugged, ESP32-C3 on a sled with a spring hook, 90° adapter instead of the loose port module, wall plate for M4 screws (v2.0)
Enclosure 2.1: more play in every fit (0.4 mm), clean bottom blank or closed back cover for the unused cable opening, lead-ins, pull tab on the carrier, 2 mm air for the display cable (v2.1)
Window contacts from Home Assistant: window symbol, airing time and a hint to close the window (v2.2)
Window states in colour, more settings in Home Assistant (measuring interval, smoothing, trend arrow, fresh air and cooling thresholds), blueprint that follows the window, Home Assistant guide (v2.4)
Enclosure 2.4: every wire soldered from below, a channel behind the SCD41 pads and a free space under the ESP32-C3, only the sensor carrier changed (v2.5)
Contributing
Issues, ideas and pull requests are welcome, see CONTRIBUTING.md. Questions and photos of your build go to Discussions. Security issues: SECURITY.md.
