Sensirion · LeonieFierz · Jan 30, 2025 · Jan 29, 2025 · Jan 30, 2025 · Jan 30, 2025
diff --git a/.github/workflows/raspberry_quality_check.yml b/.github/workflows/raspberry_quality_check.yml
@@ -1,16 +1,10 @@
 name: Quality check
 
 on:
-  pull_request:
-    branches:
-      - master
   push:
+  pull_request:
     branches:
       - master
-
 jobs:
   driver-quality:
     uses: sensirion/.github/.github/workflows/driver.c.check.yml@main
-    with:
-      examples: '["."]'
-      run-environment: "ubuntu-20.04"
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,3 @@
-/scd4x_i2c_example_usage
-.idea
+/example-usage/scd4x_i2c_example_usage
+/tests/scd4x_test_hw_i2c
+/tests/scd4x_test_sw_i2c
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,42 +1,22 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
+# CHANGELOG
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
-
-### Fixed
-- Fixed the RH/T conversion constant
-
-## [0.2.2] - 2021-04-30
-
-### Changed
-
-* Increase timing for single shot from 1350ms to 5000ms
-* Increase timing for self test from 5500ms to 10000ms
+## [Unreleased] 
 
-
-## [0.2.1] - 2021-03-01
-
-### Fixed
-- Changelog links fixed.
-
-## [0.2.0] - 2021-03-01
+## [1.0.0] - 2025-1-30
 
 ### Added
-- Convenience interfaces taking care of unit conversion to and from ticks.
 
-### Fixed
-- wake-up interface handles missing ACK from sensor on wake up.
+- All commands according to data sheet
+## [0.1.0] - 2021-2-1
 
+### Added
 
-## [0.1.0] - 2021-02-04
-
-Initial release
+- Initial version
+- Check latest 0.x.x version for changelog prior to version 1.0.0
 
-[0.2.2]: https://github.com/Sensirion/raspberry-pi-i2c-scd4x/compare/0.2.1...0.2.2
-[0.2.1]: https://github.com/Sensirion/raspberry-pi-i2c-scd4x/compare/0.2.0...0.2.1
-[0.2.0]: https://github.com/Sensirion/raspberry-pi-i2c-scd4x/compare/0.1.0...0.2.0
-[0.1.0]: https://github.com/Sensirion/raspberry-pi-i2c-scd4x/releases/tag/0.1.0
+[Unreleased]: https://github.com/Sensirion/raspberry-pi-i2c-scd4x/compare/1.0.0...HEAD
+[1.0.0]: https://github.com/Sensirion/raspberry-pi-i2c-scd4x/compare/0.1.0...1.0.0
+[0.1.0]: https://github.com/Sensirion/raspberry-pi-i2c-scd4x/releases/tag/0.1.0
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2021, Sensirion AG
+Copyright (c) 2025, Sensirion AG
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

diff --git a/Makefile b/Makefile
diff --git a/README.md b/README.md
@@ -1,73 +1,94 @@
-# Sensirion Raspberry Pi I2C SCD4x Driver
+# Sensirion Raspberry Pi I²C SCD4X Driver
 
-This document explains how to set up the SCD4x sensor to run on a Raspberry Pi
-using the provided code.
+The repository provides a driver for setting up a sensor of the SCD4X family to run on a Raspberry Pi over I²C.
 
