feat: Add SCD4X #7198

oscgonfer · 2025-07-02T10:06:07Z

This PR adds support for the SCD4X CO2 sensors by sensirion.
It builds upon on the great work by @Coloradohusky, @hafu and @fifieldt in #4601 and https://github.com/hafu/meshtastic-firmware/tree/add-scd30 (although it doesn't add SCD30 support).

This PR tries to sync that work with the current state master branch, and it's rebased on top of #7190, which is an attempt to decouple AirQualityTelemetry from PMSA0003I sensor (I have just ordered one sensor to test). I also started using the new Sensirion library for this sensor, which has a new release (and a very annoying change in the library name import).

This also goes along with meshtastic/protobufs#719 to support having real temperature and the sensor temperature separately. Testing it, you can see some differences between two sensors that are right next to each other (SHT31 and the one inside the SCD4X).

decoded {
  portnum: TELEMETRY_APP
  payload: "time: 1751450604 air_quality_metrics {   co2: 1602   co2_temperature: 28.4126797   co2_humidity: 55.2819099 }"
}

decoded {
  portnum: TELEMETRY_APP
  payload: "time: 1751450589 environment_metrics {   temperature: 31.69   relative_humidity: 50.19 }"
}

There are some comments that I point in the code directly below. I also tried to make it work with the screen, but I don't think my system allows for testing it ATM.

🤝 Attestations

I have tested that my proposed changes behave as described.
I have tested that my proposed changes do not cause any obvious regressions on the following devices:
- Seeed ESP32-S3 Xiao board

src/modules/Telemetry/Sensor/SCD4XSensor.cpp

oscgonfer · 2025-07-02T10:12:12Z

An additional comment: these type of sensors generally require a "control" interface to enable or disable features. This is mapped here - and could be a good outcome of the hackathon.

thebentern · 2025-07-02T11:09:18Z

@oscgonfer protobufs are merged and generated upstream now

oscgonfer · 2025-07-02T14:00:59Z

rebased onto #7202 - just to keep in mind that the sensirion library needs to be 1.0.0 @thebentern

fifieldt · 2025-07-03T00:23:03Z

sensirion 1.1.0 was released - updated upstream.

oscgonfer · 2025-07-03T07:42:19Z

sensirion 1.1.0 was released - updated upstream.

Merged

hafu · 2025-07-05T16:07:00Z

Thanks for your effort! I can confirm it works with:

