/philips-airpurifier-coap

💨 Philips AirPurifier custom component for Home Assistant. Supports local CoAP protocol.

Primary LanguagePython

HACS Default GitHub Latest Release Community Forum

This is a Local Push integration for Philips airpurifiers. Currently only encrypted-CoAP is implemented.

Word of Caution

Due to a bug in the Philips devices, this integration is rather instable. It might or might not work. Even if it seems ok at first, it might stop working after a while. Sometimes, a power cycle of the Philips device helps. Sometimes, only a power cycle and a Home Assistant restart together help. It is frustrating. Do not report this as an issue here. Nobody can help right now. @mhetzi contributed timer code to attempt reconnects if the device is not responsive. Sometimes, that helps. But not always. You've been warned.

It all goes back to some reverse engineering by @rgerganov and you can read about it here: https://xakcop.com/post/ctrl-air-purifier/

Philips has recently introduced a proper API to remote control the devices. However, this only works with the Philips cloud and it is not public (yet?) but only integrates Google Home, Alexa and IFTTT. Using IFTTT with HA might be a more stable choice: https://ifttt.com/Philips_air_purifer

Credits

Coffee

Buy Me A Coffee

Install

Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.

Configuration

  • The integration attempts to autodiscover your purifiers. Autodiscovery is based on the MAC address and original hostname of the devices. Home Assistant will notify you, if that is successful.
  • Alternatively, go to Configuration -> Devices & Services
  • Click Add Integration
  • Search for Philips AirPurifier and select it
  • Enter the hostname / IP address of your device
  • The model type is detected automatically. You get a warning in the log, if it is not supported.

Note: configuration.yaml is no longer supported and your configuration is not automatically migrated. You have to start fresh.

Re-configuration

  • Should your devices change their IP address on the network, they need to be re-configured
  • If autodiscovery works for your device and network, Home Assistant will discover the device again (latest at the next restart) and identify that it knows it already. The IP address is then automatically adjusted and no user interaction is needed.
  • If autodiscovery doesn't work for you, you can simply add the device again as described above, using its new IP address. Home Assistant will detect that it knows the device already and adjust the configuration.

Supported models

  • AC0850
  • AC1214
  • AC1715
  • AC2729
  • AC2889
  • AC2936
  • AC2939
  • AC2958
  • AC2959
  • AC3033
  • AC3036
  • AC3039
  • AC3055
  • AC3059
  • AC3259
  • AC3737
  • AC3829
  • AC3836
  • AC3854/50
  • AC3854/51
  • AC3858/50
  • AC3858/51
  • AC3858/86
  • AC4236
  • AC4550
  • AC4558
  • AC5659
  • AMF765
  • AMF870
  • CX5120

Is your model not supported yet?

You can help to get us there.

Please open an issue and provide the raw status-data for each combination of modes and speeds for your model.

To aquire those information please follow these steps:

Prepare the environment

Create yourself a virtual environment

python -m venv env
source ./env/bin/activate

Install aioairctrl package inside the virtual environment

python -m pip install aioairctrl

Aquire raw status-data

  • Use the philips-app to activate a mode or speed
  • run the following command to aquire the raw data (still in the virtual environment)
aioairctrl --host $DEVICE_IP status --json

to exit the virtual environment, simply type

deactivate

Debugging

To aquire debug-logs, add the following to your configuration.yaml:

logger:
  logs:
    custom_components.philips_airpurifier_coap: debug
    coap: debug
    aioairctrl: debug

logs should now be available in home-assistant.log

Usage

Entities

The integration provides fan entities for your devices which are documented here.

It also provides a number of sensor entities for the air quality and other data measured by the device, as well as some diagnostic sensor entities with information about the filter or water fill level for humidifiers. A switch entity allows you to control the child lock function, should your device have one. Finally, there are some light entities to control the display backlight and the brightness of the air quality display and some select entities to set the humidification function on the devices that have that.

Services

Unlike the original philips_airpurifier_coap integration, this version does not provide any additional services anymore. Everything can be controlled through the entities provided.

Attributes

The fan entity has some additional attributes not captured with sensors. Specifcs depend on the model. The following list gives an overview:

attribute content example
name: Name of the device bedroom
type: Configured model AC2729
model_id: Philips model ID AC2729/10
product_id: Philips product ID 85bc26fae62611e8a1e3061302926720
device_id: Philips device ID 3c84c6c8123311ebb1ae8e3584d00715
software_version: Installed software version on device 0.2.1
wifi_version: Installed WIFI version on device AWS_Philips_AIR@62.1
error_code: Philips error code 49408
error: Error in clear text no water
preferred_index: State of preferred air quality index PM2.5, IAI
runtime: Time the device is running in readable text 9 days, 10:44:41

Icons

The integration also provides the original Philips icons for your use in the frontend. The icons can be accessed with the prefix pap: and should be visible in the icon picker. Credit for this part of the code goes to @thomasloven

icon name
Preview power_button
Preview child_lock_button
Preview auto_mode_button
Preview fan_speed_button
Preview humidity_button
Preview light_dimming_button
Preview two_in_one_mode_button
Preview timer_reset_button
Preview sleep_mode
Preview auto_mode
Preview speed_1
Preview speed_2
Preview speed_3
Preview allergen_mode
Preview purification_only_mode
Preview two_in_one_mode
Preview bacteria_virus_mode
Preview nanoprotect_filter
Preview filter_replacement
Preview water_refill
Preview prefilter_clearning
Preview prefilter_wick_cleaning
Preview pm25
Preview iai
Preview wifi
Preview reset
Preview circulate
Preview clean
Preview mode
Preview pm25b
Preview rotate
Preview oscillate
Preview heating
Preview gas

Note: you might have to clear your browser cache after installation to see the icons.