-[<center><img src="images/SCD41_Development_Board.png" width="300px"></center>](https://sensirion.com/my-scd-ek)
+<img src="images/SCD41.png" width="300px">
 
-Click [here](https://sensirion.com/my-scd-ek) to learn more about the SCD4x
-sensor and the SCD41 Evaluation Kit Board.
+Click [here](https://sensirion.com/products/catalog/SEK-SCD41) to learn more about the Sensirion SCD4X sensor family.
 
-## Setup Guide
 
-### Connecting the Sensor
+Not all sensors of this driver family support all measurements.
+In case a measurement is not supported by all sensors, the products that
+support it are listed in the API description.
 
-Your sensor has the four different connectors: VCC, GND, SDA, SCL. Use
-the following pins to connect your SCD4x:
 
- *SCD4x*  |    *Raspberry Pi*    | *Jumper Wire*
- :------: | :------------------: | :-----------:
-   VCC    |        Pin 1         |      Red
-   GND    |        Pin 6         |     Black
-   SDA    |        Pin 3         |     Green
-   SCL    |        Pin 5         |     Yellow
 
-<center><img src="images/GPIO-Pinout-Diagram.png" width="900px"></center>
+## Supported sensor types
 
-### Raspberry Pi
+| Sensor name   | I²C Addresses  |
+| ------------- | -------------- |
+|[SCD40](https://sensirion.com/products/catalog/SCD40)| **0x62**|
+|[SCD41](https://sensirion.com/products/catalog/SCD41)| **0x62**|
+
+The following instructions and examples use a *SCD41*.
+
+
+
+## Connect the sensor
+
+Your sensor has 4 different connectors: SCL, GND, VDD, SDA.
+Use the following pins to connect your SCD4X:
+
+| *SCD4X* | *Cable Color*  |   *Raspberry Pi*   |
+| :----------------: | -------------- | ------------------ |
+| SCL | yellow | Pin 5
+| GND | black | Pin 6
+| VDD | red | Pin 1
+| SDA | green | Pin 3
+
+
+<img src="images/raspi-i2c-pinout-3.3V.png" width="400px">
+
+
+### Detailed sensor pinout
+
+<img src="images/SCD41_pinout.png" width="300px">
+
+| *Pin* | *Cable Color* | *Name* | *Description*  | *Comments* |
+|-------|---------------|:------:|----------------|------------|
+| 1 | yellow | SCL | I2C: Serial clock input |
+| 2 | black | GND | Ground |
+| 3 | red | VDD | Supply Voltage | 2.4V to 5.5V
+| 4 | green | SDA | I2C: Serial data input / output |
+
+
+
+## Quick start example
 
 - [Install the Raspberry Pi OS on to your Raspberry Pi](https://projects.raspberrypi.org/en/projects/raspberry-pi-setting-up)
-- [Enable the I2C interface in the raspi-config](https://www.raspberrypi.org/documentation/configuration/raspi-config.md)
-- Download the driver from the [Sensirion GitHub Page](https://github.com/Sensirion/raspberry-pi-i2c-scd4x/tags)
-  and extract the `.zip` on your Raspberry Pi
+- [Enable the I²C interface in the raspi-config](https://www.raspberrypi.org/documentation/configuration/raspi-config.md)
+- Download the SCD4X driver from [Github](https://github.com/Sensirion/raspberry-pi-i2c-scd4x) and extract the `.zip` on your Raspberry Pi
+- Connect the SCD4X sensor as explained in the [section above](#connect-the-sensor)
+- The provided example is working with a SCD41, I²C address 0x62.
+  In order to use the code with another product or I²C address you need to change it in the call scd4x_init(ADDRESS) in
+  `scd4x_i2c_example_usage.c`. The list of supported I²C-addresses is found in the header
+  `scd4x_i2c.h`.
+
 - Compile the driver
-    1. Open a [terminal](https://www.raspberrypi.org/documentation/usage/terminal/)
+    1. Open a [terminal](https://projects.raspberrypi.org/en/projects/raspberry-pi-using/8)
     2. Navigate to the driver directory. E.g. `cd ~/raspberry-pi-i2c-scd4x`
-    3. Run the `make` command to compile the driver
+    3. Navigate to the subdirectory example-usage.
+    4. Run the `make` command to compile the driver
 
        Output:
        ```
        rm -f scd4x_i2c_example_usage
        cc -Os -Wall -fstrict-aliasing -Wstrict-aliasing=1 -Wsign-conversion -fPIC -I. -o scd4x_i2c_example_usage  scd4x_i2c.h scd4x_i2c.c sensirion_i2c_hal.h sensirion_i2c.h sensirion_i2c.c \
-       	sensirion_i2c_hal.c sensirion_config.h sensirion_common.h sensirion_common.c scd4x_i2c_example_usage.c
+           sensirion_i2c_hal.c sensirion_config.h sensirion_common.h sensirion_common.c scd4x_i2c_example_usage.c
        ```
 - Test your connected sensor
     - Run `./scd4x_i2c_example_usage` in the same directory you used to
-      compile the driver.
-
-      Output:
-      ```
-      serial: 0xbff79f073b51
-      CO2: 799
-      Temperature: 20.92
-      Humidity: 35.95
-      CO2: 900
-      Temperature: 20.92
-      Humidity: 36.47
-      CO2: 926
-      Temperature: 20.81
-      Humidity: 36.85
-      ...
-      ```
-
-Troubleshooting
----------------
+      compile the driver. You should see the measurement values in the console.
+
+## Troubleshooting
 
 ### Building driver failed
 
 If the execution of `make` in the compilation step 3 fails with something like
 
-> -bash: make: command not found
+```bash
+ make: command not found
+```
 
 your RaspberryPi likely does not have the build tools installed. Proceed as follows:
 
@@ -77,30 +98,24 @@ $ sudo apt-get upgrade
 $ sudo apt-get install build-essential
 ```
 
-### Initialization failed
-
-If you run `./scd4x_i2c_example_usage` but do not get sensor readings but
-something like this instead
 
-```
-Error executing scd4x_get_serial_number(): -1
-Error executing scd4x_start_periodic_measurement(): -1
-Error executing scd4x_read_measurement(): -1
-```
+### Initialization failed
 
+If you run `./scd4x_i2c_example_usage` but do not get sensor readings
 then go through the below troubleshooting steps.
 
+
 -   Ensure that you connected the sensor correctly: All cables are fully
     plugged in and connected to the correct pin.
--   Ensure that I2C is enabled on the Raspberry Pi. For this redo the steps on
-    "Enable the I2C interface in the raspi-config" in the guide above.
--   If running the same command as root with `sudo ./scd4x_i2c_example_usage`
-    works then your user is likely missing access permissions for the I2C 
-    interface. See the next chapter how to solve this.
-    
-### Missing I2C permissions
-
-If your user is missing access to the I2C interface you should first verfiy
+-   Ensure that I²C is enabled on the Raspberry Pi. For this redo the steps on
+    "Enable the I²C interface in the raspi-config" in the guide above.
+-   Ensure that your user account has read and write access to the I²C device.
+    If it only works with user root (`sudo ./scd4x_i2c_example_usage`), it's
+    typically due to wrong permission settings. See the next chapter how to solve this.
+
+### Missing I²C permissions
+
+If your user is missing access to the I²C interface you should first verfiy
 the user belongs to the `i2c` group.
 
 ```
@@ -118,17 +133,40 @@ $ sudo reboot
 ```
 
 If that did not help you can make globally accessible hardware interfaces
-with a udev rule. Only do this if everything else failed and you are 
+with a udev rule. Only do this if everything else failed and you are
 reasoably confident you are the only one having access to your Pi.
 
-Go into the `/etc/udev/rules.d` folder and add a new file named 
+Go into the `/etc/udev/rules.d` folder and add a new file named
 `local.rules`.
 ```
 $ cd /etc/udev/rules.d/
 $ sudo touch local.rules
 ```
-Then add a single line `ACTION=="add", KERNEL=="i2c-[0-1]*", MODE="0666"` 
+Then add a single line `ACTION=="add", KERNEL=="i2c-[0-1]*", MODE="0666"`
 to the file with your favorite editor.
 ```
 $ sudo vi local.rules
 ```
+
+## Contributing
+
+**Contributions are welcome!**
+
+This Sensirion library uses
+[`clang-format`](https://releases.llvm.org/download.html) to standardize the
+formatting of all our `.c` and `.h` files. Make sure your contributions are
+formatted accordingly:
+
+The `-i` flag will apply the format changes to the files listed.
+
+```bash
+clang-format -i *.c *.h
+```
+
+Note that differences from this formatting will result in a failed build until
+they are fixed.
+
+
+## License
+
+See [LICENSE](LICENSE).
diff --git a/example-scd41-single-shot/Makefile b/example-scd41-single-shot/Makefile
@@ -0,0 +1,23 @@
+src_dir = ..
+common_sources = ${src_dir}/sensirion_config.h ${src_dir}/sensirion_common.h ${src_dir}/sensirion_common.c
+i2c_sources = ${src_dir}/sensirion_i2c_hal.h ${src_dir}/sensirion_i2c.h ${src_dir}/sensirion_i2c.c
+driver_sources = ${src_dir}/scd4x_i2c.h ${src_dir}/scd4x_i2c.c
+
+i2c_implementation ?= ${src_dir}/sensirion_i2c_hal.c
+
+CFLAGS = -Os -Wall -fstrict-aliasing -Wstrict-aliasing=1 -Wsign-conversion -fPIC -I${src_dir} -I.
+
+ifdef CI
+    CFLAGS += -Werror
+endif
+
+.PHONY: all clean
+
+all: scd4x_i2c_example_scd41_single_shot
+
+scd4x_i2c_example_scd41_single_shot: clean
+	$(CC) $(CFLAGS) -o $@  ${driver_sources} ${i2c_sources} \
+		${i2c_implementation} ${common_sources} scd4x_i2c_example_scd41_single_shot.c
+
+clean:
+	$(RM) scd4x_i2c_example_scd41_single_shot