CO2 Wall Sensor

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

---

Highlights

• 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.

How it works

flowchart LR
    SCD41["SCD41<br>CO2 / temp / humidity"] -- I2C --> ESP["ESP32-C3 SuperMini<br>ESPHome"]
    ESP -- SPI --> LCD["2&quot; IPS display<br>320 x 240"]
    ESP <-- "WiFi, native API" --> HA["Home Assistant"]
    USB["USB-C 5 V<br>(wall box or surface cable)"] --> ESP
    GH["GitHub releases"] -. "firmware update" .-> HA

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
Print material	PETG (PLA possible), about 120 g

Technical drawing (A3, ISO first angle): English PDF | German PDF

Bill of materials

The total for one device is in the last row of the table. The links are suggestions, checked in October 2026; prices change often.

Qty	Part	AliExpress	Amazon.de
1	Sensirion SCD41 breakout, 13.5 × 21.75 mm or 15 × 20 mm ²	21.19 €	AliExpress only
1	ESP32-C3 SuperMini	2.79 €	4.30 € (2 pcs: 8.59 €)
1	Waveshare 2inch LCD Module (ST7789V, 240 × 320)	12.49 €	16.31 €
10	Heat-set insert M2 × 3, outer diameter 3.0 or 3.2 mm, length 3 mm	2.39 € (50 pcs, OD 3.2)	4.69 € (205 pcs, OD 3.0)
10	Button head screw M2 × 4, ISO 7380	Amazon only	4.79 € (60 pcs)
1	USB-C 90° adapter (plug to socket) for the cable to the back	Amazon only	4.49 €

² 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.

Quick start

1. Print the two ready plates co2_wall_sensor_device.3mf and co2_wall_sensor_mounts.3mf (every part already in its print orientation, the device plate includes the desk stand: delete it for a wall mount) or the single files from cad/stl. Settings: docs/assembly.md.

2. 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.

3. 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).

4. 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)
CO2 trend, Ventilate in	sensor	ppm per hour, minutes until the red level
Air quality	text	Good, Moderate, Ventilate!
Outdoor temperature, Outdoor humidity	sensor	from Home Assistant, see outdoor values
Window hint	text	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.

1. In Fusion open Utilities > Scripts and Add-Ins, click + and add the folder cad/fusion/generate_enclosure. Run the script once.
2. 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.
3. 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.
4. Regenerate drawing, print plates and the other generated files:

pip install -r requirements.txt
python tools/drawing.py && python tools/build_3mf.py
python tools/wiring.py && python tools/display_preview.py
python tools/check_repo.py

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.
• SCD41 board: measure it and print the matching sensor carrier, see measure your sensor. Other boards: online configurator.
• 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)
• Interactive 3D assembly guide (open it, v1.6)
• ESP32-C3 holder from the measured board, tolerant to other batches (v1.7)
• Collision check of every assembly path in the CI (v1.7)
• Outdoor temperature on the display, with a hint when opening the window helps (v1.8)
• Clean cable routing without glue: wire slot and wire clip on the sensor carrier, free cable path behind the display (v1.9)
• Online configurator: sensor carrier STL from the dimensions of the board (#8, v1.9)
• 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.

License

Software and firmware: MIT. Hardware (enclosure, print files, drawing, bill of materials): CERN-OHL-P-2.0. © 2026 Tobias Schneider. Build it, adapt it, share it.