Merge branch 'sht4x_2.0.0_20231018_0736' into 'master'

Update SHT4x driver from SHT4X model version 2.0.0 See merge request MSO-SW/drivers/arduino/arduino-i2c-sht4x!5
Sensirion · Nov 1, 2023 · f6d7684 · f6d7684
2 parents caf276c + caf3e8a
commit f6d7684
Show file tree

Hide file tree

Showing 17 changed files with 863 additions and 629 deletions.
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -2,6 +2,9 @@ stages:
   - validate
   - test
 
+variables:
+  YQ_URL: https://github.com/mikefarah/yq/releases/download/v4.33.3/yq_linux_amd64
+
 compile_test:
     stage: test
     image:
@@ -10,18 +13,29 @@ compile_test:
     before_script:
         - rm -rf ../sensirion-core-arduino-library
     script:
-        - git clone --depth 1 --branch 0.5.1 https://github.com/Sensirion/arduino-core.git ../sensirion-core-arduino-library
-        - arduino-cli compile --libraries=".." --warnings all --fqbn arduino:samd:mkrzero examples/exampleUsage
-        - arduino-cli compile --libraries=".." --warnings all --fqbn arduino:avr:mega examples/exampleUsage
-        - arduino-cli compile --libraries=".." --warnings all --fqbn arduino:avr:nano examples/exampleUsage
-        - arduino-cli compile --libraries=".." --warnings all --fqbn arduino:avr:uno examples/exampleUsage
-        - arduino-cli compile --libraries=".." --warnings all --fqbn esp32:esp32:esp32 examples/exampleUsage
-        - arduino-cli compile --libraries=".." --warnings all --fqbn esp8266:esp8266:generic examples/exampleUsage
+        - git clone --depth 1 --branch 0.5.2 https://github.com/Sensirion/arduino-core.git ../sensirion-core-arduino-library
+        - arduino-cli compile --libraries=".." --warnings all --fqbn arduino:samd:mkrzero ./examples/exampleUsage/exampleUsage.ino
+        - arduino-cli compile --libraries=".." --warnings all --fqbn arduino:avr:mega ./examples/exampleUsage/exampleUsage.ino
+        - arduino-cli compile --libraries=".." --warnings all --fqbn arduino:avr:nano ./examples/exampleUsage/exampleUsage.ino
+        - arduino-cli compile --libraries=".." --warnings all --fqbn arduino:avr:uno ./examples/exampleUsage/exampleUsage.ino
+        - arduino-cli compile --libraries=".." --warnings all --fqbn esp32:esp32:esp32 ./examples/exampleUsage/exampleUsage.ino
+        - arduino-cli compile --libraries=".." --warnings all --fqbn esp8266:esp8266:generic ./examples/exampleUsage/exampleUsage.ino
+
+arduino_lint:
+  stage: validate
+  image:
+    name: registry.gitlab.sensirion.lokal/mso-sw/drivers/docker-driver-generator:0.2.0
+  tags: [linux, docker]
+  script:
+    - mkdir ~/arlint
+    - PATH=~/arlint:$PATH
+    - curl -fsSL https://raw.githubusercontent.com/arduino/arduino-lint/main/etc/install.sh | BINDIR=~/arlint sh
+    - arduino-lint --library-manager false
 
 syntax_check:
   stage: validate
   image:
-      name: registry.gitlab.sensirion.lokal/mso-sw/drivers/docker-driver-generator:0.1.0
+      name: registry.gitlab.sensirion.lokal/mso-sw/drivers/docker-driver-generator:0.2.0
   tags: [linux, docker]
   script:
     - find . -type f -iregex ".*\.\(c\|h\|cpp\|ino\)" -exec clang-format-6.0 -i -style=file {} \; && git diff --exit-code
@@ -30,15 +44,60 @@ syntax_check:
 cppcheck:
   stage: validate
   image:
-      name: registry.gitlab.sensirion.lokal/mso-sw/drivers/docker-driver-generator:0.1.0
+      name: registry.gitlab.sensirion.lokal/mso-sw/drivers/docker-driver-generator:0.2.0
   tags: [linux, docker]
   script:
