Gases - CO2 SCD4x

CO2, Humidity and Temperature sensor

Plugin details

Type: Gases

Name: CO2 SCD4x

Status ESP32: COLLECTION E CLIMATE

Status ESP8266: COLLECTION E CLIMATE

GitHub: P135_SCD4x.ino

Maintainer: tonhuisman

Used libraries: https://github.com/sparkfun/SparkFun_SCD4x_Arduino_Library

Description

The SCD40 and SCD41 are CO2 sensor units that also provide Humidity and Temperature measurement, support auto-calibration, and have temperature and altitude compensation settings. By using the low-power operation option the measurements will be available slower, but average power usage will be much lower.

The SCD41 measures CO2 values up to 5000 ppm (SCD40 up to 2000 ppm), and also supports single-shot measurement, to enable really low average power consumption as it will enter a power-saving state when not measuring.

Configuration

Device configuration

  • Name: Required by ESPEasy, must be unique among the list of available devices/tasks.

  • Enabled: The device can be disabled or enabled. When not enabled the device should not use any resources.

I2C options

The available settings here depend on the build used. At least the Force Slow I2C speed option is available, but selections for the I2C Multiplexer can also be shown. For details see the I2C Bus page

Note

According to the documentation, the SCD4x sensors support a max. I2C Clock Speed of 100 kHz, but during testing it worked fine at the regular 400 kHz speed, so your milage may vary. If the readings are out of range, or other issues arise, Force Slow I2C speed should be checked! (ESPEasy has a default setting of 100 kHz for I2C Slow device Clock Speed).

Device Settings

  • Sensor model: Select the sensor model used, available options:

Sensor model options

  • SCD40 The default, ‘basic’, sensor model, that can measure CO2 up to 2000 ppm and does not support Single-shot measurements (might show values when configured, but the values are undefined).

  • SCD41 The ‘advanced’ model that supports measuring CO2 up to 5000 ppm and Single-shot measurements.

When this setting is changed, the page is saved and reloaded to show/hide the extra setting to enable Single-shot measurements (SCD41 only).

  • Altitude: Set the altitude above sealevel in meters, where the sensor is placed. The range is 0..2000 meter.

  • Temp offset: Offset for temperature correction. Can be set to compensate any self-heating of the device, by comparing the temperature measurement with another calibrated temperature measured close to the device. The difference can be set here, and can then be stored in the sensor by using the scd4x,storesettings command.

Note

ESPEasy will not update the Altitude or Temperature offset of the sensor if the values are set to 0.

  • Low-power measurement: To use the low power mode of the chip, this option can be checked. Instead of the regular 5 seconds per measurement, it will take up to 30 seconds to obtain a result.

  • Single-shot measurements (SCD41 only): (Not shown when Sensor model SCD40 is selected) This option enables the use of Single-shot measurements, that will be started on every Interval trigger, and provide a result 5 seconds later. By using this option with a long Interval the power consumption can be really low, as it does not continuously perform measurements, but puts the chip in a power-saving mode until the next measurement. This option only works when having a SCD41 sensor connected, when enabled on an SCD40 the values are undefined, even though they may seem somewhat reasonable.

  • Automatic Self Calibration: When enabled, the automatic self-calibration will be activated when the plugin is started. If the calibration is reset via the scd4x,factoryreset command, the calibration is reset to initial factory settings, and calibration data will have to be built up again.

Warning

Automatic Self Calibration is a useful process to ensure long term stability of the sensor, and assumes the sensor is exposed to fresh air of 400 ppm at least once per 7 days.

Data Acquisition

This group of settings are standard available configuration items.

  • Single event with all values: When this setting is enabled, all available values will be sent in a single event <TaskName>#All, with all values in order as arguments to the event.

  • Show derived values: When checked, the Devices overview page, and the /json endpoint (used for updating the Devices overview page) will include any Derived values as defined. See the TaskValueSetDerived and TaskValueSetPresentation commands.

  • Event & Log derived values: When checked, the Derived values will be generated as Events, to be handled in Rules, and sent to logging devices like the Syslog server and/or SD-card logging.

(The derived values options are only available if String variables feature is included in the build.)


  • Send to Controller: Select the Controller(s) to send the Values to, either on a TaskRun command applied to the task, or on an Interval time action.

Send to Controller is only visible when one or more Controllers are configured.

Depending on the controller capabilities, some configuration settings may be shown:

../_images/Task_config_page_Controllers_section.png

All configured Controllers are shown here, including the enabled or disabled state (multiple Controllers can be enabled, only a single MQTT Controller can be enabled at one time!).

