Winix smart home integration, free and open source
Winix connected air purifiers: power, mode, fan speed, Plasmawave, air quality and filter life.
Published by guim31
- Devices
- Version 1.0.1
- Requires Gladys >=5.1.0
- ★ 0
Overview
Control your Winix connected air purifiers (C545, C610, AM90, T810, 5500-2 Wi-Fi, Tower…) from Gladys: power, mode, fan speed, Plasmawave, and follow the air quality, the PM2.5 particles when the model measures them, the ambient light and the wear of the filter.
The integration goes through the Winix cloud, the one of the Winix Smart app: it needs an Internet connection and a Winix account.
Developed without the hardware: the exchanges with the Winix cloud follow the open-source projects that described them and their real answers, but the integration has not been tried on a real purifier yet. Feedback is welcome, on the Gladys forum or in the issues of the GitHub repository.
This integration is not affiliated with Winix: it is a community project, neither endorsed nor supported by Winix.
Requirements
- Gladys 5.1.0 or later.
- A Winix Wi-Fi purifier already set up in the Winix Smart app (the app connects it to the Wi-Fi; the integration does not).
- The e-mail address and password you sign in to the Winix Smart app with.
- Winix dehumidifiers and air conditioners are not supported: they are ignored.
Configuration
- Install the integration: Integrations → Install from GitHub, or from the catalog.
- In the Configuration tab, enter the e-mail address and the password of the Winix account.
- Pick the refresh interval (2 minutes by default, 1 to 5) and the language of the feature names (French by default).
- Save: the connection status shows at the top of the page. Your purifiers appear in the Discovery tab; add them.
Important — the phone app. Winix accepts one mobile session per account. The first sign-in of Gladys may log the Winix app of your phone out: simply sign in again in the app. The integration opens a session only to list your purifiers (first start, new scan in Discovery); reading and commands do not need one, so it keeps working when the phone takes the session back.
The devices
One device per purifier, named as in the Winix app:
| Feature | Type | What it does |
|---|---|---|
| Power | switch, controllable | turns the purifier on or off |
| Mode | list, controllable | Auto, Manual or Sleep |
| Fan speed | level 0 to 4, controllable | 0 sleep, 1 low, 2 medium, 3 high, 4 turbo (5 Super Clean: Tower Prime) |
| Plasmawave | switch, controllable | turns Plasmawave on or off |
| Air pollution | risk level 0 to 3 | the Winix color ring: 0 good, 1 fair, 2 poor, 3 very poor |
| PM2.5 | µg/m³ | only on the models with that sensor |
| Ambient light | raw value | the reading of the light sensor (no unit, Winix gives none) |
| Filter life | % | what is left of the filter, 0 % when it is due |
| Filter hours left | hours | hours of use left before the change |
| Online | yes / no | the Winix cloud has news from the purifier |
- Choosing a speed switches the purifier to manual mode, as in the app. In Auto mode, the speed shown is the one the purifier chose.
- Choosing a mode or a speed turns the purifier on if it was off.
- The filter life comes from the hour counter of the purifier and the life planned for the model (6,480 h, 9 months, for most). It should start again from 100 % when the filter counter is reset on the purifier after a change (to be confirmed on real hardware).
- The sensors (PM2.5, light) are detected at the first reading. If a sensor shows up later, the Discovery tab offers Update.
Widget
The Winix purifier dashboard widget shows a purifier chosen in its settings: live PM2.5 and filter, mode, air quality and filter hours, and four buttons Auto, Manual, Sleep and Turn off (a Turn on button when it is off). The current mode carries a check mark.
Scene triggers and actions
The integration adds no scene trigger or action: everything goes through the features of the device, which Gladys scenes already read and control. A "filter to replace" is the threshold Filter life ≤ 5 % of a scene, triggered once when it is crossed; a separate trigger would repeat it.
Scene examples
- Quiet night: at 10:30 pm, set the Mode of the bedroom purifier to Sleep; at 7 am, back to Auto.
- Polluted air: when the Air pollution of the living room reaches 2 or more (or PM2.5 above 25 µg/m³), set the Fan speed to 4 and send a message; back to Auto when it drops to 0.
- Filter: when the Filter life drops below 5 %, send "Order a filter for the purifier".
- Empty house: when everybody left, turn the purifiers off; back on in Auto when the first one comes home.
Refresh and conditions of the Winix cloud
- Each purifier added to Gladys is read every 2 minutes by default (1 to 5 depending on the configuration), one after the other. Only the values that change are sent to Gladys, with a reminder every 6 h for those that do not move.
- Winix publishes no API and no quota. The cloud refuses a burst of requests for about a minute: the integration then waits a minute before going on. Avoid the one-minute interval if you have many purifiers.
- After a command, the purifier is read again 5 seconds later to show what it really did.
- The account is only used at the first start and at each scan in
Discovery; the session (refresh token, identity) and the list of the
purifiers are kept in
/data.
Data and privacy
- The password stays in the configuration of Gladys; it is only sent to the Winix sign-in service (AWS Cognito), and never in clear: the sign-in uses the SRP protocol.
/data/winix-session.jsonkeeps the refresh token, the identity of the account and the list of the purifiers, readable by the container only.- No token, password or identity ever shows in the logs.
Troubleshooting
- "Winix refused the e-mail address or the password": check them by signing in to the Winix app, then save them again. The integration does not retry the same credentials on its own, so as not to lock the account.
- The phone app logs me out: that is the single session of Winix (see Configuration). Sign in again in the app; Gladys keeps reading and controlling the purifiers.
- "The Winix cloud does not answer": an Internet or Winix outage. The integration retries at each cycle and says it once in the logs.
- A purifier is "offline": it is unplugged or lost its Wi-Fi. Check it in the Winix app.
- A new purifier does not show: run a scan in the Discovery tab.
- More details: set
LOG_LEVEL=debugin the logs of the integration.
Limits
- Depends on the Winix cloud and on Internet: no local control.
- Not tried on real hardware yet; the codes and answers come from the open-source projects credited in the README.
- One mobile session per Winix account (see Configuration).
- Air purifiers only: no Winix dehumidifier nor air conditioner.
- No child lock, display brightness or timer: the commands are power, mode, speed and Plasmawave.
- The air quality is the Winix indicator with 3 or 4 levels, not an AQI; the ambient light is a raw value.
- Feature names are set when the device is added: changing the language afterwards does not rename them.
Configuration settings
These are the settings Winix asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your Winix account | section | No | The account of the Winix Smart app, where your purifiers are already set up. Signing in here may log the phone app out once: sign in again on the phone, the integration keeps working. |
| E-mail address | string | Yes | The e-mail address you sign in to the Winix Smart app with. |
| Password | secret | Yes | The password of the Winix account. It stays in Gladys and is only sent to the Winix sign-in service. |
| Refresh interval (minutes) | number | No | How often each purifier is read from the Winix cloud, from 1 to 5 minutes. |
| Language of the feature names | select | No | Names given to the features when a purifier is added to Gladys, and texts of the integration. |
How to install Winix in Gladys
- In Gladys, open Integrations: Winix appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-winix:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/guim31/gladys-winix.
Winix requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Winix is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation