3.3.1 • Published 2d ago

homebridge-philips-air-purifier-complete

Licence

MIT

Version

3.3.1

Deps

Size

1.8 MB

Vulns

Weekly

Stars

Install scriptsThis package runs scripts during installation (preinstall/install/postinstall)

Summary Dependency Versions

homebridge-philips-air-purifier-complete

Control your Philips Air Purifier from Apple HomeKit via Homebridge — with no separate Python package install required.

This plugin bundles the aioairctrl CoAP library directly. Installing the plugin is all you need; the Python environment is set up automatically for Python 3.11 or newer.

Features

Power On/Off — Turn your air purifier on or off
4 Fan Modes — Auto, Sleep, Medium, Turbo (via rotation speed slider)
Sleep Mode Switch — Dedicated HomeKit switch that sets Sleep mode and dims the display
Air Quality Sensor — Real-time PM2.5 readings with derived AQI rating
Display Light Control — Toggle and 3-level brightness (Off / Dim / Bright)
Child Lock — Lock or unlock physical controls on the device
HEPA Filter Status — Filter life percentage and change alert
Pre-Filter Status — Cleanup cycle percentage and change alert
HTTP Protocol Support — Supports AC1xxx-series DH/AES HTTP models (e.g. AC1715) and HomeID/Condor local HTTP devices
Real-time Updates — CoAP Observe push updates (AC2xxx+) or 10-second HTTP polling (HTTP/HomeID)
Auto-reconnect — Daemon restarts automatically with exponential backoff if the device drops off

Prerequisites

Requirement	Version
Homebridge	>= 2.0.0
Node.js	>= 24.0.0
Python 3	>= 3.11
Your Philips Air Purifier's IP address	—

Python 3.11 or newer must be installed on the system running Homebridge. The official Homebridge Raspberry Pi image and most Debian/Ubuntu systems already ship a suitable Python 3, so usually no extra install is needed. On platforms that need it:

# macOS
brew install python@3.11

# Raspberry Pi / Ubuntu / Debian (Debian 12 "bookworm" ships Python 3.11)
sudo apt install python3 python3-venv

The install hook creates a plugin-local virtual environment and installs:

Python package	Supported range
`aiocoap`	`>=0.4.17,<0.5`
`pycryptodomex`	`>=3.23,<4`

Installation

Via Homebridge UI (recommended)

Open the Homebridge UI
Go to Plugins
Search for homebridge-philips-air-purifier-complete
Click Install

The plugin automatically sets up a Python virtual environment and installs its CoAP dependencies during install. No extra steps needed.

The npm preinstall check reports warnings if Node.js 24+ or Python 3.11+ is not available on the host, but it does not block installation. This keeps Homebridge UI plugin installation simple while still making unsupported runtime versions visible in the install log.

For Docker, NAS, or managed Homebridge installs where npm runs with a restricted PATH, provide the Python path explicitly:

PHILIPS_AIR_PYTHON=/absolute/path/to/python3 npm install -g homebridge-philips-air-purifier-complete

The installer also honours npm's Python setting:

npm install -g homebridge-philips-air-purifier-complete --python=/absolute/path/to/python3

If the install environment cannot expose Python until after the plugin is installed, configure pythonPath in Homebridge before starting the plugin. You can also suppress the Python preinstall warning:

PHILIPS_AIR_SKIP_PYTHON_PREINSTALL=1 npm install -g homebridge-philips-air-purifier-complete

Via npm

npm install -g homebridge-philips-air-purifier-complete

