Philips Air Binding [5.2.0.0;6.0.0.0)

marcel_verpaalen · September 27, 2026, 8:25pm

Philips Air Binding

Binding to support the integration with Philips Air Purifiers including the models based on COAP communication protocol (most >2019 models)

Note may require to (manually) install coap and upnp transport

feature:install openhab-transport-coap
feature:install openhab-transport-upnp

Installation

Uninstall/remove any older philipsair JAR from your addons folder first.
Either:
- KAR: drop the .kar file into the addons folder. It pulls in the required CoAP and UPnP transport features automatically.
- JAR: drop the .jar into the addons folder and install the transports yourself from the Karaf console:
  feature:install openhab-transport-coap openhab-transport-upnp
Check with bundle:list | grep -i philips that it is Active. The binding should now be listed when you add a Thing.

Changelog

2021-11-04 Initial market place version.

fixed: several code warnings & NPE warnings
source GitHub - marcelrv/openhab-addons at philipsair-coap-v2

2022-12-15 Minor update

Version bump for 3.4, Removed uuid pattern constraint which gives issues in the new releases
source GitHub - marcelrv/openhab-addons at philips-air-coap-oh34

2023-09-24 Version bump oh4 - Minor update

Version bump for 4.x, minor cleanup and remove dependency for apache commons
source GitHub - marcelrv/openhab-addons at philipsair-coap-oh4

2026-09-27 Version bump oh5.2 - Minor update

The binding now shows up in the UI again. It still used the old openHAB 2 style binding description, which openHAB 4+ no longer reads. So the bundle was Active but didn’t appear as an add-on, and you could only add things through the Inbox. @ollo, I think this is what you ran into.
Humidifier channels for CoAP devices. Humidity setpoint (rhset), function (func), humidity (rh), temperature (temp), water level (wl) and wick filter (wicksts) are now added automatically once your device reports them. Devices without a humidifier don’t get these extra channels. @Fargi, this should cover the parameters you were missing, without the modified JAR.
Better model recognition in UPnP discovery. Model numbers with a region suffix (e.g. AC2889/10, AC2729/50) are now recognized instead of falling back to the universal thing type.
source GitHub - marcelrv/openhab-addons at philipsair-52

2026-10-01 Major update Preparation for openhab inclusion

see description in below post Philips Air Binding [5.2.0.0;6.0.0.0) - #5 by marcel_verpaalen

source GitHub - marcelrv/openhab-addons at philipsair-53

2026-10-01 Major update: device profile for newer generations (gen 2&3)

see description in below Philips Air Binding [5.2.0.0;6.0.0.0) - #25 by marcel_verpaalen

source GitHub - marcelrv/openhab-addons at philipsair-53

Auto build Jar files
v 5.2.1 https://github.com/marcelrv/philipsair-builds/releases/download/philipsair-oh5.2.1-latest/org.openhab.binding.philipsair-5.2.1.jar
v 5.3-SNAPSHOT https://github.com/marcelrv/philipsair-builds/releases/download/philipsair-oh-snapshot-latest/org.openhab.binding.philipsair-5.3.0-SNAPSHOT.jar

auto build KAR files
v 5.2.1 https://github.com/marcelrv/philipsair-builds/releases/download/philipsair-oh5.2.1-latest/org.openhab.binding.philipsair-5.2.1.kar
v 5.3-SNAPSHOT https://github.com/marcelrv/philipsair-builds/releases/download/philipsair-oh-snapshot-latest/org.openhab.binding.philipsair-5.3.0-SNAPSHOT.kar

Notes:

