weewx-aqi-xtype

Description

This extension uses WeeWX Xtypes capability to dynamically calculate AQI. Currently it only supports pm 2.5 and pm 10. For supported pollutants, mutiple sensors are supported. Currently only the US EPA algorithm is supported.

Installation notes

Because there are multiple methods to install WeeWX, location of files can vary. See where to find things in the WeeWX User's Guide for the definitive information. The following symbolic names are used to define the various locations:

$DOWNLOAD_ROOT - The directory containing the downloaded weewx-aqi-xtype extension.
$BIN_ROOT - The directory where WeeWX executables are located.
$CONFIG_ROOT - The directory where the configuration (typically, weewx.conf) is located.

The notation vX.Y.Z designates the version being installed. X.Y.Z is the release.

Prior to making any updates/changes, always make a backup.

Preqrequisites

WeeWX version	Python version
4.6.0 or greater	Python 3.6 or greater

Installation

Download weewx-aqi-xtype

wget -P $DOWNLOAD_ROOT https://github.com/bellrichm/weewx-aqi-ztype/archive/vX.Y.Z.tar.gz

All of the releases can be found here and this is the latest.

Install weewx-aqi-xtype

wee_extension --install=$DOWNLOAD_DIR/vX.Y.Z.tar.gz

Restart WeeWX

sudo /etc/init.d/weewx restart

sudo sudo service restart weewx

sudo systemctl restart weewx

Customizing

The installation of weewx-aqi-xtype configures it so that will work with the WeeWX 'extended schema.' It will calculate the Instacast AQI and Nowcast AQI for the value of pm 2.5. To do this three sections of weewx configuration are updated. The first is [[[Generic]]] section of [StdReport][[Labels]]. Here the default label is added.

[StdReport]
    [[Labels]]
        [[[Generic]]]
            .
            .
            .
            pm2_5_aqi = AQI
            pm2_5_aqi_nowcast = AQI (Nowcast)

The second is the [[Calculations]] section of [StdWXCalculate]. Here, the calculated AQI field is added. Doing this adds it to the WeeWX loop packets and archive records.

[StdWXCalculate]
    [[Calculations]]
    .
    .
    .
        pm2_5_aqi = prefer_hardware
        # Since this requires a database look up, by default do not populate loop packets
        pm2_5_aqi_nowcast = prefer_hardware, archive

The third update is an additional section, [aqitype]. This is where the information needed to calculate the AQI is configured.

[aqitype]
    # The name of AQI field.
    # Create a section for each field to be calculated.
    [[pm2_5_aqi]]
        # The name of the WeeWX observation to be used in the calculation.
        input = pm2_5
        # The name of the algorithm.
        # Supported values: EPAAQI
        algorithm = EPAAQI
        # If the algorithm supports different pollutants(pm 2.5, pm 10, etc)
        # Supported values: pm2_5, pm10
        type = pm2_5
    [[pm2_5_aqi_nowcast]]
        # The name of the WeeWX observation to be used in the calculation.
        input = pm2_5
        # The name of the algorithm.
        # Supported values: EPAAQI, NOWCAST
        algorithm = NOWCAST
        # If the algorithm supports different pollutants(pm 2.5, pm 10, etc)
        # Supported values: pm2_5, pm10
        type = pm2_5

Suppose one has a second air quality sensor and WeeWX has been configured to store it in pm2_51. To calculate the AQI value for this sensor, both the [[Calculations]] section and [aqitype] section need to be updated. The result should look something like this.

[StdReport]
    [[Labels]]
        [[[Generic]]]
            .
            .
            .
            pm2_5_aqi = Inside AQI
            pm2_5_aqi = Outside AQI
            pm2_5_aqi_nowcast = Inside AQI (Nowcast)
            pm2_51_aqi_nowcast = Outside AQI (Nowcast)

