Carbon Dioxide Sensor Zigbee Device

The Carbon Dioxide Sensor is a Zigbee device that measures the carbon dioxide concentration of the air with a Sensirion SCD41 sensor, together with the temperature and the humidity. It reports the CO2 level in ppm, the temperature, the humidity and a Red / Amber / Green level to the coordinator, and shows the same level on three LEDs. The two thresholds behind the level are set from Zigbee2MQTT or Home Assistant and kept on the device.

Bill of Materials

The Carbon Dioxide Sensor Zigbee Device consists of the following parts:

• 1x: Seeed Studio XIAO ESP32-C6 (without pin headers, it is soldered flat onto the PCB using its castellated edge pads)

  • Seeed Studio XIAO ESP32-C6

  • Seeed Studio XIAO ESP32-C6 (Amazon)

• 1x: SCD41 Sensor Module (Sensirion SCD41 on a 4-pin I2C module with the pins GND, VDD, SCL, SDA, 2.4-5.5 V, about 21.5 x 13 mm; the module must not have its own voltage regulator)

  • SCD41 Gas Sensor Module (Amazon)

  • SCD41 Gas Sensor Module, 2 pieces (Amazon)

  • SCD41 Gas Sensor Module 2.4-5.5V (Amazon)

• 1x: Linear Voltage Regulator 3.3V 600mA (SMD, SOT-23-5)

  • AP2112K-3.3TRG1

• 2x: Ceramic Capacitor 10µF 16V X5R (SMD, 0805)

  • CC0805KRX5R7BB106

• 2x: Thick Film Resistor 2.7kΩ 1% 1/8W (SMD, 0805)

  • RC0805FR-072K7L

• 1x: Thick Film Resistor 330Ω 1% 1/8W (SMD, 0805)

  • RC0805FR-07330RL

• 1x: LED (Red, 5mm, Diffused, Low Current)

  • WP7113LSURDK

• 1x: LED (Yellow/Amber, 5mm, Diffused)

  • WP7113SYD

• 1x: LED (Green, 5mm, Diffused)

  • 151051VS04000

