Philips Air smart home integration, free and open source
Philips air purifiers and humidifiers on the local network: air quality, modes, filters.
Published by guim31
- Devices
- Version 1.0.1
- Requires Gladys >=5.1.0
- ★ 0
Control your connected Philips air purifiers and humidifiers from Gladys, on your local network, without the Philips cloud: air quality (PM2.5, allergen index, humidity), modes and fan speed, target humidity, child lock, display light, and the hours left on each filter. Changes made on the purifier or in the Philips app show up in Gladys within seconds.
Developed without the hardware: feedback welcome. This integration was written from the protocol as documented by the open-source community, and tested against a simulated purifier. If your model behaves differently, open an issue at https://github.com/guim31/gladys-philips-air/issues with the output of the probe script (see Troubleshooting).
Not affiliated with Philips or Versuni. Philips is a trademark of Koninklijke Philips N.V.
Requirements
- Gladys Assistant 5.1 or later.
- A Philips purifier or humidifier with Wi-Fi that speaks the local CoAP protocol (UDP port 5683): the AC series (AC2889, AC2729, AC3829, AC3858, AC4236, Series 2000i and 3000i…), the newer AC0850, AC0950, AC2220, AC3220, AC3420, AC4220, and the HU humidifiers (HU1509, HU4209, HU5710…). The full list is under "Supported models".
- The purifier set up once in the Philips Air+ app (it joins your Wi-Fi there), on the same local network as Gladys.
- Its IP address. Your router lists it (the device often appears as
MXCHIP…). Give it a fixed address (DHCP reservation) in your router: the integration finds the purifier at the address you enter.
Configuration
In Gladys, open Integrations → Philips Air → Configuration:
| Field | What it does |
|---|---|
| IP addresses of the purifiers | One or more IPv4 addresses, separated by commas. |
| Refresh interval | How often each purifier is read (10 s to 2 min, 30 s by default). Changes are usually pushed at once by the purifier; this read is the safety net. |
| Filter replacement warning | When the maintenance trigger fires for a filter to replace: when the purifier asks (default), or 1 day, 3 days, 1 week before. The pre-filter is always announced when the purifier asks for it. |
| Language of the device names | Language of the names given to new devices, their features, the mode list and the trigger messages. French by default. |
Save, then open the Discovery tab: one device per purifier, named after the name it has in the Philips
app and its model, for example Bedroom (AC2729/10). Add it to Gladys.
The Check the purifiers button (Configuration screen) reads every address at once and tells which purifiers answer, and which model is not in the list of the integration.
The device
Each purifier gets only the features its model has:
| Feature | In Gladys |
|---|---|
| Power | On/off switch. |
| Mode | List of the modes of the model (see below). |
| Fan speed | Manual speed, 1 to 2, 3 or 5 depending on the model. Setting it selects "Manual". |
| PM2.5 | Fine particles, in µg/m³. |
| Allergen index | Philips indoor allergen index, 1 (good) to 12 (very poor). |
| Humidity | Relative humidity, in % (models with a humidity sensor). |
| Temperature | In °C (models with a temperature sensor). |
| Target humidity | List of the targets the humidifier accepts (40 to 70 %, or 30 to 70 %). |
| Humidification | Switches the humidifier part of a 2-in-1 purifier on or off. |
| Water tank | "Low" when the tank is empty or removed, "Normal" otherwise. |
| Child lock | Locks the buttons of the purifier. |
| Display light | Brightness of the display and the air quality ring. |
| Pre-filter (hours left) | Hours before the pre-filter needs cleaning. |
| HEPA filter (hours left) | Hours before the HEPA (or NanoProtect) filter needs replacing. |
| Carbon filter (hours left) | Hours before the active carbon filter needs replacing. |
| Wick (hours left) | Hours before the humidifier wick needs replacing. |
Modes
Depending on the model: Auto, Allergen, Bacteria and virus, Pollution, Gentle, Medium, High, Sleep, Allergy sleep, Turbo, and Manual (a fixed fan speed). Choosing a mode also switches the purifier on. A model missing from the list of the integration still gets its sensors, its power switch and its filters, but no mode list.
Dashboard widget
The Philips purifier widget shows, for the purifier chosen in its settings:
- PM2.5 and humidity, live;
- the mode, the allergen index on the Philips scale (Good, Fair, Poor, Very poor), the running boost and its end time, and what the purifier asks for (or the filter closest to its end);
- buttons: two usual modes (Auto or Pollution, Sleep), Boost for 15, 30 or 60 minutes (widget setting), and on/off.
Scene trigger
Purifier maintenance needed fires once when a purifier starts asking for care, and again only after it was done (filter replaced, tank refilled):
- Pre-filter to clean (when the purifier asks for it);
- HEPA filter to replace, Carbon filter to replace, Wick to replace (when the purifier asks, or earlier: see the "Filter replacement warning" setting);
- Water tank empty (while humidifying).
Filters: the purifier, and the items you care about. Variables: item, hours_left, and message, a
ready-made text such as "Bedroom (AC2729/10): HEPA filter to replace (70 h left)" in the language of the
configuration.
Scene action
Boost the purifier runs the purifier in Turbo (or at its highest speed) for 5 to 240 minutes, then puts
it back in the mode it had, or switches it off if it was off. If someone changes the purifier during the
boost, the boost ends without touching it. The action outputs until, the end of the boost.
Scene examples
- After cooking: when the kitchen PM2.5 goes above 35 µg/m³, Boost the purifier for 20 minutes.
- Filter reminder: on Purifier maintenance needed, send
{{triggerEvent.data.message}}to your phone. - Night: at 10:30 pm, set the bedroom purifier mode to Sleep and its display light to Off; at 7 am, back to Auto.
- Away: when the house is empty, switch the purifiers to Auto; when the first person comes home, Boost the purifier for 15 minutes.
Troubleshooting
- "No Philips purifier answers": check the IP address (it may have changed: give it a fixed one), that the purifier is plugged in and on Wi-Fi, and that it answers in the Philips app. A strict firewall on the Gladys machine (ufw…) can block the UDP traffic between the integration container and your network.
- It worked, then stopped answering: the firmware of these purifiers is known to stop answering local requests after a while (also seen with Home Assistant). Unplug the purifier for 10 seconds; the integration reconnects by itself.
- A model without the mode list: your model is not in the list yet. Run the probe script from a computer
on the same network,
node scripts/probe.mjs <IP address>(in a clone of the repository, Node.js 22+): it only reads, and masks the identifiers. Paste its output in an issue. - More details: the logs of the integration (Gladys → Integrations → Philips Air → Logs) only show the
life of the purifiers at the normal level; set
LOG_LEVEL=debugon the container for every read.
Limits
- Local control only (CoAP over UDP 5683). The older models that only speak HTTP, and the newest firmware that closed the local access, are not supported.
- No automatic discovery: the purifiers do not announce themselves in a way the Gladys container can see. Enter their IP address.
- Mode lists come from what the open-source community observed; a model may accept a mode its list does not show, or the reverse. Timers, beep, ambient light and the "preferred index" of some models are not exposed.
- The pushed changes go through the Docker network of Gladys; when they do not, the next read (30 s by default) brings them.
- A boost in progress survives a restart of the integration, but ends at the next answer if the purifier was away when it was due.
Supported models
- AC series, classic firmware: AC2729, AC2889, AC2936, AC2939, AC2958, AC2959, AC3021, AC3033, AC3036, AC3039, AC3055, AC3059, AC3259, AC3829, AC3854/50, AC3854/51, AC3858/50, AC3858/51, AC3858/83, AC3858/86, AC4231, AC4236, AC5659, AC5660.
- AC1715 and AC0850 (firmware "AWS_Philips_AIR").
- New generation: AC0850 (firmware "AWS_Philips_AIR_Combo"), AC0950, AC0951, AC2210, AC2220, AC2221, AC3210, AC3220, AC3221, AC3420, AC3421, AC4220, AC4221.
- Humidifiers: HU1509, HU1510, HU4209, HU4210, HU5710.
Other models of these generations get their sensors, power and filters.
Support and credits
Issues and feedback: https://github.com/guim31/gladys-philips-air/issues
The protocol was reverse-engineered by Radoslav Gerganov (py-air-control) and implemented by betaboon and kongo09 (aioairctrl, philips-airpurifier-coap for Home Assistant); this integration owes them everything. Not affiliated with Philips or Versuni.
Configuration settings
These are the settings Philips Air asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Connecting your purifiers | section | No | Gladys talks to Philips purifiers on your local network, without the Philips cloud. Set up the purifier in the Philips Air+ app first, then enter its IP address below (a fixed address in your router is best). Not affiliated with Philips or Versuni. |
| IP addresses of the purifiers | string | No | Separated by commas. Your router lists them (the device is often named "MXCHIP"). |
| Refresh interval | select | No | How often each purifier is read. Changes are usually pushed at once; this read is the safety net. |
| Filter replacement warning | select | No | When the "Maintenance needed" trigger fires for a filter to replace (HEPA, carbon, wick). The pre-filter is announced when the purifier asks. |
| Language of the device names | select | No | Names given to new devices, their features, the mode list and the trigger messages. |
How to install Philips Air in Gladys
- In Gladys, open Integrations: Philips Air appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-philips-air: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-philips-air.
Philips Air 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
Philips Air 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