Philips Air Binding is developed by Michał Boroński
(GitHub - michalboronski/openhab-addons: Add-ons for openHAB 2.x
Coap protocol support (this version) contributed by [Marcel Verpaalen] (Profile - marcel_verpaalen - openHAB Community)
Discussion topic in this forum: Binding request: Philips air purifier
Market place topic for 3.x version: Philips Air Binding [3.0.0.0;4.0.0.0)
Market place topic for 4.x version: https://community.openhab.org/t/philips-air-binding-4-0-0-0-5-0-0-0

Alternative installation jar (you must manually install coap and upnp transport): https://verpaalen.com/openhab/org.openhab.binding.philipsair-5.2.1.jar

Resources

https://verpaalen.com/openhab/org.openhab.binding.philipsair-5.2.1.kar

dpa-openhab · September 28, 2026, 4:31pm

Why this addon version has no kar tag? Previous versions had it - https://community.openhab.org/t/philips-air-binding-4-0-0-0-5-0-0-0/ .

I try to find a marketplace add-on, which at the same time works with openHAB 5.2.0, and enables features, when installed over the market place. Thus it is distributed as KAR. In case the explanation is that it does not work this way, has it worked in the past, before openHAB 5?

marcel_verpaalen · September 28, 2026, 4:49pm

yes, seems i missed the tag. it is there now

Fargi · September 28, 2026, 6:44pm

Hi, it looks like communication with my two air purifiers is working, but the console shows numerous error messages whenever data is updated—for example, “Failed installing ‘openhab-binding-philipsair’: Error:” and “Failed to refresh bundles after processing config update.” I am using OpenHAB version 5.3.0.M1.

marcel_verpaalen · October 1, 2026, 8:55pm

Philips Air binding – updated test version (OH 5.2.1)

I’ve been reworking the Philips Air Purifier binding. This is a test version, and I’d like feedback from owners of different models before I turn it into a PR. With positive feedback that this version is working I’ll submit it for review and inclusion in the main openhab addons.

READ THE BREAKING CHANGE BELOW. You most likely need to remove your old thing and discover it new

What’s new

More models

Recent CoAP models that report numbered fields (e.g. `D03-02`, `D03102`) are now supported. Power, child lock, PM2.5, allergen index, humidity, temperature, filter lifetimes and device properties work. Power and child lock commands are translated to the device’s scheme. Other commands are not sent to these models yet.
AC2939/10, AC3033/10 and AC5659/10 (reported to work in this forum) are added to the documentation.
Some models need more details before they can be fully supported. The README lists what to send me.

Model-specific options and channels

The displayed index and air quality threshold only offer the values your model supports.
Light level commands are rounded to the supported levels (0-100, step 25).
New optional `tvoc` and `rssi` channels, filter type properties, and timer channels (only when the device reports them).
PM2.5 shows in µg/m³ and the timer in minutes. Before, SI units were used and PM2.5 rounded to 0.

Stability and reliability

CoAP devices in standby no longer go offline after two minutes. The binding pings them with a method they answer in standby, and restarts the observe relation when they respond again.
CoAP status updates are pushed from the device to the handler. The old approach slept and polled on the shared scheduler.
Commands and refreshes run in order on the openHAB scheduler instead of blocking. This also fixes some command races and key renewal.
HTTP requests use a fixed 10 second timeout, so an unreachable device can’t block a command for minutes.
Fixed key exchange and connection leaks, and the observe relation left behind when a thing is disposed.
Values the device doesn’t send now show as NULL instead of 0.
Device names with non-ASCII characters are decoded correctly (UTF-8).
CoAP discovery no longer blocks for 15 seconds or more per broadcast address.
Much less debug logging. Full CoAP dumps are only at trace level.

Cleanup

Aligned with the openHAB coding guidelines, with a rewritten README, semantic tags (AirFilter), i18n and an addon.xml.
Many more unit tests.

Breaking changes

Thing types and channel IDs were renamed (for example ac2889_10 → ac2889-10, and descriptive channel IDs). Existing things and item links will likely need to be re-created. Check the README for the current IDs.
The legacy `enableAutoDiscovery` option is removed.

Downloads (built for openHAB 5.2.1)

org.openhab.binding.philipsair-5.2.1.jar
org.openhab.binding.philipsair-5.2.1-slim.kar

The kar needs testing by others

I built the kar by hand and only tested it on my own setup. Please tell me if it works for you.

If the kar gives problems OR when transitioning from a kar to a jar:

Remove the kar from addons/, and any leftover userdata/tmp/kar/org.openhab.binding.philipsair-* folder.
Put the jar in addons/.
Install the two required features manually in the Karaf console:


   feature:install openhab-transport-coap

   feature:install openhab-transport-upnp

For testing:
https://verpaalen.com/openhab/org.openhab.binding.philipsair-5.2.1-slim.kar
https://verpaalen.com/openhab/org.openhab.binding.philipsair-5.2.1.jar

note the former https://verpaalen.com/openhab/org.openhab.binding.philipsair-5.2.1.jar has been renamed to https://verpaalen.com/openhab/org.openhab.binding.philipsair-5.2.1-legacy.jar

Mclupo · October 2, 2026, 9:34am

Raspi is updated to OH 5.2 snapshot under bookworm. Your latest binding is installed and is working.

That are the channels for device AC2939/10 (PH 01)

which were like the channels of AC0950/10 (PH02)

So for the older device most of the channels are gone.

marcel_verpaalen · October 2, 2026, 10:36am

Pls share a debug log, it will show the device responses and we can derive the right available channels

Did you remove the old thing and had it discover again?

ollo · October 2, 2026, 10:41am

Hi Marcel,

thanks, with the new jar I’m finally able to receive updates from my AC3210. I’m using the CoAP and received updates for PM25, Temp, Humidity and IAQL. AQIT stays NULL and so does the Error channel.

2026-10-02 12:45:19.796 [DEBUG] [nnection.PhilipsAirCoapAPIConnection] - Status from 192.168.178.77: {"D01102":0,"D01S03":"Schlafzimmer","D01S04":"Unicorn","D01S05":"AC3210/12","D01107":0,"D01108":3,"D01109":3,"D0110A":0,"D0110C":19,"D01S0D":"688001001383","D0110F":3,"D01S12":"0.2.3","D01213":0,"ProductId":"96b12d8fb50111ee899806d016384e4a","DeviceId":"878ba852c95711f0b0ec0591d634e763","otacheck":false,"Runtime":328108,"rssi":-46,"wifilog":false,"blelog":-1,"free_memory":97904,"WifiVersion":"AWS_Philips_AIR_Combo@86","StatusType":"status","ConnectType":"Online","D03102":1,"D03103":0,"D03105":101,"D03106":1,"D0310A":2,"D0310C":0,"D0310D":1,"D03110":0,"D03211":0,"D03112":0,"D03115":0,"D0311F":0,"D03120":1,"D03221":1,"D03224":241,"D03125":46,"D0312A":1,"D0312B":1,"D0312C":7,"D03130":0,"D03134":1,"D03135":1,"D03136":0,"D03137":1,"D03240":0,"D03180":1,"D03182":1,"D0313B":20,"D03R81":"BQEBAgIBAgMD\n","D05102":3,"D05207":720,"D05408":9600,"D0520D":601,"D0540E":2870,"name":"Schlafzimmer","modelid":"AC3210/12","swversion":"0.2.3","pwr":"1","cl":false,"iaql":1,"pm25":1,"rh":46,"temp":24.1,"fltsts0":601,"fltsts1":2870}

dpa-openhab · October 2, 2026, 11:45am

Does it still work when META-INF/MANIFEST.MF is removed from the .kar file? Do `.kar` files need `META-INF/MANIFEST.MF`? · Issue #2192 · apache/karaf · GitHub states this file can be removed, but at Describe `.kar/META-INF/MANIFEST.MF`: `Karaf-Feature-Start: false` in user-guide/kar.adoc · Issue #2961 · apache/karaf · GitHub I have written that, when looking at the source code, it seems fields from MANIFEST.MF are read and kar:create does fill these fields.
Does it still work, when from org.openhab.binding.philipsair-5.2.1 .jar the directory META-INF/maven is removed? bnd-maven-plugin prevents maven-jar-plugin/configuration/archive/addMavenDescriptor to avoid adding META-INF/maven directory · Issue #7446 · bndtools/bnd · GitHub suggests how to adjust the build process to avoid creating META-INF/maven/.

Mclupo · October 2, 2026, 11:47am

Reinstalling the device did the job. Thank’s very much for your help

marcel_verpaalen · October 2, 2026, 1:29pm

haha, maybe that was overstating it… Claude told me it build it by hand.. I did not want to insult the AI overlords by pointing our that it did not have any hands.. -

I’ll feed Claude your findings for the next build… maybe it does a better job than the first time (it needed a few tries to come with this kar file…)

Mclupo · October 2, 2026, 6:39pm

I use the PM2.5 value to toggle the item color. Now you can see, that the value jumps between 4 or 5 or 6 ug/m^3 and gets updated nearly every 2-3 seconds. Is it possible to limit the update frequency?

marcel_verpaalen · October 2, 2026, 6:53pm

I’m need to double check, i’m not so sure, as i now update whenever the device sends the data, instead of polling every x seconds.

in the old way we requested the data each time, and the intermediate reports from the device were dropped, now we only request if we did not hear from the device for some time (I think twice the defined polling time)

Fargi · October 2, 2026, 8:15pm

Great work. I recreated the Things for my AC2729 (http) and AC3829 (coap) air purifiers. All values are updated with every change (even as frequently as every second). For the AC3829, the Thing was created twice—once with only some channels, and a second time with all of them. I then deleted the first Thing. The only minor issue are the error messages appearing in the log every 60 seconds. (openHAB 5.3.0.M1)

Fargi · October 2, 2026, 8:16pm

22:04:50.811

OpenHAB

2026-10-02 22:04:50.564 [ERROR] [core.karaf.internal.FeatureInstaller] - Failed installing ‘openhab-binding-philipsair’: Error:

22:04:53.314

OpenHAB

2026-10-02 22:04:53.310 [ERROR] [core.karaf.internal.FeatureInstaller] - Failed to refresh bundles after processing config update

22:04:53.314

OpenHAB

org.apache.karaf.features.internal.util.MultiException: Error:

22:05:14.113

OpenHAB

2026-10-02 22:05:14.100 [INFO ] [tomation.jsscripting.rule.83e57b1b46] - OH> PM25> : 18 µg/m³

22:05:16.375

OpenHAB

2026-10-02 22:05:16.219 [INFO ] [tomation.jsscripting.rule.83e57b1b46] - OH> PM25> : 19 µg/m³

22:05:18.358

OpenHAB

2026-10-02 22:05:18.312 [INFO ] [tomation.jsscripting.rule.83e57b1b46] - OH> PM25> : 17 µg/m³

22:05:21.615

OpenHAB

2026-10-02 22:05:21.466 [INFO ] [tomation.jsscripting.rule.83e57b1b46] - OH> PM25> : 16 µg/m³

22:05:22.600

OpenHAB

2026-10-02 22:05:22.529 [INFO ] [tomation.jsscripting.rule.83e57b1b46] - OH> PM25> : 15 µg/m³

22:05:24.637

OpenHAB

2026-10-02 22:05:24.620 [INFO ] [tomation.jsscripting.rule.83e57b1b46] - OH> PM25> : 14 µg/m³

22:05:25.871

OpenHAB

2026-10-02 22:05:25.679 [INFO ] [tomation.jsscripting.rule.83e57b1b46] - OH> PM25> : 15 µg/m³

22:05:27.866

OpenHAB

2026-10-02 22:05:27.774 [INFO ] [tomation.jsscripting.rule.83e57b1b46] - OH> PM25> : 14 µg/m³

22:05:31.109

OpenHAB

2026-10-02 22:05:30.900 [INFO ] [tomation.jsscripting.rule.83e57b1b46] - OH> PM25> : 13 µg/m³

22:05:50.634

OpenHAB

2026-10-02 22:05:50.511 [ERROR] [core.karaf.internal.FeatureInstaller] - Failed installing ‘openhab-binding-philipsair’: Error:

22:05:53.606

OpenHAB

2026-10-02 22:05:53.444 [ERROR] [core.karaf.internal.FeatureInstaller] - Failed to refresh bundles after processing config update

22:05:53.606

OpenHAB

org.apache.karaf.features.internal.util.MultiException: Error:

22:05:57.119

OpenHAB

2026-10-02 22:05:56.934 [INFO ] [tomation.jsscripting.rule.83e57b1b46] - OH> PM25> : 14 µg/m³

22:06:04.380

OpenHAB

2026-10-02 22:06:04.248 [INFO ] [tomation.jsscripting.rule.83e57b1b46] - OH> PM25> : 15 µg/m³

marcel_verpaalen · October 2, 2026, 9:25pm

Are you using some custom transformation, automation.jsscripting.rule is not from the binding.
2026-10-02 22:05:56.934 \[INFO \] \[tomation.jsscripting.rule.83e57b1b46\] - OH> PM25> : 14 µg/m

Suggest to clean the karaf binding versions (see the post), maybe there is a stale version.
if the issue persist install the jar.

I’ll share in 1 or 2 days a update with the update for @ollo device and kar file with the info from @dpa-openhab

Fargi · October 2, 2026, 9:45pm

Yes, the PM2.5 values come from the rule; I was testing how often they change. Currently, I am not using either a .jar or .kar file in the addons folder. The version from 1.10.2026 was installed.

Fargi · October 2, 2026, 9:51pm

The errors in the log are likely related to Netty version compatibility.2026-10-02 23:42:50.649 [ERROR] [core.karaf.internal.FeatureInstaller] - Failed installing ‘openhab-binding-philipsair’: Error:
Error downloading mvn:io.netty/netty-codec-http2/4.1.133.Final
Error downloading mvn:io.netty/netty-handler/4.1.133.Final
Error downloading mvn:io.netty/netty-transport-native-unix-common/4.1.133.Final
Error downloading mvn:io.netty/netty-tcnative-classes/2.0.77.Final
Error downloading mvn:io.netty/netty-codec-mqtt/4.1.133.Final
Error downloading mvn:io.netty/netty-common/4.1.133.Final
Error downloading mvn:io.netty/netty-transport-classes-epoll/4.1.133.Final
Error downloading mvn:io.netty/netty-codec-http/4.1.133.Final
Error downloading mvn:io.netty/netty-buffer/4.1.133.Final
Error downloading mvn:io.netty/netty-transport-native-kqueue/4.1.133.Final
Error downloading mvn:io.netty/netty-handler-proxy/4.1.133.Final
Error downloading mvn:io.netty/netty-transport-native-epoll/4.1.133.Final
Error downloading mvn:io.netty/netty-codec/4.1.133.Final
Error downloading mvn:io.netty/netty-transport/4.1.133.Final
Error downloading mvn:io.netty/netty-codec-socks/4.1.133.Final
Error downloading mvn:io.netty/netty-resolver/4.1.133.Final
2026-10-02 23:42:53.356 [ERROR] [core.karaf.internal.FeatureInstaller] - Failed to refresh bundles after processing config update
org.apache.karaf.features.internal.util.MultiException: Error:
Error downloading mvn:io.netty/netty-tcnative-classes/2.0.77.Final
Error downloading mvn:io.netty/netty-codec-http2/4.1.133.Final
Error downloading mvn:io.netty/netty-transport-classes-epoll/4.1.133.Final
Error downloading mvn:io.netty/netty-common/4.1.133.Final
Error downloading mvn:io.netty/netty-transport-native-unix-common/4.1.133.Final
Error downloading mvn:io.netty/netty-handler/4.1.133.Final
Error downloading mvn:io.netty/netty-codec-mqtt/4.1.133.Final
Error downloading mvn:io.netty/netty-codec-http/4.1.133.Final
Error downloading mvn:io.netty/netty-buffer/4.1.133.Final
Error downloading mvn:io.netty/netty-handler-proxy/4.1.133.Final
Error downloading mvn:io.netty/netty-codec/4.1.133.Final
Error downloading mvn:io.netty/netty-transport-native-kqueue/4.1.133.Final
Error downloading mvn:io.netty/netty-codec-socks/4.1.133.Final
Error downloading mvn:io.netty/netty-transport-native-epoll/4.1.133.Final
Error downloading mvn:io.netty/netty-resolver/4.1.133.Final
Error downloading mvn:io.netty/netty-transport/4.1.133.Final

Mclupo · October 3, 2026, 3:38am

Model AC 0950/10 shows 14 channels, but only some are receiving data.

data for : power , child lock, PM2.5 , Allergen index, prefilter , hepa filter

no data for : fanspeed,mode. button light, LED level, displayed index , air quality threshold, error message, carbon

Mclupo · October 3, 2026, 2:42pm

Part of the log from AC 0950/10

16:35:10.064","DEBUG","org.openhab.binding.philipsair.internal.PhilipsAirHandler","Sending controls#mode as S"
"16:35:10.066","DEBUG","org.openhab.binding.philipsair.internal.connection.PhilipsAirCoapAPIConnection","Command '{""mode"":""S""}' is not supported by 192.168.1.76"
"16:35:10.079","DEBUG","org.openhab.binding.philipsair.internal.PhilipsAirHandler","Sending controls#mode as S"
"16:35:10.082","DEBUG","org.openhab.binding.philipsair.internal.connection.PhilipsAirCoapAPIConnection","Command '{""mode"":""S""}' is not supported by 192.168.1.76"
"16:35:21.243","DEBUG","org.openhab.binding.philipsair.internal.connection.PhilipsAirCoapAPIConnection","Status from 192.168.1.76: {""D01102"":0,""D01S03"":""Schlafzimmer"",""D01S04"":""Unicorn"",""D01S05"":""AC0950/10"",""D01107"":0,""D01108"":3,""D01109"":3,""D0110A"":0,""D0110B"":0,""D0110C"":18,""D01S0D"":""688001001366"",""D0110F"":3,""D01S12"":""0.3.3"",""D01213"":0,""ProductId"":""e3a1f43cfacc11ee974e06d016384e4a"",""DeviceId"":""fc50a199bceb11f18844e3188138d24e"",""otacheck"":false,""Runtime"":104267550,""rssi"":-23,""wifilog"":false,""blelog"":-1,""free_memory"":97712,""WifiVersion"":""AWS_Philips_AIR_Combo@86"",""StatusType"":""status"",""ConnectType"":""Online"",""D03102"":1,""D03103"":0,""D03104"":123,""D03105"":123,""D0310A"":2,""D0310C"":0,""D0310D"":1,""D03110"":0,""D03211"":0,""D03120"":1,""D03221"":3,""D0312A"":1,""D0312B"":1,""D0312C"":4,""D03130"":0,""D03134"":0,""D03136"":0,""D03240"":0,""D0313B"":20,""D05207"":720,""D05408"":9600,""D0520D"":662,""D0540E"":9542,""name"":""Schlafzimmer"",""modelid"":""AC0950/10"",""swversion"":""0.3.3"",""pwr"":""1"",""cl"":false,""iaql"":1,""pm25"":3,""fltsts0"":662,""fltsts1"":9542}"