Merge pull request #12 from Sensirion/scd4x_2.0_20250129_1204

Generate SCD4x driver from SCD4x model version 2.0

.github/workflows/embedded_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"

.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

CHANGELOG.md

@@ -1,32 +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] 
 
-## [0.2.1] - 2021-04-30
-
-### Changed
-
-* Increase timing for single shot from 1350ms to 5000ms
-* Increase timing for self test from 5500ms to 10000ms
-
-
-## [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
 
-## [0.1.0] - 2021-01-28
+### Added
 
-Initial release
+- Initial version
+- Check latest 0.x.x version for changelog prior to version 1.0.0
 
-[0.2.1]: https://github.com/Sensirion/embedded-i2c-scd4x/compare/0.2.0...0.2.1
-[0.2.0]: https://github.com/Sensirion/embedded-i2c-scd4x/compare/0.1.0...0.2.0
-[0.1.0]: https://github.com/Sensirion/embedded-i2c-scd4x/releases/tag/0.1.0
+[Unreleased]: https://github.com/Sensirion/embedded-i2c-scd4x/compare/1.0.0...HEAD
+[1.0.0]: https://github.com/Sensirion/embedded-i2c-scd4x/compare/0.1.0...1.0.0
+[0.1.0]: https://github.com/Sensirion/embedded-i2c-scd4x/releases/tag/0.1.0

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

README.md

@@ -1,25 +1,61 @@
-# Sensirion Embedded I2C SCD4x Driver
+# Sensirion I2C SCD4X embedded Library
 
