LoraWanDustSensor

From RevSpace
Jump to navigation Jump to search
Project LoRaWAN dust Sensor
LoraWanDustSensor.jpg
LoRaWAN airborne particulate matter sensor
Status In progress
Contact bertrik
Last Update 2021-04-24

What is it?

This is a companion project of LoraLuftdatenForwarder.

The concept consists of:

  • a sensor that measures airborne particulate matter and sends the measurement data using LoRaWAN to TheThingsNetwork (TTN)
  • a forwarder application that collects the data from TTN and forwards it to sensor.community (formerly luftdaten), opensensemap, mycayenne dashboard, etc.

Features

  • LoRaWAN-enabled particulate matter sensor node, based on off-the-shelf ESP32+LoRa hardware, specifically the TTGO LoRa32 v1 and Heltec LoRa32 v2 board.
  • Works with the most recent version (v3) of TheThingsNetwork infrastructure
  • Uses over-the-air-activation (OTAA), parameters have a sensible default and are stored in EEPROM:
    • Device EUI defaults to the ESP32 built-in unique id
    • APP EUI and APP key can be configured using the serial port
  • Uses LoRaWAN automatic-data-rate (ADR) to optimise data rate and transmit power
  • Data upload interval defaults to 5 minutes (SF7), scales with spreading-factor to satisfy the fair-use-policy of TheThingsNetwork
  • Data is encoded as Cayenne LPP, no custom payload decoder needed
  • Supported sensors (auto-detected):
    • Nova Fitness SDS011 particulate matter sensor, provides PM10, PM2.5
    • Sensirion SPS30 particulate matter sensor, provides PM10, PM4.0, PM2.5, PM1.0
    • BME280 humidity/temperature/pressure sensor, provides humidity, temperature, barometric pressure
  • Firmware can be upgraded over-the-air (WiFi)

I am publishing all source code on github and documentation on this wiki.

Similar nodes

A similar thing has been done by:

One thing in particular that my concept does better than existing solutions is to use proper OTAA for the LoRa connection to TTN. OTAA means over-the-air-activation and is a mechanism to dynamically negotiate encryption keys and communication settings.

Next steps

  • Implement a simple command set through LoRaWAN downlink commands, for example:
    • a command to trigger an immediate reboot of the node
    • a command to assist in geolocation, performing a WiFi AP scan:
      • Per AP we send 8 bytes: 1) MAC 2) RSSI 3) channel, so a total of 6 APs can be send in 48 bytes
    • create a basic command structure: command port, payload encoding, e.g. 1st byte is command id
  • Implement the ESP-Now lamp/display protocol, for easy visualisation, see https://revspace.nl/StofAnanas#Next_generation.
    • Start with sending the particulate matter measurements
    • Add a suggested colour indication later
  • Improve firmware update:
    • Show current software version in the welcome screen
    • Show hardware model (TTGO or Heltec) in the welcome screen

Links

Useful links for the TTGO LoRa board:

Hardware

The node is based on the Arduino framework:

  • For the processor board, either the TTGO ESP32 board ("ttgo-lora32-v1") or the Heltec LoRa32 V2 can be used.
  • The particulate matter sensor is the SDS011 or the SPS30, the sensor type is auto-detected.
  • The humidity/temperature sensor is the BME280 (superior to the DHT11/22).

Pinout

TTGO LoRa v1 Heltec LoRa v2 Sensor Remark
5V 5V 5V (SDS pin 3) triple-check this, swapping 5V/GND destroys the SDS011
GND GND GND (SDS pin 5) triple-check this, swapping 5V/GND destroys the SDS011
GPIO23 GPIO23 RXD (SDS pin 6) same pin for SPS30
GPIO22 GPIO22 TXD (SDS pin 7) same pin for SPS30
3.3V 3.3V/Vext BME280 3V Both Vext and 3.3V can be used
GND GND BME280 GND ground
GPIO15 GPIO15 BME280 SCL
GPIO4 GPIO4 BME280 SDA

For reference:

Firmware

Compile and upload the firmware

Source code is hosted on github:

  • Arduino node, written in C/Arduino, built using platformio. This firmware joins TTN by OTAA and sends the measurement data using Cayenne.
  • TTN-to-luftdaten forwarder, written in Java, built using gradle. This picks up the Cayenne encoded data and forwards it to the Luftdaten API.

On Linux, with platformio (the command line tool), instructions for Debian Linux are:

  • install platformio:
 sudo apt install python3-pip
 sudo pip3 install platformio
 pio update
  • get the source from github:
 git clone https://github.com/bertrik/LoraWanPmSensor
  • enter the correct directory:
 cd LoraWanPmSensor
 cd Esp32PmSensor
  • compile and upload (for TTGO LoRa32 v1 board):
 pio run -e ttgov1 -t upload

