homebridge-blueair-plugin

Homebridge plugin for BlueAir air purifiers and humidifiers with cloud connectivity.

Installation

Option 1: Install via Homebridge Config UI X:

Search for "BlueAir" in homebridge-config-ui-x and install homebridge-blueair-plugin.

Option 2: Manually Install:

sudo npm install -g homebridge-blueair-plugin

Device Setup

1. Open Homebridge Config UI X
2. Go to Plugins → Find Homebridge BlueAir Plugin
3. Click Settings (gear icon)
4. Enter your Blueair account email and password
5. Click "Sign In & Discover Devices"
   • The plugin will automatically detect your region and account UUID
   • Your devices will be listed once discovery completes
6. Click Add next to each device you want to add to HomeKit
7. (Optional) Click Edit on any device to customize its settings
8. Save the configuration and restart Homebridge

Your devices will appear in the Home app within a few moments.

Supported Devices

• Air Purifiers - BlueAir WiFi-connected air purifiers (e.g., Blue 3210i, HealthProtect series)
• Humidifiers - BlueAir humidifier devices

[!NOTE] This plugin only supports devices with cloud connectivity via AWS. Classic/legacy BlueAir devices are not supported.

Features

Air Purifier Controls

• Power on/off
• Fan speed control with debounced slider
• Auto mode toggle
• Child lock (lock physical controls)
• LED brightness control (as lightbulb service)
• Germ Shield mode (when supported)
• Night mode for quiet operation

Humidifier Controls

• Power on/off
• Fan speed control
• Target humidity (30-80%)
• Water level monitoring
• Night light brightness control

Sensors

The plugin exposes the following sensors to HomeKit when available on your device:

| Sensor | Description | |--------|-------------| | PM 2.5 | Particulate matter 2.5 microns (µg/m³) | | PM 10 | Particulate matter 10 microns (µg/m³) | | VOC | Volatile organic compounds (ppb) | | Temperature | Ambient temperature (°C/°F) | | Humidity | Relative humidity (%) | | Air Quality Index | Calculated from PM2.5, PM10, and VOC readings |

Note: While the Blueair API may provide additional sensor data (PM1, HCHO, CO₂, NO₂, O₃), these are not currently exposed to HomeKit due to HomeKit characteristic limitations.

Filter Maintenance

• Filter life level monitoring
• Filter change indicator with configurable threshold

Configuration Options

| Option | Description | |--------|-------------| | Region | BlueAir server region (Default/EU, Australia, China, Russia, USA) | | Polling Interval | API polling interval in seconds (default: 120) | | Verbose Logging | Enable detailed logging for troubleshooting | | LED Service | Show LED brightness as a lightbulb tile | | Air Quality Sensor | Show air quality sensor service | | Temperature Sensor | Show temperature sensor service | | Germ Shield | Show germ shield switch (air purifiers) | | Night Mode | Show night mode switch | | Filter Change Level | Percentage threshold for filter change alert |

Automatic Device Detection

The plugin automatically detects device capabilities based on:

1. API Device Type - Device type information from Blueair API (air purifier vs. humidifier)
2. Model Name - Pattern matching against known device models
3. Available State Keys - Features detected from device state attributes

This allows the plugin to intelligently enable/disable features based on what your specific device supports, without requiring manual configuration.

Troubleshooting

Rate Limiting

If you see "rate limit" or "too many calls" errors:

• Increase the Polling Interval in plugin settings (recommended: 180-300 seconds)
• The plugin automatically backs off with exponential retry on rate limits
• Cached device states are used as fallback during API issues

Devices Not Discovered

• Verify your credentials are correct
• Ensure devices are online in the Blueair mobile app
• Try the Clear Cache button and re-discover
• Check the Homebridge logs for detailed error messages

Accessories Not Responding

• Check that Homebridge is running and connected to the internet
• Verify devices show as "online" in the Blueair app
• Review polling interval - too low may cause rate limiting
• Check Homebridge logs with Verbose Logging enabled

Credits

This plugin is based on the original work by @kovapatrik. Special thanks to him for creating and maintaining the homebridge-blueair-purifier plugin.

If you'd like to support kovapatrik's work:

• GitHub
• Buy Me a Coffee

Original inspiration from the work of @fsj21 on the Amazon Web Services (AWS) API and construction of the documentation.

Trademarks

Apple and HomeKit are registered trademarks of Apple Inc. BlueAir is a trademark of Unilever Corporation