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 2020-06-15

The idea

The idea is to create a system consisting of:

  • a sensor that measures airborne particulate matter and sends the measurement data using LoRa to TheThingsNetwork.
  • a forwarder application that collects the data from TTN and forwards it to luftdaten.info

This has been done before by other people, but it appears there is no universal solution. I am publishing all source code on github and will put up documentation on this wiki. Everyone appears to invent their own payload format, I'd like something more universal like Cayenne. This page proposes an encoding based on the Cayenne standard.

A similar thing has been done by:

One thing in particular I'd like to do 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 communication/encryption keys instead of programmed specifically in each sensor node. Once the OTAA is done successfully, the node remembers the network id, device address, session keys, etc for future communication.

This makes it possible to have a *single* firmware image for all sensor nodes and it simplifies the setup:

  • you flash the node with a unified firmware
  • the node shows its unique id on the OLED
  • at the TTN console, you register a new device with the unique id
  • the sensor node receives encryption keys over the air automatically
  • done!

(idea: an ESP32 has a wifi connection too, perhaps registering the node can be done fully automatically, over wifi/internet)

Next steps

  • Are we bound by a 5 minute interval towards Luftdaten (dropping off the maps if sending less frequently)? YES PROBABLY
  • Implement a kind of schedule: turn the sds011 on, wait some time, take a measurement, turn it off, wait for some time
    • Luftdaten uses default send schedule of 145 seconds
    • make this match the TTN send schedule? -> YES, every 5 minutes, this is achievable even within the TTN FUP at SF7.
    • use the built-in on-off schedule of the sds011? -> NO, we probably want more control over the on-off times
    • implement calculating the median of accumulated measurements (half of the measurements is higher, other half is lower)

Links

Useful links for the TTGO LoRa board:

Hardware

The node is based on Arduino, in particular a TTGO ESP32 board with onboard SX1276 LoRa chip. The sensor is an SDS-011, just like in the luftdaten project. For humidity/temperature, I am using a BME280 (superior to the DHT11/22).

NOTE: https://www.thethingsnetwork.org/community/berlin/post/warning-attention-users-of-ttgo21-v16-boards-labeled-t3_v16-on-pcb-battery-exploded-and-got-on-fire

Page with correct pinout of the ESP32 LoRa board.

Luftdaten uses a cycle time of 145 seconds for the SDS011.

Proposed hardware connections:

  • SDS011 5V to ESP32 5V
  • SDS011 GND to ESP32 GND
  • SDS011 TXD to ESP32 GPIO35 (maybe I can find two suitable pins close together)
  • SDS011 RXD to ESP32 GPIO25 (maybe I can find two suitable pins close together)
  • BME280 3V todo
  • BME280 SDA todo
  • BME280 SCL todo
  • BME280 GND todo

Software

Source code

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.

Common

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

HOWEVER:

  • A standard analog value has a resolution of 0.01 units and is signed, leaving a maximum of 327.67 ug/m3. This value is possibly exceeded in extreme cases (new year's eve).
  • Still not as compact as direct binary encoding

So proposed format:

  • PM1.0: digital input (type 2), channel id 0, with value in units of 0.01 ug/m3, saturated to 327.67 ug/m3 (optional)
  • PM10: digital input (type 2), channel id 1, with value in units of 0.01 ug/m3, saturated to 327.67 ug/m3
  • PM2.5: digital input (type 2), channel id 2, with value in units of 0.01 ug/m3, saturated to 327.67 ug/m3
  • Temperature: temperature (type 103), with value in units of 0.1 degrees celcius
  • Humidity: humidity (type 104), with value in units of 0.5 %
  • Pressure: barometer (type 115), with value in units of 0.1 mbar, or 10 Pa (optional)

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).

Values encoded are averaged using the median over the accumulated measurements over the measurement interval.

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

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 86400x0.01x2 = 1728 seconds per day send time at the best case.
  • TheThingsNetwork has a FUP of 30s of data upload per day, actually a huge restriction compared to the send time allowed purely by radio regulations.
  • The Luftdaten backend appears to run on a 5 minute interval, or 288 measurements per day.
  • The default Luftdaten firmware sends new data every 145s by default

With the TTN FUP of 30s upload per day, 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.

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

  • skip T/RH/P completely (8 bytes left): SF7 is possible, at SF8 we spend 102 ms per transmission
  • skip P only (15 bytes left): SF7 is possible, at SF8 we spend 123 ms per transmission