• 1x: Male Header (4-Pin, 0.100" (2.54mm), Straight)

  • PRPC004SAAN-RC

• 4x: M2.2x13mm Flathead Screw

  • Flathead Screw Set

• 2x: 3D Printed Parts

  • Controller_Base.3mf

  • Controller_Cover.3mf / Controller_Cover_Handles.3mf (wall mount version)

• 1x: Custom PCB

  • Carbon_Dioxide_Sensor_Gerbers.zip

• 1x: USB-C Power Adapter (5V, 1A or more) with a USB-C cable (1m or shorter)

Before assembling the device, make sure you have all the required parts, including the 3D-printed parts and the custom PCB.

For more information on ordering a custom PCB, see Order Custom PCB. The board is 60 x 34 mm with four M2 mounting holes (2.2 mm), 3.5 mm in from each corner.

Assembly Instructions

Here are the device assembly instructions:

• Carrier Board: Solder each component onto the Custom PCB according to the Carbon Dioxide Sensor Assembly.pdf diagram. The PCB components are:

  • R1, R2 Thick Film Resistors (2.7kΩ, 0805, marked 2701): RC0805FR-072K7L

  • R3 Thick Film Resistor (330Ω, 0805, marked 3300): RC0805FR-07330RL

  • C1, C2 Ceramic Capacitors (10µF, 0805): CC0805KRX5R7BB106

  • U2 Linear Voltage Regulator (3.3V, SOT-23-5): AP2112K-3.3TRG1

  • D1 Red LED: WP7113LSURDK

  • D2 Amber LED: WP7113SYD

  • D3 Green LED: 151051VS04000

  • J1 Male Header (4-Pin, Straight): PRPC004SAAN-RC

  • XIAO ESP32-C6

  • SCD41 Sensor Module (soldered onto J1)

First, solder the five 0805 parts (R1-R3, C1, C2) and U2 onto the top side of the Custom PCB: tin one pad, slide the part in while the solder is molten, then solder the other end (the other four legs for U2). The resistors carry their value code on top; the capacitors are unmarked. Next, place the XIAO ESP32-C6 flat on the top side with its USB-C connector over the left edge of the board, so that the connector face ends flush with the board edge, and solder its 14 castellated edge pads (the PCB pads reach past the module edge and under its holes, so each joint can be soldered along the castellation or through the hole from the top). Then solder J1 with its long pins pointing up, and the LEDs on about 5 mm of lead so that their domes reach the cover: set the cover over the board and push each LED up into its hole before soldering. Solder the SCD41 Sensor Module last.

• Warning: The following components require a specific orientation. Detailed instructions on how to position them on the board are provided in Carbon Dioxide Sensor Board Polarity.pdf.

  • D1-D3 LEDs (short leg in the square pad, the upper one of each pair)

  • XIAO ESP32-C6 (flat on the board, USB-C over the left edge, its D0 pad at the pad marked D0)

  • U2 Voltage Regulator (three legs toward the LEDs, two legs toward C2)

  • J1 Male Header (short legs in the board, long pins pointing up, GND at the square pad)

  • SCD41 Sensor Module (sensor up, each pin on the J1 pin of the same name)

• SCD41 Sensor Module: Set the module onto J1 with the sensor facing up and its board parallel to the Carrier Board, so that each of its pins lands on the J1 pin with the same name: GND to GND, VDD to VDD, SCL to SCL and SDA to SDA. The names are printed next to J1's pins on both sides of the Carrier Board and next to the pins on the module. Push the module down onto the header's plastic body and solder its four pins on the module's top side. Hold the module by its edges and never touch the white membrane on top of the sensor. The module stays on the board; it is not meant to be detached.

The board expects the module's pins in the order GND, VDD, SCL, SDA. A module that prints them in another order does not fit J1 directly.

• Enclosure: Set the Carrier Board, with the module soldered on, onto the four standoffs of Controller_Base.3mf. Lower Controller_Cover.3mf (or Controller_Cover_Handles.3mf) straight down over it, with the sensor under the air window, the LEDs in their holes and the USB-C connector in the slot in the end wall, and fasten it from below with the four M2.2x13mm Flathead Screw through the countersunk holes in the base.

The screws cut their own thread in the printed plastic: drive them until the head seats and no further.

Print Controller_Base as modelled and the covers upside down, with the top plate on the print bed, so that the walls and bosses print without supports.

• Power on the device by plugging the USB-C Power Adapter into the XIAO ESP32-C6 through the slot in the cover.

The sensor needs about a minute after power-up before its readings settle; the amber LED blinks meanwhile. Keep the air window clear and never poke anything through it: the sensor's membrane sits right under it.

Figure 1 (Device)

Figure 2 (Device)

Device Software

• Flash Device Software: Flash the prebuilt firmware in the Carbon_Dioxide_Sensor_Binaries.zip archive to the XIAO ESP32-C6 with esptool (pip install esptool). Connect the XIAO with the USB-C cable and run the following command from inside the folder (on Windows the port is a COM port):

python -m esptool --chip esp32c6 --port /dev/ttyACM0 --baud 460800 --before default-reset --after hard-reset write-flash @flash_args

Extract all files from the Carbon_Dioxide_Sensor_Binaries.zip archive to a local folder and rename all *.bin.data files to *.bin.

If esptool cannot connect, hold the XIAO's BOOT button while plugging in the cable, then run the command again. The XIAO ESP32-C6 can be flashed before or after it is soldered to the Carrier Board.

• Zigbee2MQTT: Use the Carbon_Dioxide_Sensor.mjs external converter in Zigbee2MQTT.

• Home Assistant (ZHA): Use the Carbon_Dioxide_Sensor.py quirk (quirks v2) in the Zigbee Home Automation integration. Copy the file into the custom quirks folder set with custom_quirks_path in the zha section of configuration.yaml, restart Home Assistant, and then pair the device.

Rename both Carbon_Dioxide_Sensor.mjs.txt to Carbon_Dioxide_Sensor.mjs and Carbon_Dioxide_Sensor.py.txt to Carbon_Dioxide_Sensor.py.

The quirk is written for Home Assistant 2026.8 or later. In Home Assistant the entities are named Level, Amber threshold, Red threshold, Automatic self-calibration, Altitude, Temperature offset, Forced recalibration target and Forced recalibration, whether the device is connected through ZHA or through Zigbee2MQTT; the three measurements come from the standard Zigbee clusters and are named Carbon dioxide concentration, Temperature and Humidity through ZHA and CO2, Temperature and Humidity through Zigbee2MQTT. In the Zigbee2MQTT device page the values appear as co2, temperature, humidity, level, threshold_amber, threshold_red, self_calibration_automatic, sensor_altitude, offset_temperature, calibration_target and recalibration_forced.

Device Usage

• Connect Device to Zigbee Network: After flashing the software, power on the device to start the connection process. In Zigbee2MQTT, select Permit Join to allow the device to connect to the Zigbee network. The XIAO's built-in LED blinks until the connection completes, then turns off. If you need to reconnect the device, open the cover and press and hold the BOOT button for more than 3 seconds; this also restores the default settings.

• Warm-Up: For the first minute after power-up the amber LED blinks and the level reads Warmup while the sensor takes its first readings. A sensor that was unpowered for a long time, or moved into very different air, needs a few more minutes before its readings settle.

• Readings: The device reports the CO2 concentration in ppm, the Temperature, the Humidity and a Level (Green, Amber, Red, Warmup or Fault), on change and at least once a minute. The green, amber and red LEDs show the level. Outdoor air is about 400 ppm; indoor air below 1000 ppm counts as good and above 1500 ppm as poor, which is where the default thresholds sit.

• Thresholds: Set the Amber threshold and the Red threshold (in ppm, 400 to 5000) from Zigbee2MQTT or Home Assistant. The level turns Amber at or above the amber threshold and Red at or above the red threshold, and drops back only 50 ppm below each threshold so that it does not flicker. The device keeps the thresholds across power cycles and firmware updates; the defaults are 1000 and 1500 ppm.

• Calibration: The sensor keeps itself calibrated with its Automatic self-calibration, which is on by default: it takes the lowest CO2 reading of each week as fresh air (400 ppm), so the device needs fresh air for some time every week, for example a room that is aired or empty overnight. Switch it off where that never happens (a greenhouse, a constantly occupied room, a sealed space) and recalibrate by hand instead: put the powered device into air of known CO2 content, for example outdoors or at a wide open window (about 400 ppm), leave it there for at least 3 minutes, set the Forced recalibration target to that value and switch Forced recalibration on. The device recalibrates the sensor, the switch turns itself off again and the reading moves to the target within the next readings.

• Altitude and Temperature Offset: Set the Altitude of the device above sea level (in metres) for the sensor's pressure compensation; without it the CO2 reading is about 1% low per 100 m of height. The Temperature offset corrects the warmth the device itself adds to the sensor and is 4 °C by default. To check it, run the device for 15 minutes next to a reference thermometer and raise the offset by the difference if the reported temperature is too high, or lower it if too low. Both settings are stored in the sensor itself.

• Fault: A blinking red LED and the level Fault mean the device gets no answer from the sensor module. Check the module's four solder joints and that each of its pins sits on the J1 pin of the same name.

• Identify: Identify from Zigbee2MQTT or Home Assistant chases the three LEDs for the requested time.

The device is a Zigbee router: it relays traffic for other devices and should stay plugged in.