Homebridge support for Winix air purifiers.
- Dynamic Device Discovery: Automatically discovers and configures Winix purifiers linked to your account.
- Control: Power on/off, switch between sleep/auto/manual modes, and adjust airflow speed.
- Customization: Optionally expose Air Quality, Ambient Light, Plasmawave, Auto Mode, and Sleep Mode switches to HomeKit.
- Filter Management: Exposes the remaining filter life and provides an alert when it's time to change the filter, configurable to trigger at a specified percentage of remaining filter life.
- Efficiency: Features Winix API response caching to minimize requests and avoid rate limiting.
- Reliability: Automatically refreshes device list on a configurable interval to ensure devices are always up-to-date.
This plugin officially supports the following Winix air purifiers:
- C545
- C909
While other models aren't explicitly blocked, they're not yet officially supported and may not work as expected.
Winix's system limits users to a single active session per account. When the same account is used simultaneously on the Winix app and Homebridge, it can lead to being logged out from one of the sessions. An alternate account dedicated to Homebridge prevents this issue, ensuring stable operation without frequent authentication disruptions.
Yes, this is an annoying and tedious one-time setup, but it is well worth not having to continually fix authentication issues.
To create and link an alternate Winix account, please follow the instructions in the Alternate Winix Account: Creating and Linking Wiki page.
Easily configure the plugin through the Homebridge Config UI X. Simply provide your Winix account credentials for automatic device discovery and provisioning.
While not recommended, if manual setup is required, add the following to the platforms
section of your config.json
:
{
"platforms": [
{
"exposeAirQuality": true,
"exposeAmbientLight": true,
"exposePlasmawave": false,
"exposeAutoSwitch": false,
"exposeSleepSwitch": false,
"filterReplacementIndicatorPercentage": 10,
"cacheIntervalSeconds": 300,
"deviceRefreshIntervalMinutes": 60,
"auth": {
"username": "your-email@domain.com",
"userId": "f470ce5f-6b8e-44b4-a6db-b7f4d4c6f851",
"refreshToken": "<refresh token>"
},
"deviceOverrides": [
{
"deviceId": "123ABC456DEF_abc123xyz",
"serialNumber": "WNXAI12345678",
"nameDevice": "Living Room Air Purifier"
},
{
"deviceId": "789XYZ987VWX_xyz789abc",
"serialNumber": "WNXAI87654321",
"nameDevice": "Bedroom Air Purifier",
"nameAutoSwitch": "My Auto Switch"
}
],
"platform": "WinixPurifiers"
}
]
}
Name | Default Value | Note |
---|---|---|
exposeAirQuality |
false |
Whether to expose the air quality sensors to HomeKit. |
exposeAmbientLight |
false |
Whether to expose the ambient light sensors to HomeKit. |
exposePlasmawave |
false |
Whether to expose switches for Plasmawave on/off. |
exposeAutoSwitch |
false |
Whether to expose switches for Auto mode on/off. |
exposeSleepSwitch |
false |
Whether to expose switches for Sleep mode on/off. |
filterReplacementIndicatorPercentage |
10 |
Percentage of filter life remaining to trigger a filter replacement alert. |
cacheIntervalSeconds |
60 |
Time, in seconds, for how long to reuse cached responses from Winix. |
deviceRefreshIntervalMinutes |
60 |
Time, in minutes, for how often to poll Winix to refresh the device list. |
auth.username |
"" |
Your Winix account username (email). This field is meant to be read-only after being generated in the UI. |
auth.userId |
"" |
Your Winix user ID for the Cognito User Pool. This field is meant to be read-only after being generated in the UI. |
auth.refreshToken |
"" |
The refresh token for your Winix account. This field is meant to be read-only after being generated in the UI. |
deviceOverrides[].deviceId |
"<deviceId>" |
The ID of the device. |
deviceOverrides[].serialNumber |
"WNXAI00000000" |
The serial number of the device. Optional. |
deviceOverrides[].nameDevice |
"<Winix Alias>" |
The display name of the device. Optional. |
deviceOverrides[].nameAirQualitySensor |
"Air Quality" |
The display name of the air quality sensor. Optional. |
deviceOverrides[].nameAmbientLightSensor |
"Ambient Light" |
The display name of the ambient light sensor. Optional. |
deviceOverrides[].namePlasmawaveSwitch |
"Plasmawave" |
The display name of the Plasmawave switch. Optional. |
deviceOverrides[].nameAutoSwitch |
"Auto Mode" |
The display name of the Auto switch. Optional. |
deviceOverrides[].nameSleepSwitch |
"Sleep" |
The display name of the Sleep switch. Optional. |
platform |
"WinixPurifiers" |
Must always be "WinixPurifiers" in order for the plugin to load this config. |
Unfortunately, there's no way to directly migrate from the old plugin architecture to the new one. Please follow the Migration Guide in the Wiki:
Migrating from v1.x.x to v2.x.x.
Please see this issue for more details.
Try moving the purifier to a room with a different name, then move it back to the desired room. For example, if you have a room named “Bedroom” and a purifier named “Bedroom”, try moving the purifier to a room named "Living Room", then move it to "Bedroom".
- @banzalik - wrote the first Winix C545 Homebridge plugin
- @hfern - wrote the Python Driver and CLI for the Winix C545 Air Purifier in Python, which this plugin's authentication system is heavily based on
- @jonnyborbs - invaluable testing and feedback
- @martinianodl - discovered the alternate Winix account setup for Homebridge
- @shyawnkarim - all around good guy and initial plugin tester (hire him!)