or (for Heltec LoRa32 v2 board): 

 pio run -e heltecv2 -t upload

Firmware update

Firmware update

Once the initial firmware has been loaded into the device, further firmware updates can be done over WiFi:

  • Depending on the board you have, check that you have either a ttgov1.bin or heltecv2.bin firmware file
  • Connect to the access point set up by the node, it's called 'ESP-XXXXXXXXXXXX', where XX is the same as the LoRaWAN device EUI
  • Using a browser, go to http://192.168.4.1 , a firmware selection screen appears as shown on the right
  • Select the appropriate BIN file, the will be updated and reboot

Payload encoding

My firmware uses the Cayenne LPP (low power payload) encoding.

Cayenne

It's reasonably compact, it's a standard format, you can get a preview of the data in the TTN console. Interacts nicely with other platforms.

Specification for Cayenne LPP 2.0

Over-the-air payload encoding:

  • 4 bytes: PM10: analog input (type 2), channel id 1, with value in units of 0.01 ug/m3, saturated to 327.67 ug/m3
  • 4 bytes: PM2.5: analog input (type 2), channel id 2, with value in units of 0.01 ug/m3, saturated to 327.67 ug/m3
  • 4 bytes: Temperature: temperature (type 103), with value in units of 0.1 degrees celcius
  • 3 bytes: Humidity: humidity (type 104), with value in units of 0.5 %

Particulate matter concentrations higher than 327.67 ug/m3 are saturated to 327.67, this is the maximum that can be represented as analog value in Cayenne.

Optionally:

  • 4 bytes: PM1.0: analog input (type 2), channel id 0, with value in units of 0.01 ug/m3, saturated to 327.67 ug/m3
  • 4 bytes: Pressure: barometer (type 115), with value in units of 0.1 mbar, or 10 Pa (optional)

A nice thing about Cayenne is that you can simply leave items out if you don't support them, which results in a shorter yet still valid message.

Example: 

 0x01 0x01 0xXX 0xXX  0x02 0x01 0xYY 0xYY  0x03 0x67 0xTT 0xTT  0x04 0x68 0xHH
 <== PM10 value ===>  <== PM2.5 value ==>  <== temperature ==>  <= humidity =>

Total payload size is 15 bytes. The LoRaWAN header adds 13 bytes (at least).

Particulate matter values encoded are averaged over the measurement interval.

Update: discovered that the Cayenne standard *does* actually support a "particle concentration" id, this is 125, derived from IPSO id 3325 http://www.openmobilealliance.org/tech/profiles/lwm2m/3325.xml . No idea yet though how to specify the type of particle measurement, if there's any convention for PM10, PM2.5, etc. The resolution is only 1 ppm, with typical sensors delivering 0.1 ppm resolution.

Binary

How other projects encode the data:

A smaller payload means less time in the air, smaller chance of collision with other LoRaWAN packets and more packets per hour. However, there is always an overhead from the LoRaWAN package (minimum 13 bytes), so using the smallest encoding (5 bytes) compared to the largest (16 bytes), reduces the on-air-time by only 23%.

LoraWan time budget

The number of bytes per telemetry packet and the number of packets sent per day determine how much of the available "airtime" we use. TheThingsNetwork states a fair-use-policy of 30 seconds per day total uplink time.

Consider the following:

  • radio regulations generally have a 1% duty cycle requirement for the two bands used by the 8 LoRaWAN (EU) frequencies, so according to the legal limits, there is about (86400s x 1% x 2bands) = 1728 seconds per day send time at the best case.
  • TheThingsNetwork has a FUP of 30s of data upload per day. This is actually a *lot* more strict than allowed purely by radio regulations.
  • The sensor.community backend runs on a 5 minute interval, or 288 measurements per day.
  • The default sensor.community WiFi firmware sends new data every 145s by default

With the TTN FUP of 30s upload per day and 5 minute upload interval, we can spend 30s / 288 = 104 ms on each transmission.

Using the LoRaWAN airtime calculator we can determine which modes can be used. At 15 bytes payload, this is only possible at SF7, the highest LoRa speed. Stretching the TTN guideline a bit, say by a factor 2, we can achieve those transfers still only at SF7 and SF8. So you need to be relatively close to a gateway.

In terms of interval:

  • SF7: payload 17 bytes -> 71.9 ms/transmission -> every 3m27s
  • SF8: payload 17 bytes -> 123,4 ms/transmission -> every 5m55s
  • SF9: payload 17 bytes -> 226,3 ms/transmission -> every 10m32s
  • SF10: payload 17 bytes -> 452.6 ms/transmission -> every 21m43s