[StdWXCalculate]
    [[Calculations]]
    .
    .
    .
        pm2_5_aqi = prefer_hardware
        pm2_51_aqi = prefer_hardware
        # Since this requires a database look up, by default do not populate loop packets
        pm2_5_aqi_nowcast = prefer_hardware, archive     
        pm2_51_aqi_nowcast = prefer_hardware, archive

[aqitype]
    # The name of AQI field.
    # Create a section for each field to be calculated.
    [[pm2_5_aqi]]
        # The name of the WeeWX observation to be used in the calculation.
        input = pm2_5
        # The name of the algorithm.
        # Supported values: EPAAQI
        algorithm = EPAAQI
        # If the algorithm supports different pollutants(pm 2.5, pm 10, etc)
        # Supported values: pm2_5, pm10
        type = pm2_5      
    [[pm2_51_aqi]]
        # The name of the WeeWX observation to be used in the calculation.
        input = pm2_51
        # The name of the algorithm.
        # Supported values: EPAAQI
        algorithm = EPAAQI
        # If the algorithm supports different pollutants(pm 2.5, pm 10, etc)
        # Supported values: pm2_5, pm10
        type = pm2_5         
    [[pm2_51_aqi_nowcast]]
        # The name of the WeeWX observation to be used in the calculation.
        input = pm2_51
        # The name of the algorithm.
        # Supported values: EPAAQI, NOWCAST
        algorithm = NOWCAST
        # If the algorithm supports different pollutants(pm 2.5, pm 10, etc)
        # Supported values: pm2_5, pm10
        type = pm2_5

By default aqi_xtype is added to the beginning of the list of xtypes. This has the effect of overriding other xtypes (except for any added to the beginning after aqi-xtype). If for some reason it is desired to add it to the end, set prepend = False

[aqitype]
    # Add aqi-xtype to the end of the list of xtypes.
    prepend = False

Using

Now the calculated value, pm2_5_aqi can be used like any built-in WeeWX type.

Note: Nowcast values are only available with the $current and $latest tags. It does not support aggregation nor series.

Display values

For example, in a Cheetah template	Desired display	Cheetah code
Current value	$current.pm2_5_aqi
Maximum value for the year	$year.pm2_5_aqi.max
A json series of maximum values for the days of the current year	$year.pm2_5_aqi.series(aggregate_type='max', aggregate_interval='day').json

Charting

WeeWX ImageGenerator

The values are also available to the builtin WeeWX charting subsystem Here are two charts. One of the calculated pm 2.5 AQI. The scond of the pm 2.5 values.

    [[year_images]]
        aggregate_type = max
        aggregate_interval = 86400

        [[[yearaqi]]]
            yscale = 0, None, None
            [[[[pm2_5_aqi]]]]

        [[[yearpm2_5]]]
            yscale = 0, None, None
            [[[[pm2_5]]]]

weewx-jas

The values are also available to user extensions. For exanmple a graph in the weewx-jas would look like this

    [[jas]]
        [[[Extras]]]
            [[[[chart_definitions]]]]
                [[[[[pm]]]]]
                    [[[[[[series]]]]]]
                        [[[[[[[pm2_5]]]]]]]
                            yAxisIndex = 0
                        [[[[[[[pm2_5_aqi]]]]]]]
                            yAxisIndex = 1
                        [[[[[[[pm10_0]]]]]]]

Additional Cheetah Tags

In addition to the XTtype to calculate the AQI, WeeWX-aqi-xtype has a WeeWX SearchList extension which given an AQI value and standard/algorithm will return the associated color hex value. It also can look up the AQI label for a given AQI value and standard/algorithm.

$AQIColor

This is called like, $AQIColor(value, standard).

$AQIDescription

This is called like, $AQIDescription(value, standard).

Getting Help

Feel free to open an issue, start a discussion in github, or post on WeeWX google group. When doing so, see Help! Posting to weewx user for information on capturing the log. And yes, capturing the log from WeeWX startup makes debugging much easeier.

bellrichm / weewx-aqi-xtype

readme