-This is a generic embedded driver for the [Sensirion SCD4x Carbon Dioxide Sensor](https://www.sensirion.com/scd4x/).
-It enables developers to communicate with the SCD4x sensor on different hardware platforms by only adapting the I2C communication related source files.
+This document explains how to set up a sensor of the SCD4X family to run on an embedded device using the I²C interface.
 
-[<center><img src="images/SCD4x.png" width="300px"></center>](https://sensirion.com/my-scd-ek)
+<img src="images/SCD41.png" width="300px">
 
-# Getting started
+Click [here](https://sensirion.com/products/catalog/SEK-SCD41) to learn more about the Sensirion SCD4X sensor family.
 
-## Implement the I2C Interface
 
-So we need to adjust two files according to your platform.
+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.
+
+
+
+## Supported sensor types
+
+| 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*.
+
+
+
+## Setup Guide
+
+### Connect the Sensor
+
+Your sensor has 4 pins that need to be connected to your board: SCL, GND, VDD, SDA.
+Use the following description to connect your SCD4X:
+
+<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 |
+
+
+
+The recommended voltage is 3.3V.
+
+### Configure the code
+
+In order to use the provided code we need to adjust two files according to your platform.
 
 ### Edit `sensirion_i2c_hal.c`
 
-This file contains the implementation of the sensor communication
-(how to send requests to the sensor). Therefore, how this is done depends on your
-hardware platform. Therefore we can only provide function stubs in which you
-can implement the logic yourself. 
-There are sample implementations available for some platforms: [`sample-implementations`](sample-implementations).
-If you are using a Linux based platform like Raspberry Pi
-you can just replace the unimplemented HAL template with the provided
+This file contains the implementation of the sensor communication, which
+depends on your hardware platform. We provide function stubs for your
+hardware's own implementation.
+Sample implementations are available for some platforms:
+[`sample-implementations`](sample-implementations). For Linux based platforms
+like Raspberry Pi you can just replace the unimplemented HAL template with the
 implementation in `sample-implementations/linux_user_space/`:
 
 ```
@@ -28,17 +64,16 @@ cp sample-implementations/linux_user_space/sensirion_i2c_hal.c ./
 
 ### Edit `sensirion_config.h`
 
-If you are on a Linux based platform you can skip this part since
-everything is already correctly setup for you.
+Skip this part for Linux based platforms since everything is already setup for
+this case.
 
-Otherwise you need to check if the libraries `<stdint.h>` and
-`<stdlib.h>` are provided by your toolchain, compiler or system.
-If you have no idea on how to do that you can skip this
-step for now and come back when you get errors related to these names when 
-compiling the driver.
-The features we use out of those libraries are standard integer sizes
-from `<stdint.h>` and `NULL` from `<stdlib.h>`. If they are not available
-you need to specify the following integer types yourself:
+Otherwise you need to check if the libraries `<stdint.h>` and `<stdlib.h>` are
+provided by your toolchain, compiler or system. If you have no idea on how to
+do that you can skip this step for now and come back when you get errors
+related to these names when compiling the driver.
+The features we use from those libraries are type definitions for integer sizes
+from `<stdint.h>` and `NULL` from `<stdlib.h>`. If they are not available you
+need to specify the following integer types yourself:
 
 * `int64_t` = signed 64bit integer
 * `uint64_t` = unsigned 64bit integer
@@ -49,56 +84,101 @@ you need to specify the following integer types yourself:
 * `int8_t` = signed 8bit integer
 * `uint8_t` = unsigned 8bit integer
 
-In addition to that you will need to specify `NULL`.
-For both we have a detailed template where you just need to fill in
-your system specific values.
+In addition to that you will need to specify `NULL`. For both we have a
+detailed template where you just need to fill in your system specific values.
+
+## Choose the i2c address to use with your product
+
+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`.
+
 
 Now we are ready to compile and run the example usage for your sensor.
 
 ## Compile and Run
 
-Take the `.c` and `.h` files directly in this folder pass them to your 
-favorite C compiler and run the resulting binary.
-This step may vary, depending on your platform. Here we demonstrate the 
-procedure for Linux based platforms:
+Pass the source `.c` and header `.h` files in this folder into your C compiler
+and run the resulting binary. This step may vary, depending on your platform.
+Here we demonstrate the procedure for Linux based platforms:
 
 1. Open up a terminal.
 2. Navigate to the directory where this README is located.
-3. Run `make` (this compiles all the code here to one binary).
-4. Run `./scd4x_i2c_example_usage` (This will run your newly compiled binary).
-5. Now you should see the first measurement values appear in your terminal.
-   As a next step you can adjust the example usage file or write your own
-   main function to use the sensor.
+3. Navigate to the subdirectory example-usage.
+4. Run `make` (this compiles the example code into one executable binary).
+5. Run the compiled executable with `./scd4x_i2c_example_usage`
+6. Now you should see the first measurement values appear in your terminal. As
+   a next step you can adjust the example usage file or write your own main
+   function to use the sensor.
+
+## Compile and Run Tests
+
+The testframekwork used is CppUTest. Pass the source `.cpp`, `.c`  and header `.h`
+files from the tests and top level folder into your CPP compiler and run the
+resulting binary. This step may vary, depending on your platform.
+Here we demonstrate the procedure for Linux based platforms:
+
+1. Open up a terminal.
+2. Install CppUTest framework `apt install cpputest`.
+3. Navigate to the directory `tests`.
+4. Run `make` (this compiles the test code into one executable binary).
+5. Run the compiled executable with `./scd4x_test_hw_i2c`.
+6. Now you should see the test output on your console.
 
 # Background
 
 ## Files
 
 ### sensirion\_i2c.[ch]
 
-In these files you can find the implementation of the I2C protocol used by Sensirion
-sensors. The functions in these files are used by the embedded driver to build the
-correct frame out of data to be sent to the sensor or receive a frame of data from
-the sensor and convert it back to data readable by your machine. The functions in
-here calculate and check CRCs, reorder bytes for different byte orders and build the
-correct formatted frame for your sensor.
+In these files you can find the implementation of the I2C protocol used by
+Sensirion sensors. The functions in these files are used by the embedded driver
+to build the correct frame out of data to be sent to the sensor or receive a
+frame of data from the sensor and convert it back to data readable by your
+machine. The functions in here calculate and check CRCs, reorder bytes for
+different byte orders and build the correct formatted frame for your sensor.
 
 ### sensirion\_i2c\_hal.[ch]
 
-In these files you can find the implementation of the hardware abstraction layer used
-by Sensirion's I2C embedded drivers. This part of the code is specific to the underlying
-hardware platform. This is an unimplemented template for the user to implement.
-In the `sample-implementations/` folder we provide implementations for the most common
-platforms.
+These files contain the implementation of the hardware abstraction layer used
+by Sensirion's I2C embedded drivers. This part of the code is specific to the
+underlying hardware platform. This is an unimplemented template for the user to
+implement. In the `sample-implementations/` folder we provide implementations
+for the most common platforms.
 
 ### sensirion\_config.h
 
-In this file we keep all the included libraries for our drivers and global defines.
-Next to `sensirion_i2c_hal.c` *it's the only file you should need to edit to get your
-driver working.*
+In this file we keep all the included libraries for our drivers and global
+defines. Next to `sensirion_i2c_hal.c` *it's the only file you should need to
+edit to get your driver working.*
 
 ### sensirion\_common.[ch]
 
-In these files you can find some helper functions used by Sensirion's embedded drivers.
-It mostly contains byte order conversions for different variable types. These functions
-are also used by the UART embedded drivers therefore they are kept in their own file.
+In these files you can find some helper functions used by Sensirion's embedded
+drivers. It mostly contains byte order conversions for different variable
+types. These functions are also used by the UART embedded drivers therefore
+they are kept in their own file.
+
+## 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).

example-usage/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_usage
+
+scd4x_i2c_example_usage: clean
+	$(CC) $(CFLAGS) -o $@  ${driver_sources} ${i2c_sources} \
+		${i2c_implementation} ${common_sources} scd4x_i2c_example_usage.c
+
+clean:
+	$(RM) scd4x_i2c_example_usage