Merge pull request #1 from Sensirion/Ready4Release

Ready4 release
Sensirion · Feb 22, 2024 · d0ba8b4 · d0ba8b4
2 parents eb85bfc + 98c79ef
commit d0ba8b4
Show file tree

Hide file tree

Showing 15 changed files with 146 additions and 107 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 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] - TBD 
+## [0.1.0] 
 ### Added
 - Initial release
 

diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright 2024 Sensirion AG
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/LICENSE.txt b/LICENSE.txt
diff --git a/README.md b/README.md
@@ -1,21 +1,81 @@
-# Arduino BLE Client Library for Sensirion Gadgets 
+# Arduino Sensirion UPT BLE Auto Detection
 
 This library enables you to retrieve live measurements form your own Do-It-Yourself BLE enabled sensor gadget or most Sensirion Gadgets on the ESP32 platform. 
 
+## Supported Gadgets
+* AQ Minion
+* MyCO2
+* SHT3X Gadget
+* SHT40 Gadget
+* SHT43 Gadget
+* [DIY BLE Gadget](https://github.com/Sensirion/arduino-ble-gadget)
+
 ### Key features are
 
-**Please see the examples provided as reference on how to use this library.**
+**Please see [the example provided as reference](examples/GetLiveValues/GetLiveValues.ino) on how to use this library.**
 
+## How to use
 ### Recommended Hardware
 
-This project was developed and tested on Espressif [ESP32 DevKitC](https://www.espressif.com/en/products/devkits/esp32-devkitc) hardware (see e.g. [ESP32-DevKitC-32D](https://www.digikey.com/en/products/detail/espressif-systems/ESP32-DEVKITC-32D/9356990))
+This project was developed and tested on Espressif [ESP32 DevKitC](https://www.espressif.com/en/products/devkits/esp32-devkitc) hardware (see e.g. [ESP32-DevKitC-32D](https://www.digikey.com/en/products/detail/espressif-systems/ESP32-DEVKITC-32D/9356990)).
+This library requires standard library compatibility. Some boards such as Arduino AVR Uno do not ship with this functionnality.
+
+### 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).
+
+This library can be installed easily 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 UPT BLE 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 dependencies:
+* [NimBLE-Arduino](https://www.arduino.cc/reference/en/libraries/nimble-arduino/).
+* [Sensirion UPT Core](https://www.arduino.cc/reference/en/libraries/sensirion-upt-core/)
+
+Alternatively, the library can also be added manually. To do this, download the latest release from github as a .zip file via
+
+    Code => Download Zip
+
+and add it to the [Arduino IDE](http://www.arduino.cc/en/main/software) via
+
+    Sketch => Include Library => Add .ZIP Library...
 
-## Repository Contents
+In this second case, you'll have to also add all dependencies the same way.
 
-* **/examples** - Example sketches for the library (.ino). Run these from the Arduino IDE. 
-* **/src** - Source files for the library (.cpp, .h).
-* **library.properties** - General library properties for the Arduino package manager. 
+### 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).
+
+To use the library, add the following dependencies to your `platformio.ini`'s `lib_deps`:
+
+```control
+lib_deps =
+    Sensirion UPT BLE 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 UPT BLE Auto Detection"
+```
+
+To test the default example (`GetLiveValues`), use the following platformio command from the project's root directory (the one containing the `platformio.ini` file):
+```bash
+pio run -t upload
+```
+and start the Serial monitor with
+```bash
+pio device monitor
+```
+
+In case you're using some other board, it is recommended you create a new environment in the `platformio.ini` file, using the existing environment as a template. Find your `board` parameter [here](https://docs.platformio.org/en/latest/boards/index.html).
 
 ## License
 
 See [LICENSE](LICENSE.txt).
+
+## Credits
+
+https://github.com/MBjoern/arduino-ble-sensiscan
diff --git a/examples/GetLiveValues/GetLiveValues.ino b/examples/GetLiveValues/GetLiveValues.ino
@@ -1,11 +1,8 @@
-#include "ArduinoBleSensiScan.h"
+#include "Sensirion_upt_ble_auto_detection.h"
 #include <Arduino.h>
 
-void printMeasurement(const Measurement& measurement);
 void printScanResults(
     const std::map<uint16_t, std::vector<Measurement>>& scanResults);
-std::string arrayifyDeviceID(uint64_t deviceID);
-void printMACAddess(const std::string& macAddress);
 
 SensiScan sensiScan = SensiScan();
 

diff --git a/keywords.txt b/keywords.txt
@@ -0,0 +1,20 @@
+#######################################
+# Syntax Coloring Map
+#######################################
+
+#######################################
+# Datatypes (KEYWORD1)
+#######################################
+
+SensiScan	KEYWORD1
+
+#######################################
+# Methods and Functions (KEYWORD2)
+#######################################
+begin	KEYWORD2
+getScanResults	KEYWORD2
+keepAlive	KEYWORD2
+
+######################################
+# Constants (LITERAL1)
+#######################################
diff --git a/library.properties b/library.properties
@@ -1,11 +1,11 @@
-name=BLE Client for Sensirion Gadgets
+name=Sensirion UPT BLE Auto Detection
 version=0.1.0
-author=Bjoern Muntwyler
-maintainer=Bjoern Muntwyler
-sentence=Library to get live values from Sensirion Gadgets using BLE on ESP32.
-paragraph=Library to get live values from Sensirion Gadgets using BLE on ESP32.
-category=Communication
-url=https://github.com/MBjoern/arduino-ble-sensiscan
-architectures=*
-depends=NimBLE-Arduino
-
+author=Bjoern Muntwyler, Maximilian Paulsen
+maintainer=Sensirion AG <sensirion.com>
+sentence=Automatically detects Sensirion Gadgets via Bluetooth and reads out measurement data.
+paragraph=Automatically detects Sensirion Gadgets via Bluetooth and reads out measurement data.
+category=Communication, Sensors
+url=
+architectures=esp32
+depends=NimBLE-Arduino, Sensirion UPT Core
+includes=Sensirion_upt_ble_auto_detection.h
diff --git a/platformio.ini b/platformio.ini
@@ -7,13 +7,14 @@
 ;
 ; Please visit documentation for the other options and examples
 ; https://docs.platformio.org/page/projectconf.html
+
 [platformio]
 default_envs = GetLiveValues
 
 [common]
 lib_deps_external =
-    Sensirion UPT Core
-    NimBLE-Arduino
+    h2zero/NimBLE-Arduino
+    Sensirion/Sensirion UPT Core
 
 example_srcdir = ${PROJECT_DIR}/examples/GetLiveValues/
 
@@ -23,11 +24,9 @@ platform = espressif32
 framework = arduino
 monitor_speed = 115200
 extra_scripts =
-    pre:make_cpp_files.py
+    pre:py_scripts/make_cpp_files.py
 lib_deps =
     ${common.lib_deps_external}
-lib_extra_dirs =
-	${PROJECT_DIR}/src/
 check_tool = cppcheck, clangtidy
 check_skip_packages = yes
 check_flags=
@@ -39,11 +38,11 @@ check_src_filters =
 
 ; Board and example specific environments
 [env:GetLiveValues]
-build_src_filter = +<*> -<.git/> -<.svn/> +<${common.example_srcdir}>
+build_src_filter = +<*> -<.git/> +<${common.example_srcdir}>
 board = esp32dev
 
 [env:develop]
-build_src_filter = +<*> -<.git/> -<.svn/> +<${common.example_srcdir}>
+build_src_filter = +<*> -<.git/> +<${common.example_srcdir}>
 board = lilygo-t-display-s3
 monitor_filters = esp32_exception_decoder
 build_type = debug

diff --git a/make_cpp_files.py → py_scripts/make_cpp_files.py b/make_cpp_files.py → py_scripts/make_cpp_files.py
diff --git a/src/BleClient.h b/src/BleClient.h
@@ -1,11 +1,5 @@
-/*
- BleClient.h
- Created by Bjoern Muntwyler, 2021.
- Released under BSD-3 licence
- */
-
-#ifndef ARDUINO_BLE_SENSISCAN_BLECLIENT_H
-#define ARDUINO_BLE_SENSISCAN_BLECLIENT_H
+#ifndef _SENSIRION_UPT_BLE_AUTO_DETECTION_BLECLIENT_H
+#define _SENSIRION_UPT_BLE_AUTO_DETECTION_BLECLIENT_H
 
 #include "Arduino.h"
 #include "BleClientCallback.h"
@@ -19,4 +13,4 @@ class BleClient {
     virtual void keepAlive() = 0;
 };
 
-#endif // ARDUINO_BLE_SENSISCAN_BLECLIENT_H
+#endif /* _SENSIRION_UPT_BLE_AUTO_DETECTION_BLECLIENT_H */
diff --git a/src/BleClientCallback.h b/src/BleClientCallback.h
@@ -1,11 +1,5 @@
-/*
- BleClientCallback.h
- Created by Bjoern Muntwyler, 2021.
- Released under BSD-3 licence
- */
-
-#ifndef ARDUINO_BLE_SENSISCAN_BLECLIENTCALLBACK_H
-#define ARDUINO_BLE_SENSISCAN_BLECLIENTCALLBACK_H
+#ifndef _SENSIRION_UPT_BLE_AUTO_DETECTION_BLECLIENTCALLBACK_H
+#define _SENSIRION_UPT_BLE_AUTO_DETECTION_BLECLIENTCALLBACK_H
 
 class BleClientCallback {
   public:
@@ -16,4 +10,4 @@ class BleClientCallback {
                                          std::string data);
 };
 
-#endif // ARDUINO_BLE_SENSISCAN_BLECLIENTCALLBACK_H
+#endif /* _SENSIRION_UPT_BLE_AUTO_DETECTION_BLECLIENTCALLBACK_H */
diff --git a/src/NimBleClient.cpp b/src/NimBleClient.cpp
@@ -1,9 +1,3 @@
-/*
- NimBleClient.cpp
- Created by Bjoern Muntwyler, 2021.
- Released under BSD-3 licence
- */
-
 #include "NimBleClient.h"
 
 void NimBleClient::begin(BleClientCallback* callback) {

diff --git a/src/NimBleClient.h b/src/NimBleClient.h
@@ -1,11 +1,5 @@
-/*
- NimBleClient.h
- Created by Bjoern Muntwyler, 2021.
- Released under BSD-3 licence
- */
-
-#ifndef ARDUINO_BLE_SENSISCAN_NIMBLECLIENT_H
-#define ARDUINO_BLE_SENSISCAN_NIMBLECLIENT_H
+#ifndef _SENSIRION_UPT_BLE_AUTO_DETECTION_NIMBLECLIENT_H
+#define _SENSIRION_UPT_BLE_AUTO_DETECTION_NIMBLECLIENT_H
 
 #include "BleClient.h"
 #include "NimBLEDevice.h"
@@ -23,4 +17,4 @@ class NimBleClient: public BleClient, public NimBLEAdvertisedDeviceCallbacks {
     void onResult(NimBLEAdvertisedDevice* advertisedDevice);
 };
 
-#endif // ARDUINO_BLE_SENSISCAN_NIMBLECLIENT_H
+#endif /* _SENSIRION_UPT_BLE_AUTO_DETECTION_NIMBLECLIENT_H */
diff --git a/src/ArduinoBleSensiScan.cpp → src/Sensirion_upt_ble_auto_detection.cpp b/src/ArduinoBleSensiScan.cpp → src/Sensirion_upt_ble_auto_detection.cpp
@@ -1,10 +1,4 @@
-/*
- ArduinoBleSensiScan.cpp - Library for collecting sensor data via Bluetooth.
- Created by Bjoern Muntwyler, 2021.
- Released under BSD-3 licence
- */
-
-#include "ArduinoBleSensiScan.h"
+#include "Sensirion_upt_ble_auto_detection.h"
 #include "NimBleClient.h"
 
 const int COMPANY_ID_FILTER = 54534;

diff --git a/src/ArduinoBleSensiScan.h → src/Sensirion_upt_ble_auto_detection.h b/src/ArduinoBleSensiScan.h → src/Sensirion_upt_ble_auto_detection.h
@@ -1,11 +1,5 @@
-/*
- ArduinoBleSensiScan.h - Library for collecting sensor data via Bluetooth.
- Created by Bjoern Muntwyler, 2021.
- Released under BSD-3 licence
- */
-
-#ifndef ARDUINO_BLE_SENSISCAN_H
-#define ARDUINO_BLE_SENSISCAN_H
+#ifndef _SENSIRION_UPT_BLE_AUTO_DETECTION_H_
+#define _SENSIRION_UPT_BLE_AUTO_DETECTION_H_
 
 #include "Arduino.h"
 #include "BleClient.h"
@@ -34,4 +28,4 @@ class SensiScan: public BleClientCallback {
                        std::vector<Measurement>& samples);
 };
 
-#endif // ARDUINO_BLE_SENSISCAN_H
+#endif /* _SENSIRION_UPT_BLE_AUTO_DETECTION_H_ */