So, in conclusion: With the FUP of TTN and use of Cayenne encoding, you can just barely send enough data to transport Luftdaten PM data!

Node

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

Typical measurement scheme in the Luftdaten firmware, as far as I understand:

  • first it waits until (cycle_time - warmup_time - measure_time), typically 145 s, 15 s and 5 s respectively.
  • turn on the fan and wait 15 seconds for "warmup"
  • measure during 5 seconds
  • turn off the fan

The luftdaten backend appears to have a 5 minute "heartbeat", so we should at least send one measurement to avoid dropping off the map.

Proposed state machine for LoRa sensor:

  • IDLE: wait until the start of the cycle, then turn on the fan
  • WARMUP: wait 20 seconds while the sensor "warms up"
  • MEASURE: collect measurements for 10 seconds, then turn off fan, calculate median/average and send LoRaWAN message
  • SEND: wait until the LoRaWAN stack indicates the message has been sent, then go back to IDLE

-> duty cycle of the SDS011 is 30/300, so 10%

Platformio

To compile and upload the code to the node, platformio is used.

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

Design

The function of the node software is to collect data from the SDS011 (particulate matter) and BME280 (temperature/humidity) at regular intervals, encode this as a data packet and send it over LoRaWAN towards TheThingsNetwork.

For the LoRaWAN data connection, over-the-air activation (OTAA) is used. I use the following scheme, to keep administration to a minimum:

  • The Device EUI is derived from the ESP32 MAC address, the node shows this on its OLED
  • The App EUI is generated in the TTN console, it is the same for all nodes
  • The App Key is generated in the TTN console, it is the same for all nodes
  • The device is registered in the TTN console by the Device EUI (this doesn't happen automatically). Frame counter checks are disabled.
  • OTAA is done only once for each node. After that, the OTAA parameters are stored in (simulated) EEPROM.
    • A long press on the PRG button restarts the OTAA procedure
  • OTAA progress is shown on the OLED
  • If OTAA has been done successfully, the node restores the session parameters negotiated during OTAA on next bootup, so it can quickly resume sending data.
  • I'm NOT saving the upload frame counter (this would be preferable), just disable the feature in the TTN console.

TODO to figure out:

  • What about the channel setup? The node connects using 3 frequencies, but receives a bigger list of frequencies during OTAA JOIN.

I've seen the following from the node, receiving an ADR: 

 40829907: engineUpdate, opmode=0x8
 40829935: EV_TXSTART
 40829939: engineUpdate, opmode=0x888
 40830013: TXMODE, freq=868300000, len=25, SF=11, BW=125, CR=4/5, IH=0
 40944876: setupRx1 txrxFlags 0x22 --> 01
 start single rx: now-rxtime: 5
 40945013: RXMODE_SINGLE, freq=868300000, SF=11, BW=125, CR=4/5, IH=0
 rxtimeout: entry: 40951170 rxtime: 40945001 entry-rxtime: 6169 now-entry: 5 rxtime-txend: 63524
 41005584: setupRx2 txrxFlags 0x1 --> 02
 start single rx: now-rxtime: 4
 41005720: RXMODE_SINGLE, freq=869525000, SF=9, BW=125, CR=4/5, IH=0
 41017003: process options (olen=0x5)
 41017012: LinkAdrReq: p1:11 chmap:00ff chpage:00 uprt:01 ans:86
 41017019: ??ack error ack=1 txCnt=0
 41017073: decodeFrame txrxFlags 0x2 --> 22
 41017312: Received downlink, window=RX2, port=-1, ack=1, txrxFlags=0x22
 41017708: EV_TXCOMPLETE (includes waiting for RX windows)
 41018027: engineUpdate, opmode=0x800

Backend

This is implemented by my LoraLuftdatenForwarder.

It currently supports the following:

  • subscribe to a TTN MQTT stream and receive incoming message
  • decode Cayenne and custom payloads
  • forward to luftdaten.info/sensor.community
  • forward to opensensemap.org
  • forward to feinstaub app (experimental), https://pm.mrgames-server.de/

Example, 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
Retrieved from ‘https://revspace.nl/wiki/index.php?title=LoraWanDustSensor&oldid=25563’