add sps30 library

Author: PaulaScharf

CMakeLists.txt

@@ -80,6 +80,7 @@ set(CORE_SRCS
   )
 
 set(ARDUINO_ALL_LIBRARIES
+  sensirion_sps
   ArduinoOTA
   AsyncUDP
   BLE
@@ -120,6 +121,12 @@ set(ARDUINO_ALL_LIBRARIES
   Zigbee
   )
 
+set(ARDUINO_LIBRARY_sensirion_sps_SRCS libraries/sensirion-sps/sps30.cpp 
+  libraries/sensirion-sps/sps_git_version.cpp
+  libraries/sensirion-sps/sensirion_hw_i2c_implementation.cpp
+  libraries/sensirion-sps/sensirion_common.cpp
+  libraries/sensirion-sps/i2c_master_lib.cpp)
+
 set(ARDUINO_LIBRARY_ArduinoOTA_SRCS libraries/ArduinoOTA/src/ArduinoOTA.cpp)
 
 set(ARDUINO_LIBRARY_AsyncUDP_SRCS libraries/AsyncUDP/src/AsyncUDP.cpp)
@@ -356,7 +363,7 @@ foreach(libname IN LISTS ARDUINO_ALL_LIBRARIES)
   endif()
 endforeach()
 
-set(includedirs variants/${CONFIG_ARDUINO_VARIANT}/ cores/esp32/ ${ARDUINO_LIBRARIES_INCLUDEDIRS})
+set(includedirs variants/${CONFIG_ARDUINO_VARIANT}/ cores/esp32/ ${ARDUINO_LIBRARIES_INCLUDEDIRS} libraries/sensirion-sps)
 set(srcs ${CORE_SRCS} ${ARDUINO_LIBRARIES_SRCS})
 set(priv_includes cores/esp32/libb64)
 set(requires spi_flash esp_partition mbedtls wpa_supplicant esp_adc esp_eth http_parser esp_ringbuf esp_driver_gptimer esp_driver_usb_serial_jtag driver)

libraries/sensirion-sps/AUTHORS

@@ -0,0 +1 @@
+Johannes Winkelmann <[email protected]>

libraries/sensirion-sps/LICENSE.i2c_master_lib

@@ -0,0 +1,31 @@
+This package includes the I2C master library from
+  https://github.com/DSSCircuits/I2C-Master-Library
+in order to work around limitations in the I2C stack on certain Arduino boards (including the Arduino Uno).
+
+More information can be found here:
+  http://dsscircuits.com/index.php/articles/66-arduino-i2c-master-library
+
+
+
+Copyright (c) 2011-2012 Wayne Truchsess.  All right reserved.
+
+This is a modified version of the Arduino Wire/TWI
+library.  Functions were rewritten to provide more functionality
+and also the use of Repeated Start.  Some I2C devices will not
+function correctly without the use of a Repeated Start.  The
+initial version of this library only supports the Master.
+
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 2.1 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

libraries/sensirion-sps/LICENSE.sps30

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2017-2018, Sensirion AG
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* 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.
+
+* Neither the name of Sensirion AG 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.

libraries/sensirion-sps/README.md

@@ -0,0 +1,102 @@
+# Arduino library for the SPS30 particulate matter sensor
+
+To learn more about the SPS30, please visit https://www.sensirion.com/sps30/.
+For support questions on the SPS30, please visit https://sensirion.com/contact.
+
+This library is using the code from Sensirion's
+[embedded-sps](https://github.com/Sensirion/embedded-sps) library, and adding a
+handful of changes to adapt to Arduino.
+
+Most notably, for AVR based platforms (like Arduino Uno and friends), this is
+using an alternative
+[I2C Master Library](https://github.com/DSSCircuits/I2C-Master-Library) to work
+around the I2C buffer size limit that exists on those boards.
+
+## Compatibility
+
+This library has been tested on the following platforms:
+- AVR based Arduino, like Arduino Uno
+- ESP8266, using v2.5.0 or newer (Tested on Adafruit Feather Huzzah ESP8266)
+- ESP32, using v1.0.1 or newer (Tested on Adafruit Feather Huzzah ESP32)
+- SAMD (tested on Arduino MKR 1010)
+
+## Hardware setup
+
+**Important Notes:** 
+
+* The SPS30 requires 5V supply voltage +/-0.5V in order to provide correct
+  output values; the SPS30 should be compatible with 3.3V I2C levels, so as 
+  long as the supply voltage is correct the SPS30 should work fine with 3.3V 
+  setups
+* Make sure that the SPS30's Pin 4 ("Interface select") is connected to GND, on
+  power-up of the sensor, otherwise the sensor works in UART instead of I2C
+  mode and this driver will not detect the sensor. Note that the
+  interface-select configuration is read on every start of the sensor including
+  after a soft-reset.
+
+
+
+### ESP8266 partial legacy support
+
+This library automatically detects ESP8266 core versions 2.3.0, 2.4.0, 2.4.1 and
+2.4.2 and supports a limited subset of functionality on there. The following
+features are not available:
+- Reading out number concentrations,
+- Reading out the average particle size
+- Reading out the serial number
+
+## Installation
+
+### Through the Arduino IDE
+
+This library is available through Arduino IDE's Library Manager. To install,
+select ```Tools```> ```Manage Libraries...```, then search for
+```sensirion-sps```. Select the matching library and press ```Install```.
+
+### Manual installation
+
+For manual installation, follow these steps:
+
+1. Download the latest ZIP file from the
+   [Github release page](https://github.com/Sensirion/arduino-sps/releases/latest)
+1. Start the Arduino IDE
+1. Select ```Sketch > Include Library > Add .ZIP Library...```
+1. A dialog will open; here, select the file you selected in step 1
+
+## Usage
+
+### Serial Monitor (Text output)
+
+1. Open the example from ```File > Examples > arduino-sps > sps30```.
+1. Open the serial monitor from the Tools menu
+1. Press the "Upload" button to compile and upload the sketch
+
+If you check the serial monitor window, you should see something like this:
+
+![Serial monitor](doc/sps30-arduino-serial-monitor.jpg)
+
+### Serial Plotter (Graphical output)
+
+1. Open the example from ```File > Examples > arduino-sps > sps30```.
+1. Open the serial plotter from the Tools menu (if you have the serial monitor
+   open, you'll need to close it first)
+1. Uncomment line 8 of the sample program; it should now read
+   ```#define PLOTTER_FORMAT```
+1. Press the "Upload" button to compile and upload the sketch
+
+If you check the serial plotter window, you should see something like this:
+
+
+![Serial monitor](doc/sps30-arduino-serial-plotter.jpg)
+
+
+## FAQ: How PMx is defined / Why values are the same
+
+A frequently asked question about values that are the same, which seems unlikely. However, this is due to the definition of PM_x_, that says that it's particles of diameter _x_ and smaller. As such, PM10 includes all particles of diameter 10 μm and smaller, and therefore includes particles from PM4 (which itself includes particles from PM2.5). To illustrate, here's a diagram that shows this 
+
+![How PMx is defined](https://user-images.githubusercontent.com/1300460/121040377-b445d880-c766-11eb-82d9-241dcdefab1f.png)
+
+In this example:
+- PM2.5 would be 3.1 μg/m^3
+- PM4 would be 3.2 μg/m^3 (3.1 particles [2.5 and smaller] + 0.1 [>2.5, <= 4.0])
+- PM10 would be 3.2 μg/m^3 (3.1 particles [2.5 and smaller] + 0.1 [>2.5, <= 4.0] + 0 [>4.0 <= 10])

libraries/sensirion-sps/doc/sps30-arduino-serial-monitor.jpg

@@ -0,0 +1,134 @@
+#include <sps30.h>
+
+// Example arduino sketch, based on 
+// https://github.com/Sensirion/embedded-sps/blob/master/sps30-i2c/sps30_example_usage.c
+
+
+// uncomment the next line to use the serial plotter
+// #define PLOTTER_FORMAT
+
+void setup() {
+  int16_t ret;
+  uint8_t auto_clean_days = 4;
+  uint32_t auto_clean;
+
+  Serial.begin(9600);
+  delay(2000);
+
+  sensirion_i2c_init();
+
+  while (sps30_probe() != 0) {
+    Serial.print("SPS sensor probing failed\n");
+    delay(500);
+  }
+
+#ifndef PLOTTER_FORMAT
+  Serial.print("SPS sensor probing successful\n");
+#endif /* PLOTTER_FORMAT */
+
+  ret = sps30_set_fan_auto_cleaning_interval_days(auto_clean_days);
+  if (ret) {
+    Serial.print("error setting the auto-clean interval: ");
+    Serial.println(ret);
+  }
+
+  ret = sps30_start_measurement();
+  if (ret < 0) {
+    Serial.print("error starting measurement\n");
+  }
+
+#ifndef PLOTTER_FORMAT
+  Serial.print("measurements started\n");
+#endif /* PLOTTER_FORMAT */
+
+#ifdef SPS30_LIMITED_I2C_BUFFER_SIZE
+  Serial.print("Your Arduino hardware has a limitation that only\n");
+  Serial.print("  allows reading the mass concentrations. For more\n");
+  Serial.print("  information, please check\n");
+  Serial.print("  https://github.com/Sensirion/arduino-sps#esp8266-partial-legacy-support\n");
+  Serial.print("\n");
+  delay(2000);
+#endif
+
+  delay(1000);
+}
+
+void loop() {
+  struct sps30_measurement m;
+  char serial[SPS30_MAX_SERIAL_LEN];
+  uint16_t data_ready;
+  int16_t ret;
+
+  do {
+    ret = sps30_read_data_ready(&data_ready);
+    if (ret < 0) {
+      Serial.print("error reading data-ready flag: ");
+      Serial.println(ret);
+    } else if (!data_ready)
+      Serial.print("data not ready, no new measurement available\n");
+    else
+      break;
+    delay(100); /* retry in 100ms */
+  } while (1);
+
+  ret = sps30_read_measurement(&m);
+  if (ret < 0) {
+    Serial.print("error reading measurement\n");
+  } else {
+
+#ifndef PLOTTER_FORMAT
+    Serial.print("PM  1.0: ");
+    Serial.println(m.mc_1p0);
+    Serial.print("PM  2.5: ");
+    Serial.println(m.mc_2p5);
+    Serial.print("PM  4.0: ");
+    Serial.println(m.mc_4p0);
+    Serial.print("PM 10.0: ");
+    Serial.println(m.mc_10p0);
+
+#ifndef SPS30_LIMITED_I2C_BUFFER_SIZE
+    Serial.print("NC  0.5: ");
+    Serial.println(m.nc_0p5);
+    Serial.print("NC  1.0: ");
+    Serial.println(m.nc_1p0);
+    Serial.print("NC  2.5: ");
+    Serial.println(m.nc_2p5);
+    Serial.print("NC  4.0: ");
+    Serial.println(m.nc_4p0);
+    Serial.print("NC 10.0: ");
+    Serial.println(m.nc_10p0);
+
+    Serial.print("Typical particle size: ");
+    Serial.println(m.typical_particle_size);
+#endif
+
+    Serial.println();
+
+#else
+    // since all values include particles smaller than X, if we want to create buckets we 
+    // need to subtract the smaller particle count. 
+    // This will create buckets (all values in micro meters):
+    // - particles        <= 0,5
+    // - particles > 0.5, <= 1
+    // - particles > 1,   <= 2.5
+    // - particles > 2.5, <= 4
+    // - particles > 4,   <= 10
+
+    Serial.print(m.nc_0p5);
+    Serial.print(" ");
+    Serial.print(m.nc_1p0  - m.nc_0p5);
+    Serial.print(" ");
+    Serial.print(m.nc_2p5  - m.nc_1p0);
+    Serial.print(" ");
+    Serial.print(m.nc_4p0  - m.nc_2p5);
+    Serial.print(" ");
+    Serial.print(m.nc_10p0 - m.nc_4p0);
+    Serial.println();
+
+
+#endif /* PLOTTER_FORMAT */
+
+  }
+
+  delay(1000);
+}