1- # Sensirion Embedded I2C SCD4x Driver
1+ # Sensirion I2C SCD4X embedded Library
22
3- This is a generic embedded driver for the [ Sensirion SCD4x Carbon Dioxide Sensor] ( https://www.sensirion.com/scd4x/ ) .
4- It enables developers to communicate with the SCD4x sensor on different hardware platforms by only adapting the I2C communication related source files.
3+ This document explains how to set up a sensor of the SCD4X family to run on an embedded device using the I²C interface.
54
6- [ < center >< img src =" images/SCD4x .png " width =" 300px " ></ center > ] ( https://sensirion.com/my-scd-ek )
5+ < img src =" images/SCD41 .png " width =" 300px " >
76
8- # Getting started
7+ Click [ here ] ( https://sensirion.com/products/catalog/SEK-SCD41 ) to learn more about the Sensirion SCD4X sensor family.
98
10- ## Implement the I2C Interface
119
12- So we need to adjust two files according to your platform.
10+ Not all sensors of this driver family support all measurements.
11+ In case a measurement is not supported by all sensors, the products that
12+ support it are listed in the API description.
13+
14+
15+
16+ ## Supported sensor types
17+
18+ | Sensor name | I²C Addresses |
19+ | ------------- | -------------- |
20+ | [ SCD40] ( https://sensirion.com/products/catalog/SCD40 ) | ** 0x62** |
21+ | [ SCD41] ( https://sensirion.com/products/catalog/SCD41 ) | ** 0x62** |
22+
23+ The following instructions and examples use a * SCD41* .
24+
25+
26+
27+ ## Setup Guide
28+
29+ ### Connect the Sensor
30+
31+ Your sensor has 4 pins that need to be connected to your board: SCL, GND, VDD, SDA.
32+ Use the following description to connect your SCD4X:
33+
34+ <img src =" images/SCD41_pinout.png " width =" 300px " >
35+
36+ | * Pin* | * Cable Color* | * Name* | * Description* | * Comments* |
37+ | -------| ---------------| :------:| ----------------| ------------|
38+ | 1 | yellow | SCL | I2C: Serial clock input |
39+ | 2 | black | GND | Ground |
40+ | 3 | red | VDD | Supply Voltage | 2.4V to 5.5V
41+ | 4 | green | SDA | I2C: Serial data input / output |
42+
43+
44+
45+ The recommended voltage is 3.3V.
46+
47+ ### Configure the code
48+
49+ In order to use the provided code we need to adjust two files according to your platform.
1350
1451### Edit ` sensirion_i2c_hal.c `
1552
16- This file contains the implementation of the sensor communication
17- (how to send requests to the sensor). Therefore, how this is done depends on your
18- hardware platform. Therefore we can only provide function stubs in which you
19- can implement the logic yourself.
20- There are sample implementations available for some platforms: [ ` sample-implementations ` ] ( sample-implementations ) .
21- If you are using a Linux based platform like Raspberry Pi
22- you can just replace the unimplemented HAL template with the provided
53+ This file contains the implementation of the sensor communication, which
54+ depends on your hardware platform. We provide function stubs for your
55+ hardware's own implementation.
56+ Sample implementations are available for some platforms:
57+ [ ` sample-implementations ` ] ( sample-implementations ) . For Linux based platforms
58+ like Raspberry Pi you can just replace the unimplemented HAL template with the
2359implementation in ` sample-implementations/linux_user_space/ ` :
2460
2561```
@@ -28,17 +64,16 @@ cp sample-implementations/linux_user_space/sensirion_i2c_hal.c ./
2864
2965### Edit ` sensirion_config.h `
3066
31- If you are on a Linux based platform you can skip this part since
32- everything is already correctly setup for you .
67+ Skip this part for Linux based platforms since everything is already setup for
68+ this case .
3369
34- Otherwise you need to check if the libraries ` <stdint.h> ` and
35- ` <stdlib.h> ` are provided by your toolchain, compiler or system.
36- If you have no idea on how to do that you can skip this
37- step for now and come back when you get errors related to these names when
38- compiling the driver.
39- The features we use out of those libraries are standard integer sizes
40- from ` <stdint.h> ` and ` NULL ` from ` <stdlib.h> ` . If they are not available
41- you need to specify the following integer types yourself:
70+ Otherwise you need to check if the libraries ` <stdint.h> ` and ` <stdlib.h> ` are
71+ provided by your toolchain, compiler or system. If you have no idea on how to
72+ do that you can skip this step for now and come back when you get errors
73+ related to these names when compiling the driver.
74+ The features we use from those libraries are type definitions for integer sizes
75+ from ` <stdint.h> ` and ` NULL ` from ` <stdlib.h> ` . If they are not available you
76+ need to specify the following integer types yourself:
4277
4378* ` int64_t ` = signed 64bit integer
4479* ` uint64_t ` = unsigned 64bit integer
@@ -49,56 +84,101 @@ you need to specify the following integer types yourself:
4984* ` int8_t ` = signed 8bit integer
5085* ` uint8_t ` = unsigned 8bit integer
5186
52- In addition to that you will need to specify ` NULL ` .
53- For both we have a detailed template where you just need to fill in
54- your system specific values.
87+ In addition to that you will need to specify ` NULL ` . For both we have a
88+ detailed template where you just need to fill in your system specific values.
89+
90+ ## Choose the i2c address to use with your product
91+
92+ The provided example is working with a SCD41, I²C address 0x62.
93+ 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
94+ ` scd4x_i2c_example_usage.c ` . The list of supported I²C-addresses is found in the header
95+ ` scd4x_i2c.h ` .
96+
5597
5698Now we are ready to compile and run the example usage for your sensor.
5799
58100## Compile and Run
59101
60- Take the ` .c ` and ` .h ` files directly in this folder pass them to your
61- favorite C compiler and run the resulting binary.
62- This step may vary, depending on your platform. Here we demonstrate the
63- procedure for Linux based platforms:
102+ Pass the source ` .c ` and header ` .h ` files in this folder into your C compiler
103+ and run the resulting binary. This step may vary, depending on your platform.
104+ Here we demonstrate the procedure for Linux based platforms:
64105
651061 . Open up a terminal.
661072 . Navigate to the directory where this README is located.
67- 3 . Run ` make ` (this compiles all the code here to one binary).
68- 4 . Run ` ./scd4x_i2c_example_usage ` (This will run your newly compiled binary).
69- 5 . Now you should see the first measurement values appear in your terminal.
70- As a next step you can adjust the example usage file or write your own
71- main function to use the sensor.
108+ 3 . Navigate to the subdirectory example-usage.
109+ 4 . Run ` make ` (this compiles the example code into one executable binary).
110+ 5 . Run the compiled executable with ` ./scd4x_i2c_example_usage `
111+ 6 . Now you should see the first measurement values appear in your terminal. As
112+ a next step you can adjust the example usage file or write your own main
113+ function to use the sensor.
114+
115+ ## Compile and Run Tests
116+
117+ The testframekwork used is CppUTest. Pass the source ` .cpp ` , ` .c ` and header ` .h `
118+ files from the tests and top level folder into your CPP compiler and run the
119+ resulting binary. This step may vary, depending on your platform.
120+ Here we demonstrate the procedure for Linux based platforms:
121+
122+ 1 . Open up a terminal.
123+ 2 . Install CppUTest framework ` apt install cpputest ` .
124+ 3 . Navigate to the directory ` tests ` .
125+ 4 . Run ` make ` (this compiles the test code into one executable binary).
126+ 5 . Run the compiled executable with ` ./scd4x_test_hw_i2c ` .
127+ 6 . Now you should see the test output on your console.
72128
73129# Background
74130
75131## Files
76132
77133### sensirion\_ i2c.[ ch]
78134
79- In these files you can find the implementation of the I2C protocol used by Sensirion
80- sensors. The functions in these files are used by the embedded driver to build the
81- correct frame out of data to be sent to the sensor or receive a frame of data from
82- the sensor and convert it back to data readable by your machine. The functions in
83- here calculate and check CRCs, reorder bytes for different byte orders and build the
84- correct formatted frame for your sensor.
135+ In these files you can find the implementation of the I2C protocol used by
136+ Sensirion sensors. The functions in these files are used by the embedded driver
137+ to build the correct frame out of data to be sent to the sensor or receive a
138+ frame of data from the sensor and convert it back to data readable by your
139+ machine. The functions in here calculate and check CRCs, reorder bytes for
140+ different byte orders and build the correct formatted frame for your sensor.
85141
86142### sensirion\_ i2c\_ hal.[ ch]
87143
88- In these files you can find the implementation of the hardware abstraction layer used
89- by Sensirion's I2C embedded drivers. This part of the code is specific to the underlying
90- hardware platform. This is an unimplemented template for the user to implement.
91- In the ` sample-implementations/ ` folder we provide implementations for the most common
92- platforms.
144+ These files contain the implementation of the hardware abstraction layer used
145+ by Sensirion's I2C embedded drivers. This part of the code is specific to the
146+ underlying hardware platform. This is an unimplemented template for the user to
147+ implement. In the ` sample-implementations/ ` folder we provide implementations
148+ for the most common platforms.
93149
94150### sensirion\_ config.h
95151
96- In this file we keep all the included libraries for our drivers and global defines.
97- Next to ` sensirion_i2c_hal.c ` * it's the only file you should need to edit to get your
98- driver working.*
152+ In this file we keep all the included libraries for our drivers and global
153+ defines. Next to ` sensirion_i2c_hal.c ` * it's the only file you should need to
154+ edit to get your driver working.*
99155
100156### sensirion\_ common.[ ch]
101157
102- In these files you can find some helper functions used by Sensirion's embedded drivers.
103- It mostly contains byte order conversions for different variable types. These functions
104- are also used by the UART embedded drivers therefore they are kept in their own file.
158+ In these files you can find some helper functions used by Sensirion's embedded
159+ drivers. It mostly contains byte order conversions for different variable
160+ types. These functions are also used by the UART embedded drivers therefore
161+ they are kept in their own file.
162+
163+ ## Contributing
164+
165+ ** Contributions are welcome!**
166+
167+ This Sensirion library uses
168+ [ ` clang-format ` ] ( https://releases.llvm.org/download.html ) to standardize the
169+ formatting of all our ` .c ` and ` .h ` files. Make sure your contributions are
170+ formatted accordingly:
171+
172+ The ` -i ` flag will apply the format changes to the files listed.
173+
174+ ``` bash
175+ clang-format -i * .c * .h
176+ ```
177+
178+ Note that differences from this formatting will result in a failed build until
179+ they are fixed.
180+
181+
182+ # License
183+
184+ See [ LICENSE] ( LICENSE ) .
0 commit comments