From 426b1341171106d9f51fe619de573bd41f2515af Mon Sep 17 00:00:00 2001 From: Quentin Fisch Date: Sun, 24 Mar 2024 12:05:58 +0100 Subject: [PATCH 1/2] Added badges in readme --- README.md | 65 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 43 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 121bd39..e98307c 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Arduino Sensirion UPT I2C Auto Detection +![arduino badge](https://img.shields.io/badge/Arduino-00979D?style=flat&logo=Arduino&logoColor=white) [![platform-io-badge](https://badges.registry.platformio.org/packages/sensirion/library/Sensirion%20UPT%20I2C%20Auto%20Detection.svg)](https://registry.platformio.org/libraries/sensirion/Sensirion20UPT20I2C20Auto20Detection) + Arduino Library for automatic detection of Sensirion sensors on an I2C Bus. It allows for easy read-out of the data of Sensirion Sensors using an ESP32 board. ## Supported sensors: @@ -14,6 +16,7 @@ Arduino Library for automatic detection of Sensirion sensors on an I2C Bus. It a - SVM4X ### Sensor Oddities + - SCD30. This sensor has a particular method of retrieveing measurements, which typically enters a waiting loop until the measurement is ready. To avoid this blocking call, the library uses an alternative method, that sometimes yields I2C errors. These errors are not fatal and can be ignored. - SGP41. The SGP41 arduino I2C driver returns raw VOC and NOX values, as opposed to the SEN5X sensors, which internally feed the raw values through [Sensirion's gas index algorithm](https://github.com/Sensirion/gas-index-algorithm) and returns a gas index in the range of [0, 500]. - STC3X. The STC3X requires a conditioning phase of up to 10 seconds (this library considers 8 sufficient), during which the value of the data points will be UNDEFINED/0. @@ -27,6 +30,7 @@ This project was developed and tested on Espressif [ESP32 DevKitC](https://www.e The ESP32 and all sensors need to be connected to the I2C bus. On the ESP32, the SDA pin (data) is 21 and the SCL pin (clock) is 22. ### Arduino + Install the software from the [official website](https://www.arduino.cc/en/software) and read [this short tutorial](https://docs.arduino.cc/software/ide-v2/tutorials/getting-started-ide-v2/) to get an introduction to the IDE. Next, select your board and port in the Board Manager by following [these instructions](https://support.arduino.cc/hc/en-us/articles/4406856349970-Select-board-and-port-in-Arduino-IDE). @@ -36,16 +40,17 @@ Start the [Arduino IDE](http://www.arduino.cc/en/main/software) and open the Lib Sketch => Include Library => Manage Libraries... Search for the `Sensirion UPT I2C Auto Detection` library in the `Filter your search...` field and install it by clicking the `install` button. Make sure to click "Install All", lest you'll have to manually search for and install the following: -* [Sensirion Arduino Core](https://www.arduino.cc/reference/en/libraries/sensirion-core/) -* [Sensirion UPT Core](https://www.arduino.cc/reference/en/libraries/sensirion-upt-core/) -* [Sensirion I2C SCD4x](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-scd4x/) -* [Sensirion I2C SFA3x](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-sfa3x/) -* [Sensirion I2C SVM4x](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-svm4x/) -* [Sensirion I2C SHT4x](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-sht4x/) -* [Sensirion I2C SEN5x](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-sen5x/) -* [Sensirion I2C SCD30](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-scd30/) -* [Sensirion I2C SGP41](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-sgp41/) -* [Sensirion I2C STC3x](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-stc3x/) + +- [Sensirion Arduino Core](https://www.arduino.cc/reference/en/libraries/sensirion-core/) +- [Sensirion UPT Core](https://www.arduino.cc/reference/en/libraries/sensirion-upt-core/) +- [Sensirion I2C SCD4x](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-scd4x/) +- [Sensirion I2C SFA3x](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-sfa3x/) +- [Sensirion I2C SVM4x](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-svm4x/) +- [Sensirion I2C SHT4x](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-sht4x/) +- [Sensirion I2C SEN5x](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-sen5x/) +- [Sensirion I2C SCD30](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-scd30/) +- [Sensirion I2C SGP41](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-sgp41/) +- [Sensirion I2C STC3x](https://www.arduino.cc/reference/en/libraries/sensirion-i2c-stc3x/) Alternatively, the library can also be added manually. To do this, download the latest release from github as a .zip file via @@ -58,6 +63,7 @@ and add it to the [Arduino IDE](http://www.arduino.cc/en/main/software) via In this second case, you'll have to also add all dependencies the same way (links to all .zip files given below in the Dependencies section). ### PlatformIO + An often more straightforward alternative to the Arduino IDE is the PlatformIO framework, which is the recommended approach on Linux/Unix systems and is detailed in the following. The most straight-forward way to use [PlatformIO](https://platformio.org/platformio-ide) is as an extension to Microsoft's [Visual Studio Code](https://code.visualstudio.com/), you'll find it easily among the extensions available for it. Please refer to the official installation instructions [here](https://platformio.org/install/ide?install=vscode). @@ -68,25 +74,33 @@ To use the library, add the following dependencies to your `platformio.ini`'s `l lib_deps = Sensirion/Sensirion UPT I2C Auto Detection ``` + PlatformIO will automatically fetch the latest version of the dependencies during the build process. Alternatively, to install this library in your project environment execute the following command in a terminal: + ```bash pio pkg install --library "Sensirion/Sensirion UPT I2C Auto Detection" ``` To test the default example (`basicUsage`), use the following platformio command from the project's root directory (the one containing the `platformio.ini` file): + ```bash pio run -e basicUsage -t upload ``` + and start the Serial monitor with + ```bash pio device monitor ``` + The second example can be run by specifying the build environement `advancedUsage`, as such: + ```bash pio run -e advancedUsage -t upload && pio device monitor ``` + Available environments are `basicUsage`, `advancedUsage` and `hacksterExample`. Environment `basicUsage` is default and will be used if you omit the `-e` flag. Please refer to the README in `examples/hacksterExample` for more information about this environment, as it is designed to accompany an example published to [Hackster.io](https://www.hackster.io/sensirion-software/easily-read-out-sensirion-sensor-measurements-on-arduino-9c1862). @@ -96,16 +110,16 @@ In case you're using some other board, it is recommended you create a new enviro This library uses the following dependencies. -* [Sensirion Core](https://github.com/Sensirion/arduino-core) -* [Sensirion UPT Core](https://github.com/Sensirion/upt-core) -* [SCD30](https://github.com/Sensirion/arduino-i2c-scd30) -* [SCD4X](https://github.com/Sensirion/arduino-i2c-scd4x) -* [SEN5X](https://github.com/Sensirion/arduino-i2c-sen5x) -* [SFA3X](https://github.com/Sensirion/arduino-i2c-sfa3x) -* [SGP41](https://github.com/Sensirion/arduino-i2c-sgp41) -* [SHT4X](https://github.com/Sensirion/arduino-i2c-sht4x) -* [SVM40](https://github.com/Sensirion/arduino-i2c-svm40) -* [STC3X](https://github.com/Sensirion/arduino-i2c-stc3x) +- [Sensirion Core](https://github.com/Sensirion/arduino-core) +- [Sensirion UPT Core](https://github.com/Sensirion/upt-core) +- [SCD30](https://github.com/Sensirion/arduino-i2c-scd30) +- [SCD4X](https://github.com/Sensirion/arduino-i2c-scd4x) +- [SEN5X](https://github.com/Sensirion/arduino-i2c-sen5x) +- [SFA3X](https://github.com/Sensirion/arduino-i2c-sfa3x) +- [SGP41](https://github.com/Sensirion/arduino-i2c-sgp41) +- [SHT4X](https://github.com/Sensirion/arduino-i2c-sht4x) +- [SVM40](https://github.com/Sensirion/arduino-i2c-svm40) +- [STC3X](https://github.com/Sensirion/arduino-i2c-stc3x) In case automatic dependency installation doesn't work, you will have to install them manually. @@ -118,15 +132,18 @@ For example code showing how to use the user API, look at `examples/basicUsage/b In any case, the following steps are essential. Include the library: + ```cpp #include "Sensirion_upt_i2c_auto_detection.h" ``` + Instantiate I2CAutoDetector and SensorManager globally (before void setup()): ```cpp I2CAutoDetector i2CAutoDetector(Wire); SensorManager sensorManager(i2CAutoDetector); ``` + Begin Serial, Wire in void setup(): ```cpp @@ -135,27 +152,31 @@ Begin Serial, Wire in void setup(): ``` Still in `void setup()`, fetch the maximum number of simultaneously connected sensors and allocate memory for the hashmap: + ```cpp maxNumSensors = sensorManager.getMaxNumberOfSensors(); pCurrentData = new const DataPointList* [maxNumSensors] { nullptr }; ``` Update and retrieve Data object in `void loop()`: + ```cpp sensorManager.refreshAndGetSensorReadings(pCurrentData); ``` Alternatively, more control over the different routines (bus scan for new sensors, state machine update and reading retrieval) is provided through respective functions. The following snippet is equivalent to the above single function call: + ```cpp sensorManager.refreshConnectedSensors(); sensorManager.executeSensorCommunication(); sensorManager.getSensorReadings(pCurrentData); ``` -The sensor manager handles command dispatch to the detected sensors, to make sure minimum intervals between commands are respected. Data readout is decoupled from sensor state machine updates, but only the last recorded measurement is available. Note: some sensors have a decay time, after which a conditioning procedure must be executed before readings are available (eg. SGP41). This decay time must not be exceeded inbetween ```cpp SensorManager::updateStateMachines()``` function calls, else `SensorManager` is never able to provide a measurement for these sensors. +The sensor manager handles command dispatch to the detected sensors, to make sure minimum intervals between commands are respected. Data readout is decoupled from sensor state machine updates, but only the last recorded measurement is available. Note: some sensors have a decay time, after which a conditioning procedure must be executed before readings are available (eg. SGP41). This decay time must not be exceeded inbetween `cpp SensorManager::updateStateMachines()` function calls, else `SensorManager` is never able to provide a measurement for these sensors. If three 3 consecutive errors occur while trying to read the data ror a sensor, the sensor is considered lost and not read out anymore in the following to save resources. If all is well, you should see the output as such in the device monitor: + ```control Data retrieved via sensor manager: ------------------------------------------- @@ -187,5 +208,5 @@ Data retrieved via sensor manager: # Limitations - This library does not support more than one sensor of the same type at a time. -- Only a single bus is supported. Multiple SensorManager instances must be used to get data from sensors connected to different buses. We suggest using TwoWire instead of the Arduino standard ```Wire.h``` in this case, since it does not support multiple I2C buses. +- Only a single bus is supported. Multiple SensorManager instances must be used to get data from sensors connected to different buses. We suggest using TwoWire instead of the Arduino standard `Wire.h` in this case, since it does not support multiple I2C buses. - As UPT Core, a dependency of this library, uses C++ Standard Template Library (STL), it won't run on most Arduino boards by default. ESP32s or other boards that support the STL will work more smoothly. From 84c588ac9fc9e7a5401049b48561a4654246715b Mon Sep 17 00:00:00 2001 From: Quentin Fisch Date: Sun, 24 Mar 2024 12:08:56 +0100 Subject: [PATCH 2/2] update CI arduino LINT --- .github/workflows/arduino.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/arduino.yml b/.github/workflows/arduino.yml index 19af482..766191e 100644 --- a/.github/workflows/arduino.yml +++ b/.github/workflows/arduino.yml @@ -11,6 +11,8 @@ jobs: steps: - uses: actions/checkout@v4 - uses: arduino/arduino-lint-action@v1 + with: + library-manager: update arduino-ci: runs-on: ubuntu-latest