Heltec v3
RAK11310
RAK4631 (needs some fixes in Move PMSA003I to separate class and update AQ telemetry #7190

oscgonfer · 2025-07-06T06:37:09Z

Thanks for your effort! I can confirm it works with:

* Heltec v3

* RAK11310

* RAK4631 (needs [some fixes](https://github.com/meshtastic/firmware/pull/7190#pullrequestreview-2990183787) in

Thank you @hafu ! I fixed and rebased #7190

CLAassistant · 2025-07-22T18:09:49Z

All committers have signed the CLA.

CLAassistant · 2025-07-22T18:09:49Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ oscgonfer
❌ peterzqx
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

Co-authored-by: Hannes Fuchs <hannes.fuchs+git@0xef.de>

* Adds VOC measurements and state * Still not working on VOC Index persistence * Should it stay in continuous mode?

* Adds initial timer for SEN55 to not sleep if VOCstate is not stable (1h) * Adds conditions for stability and sensor state

* Adds a new RHT/Gas only mode, with 3600s stabilization time * Fixes the VOCState buffer mismatch * Fixes SEN50/54/55 model mistake

paulwalko · 2026-01-16T18:34:16Z

Not stale, waiting for merging #7190

I saw #7190 was merged a few days ago (I really appreciate all the hard work on that!) and was wondering if there was anything else we're waiting on for this PR now? Once it gets merged I have a bunch of nodes with co2 sensors I'd be happy to test with.

thebentern · 2026-01-16T18:56:33Z

Not stale, waiting for merging #7190

I saw #7190 was merged a few days ago (I really appreciate all the hard work on that!) and was wondering if there was anything else we're waiting on for this PR now? Once it gets merged I have a bunch of nodes with co2 sensors I'd be happy to test with.

Gotta work through a number of merge conflicts, but otherwise optimistic on moving this one forward :-)

oscgonfer · 2026-01-16T19:22:32Z

(To avoid duplicating work) I'm aiming to work on this during the next couple of days as well @thebentern

I'm doing this in parallel to the other SEN5X series, there some conflicts on sleep mode that I have almost sorted out.

oscgonfer · 2026-01-17T19:33:06Z

Hi folks, this PR and #7245 will need meshtastic/protobufs#750

* Improve reClockI2C conditions for different variants * Add sleep, wakeUp, pendingForReady, hasSleep functions to PM sensors to save battery * Add SEN5X

* Fixes difference between idle and sleep * In LowPower, sleep is disabled * Requires testing for I2C clock comms for commands

oscgonfer · 2026-01-18T17:46:58Z

@paulwalko @thebentern I added changes and tested locally. It all works, but requires meshtastic/protobufs#750

⚠️ Warning: ⚠️ This is now rebased onto #7245

There's a couple of pending to-dos, specially on the admin commands part and the I2C clock adaptation. I'd appreciate some help with admin commands checks, if possible, or some guidance on how to set it up to test them in a fast way.

paulwalko · 2026-01-19T19:17:54Z

Is the reclock logic needed for nrf52 architectures? When building I got the "scd41 can't be used at this clock speed, with a screen" warning, which was fixed with the following changes to exclude non esp32 architectures:

 #ifdef SCD4X_I2C_CLOCK_SPEED
+#ifdef ARCH_ESP32
 #ifdef CAN_RECLOCK_I2C
     uint32_t currentClock = reClockI2C(SCD4X_I2C_CLOCK_SPEED, _bus, false);
     if (currentClock != SCD4X_I2C_CLOCK_SPEED){
@@ -33,6 +34,7 @@ bool SCD4XSensor::initDevice(TwoWire *bus, ScanI2C::FoundDevice *dev)
     LOG_WARN("%s can't be used at this clock speed, with a screen", sensorName);
     return false;
 #endif /* CAN_RECLOCK_I2C */
+#endif /* ARCH_ESP32 */
 #endif /* SCD4X_I2C_CLOCK_SPEED */

All of my nodes with SCD41 sensors are nrf52 based.

oscgonfer · 2026-01-19T21:53:07Z

Is the reclock logic needed for nrf52 architectures? When building I got the "scd41 can't be used at this clock speed, with a screen" warning, which was fixed with the following changes to exclude non esp32 architectures:
 #ifdef SCD4X_I2C_CLOCK_SPEED
+#ifdef ARCH_ESP32
 #ifdef CAN_RECLOCK_I2C
     uint32_t currentClock = reClockI2C(SCD4X_I2C_CLOCK_SPEED, _bus, false);
     if (currentClock != SCD4X_I2C_CLOCK_SPEED){
@@ -33,6 +34,7 @@ bool SCD4XSensor::initDevice(TwoWire *bus, ScanI2C::FoundDevice *dev)
     LOG_WARN("%s can't be used at this clock speed, with a screen", sensorName);
     return false;
 #endif /* CAN_RECLOCK_I2C */
+#endif /* ARCH_ESP32 */
 #endif /* SCD4X_I2C_CLOCK_SPEED */
All of my nodes with SCD41 sensors are nrf52 based.

Hi, maybe the logic is not right in reClockI2C.cpp now.
The issue is the following, only ESP32 core can get and set the I2C clock speed. If there is a screen plugged in, at least in ESP32, the I2C clock speed switches from 100kHz to 700kHz on boot, which then makes us have to change the I2C speed everytime we interact with a sensor.

In particular, the SCD4X needs a I2C clock speed of max 400kHz, which is not compatible with the screen. So... we need a way to know whether or not a screen is present for those cores that can't get the Clock speed, so that we can set up the sensor speed. I thought that the HAS_SCREEN flag did it, but I guess I am wrong (or the logic in reClockI2C.cpp is not properly done... If we know that the speed is always 700kHz for all screens, then it's an easy fix, but we need to know that the screen is present.

Do your NRFs have screens?

paulwalko · 2026-01-19T22:09:49Z

Thanks for the explanation. I should've mentioned, my devices do not have a screen. I did see that the SCD4x has a max of 400 Mhz, but didn't realize the screen switches up to 700 Mhz which explains a lot. My nodes are the nrf52 diy variant, but for the vast majority of other nodes with known configurations I imagine the logic should work.

One more issue I encountered, the serialization of the air_quality_metrics in src/serialization/MeshSerializer.cpp needs to be updated to support the new co2 fields:

diff --git a/src/serialization/MeshPacketSerializer.cpp b/src/serialization/MeshPacketSerializer.cpp
index 92e700368..f0425580e 100644
--- a/src/serialization/MeshPacketSerializer.cpp
+++ b/src/serialization/MeshPacketSerializer.cpp
@@ -161,6 +161,15 @@ std::string MeshPacketSerializer::JsonSerialize(const meshtastic_MeshPacket *mp,
                     //     msgPayload["pm100_e"] =
                     //         new JSONValue((unsigned int)decoded->variant.air_quality_metrics.pm100_environmental);
                     // }
+                    if (decoded->variant.air_quality_metrics.has_co2) {
+                        msgPayload["co2"] = new JSONValue((unsigned int)decoded->variant.air_quality_metrics.co2);
+                    }
+                    if (decoded->variant.air_quality_metrics.has_co2_temperature) {
+                        msgPayload["co2_temperature"] = new JSONValue(decoded->variant.air_quality_metrics.co2_temperature);
+                    }
+                    if (decoded->variant.air_quality_metrics.has_co2_humidity) {
+                        msgPayload["co2_humidity"] = new JSONValue(decoded->variant.air_quality_metrics.co2_humidity);
+                    }

oscgonfer · 2026-01-19T22:16:09Z

Thanks for the explanation. I should've mentioned, my devices do not have a screen. I did see that the SCD4x has a max of 400 Mhz, but didn't realize the screen switches up to 700 Mhz which explains a lot. My nodes are the nrf52 diy variant, but for the vast majority of other nodes with known configurations I imagine the logic should work.

I think that in your particular case, compiling with HAS_SCREEN 0 would do. However, I think I'd be better to have a way to check for the presence of the screen at runtime. Maybe @thebentern can give us a hand here?

One more issue I encountered, the serialization of the air_quality_metrics in src/serialization/MeshSerializer.cpp needs to be updated to support the new co2 fields:

diff --git a/src/serialization/MeshPacketSerializer.cpp b/src/serialization/MeshPacketSerializer.cpp
index 92e700368..f0425580e 100644
--- a/src/serialization/MeshPacketSerializer.cpp
+++ b/src/serialization/MeshPacketSerializer.cpp
@@ -161,6 +161,15 @@ std::string MeshPacketSerializer::JsonSerialize(const meshtastic_MeshPacket *mp,
                     //     msgPayload["pm100_e"] =
                     //         new JSONValue((unsigned int)decoded->variant.air_quality_metrics.pm100_environmental);
                     // }
+                    if (decoded->variant.air_quality_metrics.has_co2) {
+                        msgPayload["co2"] = new JSONValue((unsigned int)decoded->variant.air_quality_metrics.co2);
+                    }
+                    if (decoded->variant.air_quality_metrics.has_co2_temperature) {
+                        msgPayload["co2_temperature"] = new JSONValue(decoded->variant.air_quality_metrics.co2_temperature);
+                    }
+                    if (decoded->variant.air_quality_metrics.has_co2_humidity) {
+                        msgPayload["co2_humidity"] = new JSONValue(decoded->variant.air_quality_metrics.co2_humidity);
+                    }

I'll fix that one! Totally missed that! Thank you!

oscgonfer marked this pull request as ready for review July 2, 2025 10:08

oscgonfer commented Jul 2, 2025

View reviewed changes

src/modules/Telemetry/Sensor/SCD4XSensor.cpp Outdated Show resolved Hide resolved

oscgonfer changed the title ~~Add SCD4X~~ feat: Add SCD4X Jul 2, 2025

oscgonfer force-pushed the feat/add-scd4x branch 2 times, most recently from 247768e to 84865cd Compare July 2, 2025 12:46

This was referenced Jul 2, 2025

Sensirion SCD4X fablabbcn/smartcitizen-meshtastic#10

Open

Sensirion SEN5X/6X fablabbcn/smartcitizen-meshtastic#6

Open

oscgonfer force-pushed the feat/add-scd4x branch from e7a214d to 6237b2e Compare July 6, 2025 06:35

caveman99 force-pushed the feat/add-scd4x branch from 6237b2e to 3a1a07a Compare July 14, 2025 13:54

vidplace7 added the enhancement New feature or request label Jul 18, 2025

oscgonfer force-pushed the feat/add-scd4x branch from 443a573 to ec57c62 Compare July 22, 2025 18:09

oscgonfer and others added 10 commits July 25, 2025 12:31

Move PMSA003I to separate class and update AQ telemetry

7f042a0

AirQualityTelemetry module not depend on PM sensor presence

835adb2

Remove commented line

3b470b7

Fixes on PMS class

2f68458

Add missing warmup period to wakeUp function

e4903eb

Fixes on compilation for different variants

9111f88

Add functions to check for I2C bus speed and set it

40af7b8

Add ScreenFonts.h

ff8691d

Co-authored-by: Hannes Fuchs <hannes.fuchs+git@0xef.de>

PMSA003I 1st round test

0dda175

Fix I2C scan speed

14eaa3e

oscgonfer added 6 commits January 15, 2026 12:04

Add placeholder for admin message

456ee95

Add VOC measurements and persistence (WIP)

f722ce0

* Adds VOC measurements and state * Still not working on VOC Index persistence * Should it stay in continuous mode?

Add one-shot mode config flag to SEN5X

8194be0

Add nan checks on sensor data from SEN5X

53f43dc

Working implementation on VOCState

972aec1

* Adds initial timer for SEN55 to not sleep if VOCstate is not stable (1h) * Adds conditions for stability and sensor state

Fixes on VOC state and mode swtiching

9ac258d

* Adds a new RHT/Gas only mode, with 3600s stabilization time * Fixes the VOCState buffer mismatch * Fixes SEN50/54/55 model mistake

oscgonfer added 10 commits January 17, 2026 20:40

Adapt SEN5X to new sensor list structure. Improve reclock.

31da50a

* Improve reClockI2C conditions for different variants * Add sleep, wakeUp, pendingForReady, hasSleep functions to PM sensors to save battery * Add SEN5X

Merge branch 'master' into feat/add-sen5x

4fd2ed7

Fix merge errors

457eac3

Merge branch 'feat/add-sen5x' into feat/add-scd4x

0d455e1

Small reordering in PMS class for consistency

d547c4c

If one sensor fails, AQ telemetry still reports data

2f95db2

Small formatting fix

f6cd9db

Add SEN5X to AQI in ScanI2C

b4a2560

SCD4X now part of AQ module with template list

52ca090

* Fixes difference between idle and sleep * In LowPower, sleep is disabled * Requires testing for I2C clock comms for commands

Remove unnecessary import

c6c97f1

oscgonfer force-pushed the feat/add-scd4x branch from 89168b8 to c6c97f1 Compare January 18, 2026 17:45

oscgonfer and others added 2 commits January 20, 2026 09:47

Add co2 to serialized AQ metrics

26a05c3

Merge branch 'master' into feat/add-scd4x

7b995e1

oscgonfer mentioned this pull request Jan 20, 2026

feat/add sfa30 #9372

Open

paulwalko mentioned this pull request Jan 24, 2026

Support setting moduleConfig.telemetry.air_quality_enabled meshtastic/python#892

Closed

Uh oh!

feat: Add SCD4X #7198

Are you sure you want to change the base?

feat: Add SCD4X #7198

Uh oh!

Conversation

oscgonfer commented Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤝 Attestations

Uh oh!

Uh oh!

oscgonfer commented Jul 2, 2025

Uh oh!

thebentern commented Jul 2, 2025

Uh oh!

oscgonfer commented Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fifieldt commented Jul 3, 2025

Uh oh!

oscgonfer commented Jul 3, 2025

Uh oh!

hafu commented Jul 5, 2025

Uh oh!

oscgonfer commented Jul 6, 2025

Uh oh!

CLAassistant commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CLAassistant commented Jul 22, 2025

Uh oh!

paulwalko commented Jan 16, 2026

Uh oh!

thebentern commented Jan 16, 2026

Uh oh!

oscgonfer commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oscgonfer commented Jan 17, 2026

Uh oh!

oscgonfer commented Jan 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

paulwalko commented Jan 19, 2026

Uh oh!

oscgonfer commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

paulwalko commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oscgonfer commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

oscgonfer commented Jul 2, 2025 •

edited

Loading

oscgonfer commented Jul 2, 2025 •

edited

Loading

CLAassistant commented Jul 22, 2025 •

edited

Loading

oscgonfer commented Jan 16, 2026 •

edited

Loading

oscgonfer commented Jan 18, 2026 •

edited

Loading

oscgonfer commented Jan 19, 2026 •

edited

Loading

paulwalko commented Jan 19, 2026 •

edited

Loading

oscgonfer commented Jan 19, 2026 •

edited

Loading