|
1 | | -# raspberry-pi-i2c-scd30 |
| 1 | +# Sensirion Raspberry Pi I2C SCD30 Driver |
2 | 2 |
|
| 3 | +This document explains how to set up a SCD30 sensor to run on a Raspberry Pi |
| 4 | +using the provided code. |
3 | 5 |
|
| 6 | +<center><img src="images/sensor_scd30_image.jpg" width="300px"></center> |
4 | 7 |
|
5 | | -## Getting started |
| 8 | +Click [here](https://sensirion.com/products/catalog/SCD30/) to learn more about the Sensirion SCD30 sensor. |
6 | 9 |
|
7 | | -To make it easy for you to get started with GitLab, here's a list of recommended next steps. |
8 | 10 |
|
9 | | -Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)! |
10 | 11 |
|
11 | | -## Add your files |
| 12 | +The default I²C address of [SCD30](https://sensirion.com/products/catalog/SCD30/) is **0x61**. |
12 | 13 |
|
13 | | -- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files |
14 | | -- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command: |
15 | 14 |
|
16 | | -``` |
17 | | -cd existing_repo |
18 | | -git remote add origin https://gitlab.sensirion.lokal/MSO-SW/drivers/raspberry-pi/raspberry-pi-i2c-scd30.git |
19 | | -git branch -M master |
20 | | -git push -uf origin master |
21 | | -``` |
22 | 15 |
|
23 | | -## Integrate with your tools |
| 16 | +## Setup Guide |
| 17 | + |
| 18 | +### Connecting the Sensor |
| 19 | + |
| 20 | +Your sensor has the 7 different connectors: VDD, GND, SCL, SDA, RDY, PWM, SEL. |
| 21 | +Use the following pins to connect your SCD30: |
| 22 | + |
| 23 | +| *SCD30* | *Cable Color* | *Raspberry Pi* | |
| 24 | +| :----------------: | -------------- | ------------------ | |
| 25 | +| VDD | | Pin 1 |
| 26 | +| GND | | Pin 6 |
| 27 | +| SCL | | Pin 5 |
| 28 | +| SDA | | Pin 3 |
| 29 | +| RDY | | Pin |
| 30 | +| PWM | | Pin |
| 31 | +| SEL | | Pin 9 |
| 32 | + |
| 33 | + |
| 34 | +<img src="images/raspi-i2c-pinout-3.3V-SEL.png" width="400px"> |
| 35 | + |
24 | 36 |
|
25 | | -- [ ] [Set up project integrations](https://gitlab.sensirion.lokal/MSO-SW/drivers/raspberry-pi/raspberry-pi-i2c-scd30/-/settings/integrations) |
| 37 | +#### Detaild sensor pinout |
26 | 38 |
|
27 | | -## Collaborate with your team |
| 39 | +<img src="images/scd30_pinout.jpg" width="300px"> |
28 | 40 |
|
29 | | -- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/) |
30 | | -- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html) |
31 | | -- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically) |
32 | | -- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/) |
33 | | -- [ ] [Automatically merge when pipeline succeeds](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html) |
| 41 | +| *Pin* | *Cable Color* | *Name* | *Description* | *Comments* | |
| 42 | +|-------|---------------|:------:|----------------|------------| |
| 43 | +| 1 | |VDD | Supply Voltage | 3.3 to 5.5V |
| 44 | +| 2 | |GND | Ground | |
| 45 | +| 3 | |SCL | I2C: Serial clock input | |
| 46 | +| 4 | |SDA | I2C: Serial data input / output | |
| 47 | +| 5 | |RDY | | High when data is available |
| 48 | +| 6 | |PWM | | |
| 49 | +| 7 | |SEL | Interface select | Interface select; Pull to ground or floating for I2c |
| 50 | +### Raspberry Pi |
34 | 51 |
|
35 | | -## Test and Deploy |
| 52 | +- [Install the Raspberry Pi OS on to your Raspberry Pi](https://projects.raspberrypi.org/en/projects/raspberry-pi-setting-up) |
| 53 | +- [Enable the I²C interface in the raspi-config](https://www.raspberrypi.org/documentation/configuration/raspi-config.md) |
| 54 | +- Download the SCD30 driver from [Github](https://github.com/Sensirion/raspberry-pi-i2c-scd30) and extract the `.zip` on your Raspberry Pi |
36 | 55 |
|
37 | | -Use the built-in continuous integration in GitLab. |
| 56 | +- Compile the driver |
| 57 | + 1. Open a [terminal](https://www.raspberrypi.com/documentation/computers/using_linux.html#terminal) |
| 58 | + 2. Navigate to the driver directory. E.g. `cd ~/raspberry-pi-i2c-scd30` |
| 59 | + 3. Run the `make` command to compile the driver |
38 | 60 |
|
39 | | -- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html) |
40 | | -- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing(SAST)](https://docs.gitlab.com/ee/user/application_security/sast/) |
41 | | -- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html) |
42 | | -- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/) |
43 | | -- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html) |
| 61 | + Output: |
| 62 | + ``` |
| 63 | + rm -f scd30_i2c_example_usage |
| 64 | + cc -Os -Wall -fstrict-aliasing -Wstrict-aliasing=1 -Wsign-conversion -fPIC -I. -o scd30_i2c_example_usage scd30_i2c.h scd30_i2c.c sensirion_i2c_hal.h sensirion_i2c.h sensirion_i2c.c \ |
| 65 | + sensirion_i2c_hal.c sensirion_config.h sensirion_common.h sensirion_common.c scd30_i2c_example_usage.c |
| 66 | + ``` |
| 67 | +- Test your connected sensor |
| 68 | + - Run `./scd30_i2c_example_usage` in the same directory you used to |
| 69 | + compile the driver. You should see the measurement values in the console. |
| 70 | +
|
| 71 | +## Troubleshooting |
| 72 | +
|
| 73 | +### Building driver failed |
| 74 | +
|
| 75 | +If the execution of `make` in the compilation step 3 fails with something like |
| 76 | +
|
| 77 | +```bash |
| 78 | + make: command not found |
| 79 | +``` |
| 80 | + |
| 81 | +your RaspberryPi likely does not have the build tools installed. Proceed as follows: |
| 82 | + |
| 83 | +``` |
| 84 | +$ sudo apt-get update |
| 85 | +$ sudo apt-get upgrade |
| 86 | +$ sudo apt-get install build-essential |
| 87 | +``` |
44 | 88 |
|
45 | | -*** |
46 | 89 |
|
47 | | -# Editing this README |
| 90 | +### Initialization failed |
48 | 91 |
|
49 | | -When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thank you to [makeareadme.com](https://www.makeareadme.com/) for this template. |
| 92 | +If you run `./scd30_i2c_example_usage` but do not get sensor readings but something like this instead |
50 | 93 |
|
51 | | -## Suggestions for a good README |
52 | | -Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information. |
| 94 | +``` |
| 95 | +Error executing soft_reset(): -1 |
| 96 | +Error executing read_firmware_version(): -1 |
| 97 | +Error executing start_periodic_measurement(): -1 |
| 98 | +... |
| 99 | +``` |
| 100 | +then go through the below troubleshooting steps. |
53 | 101 |
|
54 | | -## Name |
55 | | -Choose a self-explaining name for your project. |
56 | 102 |
|
57 | | -## Description |
58 | | -Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors. |
| 103 | +- Ensure that you connected the sensor correctly: All cables are fully |
| 104 | + plugged in and connected to the correct pin. |
| 105 | +- Ensure that I²C is enabled on the Raspberry Pi. For this redo the steps on |
| 106 | + "Enable the I²C interface in the raspi-config" in the guide above. |
| 107 | +- Ensure that your user account has read and write access to the I²C device. |
| 108 | + If it only works with user root (`sudo ./scd30_i2c_example_usage`), it's |
| 109 | + typically due to wrong permission settings. See the next chapter how to solve this. |
59 | 110 |
|
60 | | -## Badges |
61 | | -On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge. |
| 111 | +### Missing I²C permissions |
62 | 112 |
|
63 | | -## Visuals |
64 | | -Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method. |
| 113 | +If your user is missing access to the I²C interface you should first verfiy |
| 114 | +the user belongs to the `i2c` group. |
65 | 115 |
|
66 | | -## Installation |
67 | | -Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection. |
| 116 | +``` |
| 117 | +$ groups |
| 118 | +users input some other groups etc |
| 119 | +``` |
| 120 | +If `i2c` is missing in the list add the user and restart the Raspberry Pi. |
68 | 121 |
|
69 | | -## Usage |
70 | | -Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README. |
| 122 | +``` |
| 123 | +$ sudo adduser your-user i2c |
| 124 | +Adding user `your-user' to group `i2c' ... |
| 125 | +Adding user your-user to group i2c |
| 126 | +Done. |
| 127 | +$ sudo reboot |
| 128 | +``` |
71 | 129 |
|
72 | | -## Support |
73 | | -Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc. |
| 130 | +If that did not help you can make globally accessible hardware interfaces |
| 131 | +with a udev rule. Only do this if everything else failed and you are |
| 132 | +reasoably confident you are the only one having access to your Pi. |
74 | 133 |
|
75 | | -## Roadmap |
76 | | -If you have ideas for releases in the future, it is a good idea to list them in the README. |
| 134 | +Go into the `/etc/udev/rules.d` folder and add a new file named |
| 135 | +`local.rules`. |
| 136 | +``` |
| 137 | +$ cd /etc/udev/rules.d/ |
| 138 | +$ sudo touch local.rules |
| 139 | +``` |
| 140 | +Then add a single line `ACTION=="add", KERNEL=="i2c-[0-1]*", MODE="0666"` |
| 141 | +to the file with your favorite editor. |
| 142 | +``` |
| 143 | +$ sudo vi local.rules |
| 144 | +``` |
77 | 145 |
|
78 | 146 | ## Contributing |
79 | | -State if you are open to contributions and what your requirements are for accepting them. |
80 | 147 |
|
81 | | -For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self. |
| 148 | +**Contributions are welcome!** |
| 149 | + |
| 150 | +We develop and test this driver using our company internal tools (version |
| 151 | +control, continuous integration, code review etc.) and automatically |
| 152 | +synchronize the master branch with GitHub. But this doesn't mean that we don't |
| 153 | +respond to issues or don't accept pull requests on GitHub. In fact, you're very |
| 154 | +welcome to open issues or create pull requests :) |
| 155 | + |
| 156 | +This Sensirion library uses |
| 157 | +[`clang-format`](https://releases.llvm.org/download.html) to standardize the |
| 158 | +formatting of all our `.c` and `.h` files. Make sure your contributions are |
| 159 | +formatted accordingly: |
| 160 | + |
| 161 | +The `-i` flag will apply the format changes to the files listed. |
| 162 | + |
| 163 | +```bash |
| 164 | +clang-format -i *.c *.h |
| 165 | +``` |
82 | 166 |
|
83 | | -You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser. |
| 167 | +Note that differences from this formatting will result in a failed build until |
| 168 | +they are fixed. |
84 | 169 |
|
85 | | -## Authors and acknowledgment |
86 | | -Show your appreciation to those who have contributed to the project. |
87 | 170 |
|
88 | 171 | ## License |
89 | | -For open source projects, say how it is licensed. |
90 | 172 |
|
91 | | -## Project status |
92 | | -If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers. |
| 173 | +See [LICENSE](LICENSE). |
0 commit comments