For each controller the user can select wether the data should be sent on each Interval (or explicit TaskRun).

For the Domoticz controllers the value index (IDX) has to be configured.

For some controllers, like Home Assistant/openHAB, there are extra options available.

  • Group: This represents the group id to combine all values from multiple tasks into a single grouped-device during MQTT AutoDiscovery. Groups, by design, can span multiple ESPEasy devices, if desired, as long as the Task/Valuename combinations are unique. If a group should only combine Tasks from a single ESPEasy unit, the group id should be unique across multiple ESPEasy units. The group description, default Group <n>, can be adjusted in Home Assistant. If the Group value matches the current Unit nr, the Unit name, %sysname%, is used instead of Group <nr>.

  • Retained: For MQTT Controllers, this setting can be enabled to send the values for the current task with the Retain flag set. The Publish Retain flag in the Controller settings will override this by sending all task values with Retain flag enabled.

  • Send derived: This checkbox determines if any configured Derived values should also be sent to the controller (and included in the AutoDiscovery if that’s available and enabled).

  • Resend MQTT Discovery: When checked, will start a resend of the MQTT Discovery process for this task after a random delay, when Submit is clicked, so any changed settings will be updated in the MQTT broker. This setting is only available if the controller is enabled, the Auto Discovery feature is available and enabled for the controller. This setting is not stored.

Other controllers, like f.e. FHEM HTTP, do not support additional settings besides the checkbox to enable sending the data.


  • Interval By default, Interval will be set to 60 sec. The data will be collected and optionally sent to any configured controllers using this interval.

Values

The plugin provides measurements CO2 in ppm, Humidity in a range of 0..100%, and Temperature in degrees Celcius, with the Temp offset applied.

Per Value is a Stats checkbox available, that when checked, gathers the data and presents recent data in a graph, as described here: Task Value Statistics:

Commands available

Command Syntax

Extra information
scd4x,storesettings
Saves the current Altitude and Temperature offset values in the sensor. After applying this command, the Device configuration for Altitude and Temp offset can be set to 0, so they won’t be reset.
scd4x,factoryreset[,resetcode]
This command resets the sensor to factory default settings.

Warning

This command is by default excluded from the build, as the chance you really want to perform a factory reset is very, very small! Check out the setfrc subcommand. It can be included via a Custom build.

To (somewhat) protect the configuration and carefully built up calibration, this command has to be applied twice, a first time to generate a reset code (output to the log at ERROR level), and a second time with that code included to actually apply the reset. This reset will take about 2.5 seconds, blocking the entire ESPEsy unit, blocking any ESPEasy operation to run during that time! so be careful when applying this command.
After successful completion, this will be written to the log at INFO level, if unsuccessful it will report on ERROR log level.
scd4x,selftest[,selftestcode]
This command will initiate a selftest of the unit, that will take up to 11 seconds to complete, blocking any ESPEasy operation to run during that time!
To protect the regular operation of ESPEasy, this command has to be applied twice, a first time to generate a selftest code (output to the log at ERROR level), and a second time with that code included to actually apply the selftest.
After successful completion, this will be written to the log at INFO level, if unsuccessful it will report on ERROR log level.
scd4x,setfrc,<co2level>
co2level range: SCD40: 400..2000 ppm, SCD41: 400..5000 ppm.
Force-reset the calibration to a specific CO2 level. This will take up to 1 second to execute, blocking any ESPEasy operation to run during that time.
Before using this command, the sensor should have been running for at least 3 minutes, to stabilize the measurements.
After successful execution, the applied correction will be logged at INFO level.

Get Config Values

Get Config Values retrieves values or settings from the sensor or plugin, and can be used in Rules, Display plugins, Formula’s etc. The square brackets are part of the variable. Replace <taskname> by the Name of the task.

Config value

Information
[<taskname>#GetAltitude]
Returns the current Altitude setting of the sensor in meters above sealevel.
[<taskname>#GetTempOffset]
Returns the current Temperature offset setting of the sensor in degrees Celcius. Includes by default 2 decimal positions, that can be adjusted using Rules: Formatting referred values.
[<taskname>#GetDataReady]
Returns 1 if new data is available at the sensor, and 0 if not.
[<taskname>#GetSelfCalibration]
Returns 1 if Automatic Self Calibration is enabled at the sensor, and 0 if not.
[<taskname>#SerialNumber]
Returns the electronic serial number of the sensor.

Change log

Changed in version 2.0: …

added 2022-08-03 Initial release version.