With a smaller payload, can we use higher spreading factors? :

  • smallest possible binary payload is 4 bytes (PM10 and PM2.5, no temperature, no humidity): SF7 takes 51.5 ms, SF8 takes 92.7 ms, SF9 takes 164.9 ms
  • smallest Cayenne payload is 8 bytes (PM10 and PM2.5, no temperature, no humidity): SF7 takes 56.6 ms, SF8 takes 102.9 ms, SF9 takes 185.3 ms

So, in conclusion: With the FUP of TTN and use of Cayenne encoding, you can just barely send enough data to transport PM data! Also note that the payload size does not actually differ *that* much, this is because of the LoRaWAN overhead of 13 bytes minimum and pre-amble symbols which are sent anyway.

Node design

Source code for the particulate matter measurement node can be found on the github page.

The luftdaten backend has a 5 minute "heartbeat", so at least one measurement per 5 minutes should be sent to avoid disappearing from the map.

Measurements run in a cycle running through the following states:

  • INIT: determine presence of the SDS011, print the SDS011 serial number
  • IDLE: wait until the start of the cycle, then turn on the fan
  • WARMUP: wait 20 seconds while the sensor "warms up"
  • MEASURE: measure 10 seconds, then turn off fan, calculate median/average and send LoRaWAN message

Building with platformio

Platformio is used to compile and upload the code to the node.

To install platformio (example for Debian): 

 sudo apt install python3-pip
 sudo pip3 install platformio
 pio update

To compile and upload: 

 pio run -t upload

TTN key provisioning

The node needs to be registered at TheThingsNetwork, in order for its messages to be accepted by the TTN.

To keep things simple, there is no key provisioning for the nodes themselves. All nodes use the same firmware with the same APP EUI and the same APP KEY. The thing that makes each node unique is its DEVEUI, this is derived from the built-in unique ESP32 id.

On the TTN side, each node will have to be registered by its DEV EUI. The following scheme is used to make TTN provisioning as simple as possible:

  • Each node can be programmed with the *same* firmware, no source code modification is required
  • The node administrator needs to enter the following properties at the TTN console, for each node:
    • The Device EUI is derived from the node-specific ESP32 MAC address, the node shows this on its OLED
    • The App EUI has a fixed value and is the same for all nodes
    • The App Key has a fixed value and is the same for all nodes
    • Use 32-bit frame counter, leave frame counter checks enabled

The node uses a fixed App EUI and App key by default, but each node can also be configured to use a custom set of OTAA keys.

Backend

This is implemented by my LoraLuftdatenForwarder (source code).

It currently supports the following:

  • Subscribes to a TTN MQTT stream and receives incoming messages, both TTN "v2" and "v3" stacks are supported.
  • Decodes Cayenne and custom payloads.
  • Forwards to sensor.community (formerly luftdaten.info)
  • Forwards to opensensemap.org, the opensensebox id is automatically picked up from an attribute specified in the TTN v3 console.
  • Forwards to [1], with login credentials provided by an TTN v3 device attribute, just like above
  • Forward to feinstaub app (experimental), https://pm.mrgames-server.de/

Development

To receive data using mosquitto, separately from the backend: 

 mosquitto_sub -h eu.thethings.network -p 1883 -t +/devices/+/up -u particulatematter -P ttn-account-v2.cNaB2zO-nRiXaCUYmSAugzm-BaG_ZSHbEc5KgHNQFsk

Example upstream data: 

 particulatematter/devices/ttgo_mac/up {"app_id":"particulatematter","dev_id":"ttgo_mac","hardware_serial":"000084B14CA4AE30","port":1,"counter":16,"payload_raw":"AAEALAAd/////w==","metadata":{"time":"2019-04-13T08:37:45.338427686Z","frequency":868.3,"modulation":"LORA","data_rate":"SF11BW125","airtime":823296000,"coding_rate":"4/5","gateways":[{"gtw_id":"eui-008000000000b8b6","timestamp":2000599916,"time":"2019-04-13T08:37:45.320735Z","channel":1,"rssi":-115,"snr":-3,"rf_chain":1,"latitude":52.0182,"longitude":4.70844,"altitude":27}]}}

Example downstream data: 

 particulatematter/devices/ttgo_mac/events/down/sent {"payload":"YPUvASalGgEDEf8AAcqtmOw=","message":{"app_id":"particulatematter","dev_id":"ttgo_mac","port":0},"gateway_id":"eui-008000000000b8b6","config":{"modulation":"LORA","data_rate":"SF9BW125","airtime":164864000,"counter":282,"frequency":869525000,"power":27}}

Gateway API: 

 https://account.thethingsnetwork.org/api/v2/gateways/eui-xxxxxxxxxxx

Useful tools:

Retrieved from ‘https://revspace.nl/wiki/index.php?title=LoraWanDustSensor&oldid=27031’