AirLink
Introduction
NOTE: Before version 6.1 this section was named AirQuality
In 2020 support for the Davis Airlink device was introduced in CumulusMX. Although Air Quality sensors had been supported by CumulusMX as Extra Sensors, this Davis device had specific tables and support incorporated and as such required specific support by CumulusUtils. The Davis Airlink is supported by a Table view and by graphing the measured values. Future Air Quality devices will need a consistent use of an underlying data structure and interface to be supported.
Air Quality in the context of the AirLink is about Particulate Matter or fine dust particles of size of less then 10 and less than 2.5 . Duration of exposure of a certain average value gives an Air Quality Index which differs per country. On the forum information about this is available and linked below.
Operation
The operation requires two steps:
- creating the Airlink page to be used by the user (or in the generated website)
- creating the datafile to be used by the Airlink page. Although CumulusMX is able to produce an AirQuality.JSON datafile, that file is not used because it uses only the direct measured data. CumulusUtils produces its own datafile to be able to display all possible averages produced by the AirLink (and which are stored but not used by CumulusMX). These values are: raw data, one hour running average, three hour running average, 24 hour running average and the nowcast average.
The commands for the above named steps are:
utils/bin/cumulusutils.exe Airlink => this command includes the following step to create the first datafile
and:
utils/bin/cumulusutils.exe UserAskedData => this command produces the Airlink datafiles with only those data required for the user wanted display.
Country settings
CumulusMX knows the following country settings:
US, GB, CA, EUAQI, EUCAQI, AU, NL, BE
The type indicator has been left out except for the EU so USA-EPA becomes simply US in this example.
CumulusUtils knows the following countries:
US, GB, CA, EU, AU, NL, BE
These match one to one which is easy to understand except for the EU. Both EU settings from CumulusMX are projected on EU in CumulusUtils.
These country systems are explained in this post here.
As you can see in that forum post linked above, the values for the two EU AQI standards do not differ that much so I merged them into EU-CAQI. The choice of these AQI calculations leads in CUtils to the reference lines. CUtils does chart the concentrations only, not the AQI.
The Canadian system is the only one which uses a formula and not a table. That is why it only accepts 3 hr averages.
To program the exact AQI representation at certain concentrations for specific particle size is - according to me, i.e. HansR - an incorrect presentation of the danger levels involved (apart from the complexity in doing so). Danger levels involved must be uniform and the same everywhere in the world, as they are to be projected on humans and not dependent on politics of a country (compare e.g. the danger levels of the US to those of the EU). So CumulusUtils deviates here from CMX and it may in future even remove the AQI per country completely and replace that with the WHO reference which recently has become available (see my link to the forum post above).
Output
The output is the file: airlink.txt and contains the TableView and the GraphView of the data. Beside that the file airlinkrealtime.txt is used to be processed by CumulusMX for support of realtime behaviour (see Inner working, the user has to add this to the section Extra Web Files of CumulusMX).
The output for the datafiles is: airlinkdataOut2p5.json and airlinkdataOut10.json
Inifile Parameters
The Airlink module has the following inifile parameters (see cumulusutils.ini):
(Before version 6.1 this section was named AirQuality)
[Airlink] CountrySelected=EU => Determines the country for which the AQI must be calculated. This value must be identical to what is entered in CMX WantToSeeNow=true => If true will show the raw data WantToSeeNowCast=true => If true will show the nowcast average WantToSee1hr=true => If true will show the one hour running average WantToSee3hr=true => If true will show the three hour running average WantToSee24hr=true => If true will show the 24 hour running average WantToSeeWind=true => If true will show the windbarbs in the chart indicating the wind direction CleanupAirlinkLogs=false => If true will remove old logfiles and keep only the current and the previous month
Inner working
If at least one sensor has been activated within CumulusMX, CumulusUtils will create the Airlink output. If no sensor has been activated nothing will be generated.
For each sensor (In and Out) similar code is produced with similar coding of variable names.
Then, for facilitating realtime behaviour, the file airlinkrealtime.txt is generated which the user has to enter in the Extra Webfiles section in the settings of CumulusMX. The target directory must be the webroot (where the Airlink page is activated). Tick: Process, Realtime and FTP.
Then the menu is generated, creating two buttons to enable the user to switch between Table view and Graph view. In case of the Website Generator there is also a help button displaying information about the Airlink. This help button is not available when running as a module.
TableView
After these initial generations the table itself is generated where for each type of value the user wishes to see (Now, 1 hour average, 3 hour average, 24 hour average and NowCast) a specific code section is generated. For e.g. NowCast this looks like:
var nowcastPM2p5_OutVal = AirLinkRT[7+0];
var nowcastPM10_OutVal = AirLinkRT[12+0];
var nowcastPM2p5_OutAQI = AirLinkRT[17+0];
var nowcastPM2p5_OutAQIint = NormaliseAQI(nowcastPM2p5_OutAQI);
var nowcastPM10_OutAQI = AirLinkRT[22+0];
var nowcastPM10_OutAQIint = NormaliseAQI(nowcastPM10_OutAQI);
$('#nowcastPM2p5_OutVal').html(nowcastPM2p5_OutVal);
$('#nowcastPM2p5_OutAQI').html(nowcastPM2p5_OutAQI);
$('#nowcastPM10_OutVal').html(nowcastPM10_OutVal);
$('#nowcastPM10_OutAQI').html(nowcastPM10_OutAQI);
for (i = 0; i < 5; i++) { (i+1 == nowcastPM2p5_OutAQIint ? $('#nowcastPM2p5ArrowOut'+i).html('▲') : $('#nowcastPM2p5ArrowOut'+i).html(' ') ); }
for (i = 0; i < 5; i++) { (i+1 == nowcastPM10_OutAQIint ? $('#nowcastPM10ArrowOut'+i).html('▲') : $('#nowcastPM10ArrowOut'+i).html(' ') ); }
Where the coding of the fields and variables is rigid and should not be modified. There have been inventive modification spotted in the wild (e.g. disabling the graph) which though highly appreciated of course will get no support. Modifying generated code leaves you on your own.
GraphView
Together with the table view the Graph view is generated. The graphview does not display the realtime values but displays according to the Recent graph settings of CumulusMX i.e. according to the setting of the GraphHours parameter in the section Graphs in Cumulus.ini.
The line colouring obeys the default colouring of the current theme. No colouring is applied or defined with the graph itself.
One special feature for all charts in CumulusUtils is the possibility for the background image. This is described in the chapter on the website
The Air Quality Index (AQI)
The AQI is different per country. It is the warning level translation from the actual concentrations of Particulate matter measured. The AQI differs per country but differs not only in value but also in the series of value used. I created thread on the forum (first two posts) with information. For the calculations the values produced by CMX are used. The spreadsheet shows the values used in countries and their relation with the actual PM concentration. See also the Help button.
The Help Button
Because the Help button is not available in the the modular use of the Airlink module its content is given here.
In Air Quality (with either the cheap sensors or the government published data) it is important to know about the Air Quality Indices (AQI) and PM concentrations. Those are very different things. The AQI differ very much per country, per period (1 hr, 3 hr or 24 hr averages) and in scales (6 divisions or 10 divisions with subdivisions). To make it even more complex, some countries did combine the fine dust (PM) AQIs with indices for SO2 and NO2. That is ignored here. These graphs only deal with Particulate Matter sensors. Please be aware that the scaling of the graphs is dynamic.
I made a post on the forum in which I added some links to the sites for specific countries. You will have to study yourself (if you want).
Please be aware that these charts only give the absolute measurements of the PM concentrations as given by the sensors used. The AQI levels for the different countries have great variations and I will not go through the trouble to display those levels in the graphs for the normative country selected.
The graphs show the indicative AQI levels of the EU-CAQI standards for the 1 hr series. These will show you reasonable short term danger levels although maybe not standardized in your country. 24 hr levels are considered irrelevant in the context of a personal station: you will be dead before this level reaches a level where help services are activated. If the 1 hr level shows an unhealthy level you better start running away (precautionary principle).
Yes, big differences in different countries. Therefore: study the documents and the danger levels in the matrix I supplied.