[Plugin] Purpleair AQI Calculations Plugin

azchrisf · Post by **azchrisf** » Thu Sep 24, 2026 1:25 am

[Release] Meteobridge AQI Plugin v1.0.3

I created a User-Defined Plugin for Meteobridge that reads PM2.5 data from an existing Purpleair station, and publishes calculated U.S. EPA Air Quality Index values as a separate Meteobridge station.

Features

The plugin provides:

Instantaneous PM2.5 AQI-equivalent
EPA particulate NowCast AQI
Current PM2.5 concentration
NowCast PM2.5 concentration
Numeric EPA air-quality category
Optional EPA U.S.-wide PurpleAir correction
Stale and invalid sensor-data rejection
Plugin health and error reporting
Persistent history for NowCast calculations
EPA 2024 PM2.5 AQI breakpoints

This is my setup (Purpleair is Station 1 and the AQI Plugin is Station 4 - granted not very much dust out at the moment this was taken):

: pp.png (25.33 KiB) Viewed 9 times

The instantaneous AQI-equivalent becomes available with the first valid PM2.5 sample. EPA NowCast requires sufficient hourly history and normally appears after approximately one to two hours.

Supported Meteobridge Platforms

This plugin was developed under Meteobridge VM edition.
This release requires a Meteobridge platform with a local scripts directory and writable local storage.

Supported platforms:

Meteobridge PRO, including the original red and black models
Meteobridge PRO2
Meteobridge NANO SD
Meteobridge Raspberry Pi
Meteobridge VM

This package does not support:

Original TP-Link, D-Link, or other router hardware flashed with Meteobridge
Meteobridge NANO without the SD storage option

Although some older platforms can download a User-Defined Plugin from a URL, this is intentionally a two-file local plugin. It requires a separate configuration file and writable storage for NowCast history, status information, and logs.

There is no single-file or URL-only edition.

Installation

No installer, service, cron job, or /root/datafeed modification is required.
You can download the code at https://github.com/AZChris83/MBPurpleAirAQI

Make configuration adjustments as needed and detailed below in meteobridge-aqi.conf FIRST
Then, copy these two files into the Meteobridge scripts directory:

Code: Select all

meteobridge-aqi.plugin
meteobridge-aqi.conf

Then:

Open the Meteobridge Weather Station configuration.
Add an additional station.
Select User-Defined Plugin as the station type.
Select meteobridge-aqi.plugin.
Save the configuration.
Restart the station process if requested.

The package includes complete installation, configuration, troubleshooting, updating, and removal documentation.

PM2.5 Source Configuration

For a PurpleAir connected as Meteobridge Station 1:

Code: Select all

SOURCE_STATION=1
PM25_SENSOR="air1pm"

The plugin resolves this to:

Code: Select all

air1!1pm

On the standard Meteobridge mapping, air1!1pm is PM2.5. The air1!0pm channel is PM10 or the default particulate channel and should not be used for PM2.5 AQI.

A fully qualified sensor name can also be entered directly:

Code: Select all

PM25_SENSOR="air1!1pm"

Output Sensors

The plugin publishes:

data0num: Instantaneous AQI-equivalent
data1num: EPA NowCast AQI
data2num: AQI category code
data3num: Current PM2.5 concentration
data4num: NowCast PM2.5 concentration
data5num: Plugin status code

The outputs belong to the User-Defined Plugin station. For example, when the plugin is Station 4, its physical sensor names are data4!0num through data4!5num.

Category codes:

Code: Select all

0 = Good
1 = Moderate
2 = Unhealthy for Sensitive Groups
3 = Unhealthy
4 = Very Unhealthy
5 = Hazardous

Status codes:

Code: Select all

0 = Healthy
1 = PM2.5 source missing, invalid, stale, or unreachable
2 = Humidity unavailable while PurpleAir correction requires it
3 = Configuration or storage error

The plugin emits a status record immediately at startup so Meteobridge does not disconnect it while waiting for the first PM2.5 query.

EPA 2024 PM2.5 Breakpoints

Code: Select all

PM2.5 µg/m³      AQI         Category
0.0 to 9.0       0 to 50     Good
9.1 to 35.4      51 to 100   Moderate
35.5 to 55.4     101 to 150  Unhealthy for Sensitive Groups
55.5 to 125.4    151 to 200  Unhealthy
125.5 to 225.4   201 to 300  Very Unhealthy
225.5 to 325.4   301 to 500  Hazardous

PM2.5 is truncated to one decimal place before interpolation, and AQI is rounded to the nearest whole number.

PurpleAir Correction

The optional EPA U.S.-wide PurpleAir correction is disabled by default. It should only be enabled when the selected field is raw PurpleAir PM2.5 CF=1 data.

If PurpleAir or Meteobridge has already corrected the selected value, enabling the plugin correction would apply it twice and produce an incorrect result.

Requirements

A supported Meteobridge platform
User-Defined Plugin station support
An existing PM2.5 sensor visible to Meteobridge
A local scripts directory
Writable local storage
POSIX shell and awk
curl or wget
No Python dependency

Important Limitations

The instantaneous result is an AQI-equivalent based on the latest PM2.5 measurement. It is not the official EPA 24-hour AQI.

EPA NowCast is generally the better value for representing current health conditions because it uses weighted hourly averages.

This plugin is not a regulatory monitor. Results may differ from AirNow because of sensor hardware, placement, correction methods, quality control, and averaging periods.

The plugin is released under the MIT License - AI did assist in programming this plugin FYI.

ENJOY!