Blueair smart home integration, free and open source
Blueair air purifiers through the Blueair cloud: air quality, filter, fan and modes.
Published by guim31
- Devices
- Version 1.0.1
- Requires Gladys >=5.1.0
- ★ 0
Follow and control your Blueair air purifiers from Gladys: air quality (PM2.5, PM10, VOC), filter life, power, fan speed, auto / night / eco modes, display brightness and child lock — through the Blueair cloud, the same one the Blueair app uses. Get told once when a filter needs replacing, and put every purifier in night mode with one tap at bedtime.
Developed without the hardware: feedback welcome. This integration was built and tested against real answers of the Blueair cloud captured by the open-source projects blueair_api and ha_blueair, not against a purifier or an account. If something does not work as described, please say so on the Gladys forum or in the issues.
Not affiliated with, endorsed or supported by Blueair or Unilever. Blueair is a trademark of its owner.
What you need
- Gladys Assistant 5.1.0 or later.
- A Blueair purifier connected to Wi-Fi and set up in the Blueair app (Blue Pure Max, Protect, DustMagnet, HealthProtect, Signature, Classic, 2-in-1…).
- The e-mail and password of your Blueair account, and its region (the one chosen when the account was created).
- An Internet connection: everything goes through the Blueair cloud, there is no local control of Blueair devices.
Set up
- Install the integration from the Gladys catalog.
- In Configuration, enter the Blueair account e-mail, the Blueair account password and the Account region (Europe, North America, Australia, China).
- Save, then click Test the connection: the message under the button lists the devices of the account.
- Open the Discover tab: one device per Blueair device of the account. Click Add, pick a room, save.
Options:
- Refresh interval: how often the devices are read, from 1 to 5 minutes (2 minutes by default).
- Filter to replace at: the filter life left (5, 10, 15 or 20 %, 10 % by default) at which the filter counts as to replace.
- Language of the feature names: English, French, German or Spanish. The names are given when a device is added (French by default).
The password is only sent to Blueair. The integration keeps the Blueair
session under /data so a restart does not log in again.
The device of each purifier
Features
Each feature appears only when the device has it.
| Feature | What it is |
|---|---|
| Power | Switch: on, the purifier runs; off, standby |
| Fan speed | The manual speed, within the bounds of the model (see below) |
| Mode | Manual, Auto, Night, Eco (Eco on the Signature series only) |
| Display brightness | Brightness of the display and lights, 0–100 (0–4 on Classic models) |
| Child lock | Locks the buttons of the purifier |
| Filter life | Filter life left, in % |
| Filter to replace | 1 when the filter life left reaches the threshold of the configuration |
| PM2.5 | Fine particles, µg/m³ |
| PM10 | Coarse particles, µg/m³ |
| VOC | Volatile organic compounds, ppb (Protect, HealthProtect, Classic i-series) |
| CO2 | Carbon dioxide, ppm (Classic i-series) |
| Temperature | °C, on the models with the sensor |
| Humidity | %, on the models with the sensor |
| Online | 1 when the purifier is connected to the Blueair cloud |
Choosing a fan speed switches the purifier to manual mode, like the app does. Particle values are shown the way the Blueair app shows them (the cloud sends them 1.32 times higher; the integration corrects them like ha_blueair does). PM1 is not published: Gladys has no PM1 sensor.
Models
- Fan speed bounds: 0–91 on the four-speed models (Blue Pure Max, Protect, 2-in-1), 0–100 on the others, 1–3 on humidifiers, 0–3 on the Classic models of the older cloud (0 is off there).
- ComfortPure 3-in-1 (T10i, T20i): these devices heat. They are read only in Gladys (air quality, temperature, filter): a wrong scene must never leave a heater on. Use the Blueair app to drive them.
- Older models (Classic 205/280i/290i/480i/680i, Sense+) live on the older Blueair cloud: they are found with the same account. Their filter only says "to replace" or not, without a percentage.
- Humidifiers on the account also appear, with their power, speed, modes and sensors.
Dashboard widget
The Blueair purifiers widget, two layouts:
- every device (no device chosen in its settings): one line per device — its mode and PM2.5, colored green, orange or red by the air quality, "Filter to replace" when it is due, "Offline" when it is not connected — and two buttons, All in auto and All in night;
- one device: live tiles (PM2.5, filter life, temperature or VOC), its mode, filter and connection, and buttons: Turn off / Turn on and its modes (Auto, Night, Eco). The current mode has a check mark.
Scenes
Trigger
Blueair filter to replace: once per filter, when its life left reaches the threshold of the configuration (or when an older Classic says its filter is to replace). Not again for the same filter, even after a restart; once the filter is replaced, the next one will be announced. Filter: a device (empty: any). Information passed on: device name, model, filter life left (%).
Action
Set the Blueair mode: puts one device, or every device that offers the mode (device left empty), in Auto, Night, Eco or Manual mode. Returns the number of devices changed.
The device features can also be used directly in scenes: turn a purifier on or off, set its fan speed, or start a scene when PM2.5 goes above a value.
Scene ideas
- Bedtime: at 10:30 pm, Set the Blueair mode → Night, every device. In the morning, back to Auto.
- Filter reminder: trigger Blueair filter to replace → send a message "Replace the filter of {device name} ({filter life left} % left)".
- Smoke from the kitchen: when the PM2.5 of the kitchen purifier goes above 35 µg/m³, set its fan speed to the maximum; back to Auto when it drops below 10.
- Nobody home: when the house is empty, turn the purifiers off; on the way back, turn them on in Auto.
Refresh and Blueair cloud limits
Blueair publishes no quota for its cloud. The integration stays light:
- one request per device at each refresh (1 to 5 minutes, 2 by default);
- the air quality values are 5-minute averages on the Blueair side: they are read at most once every 5 minutes;
- the list of devices is read again every 6 hours (or with Scan in the Discover tab);
- the login is kept under
/dataand renewed from the session, without sending the password again; - a refused password stops every request until the configuration changes (repeated attempts would lock the account); a "too many requests" answer pauses everything for 10 minutes.
Gladys does not poll these devices: the integration refreshes them on its own timer. Changes made in the Blueair app show in Gladys at the next refresh.
Troubleshooting
- "e-mail or password refused by Blueair": check them in the Blueair app, then save the configuration again (the integration stops trying until then).
- "open the Blueair app once and complete your profile (name)": Blueair now requires a name on the account. Open the app, complete the profile, then click Test the connection.
- Connected, but no device: the region is probably wrong — try the other one (accounts created in the United Kingdom are often in "Europe").
- A purifier shows "Offline": check its Wi-Fi in the Blueair app. The Blueair cloud sometimes reports a working purifier as offline: recent sensor values count as a sign of life.
- Values do not change: the air quality values only change every 5 minutes on the Blueair side.
- Logs: set
LOG_LEVEL=debugto see every request (never the password or the tokens).
Limits
- Cloud only: no local control, and nothing works without Internet or when the Blueair cloud is down.
- No real-time updates: changes appear at the next refresh (MQTT, used by the app, is not implemented).
- The ComfortPure 3-in-1 heaters are read only. Their heating and cooling modes are not shown.
- PM1, the germ shield, the night light, the timer and the humidifier wick are not published.
- Accounts whose devices live in another region than the account itself (rare) are not supported.
- Developed without the hardware: the model families follow blueair_api and ha_blueair, which were built with real devices. Feedback is welcome.
Configuration settings
These are the settings Blueair asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your Blueair account | section | No | Enter the e-mail and password you use in the Blueair app, and the region chosen when the account was created. Every Blueair device of the account appears in the Discovery tab. The integration goes through the Blueair cloud: an Internet connection is needed. Not affiliated with Blueair or Unilever. |
| Blueair account e-mail | string | Yes | |
| Blueair account password | secret | Yes | |
| Account region | select | Yes | The region chosen in the Blueair app when the account was created. |
| Refresh interval | select | No | How often the devices are read from the Blueair cloud. Air quality values are 5-minute averages. |
| Filter to replace at | select | No | Filter life left at which the filter counts as to replace (feature and scene trigger). |
| Language of the feature names | select | No | Used for the devices added from now on, and the messages of the integration. |
How to install Blueair in Gladys
- In Gladys, open Integrations: Blueair appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-blueair:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/guim31/gladys-blueair.
Blueair requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Blueair is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation