PurpleAir Smart-Home-Integration, kostenlos und Open Source

Unofficial connector: your PurpleAir air quality sensors, local or cloud.

• Veröffentlicht von LM1LC3N7
• Geräte
• Version 0.1.1
• Erfordert Gladys >=5.1.0
• ★ 0

Auf GitHub ansehenAlle Integrationen

Info

Die Dokumentation dieser Integration wird von ihrem Autor geschrieben und ist bisher nur auf Englisch verfügbar.

Unofficial connector, not affiliated with PurpleAir, Inc. It brings the readings of your PurpleAir air quality sensors into Gladys, read only: nothing is ever changed on a sensor.

This integration has never been tested with a real PurpleAir sensor nor a real API key yet. Your feedback is welcome on the Gladys forum.

What you get

For each sensor, a device in the Discovery tab with:

Feature	Category	Unit
PM2.5	PM2.5 sensor	µg/m³
PM10	PM10 sensor	µg/m³
AQI (US EPA, PM2.5)	Air quality sensor	AQI
Temperature (sensor)	Temperature sensor	°C
Humidity (sensor)	Humidity sensor	%
Pressure (sensors with BME)	Pressure sensor	hPa

• PM2.5 and PM10: the mean of the two lasers (channels A and B) when the sensor has two; the ATM correction outdoors, CF=1 indoors, as the PurpleAir API does.
• AQI: the US EPA index computed from the current PM2.5 with the breakpoints of the 2024 revision (indicative: the official index uses 24-hour averages).
• Temperature and humidity are measured inside the sensor: the temperature reads a few degrees above the outdoor air, the humidity a few points below. They are published as measured, without correction.
• A/B check: when the two lasers disagree (a gap of 5 µg/m³ or more AND 70 % or more of their mean, the US EPA quality check for PurpleAir), a laser is probably failing: the particles (and the AQI) of that read are not published, the status and the test button say "channels A/B disagree"; temperature, humidity and pressure still are. In cloud mode, PurpleAir's own channel_flags does the same (any downgraded channel).
• PM1 is shown by the test button but not published: Gladys has no PM1 category yet.

Local mode (recommended, free)

Every PurpleAir sensor serves its readings on your network (http://<sensor address>/json). No account, no key, no cost.

1. Give the sensor a fixed IP address in your router (DHCP reservation).
2. Enter that address in "Sensor address (local)" (up to three sensors).
3. Keep the default interval of 2 minutes (the sensor averages over 2 minutes), or choose up to 60.

The integration recognizes a sensor by its MAC address: if the router gives its address to another sensor, that one becomes a new device and the first one gets no value from it.

Cloud mode (optional, paid)

For a sensor out of your network (a neighbour's sensor on the map, a sensor at another house). The official PurpleAir API charges points for each call, bought from PurpleAir.

1. Create an API key in develop.purpleair.com (a READ key) and enter it in "API key (read)".
2. Find the sensor index on the PurpleAir map: click the sensor, the number after select= in the link is its index.
3. For a private sensor, also enter its read key.
4. The interval is 60 minutes by default (10 minutes at least): each call costs points for each field asked. Only the fields used are asked (last seen, channel flags, PM1, PM2.5, PM10, temperature, humidity, pressure; the name and the model only at the first call, they never change). Removing a sensor or the key by mistake and putting it back does not make an early call.

The API key is kept by Gladys in its database, never shown again, and sent only to the PurpleAir API (api.purpleair.com) in a header, never in a link nor in the logs. The read key of a private sensor is kept the same way; the API wants it in the request link, which is never logged.

Pace and errors

• Nothing reads a sensor (nor calls the API) sooner than its interval: not the test button, nor the Discovery tab, nor a reconnection, nor a saved configuration, nor a restart of the container. The time of the last request is kept in /data (written at most once a minute).
• A sensor or the API answering 429 or 5xx: a pause (Retry-After, else 5 minutes doubling, 1 minute to 6 hours), kept across restarts; the test button waits for it too.
• A refused API key, or an account without points: no cloud call for 6 hours (or until you change the key); the test button tries again once the interval has passed. The local sensors carry on.
• An unknown sensor index or a refused private sensor: no call for that sensor for 6 hours (or until its read key changes).
• A cloud sensor that PurpleAir has not heard from for an hour publishes nothing ("offline").

Test button

"Test the sensors" reads each sensor whose interval has passed and shows the last values (PM1 included) and the time of the next possible read.

Credits

The cloud client follows aiopurpleair (MIT, Aaron Bach), the library Home Assistant uses: endpoint, header of the key, error codes. See THIRD_PARTY_NOTICES.md.

Konfigurationseinstellungen

Diese Einstellungen fragt PurpleAir in seinem Konfigurationsbildschirm in Gladys ab.

Einstellung	Typ	Pflichtfeld	Beschreibung
PurpleAir in Gladys	section	Nein	Unofficial connector, not affiliated with PurpleAir, Inc. It reads your PurpleAir sensors: PM2.5, PM10, the US AQI computed from PM2.5, and the temperature, humidity and pressure measured inside the sensor. Read only: nothing is ever changed on the sensor. Local mode is recommended: free, no account, enter the IP address of the sensor on your network (a fixed address in your router is best). The cloud mode uses the official API, whose calls cost points (paid credits): it is read every hour by default. Never tested with a real sensor yet.
Sensor address (local)	string	Nein	Its IPv4 address (or host name) on your network: the integration reads its page http://<address>/json. Free, no account.
Second sensor address (local)	string	Nein
Third sensor address (local)	string	Nein
Local read interval (minutes)	number	Nein	One request per sensor each time; the sensor averages over 2 minutes. Nothing reads a sensor sooner, not even the test button or a restart.
Cloud mode (optional, paid)	section	Nein	For a sensor you cannot reach on your network. Create an API key (a READ key) in develop.purpleair.com: each call costs points, bought from PurpleAir. The sensor index is the number shown in the PurpleAir map ("select=" in its link). A private sensor also needs its read key.
API key (read)	secret	Nein	Kept by Gladys in its database, never shown again; sent only to the PurpleAir API (api.purpleair.com), in a header, never in a link nor in the logs.
Sensor index (cloud)	string	Nein
Read key of a private sensor (optional)	secret	Nein	Kept by Gladys in its database, never shown again; sent only to the PurpleAir API.
Second sensor index (cloud)	string	Nein
Second sensor: read key (optional)	secret	Nein	Kept by Gladys in its database, never shown again; sent only to the PurpleAir API.
Third sensor index (cloud)	string	Nein
Third sensor: read key (optional)	secret	Nein	Kept by Gladys in its database, never shown again; sent only to the PurpleAir API.
Cloud read interval (minutes)	number	Nein	One API call per sensor each time, each costing points: 60 minutes by default, 10 at least. Nothing calls the API sooner, not even the test button or a restart.

So installierst du PurpleAir in Gladys

1. Öffne in Gladys Integrationen: PurpleAir erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/lm1lc3n7/gladys-purpleair:0.1.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration).
3. Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
4. Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/LM1LC3N7/gladys-purpleair.

PurpleAir benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.

Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.

Über externe Integrationen

PurpleAir ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von LM1LC3N7 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.

• Alle Integrationen durchsuchen, native und aus der Community
• Deine eigene externe Integration bauen und veröffentlichen
• Quellcode auf GitHub — Quelle dieser Dokumentation

Abonniere den Newsletter von Gladys Assistant

Ein paar E-Mails im Monat zu neuen Releases und Neuigkeiten aus dem Projekt. Verschickt von Pierre-Gilles Leymarie, dem Gründer des Projekts. Jederzeit abbestellbar 🙂