StofAnanas: Difference between revisions

From RevSpace
Jump to navigation Jump to search
 
(110 intermediate revisions by the same user not shown)
Line 3: Line 3:
  |Picture=StofAnanas.jpg
  |Picture=StofAnanas.jpg
  |Omschrijving=Showing particulate matter concentration as a coloured light
  |Omschrijving=Showing particulate matter concentration as a coloured light
  |Status=In progress
  |Status=Completed
  |Contact=bertrik
  |Contact=bertrik
}}
}}


== The idea ==
== The concept ==
Show current airborne particulate matter concentration using a LED light in a lamp, inspired by http://stoflamp.nl
The stofananas/stoflama visualizes the current airborne particulate matter concentration from the nearest sensor.community measurement station, inspired by http://stoflamp.nl
The data that the LED colour is based on is simply retrieved over WiFi from the luftdaten website.
The data that the LED colour is based on is retrieved over WiFi from the stofradar.nl website every 5 minutes.


This lamp is a soft plastic translucent pine apple ("ananas"), bought at the "Action" store.
This lamp is a soft plastic translucent pine apple ("ananas") or lama, bought at the "Action" store.


Features:
Features:
* The lamp shows particulate matter concentration as a colour, from dark blue for low concentration to bright pink for high concentration
* The lamp shows particulate matter concentration as a colour, from dark blue for low concentration to bright pink for high concentration
* The lamp retrieves the PM value over wifi from the the luftdaten website
* The lamp retrieves the PM value over wifi from the the stofradar.nl website, there is a one-time setup to configure your WiFi network so the device can access the internet
* The luftdaten measurement station can be entered at the same time as when wifi credentials are entered.
* The lamp determines its location by based on signal strength and BSSID of nearby WiFi base stations.
* should be compatible with [https://nl.aliexpress.com/item/32891674707.html Wemos D1 RGB LED shields]. My PL9823 LED appears to be compatible with WS2812B LEDs.
* The hardware consists of a Wemos D1 mini board (about E3,-), a LED shield and a USB power supply + cable.
* The software supports two different kinds of Wemos D1 mini LED "shield", both the shield with a single LED and the shield with 7 LEDs arranged in a star.  
* Experimental branch retrieves particulate matter data from stofradar.nl, which is more responsive, also includes data from RIVM


Ideas/nice to have:
Ideas/nice to have/todo:
* The lamp "breathes" by varying the intensity over time, e.g. a cycle of 10 seconds where the light dims a bit and brightens a bit
* some kind of compatibility mode with the stoflamp from stoflamp.nl
** perhaps increase the breathing rate for higher PM
* Run the software directly on a WiFi-enabled E14 RGB lamp from the Action store. This lamp has the microcontroller already built in. No separate USB power adapter is needed, it runs directly off 230V. See the [[WifiLamp]] project.
** perhaps modulate the colour saturation instead of intensity
* Instead of controlling a light directly, send a command over infrared remote to an RGB lamp already having remote control, see https://www.instructables.com/Reverse-Engineering-RGB-LED-Bulb-with-IR-remote/
* Automatic determination of location by means of wifi location, so you don't even need to input a luftdaten monitoring station id (do this on every startup for example)
 
** example query to get (very coarse) position data from Mozilla:
== Building it ==
  https://location.services.mozilla.com/v1/geolocate?key=test
[[File:stoflama_parts.jpg|right|thumb|stoflama]]
** example query to list of sensors centered around a location from Luftdaten:
 
  http://api.luftdaten.info/v1/filter/area=52.022,4.692,1.0
It consists of a few parts:
* Remote control over IR
* a Wemos D1 mini board
* a LED shield, either the one with 1 LED, or the one with 7 LEDs (preferred, brighter)
* a 5V USB charger with stable voltage output + USB cable
* a plastic lamp enclosure
 
Steps:
* solder the female headers onto the Wemos D1 mini, start with soldering just one pin so you can re-heat it and adjust it if the fit with the male pins is not quite right.
* push the male headers into the female headers and solder the male headers onto the LED shield
* connect the USB micro cable and flash the firmware into the Wemos d1 mini board
* verify that it works as expected, on startup it does a quick colour animation, starting and ending with the red colour
* remove the USB micro cable and push the Wemos d1 mini board + LED shield into the plastic enclosure
* reattach the USB micro cable and verify it still works
 
It helps to make a few little knife cuts in the plastic of the enclosure to make the wemos d1 mini board fit more easily.


== Operation Manual ==
== Operation Manual ==
[[File:ananas_config.png|right|thumb|configuration]]
[[File:stoflama.jpg|right|thumb|stoflama]]


=== Programming ===
=== Flashing the firmware ===
* connect everything up as indicated under 'hardware' and connect the Wemos D1 board to the USB port of your development PC / laptop
* Connect everything up as indicated under 'hardware' and connect the Wemos D1 board to the USB port of your development PC / laptop
* flash the software into the Wemos D1 mini, typically from the command line using platformio:
* Flash the software into the Wemos D1 mini. Open a command line and enter the 'stofananas' source code directory, then compile and upload it using the following command:
   pio run -t upload
   pio run -t upload
This assumes you have platformio installed, this is done on Debian Linux for example, as follows:
  sudo apt install python-pip
  sudo pip install platformio


=== Configuration ===
=== Configuration ===
* on https://netherlands.maps.luftdaten.info find the particulate matter station you want to follow and note the number of the station, for example "12246"
[[File:ananas_config.png|right|thumb|configuration]]
* on a mobile phone, connect to the "ESP-STOFANANAS" network, and select login
* when presented with the captive portal, select a WiFi network, fill in the WiFi password, AND ALSO fill in the number you looked up earlier, press SAVE
* NOTE: when the configuration is ongoing, the LED will be YELLOW, it turns OFF when configuration is done.


Alternatively:
Automatic configuration:
* move close to the particulate matter sensor (< 100 meters) and make sure at least the WiFi credentials have been entered and saved
* power up the lamp
* open a console to the serial port (115200 bps) and run the following commands:
* on a mobile phone, connect to the "ESP-PMLAMP" network, and select login
* to get a list of available commands:
* when presented with the captive portal, select a WiFi network, fill in the WiFi password, press SAVE
  help
* to auto-configure the luftdaten id (does a WiFi scan to geolocate and tries to find a particulate matter sensor close by):
  config auto
* within a few seconds, you should see it prints the current approximate geographic location and the id of the luftdaten station, the id should be non-zero


=== Usage ===
=== Usage ===
* Power up the lamp while in range of the WiFi network you configured
* Power up the lamp while in range of the WiFi network you configured. The LED shows a colour animation when starting up (starting with red and ending with red)
* The LED should start yellow (connecting to the WiFi), then briefly change to OFF (retrieving PM value from Luftdaten), then change to a colour representing a PM concentration
* The LED turns white for a short time, then changes to a colour representing a PM concentration
* A new PM measurement is retrieved every 5 minutes.
* A new PM measurement is retrieved automatically every 5 minutes.
* A flashing colour (1x per second) means that something went wrong, either communication with the sensor.community server or decoding the sensor.community server response


== Hardware ==
== Hardware ==
[[File:pl9823.png|right|thumb|pinout]]
The electronic part consists of a Wemos D1 mini board and a LED shield.
The lamp is controlled by an ESP8266, a Wemos D1 mini board.
The LED is an RGB LED with built-in PL9823 controller.
The PL9823 is compatible with the WS2812B RGB LED as far as I can tell (the WS2812B driver in the FastLED library works with the PL9823).


Connections (using dupont female-female):
The LED can be one of these LED shields:
* LED Din to Wemos D1 mini pin D3
* 1-LED shield: https://wiki.wemos.cc/products:d1_mini_shields:ws2812b_rgb_shield
* LED Gnd to Wemos D1 mini pin GND
* 7-LED shield: https://www.wemos.cc/en/latest/d1_mini_shield/rgb_led.html
* LED Vdd to Wemos D1 mini pin 5V


This is the same pinout as used by the [https://wiki.wemos.cc/products:d1_mini_shields:ws2812b_rgb_shield Wemos WS2812B RGB shield]
The 7-LED shield is a lot brighter than the 1-LED shield, I recommend to use the 7-led shield.
 
Unfortunately not all LED shields are equal, some contain an RGB LED, others have the RGB colours switched.
During startup, the colour animation should start and end with the RED colour.


== Software ==
== Software ==
Line 77: Line 89:
To compile and upload it, I use platform io:
To compile and upload it, I use platform io:
   pio run -t upload
   pio run -t upload
The ESP8266 board support should be version 2.6.3!


You can also compile it with the Arduino IDE, libraries used:
You can also compile it with the Arduino IDE, libraries used:
* WiFiManager (v 0.14) is used to manage WiFi connection to the local AP
* ArduinoJSON (v 6.19.4) for parsing the sensor.community response
* ArduinoJSON (v 6.11) for the parsing the luftdaten response
* FastLED (v 3.5.0) is used to control the RGB LED
* FastLED (v 3.2.9) is used to control the RGB LED
* WiFiManager (v 0.16.0) is used to manage WiFi connection to the local WiFi access point
 
=== stofradar.nl interface ===
The firmware performs a GET on
  http://stofradar.nl:9000/air/<latitude>/<longitude>
 
This returns a JSON message as follows
  {"pm2.5":4.25}


=== Luftdaten interface ===
=== Colour mapping ===
The current measurement value of a particular sensor can be determined by parsing the JSON messages retrieved over a REST interface, by performing an HTTP GET on URL
[[File:Fastled_rainbow.jpg|right|thumb|FastLED rainbow hue chart]]
  http://api.luftdaten.info/v1/sensor/<sensor-id>/
where <sensor-id> is the database id used by luftdaten (and visible on their map).
The trailing slash in the URL is significant.


For example:
Mapping is currently as follows, using the PM2.5 value:
  http://api.luftdaten.info/v1/sensor/12246/
* 0 ug/m3: <span style="background:#0000FF>deep blue</span>
* 15 ug/m3: <span style="background:#00F00F>green</span>
* 30 ug/m3: <span style="background:#FFFF00>yellow</span>
* 60 ug/m3: <span style="background:#FF0000>red</span>
* 120+ ug/m3: <span style="background:#FF0080>pink</span>


The software looks for the "P1" (PM10) sensor value in the JSON message and averages all measurements it finds (usually the current one and a previous one).
This follows roughly a spectral colour scale with continuously varying 'hue',
PM-values doubling for each step, with piecewise linear interpolation.


=== Colour mapping ===
RIVM has an interesting paper on this subject at
Mapping is as follows, with piecewise linear interpolation:
https://www.rivm.nl/bibliotheek/rapporten/2014-0050.pdf
* 0 ug/m3: deep blue
 
* 25 ug/m3: green
Chapter 8.3 unfortunately still puts the final colour scale for an air quality index as a point under discussion:
* 50 ug/m3: yellow
 
* 100 ug/m3: red
  "Er is overeenstemming over het baseren van de index op dosis-respons
* 200 ug/m3 (and higher): pink
  relaties en het schalen van de componenten naar ordegrootte
  gezondheidseffecten. De analyse die heeft geleid tot een indeling in tien
  klassen is beschreven in hoofdstuk 6. Er is tevens de wens geuit, zowel
  door gebruikers als experts, om in de uiteindelijke presentatie te komen
  tot vier klassen met bijbehorende kleur, labels en handelingsperspectief.
  '''De precieze afkappunten daarvoor zijn arbitrair. Na de expertbijeenkomst,
  '''bijeenkomsten met gebruikers en twee commentaarronden onder de experts
  '''is nog geen consensus over de uiteindelijke indeling van de index in vier klassen.
  De onderstaande indeling (zie Tabel 11) doet zoveel mogelijk recht aan de adviezen van
  de experts en gebruikers, en biedt mogelijkheden om een consistent
  geheel te vormen met de smogregeling. Nog openstaande
  discussiepunten worden hier beschreven."
 
The https://www.luchtmeetnet.nl/ page uses the following range:
https://www.luchtmeetnet.nl/informatie/luchtkwaliteit/luchtkwaliteitsindex-(lki)
 
== Next generation ==
[[File:pmlamp_sequence.png|right|thumb|lamp-sensor pairing sequence diagram]]
 
The next generation uses the ESP-NOW protocol, supported by both the ESP8266 and ESP32 microcontrollers.
ESP-NOW is a connection-less WiFi protocol running at a reduced rate of 1 Mbps, it does not require any credentials (like WEP/WPA) to be entered.
'''The lamp is *not* connected to regular WiFi, this is different from (say) the mechanism used by the sensor.community flashing tool to find a sensor in the local network.'''
 
The idea is that you just put a ESP-now enabled light in the vicinity (several 10s of meters) of the particulate matter sensor
and they will automatically discover each others' presence and start communicating measurement values.
 
=== Protocol ===
Pairing works as follows:
* The lamp sends broadcast discovery messages (possibly on different channels) to announce its presence and discover the sensor, it flashes blue while doing so.
* The dust sensor receives the broadcast discovery message and sends an associate message back.
* The lamp receives the associate message, it stops flashing blue.
* The (implicit) ACK from the lamp back to the sensor signals that the association is complete, the sensor remembers the lamp MAC and id
* When a new measurement is done, the sensor sends a data message to the lamp. The lamp shows the associated color.
 
The data format is JSON, human readable, extensible. Not so friendly on data size, but we can send up to 250 bytes, should be enough.
The dust sensor can show in its internal web page that a lamp was found and can display the lamp id.
 
Example broadcast discovery packet (lamp to dust sensor):
  {"msg":"discover","id":"PMLAMP-000D1DD8"}
 
Example unicast discovery response packet (dust sensor to lamp):
  {"msg":"associate","id":"SENSOR-00EE18EC"}
 
Example unicast measurement/color packet (dust sensor to lamp):
  {"msg":"data","PM10":12.3,"PM2.5":8.4,"PM1.0":4.5,"humidity":42.5,"temperature":14.3,"pressure":102511,"color":"#11FF00"}
  {"msg":"data","color":"#ffff00"}
The lamp software can be implemented to either just display the color, or calculate it from the measurement.
 
When the sensor does not receive an ACK from the lamp during a number of consecutive transmissions (say 3), it assumes that the lamp is offline and goes back to discovery mode.
When the lamp does not receive a message from the sensor during a certain interval (say 300 seconds), it assumes that the sensor is offline and goes back to discovery mode.
 
=== Hardware ===
You need two wemos d1 mini boards, one acting as the 'sensor', the other one as the 'lamp'.
The wemos d1 mini acting as 'lamp' should be fitted with an RGB shield.
 
=== Software ===
Source code is available here: https://github.com/bertrik/pmlamp-espnow-proto
 
Power on the lamp, the LED starts flashing blue, then power on the sensor, the LED stops flashing. You can connect over serial to the sensor node and type a command like 'led FF0000' to set the color of the lamp to red.
 
=== Other resources ===
* http://smallbits.marshall-tribe.net/blog/2018/05/20/esp8266-now-talk

Latest revision as of 12:50, 1 February 2023

Project StofAnanas
StofAnanas.jpg
Showing particulate matter concentration as a coloured light
Status Completed
Contact bertrik
Last Update 2023-02-01

The concept

The stofananas/stoflama visualizes the current airborne particulate matter concentration from the nearest sensor.community measurement station, inspired by http://stoflamp.nl The data that the LED colour is based on is retrieved over WiFi from the stofradar.nl website every 5 minutes.

This lamp is a soft plastic translucent pine apple ("ananas") or lama, bought at the "Action" store.

Features:

  • The lamp shows particulate matter concentration as a colour, from dark blue for low concentration to bright pink for high concentration
  • The lamp retrieves the PM value over wifi from the the stofradar.nl website, there is a one-time setup to configure your WiFi network so the device can access the internet
  • The lamp determines its location by based on signal strength and BSSID of nearby WiFi base stations.
  • The hardware consists of a Wemos D1 mini board (about E3,-), a LED shield and a USB power supply + cable.
  • The software supports two different kinds of Wemos D1 mini LED "shield", both the shield with a single LED and the shield with 7 LEDs arranged in a star.
  • Experimental branch retrieves particulate matter data from stofradar.nl, which is more responsive, also includes data from RIVM

Ideas/nice to have/todo:

  • some kind of compatibility mode with the stoflamp from stoflamp.nl
  • Run the software directly on a WiFi-enabled E14 RGB lamp from the Action store. This lamp has the microcontroller already built in. No separate USB power adapter is needed, it runs directly off 230V. See the WifiLamp project.
  • Instead of controlling a light directly, send a command over infrared remote to an RGB lamp already having remote control, see https://www.instructables.com/Reverse-Engineering-RGB-LED-Bulb-with-IR-remote/

Building it

stoflama

It consists of a few parts:

  • a Wemos D1 mini board
  • a LED shield, either the one with 1 LED, or the one with 7 LEDs (preferred, brighter)
  • a 5V USB charger with stable voltage output + USB cable
  • a plastic lamp enclosure

Steps:

  • solder the female headers onto the Wemos D1 mini, start with soldering just one pin so you can re-heat it and adjust it if the fit with the male pins is not quite right.
  • push the male headers into the female headers and solder the male headers onto the LED shield
  • connect the USB micro cable and flash the firmware into the Wemos d1 mini board
  • verify that it works as expected, on startup it does a quick colour animation, starting and ending with the red colour
  • remove the USB micro cable and push the Wemos d1 mini board + LED shield into the plastic enclosure
  • reattach the USB micro cable and verify it still works

It helps to make a few little knife cuts in the plastic of the enclosure to make the wemos d1 mini board fit more easily.

Operation Manual

stoflama

Flashing the firmware

  • Connect everything up as indicated under 'hardware' and connect the Wemos D1 board to the USB port of your development PC / laptop
  • Flash the software into the Wemos D1 mini. Open a command line and enter the 'stofananas' source code directory, then compile and upload it using the following command:
 pio run -t upload

This assumes you have platformio installed, this is done on Debian Linux for example, as follows:

 sudo apt install python-pip
 sudo pip install platformio

Configuration

configuration

Automatic configuration:

  • power up the lamp
  • on a mobile phone, connect to the "ESP-PMLAMP" network, and select login
  • when presented with the captive portal, select a WiFi network, fill in the WiFi password, press SAVE

Usage

  • Power up the lamp while in range of the WiFi network you configured. The LED shows a colour animation when starting up (starting with red and ending with red)
  • The LED turns white for a short time, then changes to a colour representing a PM concentration
  • A new PM measurement is retrieved automatically every 5 minutes.
  • A flashing colour (1x per second) means that something went wrong, either communication with the sensor.community server or decoding the sensor.community server response

Hardware

The electronic part consists of a Wemos D1 mini board and a LED shield.

The LED can be one of these LED shields:

The 7-LED shield is a lot brighter than the 1-LED shield, I recommend to use the 7-led shield.

Unfortunately not all LED shields are equal, some contain an RGB LED, others have the RGB colours switched. During startup, the colour animation should start and end with the RED colour.

Software

Getting and building the source code

Source code is available on github.

To compile and upload it, I use platform io:

 pio run -t upload

The ESP8266 board support should be version 2.6.3!

You can also compile it with the Arduino IDE, libraries used:

  • ArduinoJSON (v 6.19.4) for parsing the sensor.community response
  • FastLED (v 3.5.0) is used to control the RGB LED
  • WiFiManager (v 0.16.0) is used to manage WiFi connection to the local WiFi access point

stofradar.nl interface

The firmware performs a GET on

 http://stofradar.nl:9000/air/<latitude>/<longitude>

This returns a JSON message as follows

 {"pm2.5":4.25}

Colour mapping

FastLED rainbow hue chart

Mapping is currently as follows, using the PM2.5 value:

  • 0 ug/m3: deep blue
  • 15 ug/m3: green
  • 30 ug/m3: yellow
  • 60 ug/m3: red
  • 120+ ug/m3: pink

This follows roughly a spectral colour scale with continuously varying 'hue', PM-values doubling for each step, with piecewise linear interpolation.

RIVM has an interesting paper on this subject at https://www.rivm.nl/bibliotheek/rapporten/2014-0050.pdf

Chapter 8.3 unfortunately still puts the final colour scale for an air quality index as a point under discussion:

 "Er is overeenstemming over het baseren van de index op dosis-respons
 relaties en het schalen van de componenten naar ordegrootte
 gezondheidseffecten. De analyse die heeft geleid tot een indeling in tien
 klassen is beschreven in hoofdstuk 6. Er is tevens de wens geuit, zowel
 door gebruikers als experts, om in de uiteindelijke presentatie te komen
 tot vier klassen met bijbehorende kleur, labels en handelingsperspectief.
 De precieze afkappunten daarvoor zijn arbitrair. Na de expertbijeenkomst, 
 bijeenkomsten met gebruikers en twee commentaarronden onder de experts
 is nog geen consensus over de uiteindelijke indeling van de index in vier klassen.
 De onderstaande indeling (zie Tabel 11) doet zoveel mogelijk recht aan de adviezen van
 de experts en gebruikers, en biedt mogelijkheden om een consistent
 geheel te vormen met de smogregeling. Nog openstaande
 discussiepunten worden hier beschreven."

The https://www.luchtmeetnet.nl/ page uses the following range: https://www.luchtmeetnet.nl/informatie/luchtkwaliteit/luchtkwaliteitsindex-(lki)

Next generation

lamp-sensor pairing sequence diagram

The next generation uses the ESP-NOW protocol, supported by both the ESP8266 and ESP32 microcontrollers. ESP-NOW is a connection-less WiFi protocol running at a reduced rate of 1 Mbps, it does not require any credentials (like WEP/WPA) to be entered. The lamp is *not* connected to regular WiFi, this is different from (say) the mechanism used by the sensor.community flashing tool to find a sensor in the local network.

The idea is that you just put a ESP-now enabled light in the vicinity (several 10s of meters) of the particulate matter sensor and they will automatically discover each others' presence and start communicating measurement values.

Protocol

Pairing works as follows:

  • The lamp sends broadcast discovery messages (possibly on different channels) to announce its presence and discover the sensor, it flashes blue while doing so.
  • The dust sensor receives the broadcast discovery message and sends an associate message back.
  • The lamp receives the associate message, it stops flashing blue.
  • The (implicit) ACK from the lamp back to the sensor signals that the association is complete, the sensor remembers the lamp MAC and id
  • When a new measurement is done, the sensor sends a data message to the lamp. The lamp shows the associated color.

The data format is JSON, human readable, extensible. Not so friendly on data size, but we can send up to 250 bytes, should be enough. The dust sensor can show in its internal web page that a lamp was found and can display the lamp id.

Example broadcast discovery packet (lamp to dust sensor):

 {"msg":"discover","id":"PMLAMP-000D1DD8"}

Example unicast discovery response packet (dust sensor to lamp):

 {"msg":"associate","id":"SENSOR-00EE18EC"}

Example unicast measurement/color packet (dust sensor to lamp):

 {"msg":"data","PM10":12.3,"PM2.5":8.4,"PM1.0":4.5,"humidity":42.5,"temperature":14.3,"pressure":102511,"color":"#11FF00"}
 {"msg":"data","color":"#ffff00"}

The lamp software can be implemented to either just display the color, or calculate it from the measurement.

When the sensor does not receive an ACK from the lamp during a number of consecutive transmissions (say 3), it assumes that the lamp is offline and goes back to discovery mode. When the lamp does not receive a message from the sensor during a certain interval (say 300 seconds), it assumes that the sensor is offline and goes back to discovery mode.

Hardware

You need two wemos d1 mini boards, one acting as the 'sensor', the other one as the 'lamp'. The wemos d1 mini acting as 'lamp' should be fitted with an RGB shield.

Software

Source code is available here: https://github.com/bertrik/pmlamp-espnow-proto

Power on the lamp, the LED starts flashing blue, then power on the sensor, the LED stops flashing. You can connect over serial to the sensor node and type a command like 'led FF0000' to set the color of the lamp to red.

Other resources