-    - cppcheck --std=c++11 --language=c++ --error-exitcode=1 --enable=warning,style,performance,portability src/*
+    - cppcheck --std=c++11 --language=c++ --error-exitcode=1 --enable=warning,style,performance,portability --suppress=unreadVariable src/*
 
 TODO_check:
   stage: validate
   image:
-      name: registry.gitlab.sensirion.lokal/mso-sw/drivers/docker-driver-generator:0.1.0
+      name: registry.gitlab.sensirion.lokal/mso-sw/drivers/docker-driver-generator:0.2.0
+  tags: [linux, docker]
+  script:
+    - '! grep -rnw --exclude=.gitlab-ci.yml --exclude-dir=.git . -e "TODO"'
+
+metadata_check:
+  stage: validate
+  image:
+    name: registry.gitlab.sensirion.lokal/mso-sw/drivers/docker-driver-generator:0.2.0
   tags: [linux, docker]
+  before_script:
+    - apt-get -qq update && apt-get -qq install -y wget
+    - if ! [ -d downloads/ ]; then mkdir downloads; fi
+    - if ! [ -e downloads/yq ]; then wget --no-verbose $YQ_URL -O downloads/yq; fi
+    - cp downloads/yq /usr/local/bin/yq && chmod +x /usr/local/bin/yq
   script:
-    - '! grep -rnw --exclude=.gitlab-ci.yml --exclude-dir=.git . -e "TODO: DRIVER_GENERATOR"'
+    # check if metadata.yml exists
+    - >
+      if ! [ -f "metadata.yml" ]; then
+        echo "metadata.yml file not found"
+        exit 1
+      fi
+    # check that dg_status is 'released'
+    - export DG_STATUS=$(yq ".dg_status.[]" ./metadata.yml)
+    - >
+      if [ $DG_STATUS != "released" ]; then
+        echo "dg_status in metadata.yml has to be 'released', not '$DG_STATUS'"
+        exit 1
+      fi
+    # check that last_generated is not older than timestamp of last non-merge commit (+ 3 minutes)
+    - export IS_MANUALLY_MODIFIED=$(yq ".is_manually_modified" ./metadata.yml)
+    - >
+      if [ $IS_MANUALLY_MODIFIED = false ]; then
+        export LAST_GENERATED_TS=$(yq ".last_generated" ./metadata.yml)
+        export LAST_GENERATED_TS_EPOCH=$(date -d "$LAST_GENERATED_TS" +%s)
+        export LAST_NON_MERGE_COMMIT_TS=$(git log --format=%ad --date=iso-strict --no-merges -1)
+        export COMMIT_TS_EPOCH=$(date -d "$LAST_NON_MERGE_COMMIT_TS" +%s)
+        if [ $(($LAST_GENERATED_TS_EPOCH + 180)) -lt $COMMIT_TS_EPOCH  ]; then
+          echo "'last_generated' timestamp in metadata.yml is older than commit timestamp ($LAST_GENERATED_TS vs $LAST_NON_MERGE_COMMIT_TS)"
+          exit 1
+        fi
+      fi
+    # check that 'is_manually_modified' is set to true if commit is not from driver generator
+    - export LAST_NON_MERGE_COMMIT_AUTHOR=$(git log --format=%an --no-merges -1)
+    - >
+      if ! [ "$LAST_NON_MERGE_COMMIT_AUTHOR" = "Driver Generator 2" ] && [ "$IS_MANUALLY_MODIFIED" = false ]; then
+        echo "Last commit is not from Driver Generator. Please update 'is_manually_modified' in metadata.yml"
+        exit 1
+      fi
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,10 +5,15 @@ 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).
 
 
-## [0.1.0] - 2021-07-27
+## [Unreleased]
 
-Initial Release
+Defined I2C addresses for different sensor models.
+You must now pass the I2C address to use in the begin() method of SensirionI2cSht4x
 
-[0.1.0]: https://github.com/Sensirion/arduino-i2c-sht4x/releases/tag/0.1.0
+Improved README
 
+## [0.1.0] - 2021-07-27
 
+Initial release
+
+[0.1.0]: https://github.com/Sensirion/arduino-i2c-sht4x/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) 2023, Sensirion AG
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

diff --git a/README.md b/README.md
@@ -1,56 +1,182 @@
-# Sensirion I2C SHT4X Arduino Library
+# Sensirion I²C SHT4X Arduino Library
 
-This is the Sensirion SHT4X library for Arduino using the
-modules I2C interface.
+This is the Sensirion SHT4X library for Arduino allowing you to 
+communicate with a sensor of the SHT4X family over I²C.
 
-[<center><img src="images/sht4x.png" width="300px"></center>](https://www.sensirion.com/sht4x)
+<img src="images/SHT4x.png" width="300px">
 
-Click [here](https://www.sensirion.com/sht4x) to learn more about the SHT4X
-sensor and Evaluation Kit.
+Click [here](https://sensirion.com/products/catalog/SEK-SHT40/) to learn more about the Sensirion SHT4X sensor family.
 
 
-# Installation
 
-To install, download the latest release as .zip file and add it to your
-[Arduino IDE](http://www.arduino.cc/en/main/software) via
+## Supported sensor types
 
-	Sketch => Include Library => Add .ZIP Library...
+| Sensor name   | I²C Addresses  |
+| ------------- | -------------- |
+|[SHT40](https://sensirion.com/products/catalog/SHT40/)| **0x44**, 0x45|
+|[SHT41](https://sensirion.com/products/catalog/SHT41/)| **0x44**, 0x45|
+|[SHT45](https://sensirion.com/products/catalog/SHT45/)| **0x44**, 0x45|
 
-Don't forget to **install the dependencies** listed below the same way via `Add
-.ZIP Library`
+The following instructions and examples use a *SHT40*.
 
-Note: Installation via the Arduino Library Manager is coming soon.
 
-# Dependencies
 
+## Installation of the library
+
+This library can be installed using the Arduino Library manager:
+Start the [Arduino IDE](http://www.arduino.cc/en/main/software) and open
+the Library Manager via
+
+`Sketch` ➔ `Include Library` ➔ `Manage Libraries...`
+
+Search for the `Sensirion I2C SHT4X` library in the `Filter
+your search...` field and install it by clicking the `install` button.
+
+If you cannot find it in the library manager, download the latest release as .zip file 
+and add it to your [Arduino IDE](http://www.arduino.cc/en/main/software) via
+
+`Sketch` ➔ `Include Library` ➔ `Add .ZIP Library...`
+
+Don't forget to **install the dependencies** listed below the same way via library 
+manager or `Add .ZIP Library`
+
+#### Dependencies
 * [Sensirion Core](https://github.com/Sensirion/arduino-core)
 
+## Sensor wiring
+
+Use the following pin description to connect your SHT4X to the standard I²C bus of your Arduino board:
+
+<img src="images/SHT40_pinout.png" width="300px">
+
+| *Pin* | *Cable Color* | *Name* | *Description*  | *Comments* |
+|-------|---------------|:------:|----------------|------------|
+| 1 | green | SDA | I2C: Serial data input / output | 
+| 2 | black | GND | Ground | 
+| 3 | yellow | SCL | I2C: Serial clock input | 
+| 4 | red | VDD | Supply Voltage | 1.1V to 3.6V
+
+The recommended voltage is 3.3V.
+
+Please refer to the datasheet for proper circuit setup. There are 3rd party boards for easy connection of the SHT4x sensor to your Arduino Board.
+
+### Board specific wiring
+You will find pinout schematics for recommended board models below:
+
+
+
+<details><summary>Arduino Uno</summary>
+<p>
+
+| *SHT4X* | *SHT4X Pin* | *Cable Color* | *Board Pin* |
+| :---: | --- | --- | --- |
+| SDA | 1 | green | D18/SDA |
+| GND | 2 | black | GND |
+| SCL | 3 | yellow | D19/SCL |
+| VDD | 4 | red | 3.3V |
+
+
+
+<img src="images/Arduino-Uno-Rev3-i2c-pinout-3.3V.png" width="600px">
+</p>
+</details>
+
+
+
+<details><summary>Arduino Nano</summary>
+<p>
+
+| *SHT4X* | *SHT4X Pin* | *Cable Color* | *Board Pin* |
+| :---: | --- | --- | --- |
+| SDA | 1 | green | A4 |
+| GND | 2 | black | GND |
+| SCL | 3 | yellow | A5 |
+| VDD | 4 | red | 3.3V |
+
+
 
-# Quick Start
+<img src="images/Arduino-Nano-i2c-pinout-3.3V.png" width="600px">
+</p>
+</details>
 
-1. Connect the SHT4X Sensor to your Arduino board's standard
-   I2C bus. Check the pinout of your Arduino board to find the correct pins.
-   The pinout of the SHT4X Sensor board can be found in the
-   data sheet.
 
-	* **VDD** of the SEK-SHT4X to the **3.3V** of your Arduino board
-	* **GND** of the SEK-SHT4X to the **GND** of your Arduino board
-	* **SCL** of the SEK-SHT4X to the **SCL** of your Arduino board
-	* **SDA** of the SEK-SHT4X to the **SDA** of your Arduino board
 
-2. Open the `exampleUsage` sample project within the Arduino IDE
+<details><summary>Arduino Micro</summary>
+<p>
 
-		File => Examples => Sensirion I2C SHT4X => exampleUsage
+| *SHT4X* | *SHT4X Pin* | *Cable Color* | *Board Pin* |
+| :---: | --- | --- | --- |
+| SDA | 1 | green | D2/SDA |
+| GND | 2 | black | GND |
+| SCL | 3 | yellow | ~D3/SCL |
+| VDD | 4 | red | 3.3V |
 
-3. Click the `Upload` button in the Arduino IDE or
 
-		Sketch => Upload
+
+<img src="images/Arduino-Micro-i2c-pinout-3.3V.png" width="600px">
+</p>
+</details>
+
+
+
+<details><summary>Arduino Mega 2560</summary>
+<p>
+
+| *SHT4X* | *SHT4X Pin* | *Cable Color* | *Board Pin* |
+| :---: | --- | --- | --- |
+| SDA | 1 | green | D20/SDA |
+| GND | 2 | black | GND |
+| SCL | 3 | yellow | D21/SCL |
+| VDD | 4 | red | 3.3V |
+
+
+
+<img src="images/Arduino-Mega-2560-Rev3-i2c-pinout-3.3V.png" width="600px">
+</p>
+</details>
+
+
+
+<details><summary>ESP32 DevKitC</summary>
+<p>
+
+| *SHT4X* | *SHT4X Pin* | *Cable Color* | *Board Pin* |
+| :---: | --- | --- | --- |
+| SDA | 1 | green | GPIO 21 |
+| GND | 2 | black | GND |
+| SCL | 3 | yellow | GPIO 22 |
+| VDD | 4 | red | 3V3 |
+
+
+
+<img src="images/esp32-devkitc-i2c-pinout-3.3V.png" width="600px">
+</p>
+</details>
+
+
+## Quick Start
+
+1. Install the libraries and dependencies according to [Installation of the library](#installation-of-the-library)
+
+2. Connect the SHT4X sensor to your Arduino as explained in [Sensor wiring](#sensor-wiring)
+
+3. Open the `exampleUsage` sample project within the Arduino IDE:
+
+   `File` ➔ `Examples` ➔ `Sensirion I2C SHT4X` ➔ `exampleUsage`
+
+
+   The provided example is working with a SHT40, I²C address 0x44.
+   In order to use the code with another product or I²C address you need to change it in the code of `exampleUsage`. 
+   You find the list with pre-defined addresses in `src/SensirionI2CSht4x.h`.
+
+
+5. Click the `Upload` button in the Arduino IDE or `Sketch` ➔ `Upload`
 
 4. When the upload process has finished, open the `Serial Monitor` or `Serial
    Plotter` via the `Tools` menu to observe the measurement values. Note that
-   the `Baud Rate` in the corresponding window has to be set to `115200 baud`.
+   the `Baud Rate` in the used tool has to be set to `115200 baud`.
 
-# Contributing
+## Contributing
 
 **Contributions are welcome!**
 
@@ -74,6 +200,7 @@ clang-format -i src/*.cpp src/*.h
 Note that differences from this formatting will result in a failed build until
 they are fixed.
 
-# License
+
+## License
 
 See [LICENSE](LICENSE).