If the automatic setup fails (e.g., Python 3.11+ wasn't installed yet), re-run it manually:

bash $(npm root -g)/homebridge-philips-air-purifier-complete/postinstall.sh

Migrating from v2.x to v3.0.0

v3.0.0 changes the plugin type from accessory to platform. Update your Homebridge config.json before restarting Homebridge.

Move device entries from "accessories" into "platforms"[0]."devices":

Before: v2.x accessory config

{
  "accessories": [
    {
      "name": "Air Purifier",
      "host": "192.168.1.17",
      "accessory": "PhilipsAirPurifier"
    }
  ]
}

After: v3.x platform config

{
  "platforms": [
    {
      "platform": "PhilipsAirPurifier",
      "name": "Philips Air Purifiers",
      "devices": [
        {
          "name": "Air Purifier",
          "host": "192.168.1.17"
        }
      ]
    }
  ]
}

Remove the "accessory": "PhilipsAirPurifier" key from each device entry.
Restart Homebridge.

From v3.2.3, old top-level "accessory": "PhilipsAirPurifier" entries are not loaded by default. If Homebridge logs Loading 1 accessories... followed by Legacy accessories[] config detected, the old entry is still present in the full Homebridge config.json even if this plugin's platform settings modal only shows { "platform": "PhilipsAirPurifier" }. Remove the old object from the top-level "accessories" array and keep the device under "platforms"[]."devices" instead. For temporary rollback only, set PHILIPS_AIR_ALLOW_LEGACY_ACCESSORY=1 before starting Homebridge.

Migration examples

CoAP device

Before:

{
  "accessories": [
    {
      "accessory": "PhilipsAirPurifier",
      "name": "Bedroom",
      "host": "192.168.1.100"
    }
  ]
}

After:

{
  "platforms": [
    {
      "platform": "PhilipsAirPurifier",
      "name": "Philips Air Purifiers",
      "devices": [
        {
          "name": "Bedroom",
          "host": "192.168.1.100"
        }
      ]
    }
  ]
}

HTTP or HomeID device

Before:

{
  "accessories": [
    {
      "accessory": "PhilipsAirPurifier",
      "name": "Study",
      "host": "192.168.1.102",
      "protocol": "homeid-http",
      "useHttps": true,
      "clientId": "BASE64_CLIENT_ID",
      "clientSecret": "BASE64_CLIENT_SECRET"
    }
  ]
}

After:

{
  "platforms": [
    {
      "platform": "PhilipsAirPurifier",
      "name": "Philips Air Purifiers",
      "devices": [
        {
          "name": "Study",
          "host": "192.168.1.102",
          "protocol": "homeid-http",
          "useHttps": true,
          "clientId": "BASE64_CLIENT_ID",
          "clientSecret": "BASE64_CLIENT_SECRET"
        }
      ]
    }
  ]
}

Air+ cloud device

Before:

{
  "accessories": [
    {
      "accessory": "PhilipsAirPurifier",
      "name": "Air Purifier (Air+)",
      "host": "cloud",
      "protocol": "airplus-cloud",
      "airplusDeviceUuid": "AIRPLUS_DEVICE_UUID",
      "airplusTokenFile": "/home/homebridge/.homebridge/philips-airplus-AIRPLUS_DEVICE_UUID.json"
    }
  ]
}

After:

{
  "platforms": [
    {
      "platform": "PhilipsAirPurifier",
      "name": "Philips Air Purifiers",
      "devices": [
        {
          "name": "Air Purifier (Air+)",
          "host": "cloud",
          "protocol": "airplus-cloud",
          "airplusDeviceUuid": "AIRPLUS_DEVICE_UUID",
          "airplusTokenFile": "/home/homebridge/.homebridge/philips-airplus-AIRPLUS_DEVICE_UUID.json"
        }
      ]
    }
  ]
}

Note: HomeKit will treat migrated devices as new accessories. Re-add them to rooms, scenes, and automations in the Home app.

Configuration

Add to your Homebridge config.json under "platforms":

{
  "platforms": [
    {
      "platform": "PhilipsAirPurifier",
      "name": "Philips Air Purifiers",
      "devices": [
        {
          "name": "Living Room Air Purifier",
          "host": "192.168.1.100"
        }
      ]
    }
  ]
}

For AC1xxx models that use HTTP:

{
  "platforms": [
    {
      "platform": "PhilipsAirPurifier",
      "name": "Philips Air Purifiers",
      "devices": [
        {
          "name": "Bedroom Air Purifier",
          "host": "192.168.1.101",
          "protocol": "http"
        }
      ]
    }
  ]
}

For HomeID/Condor local HTTP devices:

{
  "platforms": [
    {
      "platform": "PhilipsAirPurifier",
      "name": "Philips Air Purifiers",
      "devices": [
        {
          "name": "Study Air Purifier",
          "host": "192.168.1.102",
          "protocol": "homeid-http",
          "useHttps": true,
          "clientId": "BASE64_CLIENT_ID",
          "clientSecret": "BASE64_CLIENT_SECRET"
        }
      ]
    }
  ]
}

Use the Homebridge plugin configuration form to add, edit, or remove CoAP, HTTP, HomeID, and Air+ cloud devices. The form presents devices[] as one tab per purifier, with protocol-specific fields shown only when they apply.

Air+ cloud devices also need an account token. Open Plugin Settings, enter the Philips account email, complete the verification code flow, select the device, then review the new Air+ card and click Save Changes.

The JSON Config tab remains supported for direct edits to devices[]. Existing v3.1 installations that still contain additionalDevicesJson continue to merge those entries at runtime for backwards compatibility, but that field is no longer shown in the GUI.

Configuration Options

Option	Required	Default	Description
`platform`	Yes	—	Must be `PhilipsAirPurifier` in the platform entry.
`name`	No	`Philips Air Purifiers`	Platform name for the Homebridge UI.
`devices`	Yes	`[]`	Array of purifier device entries.
`devices[].name`	Yes	—	Name shown in HomeKit.
`devices[].host`	Yes, except Air+	—	IPv4 address of your purifier. Use `cloud` for `airplus-cloud`.
`devices[].protocol`	No	`coap`	Communication protocol. Use `http` for AC1xxx DH/AES models, `homeid-http` for HomeID/Condor local HTTP devices, or `airplus-cloud` for Philips Air+ cloud devices.
`devices[].useHttps`	No	`false`	Use HTTPS for `homeid-http` devices with self-signed certificates. Ignored for `coap` and `http`.
`devices[].clientId`	No	—	Base64 HomeID local API client ID for PhilipsCondor challenge authentication.
`devices[].clientSecret`	No	—	Base64 HomeID local API client secret for PhilipsCondor challenge authentication.
`devices[].encryptionKey`	No	Auto-fetched when possible	Optional hex AES key for HomeID encrypted payloads. Leave blank unless you already know it.
`devices[].airplusDeviceUuid`	Yes for Air+	—	Philips Air+ device UUID. Filled automatically by the setup wizard.
`devices[].airplusTokenFile`	No	`~/.homebridge/philips-airplus-{uuid}.json`	Token file written by the setup wizard or CLI setup script.
`devices[].pythonPath`	No	Auto-detected	Path to Python 3.11 or newer with `aiocoap` and `pycryptodomex` installed. Leave blank to use the plugin's bundled virtual environment.
`additionalDevicesJson`	No	—	Legacy v3.1 runtime fallback. Additional entries are still merged with `devices[]`, but this field is no longer shown in the GUI.

Model Compatibility

Protocol	Models	Notes
`coap` (default)	AC2xxx, AC3xxx, AC4xxx	CoAP Observe push updates
`http`	AC1xxx DH/AES models (e.g. AC1715)	HTTP polling every 10 seconds via `/air`
`homeid-http`	HomeID/Condor local HTTP devices	HTTP/HTTPS polling every 10 seconds via `/status`, `/air`, and `/fltsts`
`airplus-cloud`	Devices registered in the Philips Air+ app	Cloud MQTT updates via the Air+ account token

If your device shows Network error: NetworkError on every command, try setting "protocol": "http" in that device entry.

Air+ Cloud Setup (AC0650, AC1715)

Quick Setup (Homebridge UI — recommended)

Install the plugin via the Homebridge UI
Go to Plugins → Philips Air Purifier → Plugin Settings
Enter the email address for your Philips Air+ account
Click Send Code
Enter the verification code from the email and click Verify & List Devices
Click Add Device next to your purifier
Review the new Air+ device card and click Save Changes
Restart Homebridge

Each device needs its own setup run. Run through the wizard once per purifier.

The older browser redirect-copy login remains available under Advanced: log in via browser. Use it only as a fallback; the email verification code flow avoids the desktop deep-link mismatch that can produce invalid_grant errors.

Apple Private Relay note: A *@privaterelay.appleid.com address may never receive the verification code (Apple does not forward mail from unregistered senders to Sign-in-with-Apple relay addresses). If Send Code appears to work but no email arrives, use your real Philips account email or the Advanced: log in via browser fallback. See Troubleshooting.

Deleting an Air+ device from the Homebridge form removes it from the Homebridge config only. The token file is intentionally left on disk at ~/.homebridge/philips-airplus-{uuid}.json so an accidental delete does not revoke local setup state. Remove that file manually if you are cleaning up an Air+ device permanently.

Advanced / Headless Setup (SSH)

If your Homebridge host has no browser access (Docker, NAS, headless Raspberry Pi):

cd /path/to/homebridge-philips-air-purifier-complete
source .venv/bin/activate
python scripts/airplus_setup.py

Follow the on-screen instructions. The script sends an email verification code, saves a token file to ~/.homebridge/philips-airplus-{uuid}.json and prints the Homebridge config to add.

To use the legacy browser redirect-copy fallback instead:

python scripts/airplus_setup.py --browser

Connectivity Check (optional)

Before configuring Homebridge, you can verify the plugin can reach your device:

# Activate the plugin's virtual environment
source $(npm root -g)/homebridge-philips-air-purifier-complete/.venv/bin/activate

# Run a sensor query
python $(npm root -g)/homebridge-philips-air-purifier-complete/philips_air_api.py 192.168.1.100 sensors

# Probe HomeID local HTTP endpoints without changing device state
python $(npm root -g)/homebridge-philips-air-purifier-complete/philips_air_api.py 192.168.1.100 probe-homeid
python $(npm root -g)/homebridge-philips-air-purifier-complete/philips_air_api.py 192.168.1.100 probe-homeid --use-https

You should see a JSON payload with PM2.5, filter life, temperature, and so on. CoAP can be flaky on the first connection — re-run if you get a timeout.

HomeKit Tiles

Once configured, your air purifier appears in the Apple Home app with:

Tile	What It Controls
Air Purifier	Power, Auto/Manual mode, fan speed (Sleep / Medium / Turbo)
Sleep Mode	Switch that activates Sleep mode and dims the display
Air Quality	PM2.5 density and derived AQI rating
Display Light	On/off toggle and 3-level brightness
Child Lock	Lock/unlock physical controls on the device
HEPA Filter	Remaining filter life percentage, change alert below 10%
Pre-Filter	Cleanup cycle status, change alert below 10%

Architecture

Homebridge (Node.js)
    │
    │  stdin/stdout JSON
    │
    ▼
philips_air_api.py  ─── aioairctrl/ (bundled) ──► aiocoap ──► Philips device (CoAP)
    │
    ├──────────────────── DH/AES HTTP polling ──────────────► Philips device (HTTP)
    │
    └──────────────────── HomeID HTTP/HTTPS polling ────────► Philips device (HomeID)
    │
    │  CoAP Observe (push)
    │  ≈ every 30s or on change
    │  HTTP polling every 10s
    ▼
State cache ──► HomeKit characteristics

The Python daemon maintains a CoAP Observe subscription to the device
For HTTP models, the Python daemon polls the local API every 10 seconds
HomeID mode polls status, air, and fltsts, and supports PhilipsCondor challenge authentication
Commands (power, mode, light) are sent directly and complete in ~100–300ms
The Node.js plugin communicates with the daemon over stdin/stdout JSON
If the daemon exits for any reason, Homebridge restarts it with exponential backoff (5s → 10s → 30s → 60s)

CLI Tool

The bundled Python script can be used standalone for diagnostics:

python3 philips_air_api.py 192.168.1.100 sensors
python3 philips_air_api.py 192.168.1.100 status
python3 philips_air_api.py 192.168.1.100 power on
python3 philips_air_api.py 192.168.1.100 power off
python3 philips_air_api.py 192.168.1.100 mode auto
python3 philips_air_api.py 192.168.1.100 mode sleep
python3 philips_air_api.py 192.168.1.100 mode medium
python3 philips_air_api.py 192.168.1.100 mode turbo
python3 philips_air_api.py 192.168.1.100 light 0      # off
python3 philips_air_api.py 192.168.1.100 light 115    # dim
python3 philips_air_api.py 192.168.1.100 light 123    # bright
python3 philips_air_api.py 192.168.1.100 childlock on
python3 philips_air_api.py 192.168.1.100 childlock off

Troubleshooting

Plugin loads but device is "No Response" in HomeKit

Verify the IP address is correct and the device is on the same network
Run the connectivity check above
Check Homebridge logs for daemon error messages

Python setup failed during install

Ensure Python 3.11+ and the matching venv package are installed, then re-run bash postinstall.sh

Preinstall warnings

Warnings about Node.js mean node --version did not report v24.0.0 or newer during install
Warnings about Python mean python3 --version did not report Python 3.11 or newer during install
If Python 3.11+ is installed but not visible to npm, install with PHILIPS_AIR_PYTHON=/absolute/path/to/python3 npm install -g homebridge-philips-air-purifier-complete
If Python can only be configured after install, set pythonPath in the Homebridge plugin configuration before starting Homebridge

Persistent CoAP timeouts

CoAP (UDP) can be blocked by some network configurations; ensure UDP is allowed between Homebridge and the device
Assign a static IP to the device in your router's DHCP settings

Network error: NetworkError on every command

Your device may use HTTP instead of CoAP. Set "protocol": "http" for AC1xxx DH/AES models such as AC1715.
If your device responds to HomeID local HTTP endpoints or PhilipsCondor authentication challenges, use "protocol": "homeid-http" and configure clientId / clientSecret if required.

Air+ verification code email never arrives (Apple Private Relay)

If you use an Apple Private Relay / "Hide My Email" address (*@privaterelay.appleid.com), the code email may be silently dropped. Apple only forwards mail to a Sign in with Apple relay address from sender domains Philips has registered with Apple; Philips' OTP sender is not guaranteed to be registered, so the email bounces before it reaches you.
Workarounds: (a) use the real email address behind your Philips account instead of the relay address; (b) check whether a standalone iCloud+ "Hide My Email" alias (which forwards from any sender) receives the code; or (c) use the Advanced: log in via browser fallback flow.
This is an Apple/Philips delivery limitation — the plugin passes your email straight to Philips and cannot change how the code is sent.

Project	Author	Licence
louiscrc/homebridge-philips-air-purifier	louiscrc	MIT
betaboon/aioairctrl	betaboon	MIT

See CONTRIBUTORS.md for the full contributor list.

Support

Issues: GitHub Issues
Homebridge community: homebridge.io

Install

npm i homebridge-philips-air-purifier-complete

npx homebridge-philips-air-purifier-complete

yarn add homebridge-philips-air-purifier-complete

pnpm add homebridge-philips-air-purifier-complete

bun add homebridge-philips-air-purifier-complete

Provenance

Built and signed on: GitHub Actions
Source Commit: github.com/MaddogWarner/homebridge-philips-air-purifier-complete@6f18545
Build File: .github/workflows/publish.yml
Public Ledger: Transparency log entry

Module

CJS

Health score

C60/100

active

No known vulnerabilities

Published with provenance

Quality

README

Tests

Stable release

Alternatives

@sindresorhus/slugify3.7M/wk solid-js2.7M/wk expo-glass-effect2.5M/wk nanoassert780.8K/wk @ffmpeg/ffmpeg529.5K/wk

Maintainers

~maddogwarnerauthor

Node

>=24.0.0

Links

npm ↗github ↗homepage ↗

Keywords

homebridge-plugin philips air-purifier homekit coap

homebridge-philips-air-purifier-complete

homebridge-philips-air-purifier-complete

Features

Prerequisites

Installation

Via Homebridge UI (recommended)

Via npm

Migrating from v2.x to v3.0.0

Migration examples

CoAP device

HTTP or HomeID device

Air+ cloud device

Configuration

Configuration Options

Model Compatibility

Air+ Cloud Setup (AC0650, AC1715)

Quick Setup (Homebridge UI — recommended)

Advanced / Headless Setup (SSH)

Connectivity Check (optional)

HomeKit Tiles

Architecture

CLI Tool

Troubleshooting

Versioning

License

Credits and Attribution

Support

Keywords