Winix Purifier C545 Integration Request

There’s an awesome python program by hfren at github to control Winix C545 Air Purifiers. At the moment it is possible to install the pip winix program and use shell commands to control it in Home Assistant. I was hoping someone here could make an even better integration. At the moment his program doesn’t support getting the status of the Winix C545 air purifier, but the controls work nicely.

I’m pretty sure this is a fairly common Air Purifier as it’s sold at Costco and I’m sure a lot of people have them now becuase of the fires on the West coast. It’d be nice to get a nice controller for it in HA.

Thank you for reading!

7 Likes

The Winix pypi script by hfern has been updated to get status and information from the C545 Air Purifier.

winix getstate
          power : on
           mode : auto
        airflow : low
            aqi : 1
         plasma : on
    filter_hour : 531
    air_quality : good
     air_qvalue : 104
  ambient_light : 181

Based on the work of the gentleman you cite and couple of others on Github, I created a first pass that publishes the Winix C545 data retrieved from the cloud to MQTT. I ingest this into Home Assistant and Homekit via Homebridge. It has been working okay, I too would like to control the units. I have just not found the time. Perhaps you can use this code (it’s not that great) and the work by the others on Github to make some more HA’ic…

The fundamental flaw with the current approach (due to no open API from vendor to connect locally) is that you are not able to talk directly to the units.

Good hunting and clean breathing!

#sensors.yaml
# Winix air purifers
  - platform: mqtt
    name: 'Air Quality Living Room'
    state_topic: "winix/xx:xx:xx:xx:xx:xx"
    unit_of_measurement: "AQI"
    value_template: "{{ value_json.air_quality_ordinal }}"
    json_attributes_topic: "winix/xx:xx:xx:x:xx:xx"

  - platform: mqtt
    name: 'Air Quality Small Bedroom'
    state_topic: "winix/xx:xx:xx:xx:xx:xx"
    unit_of_measurement: "AQI"
    value_template: "{{ value_json.air_quality_ordinal }}"
    json_attributes_topic: "winix/xx:xx:xx:xx:xx:xx"
#ui-lovelace.yaml

    - type: 'custom:config-template-card'
      variables:
        - states['sensor.air_quality_living_room'].state
      entities:
        - sensor.air_quality_living_room
      card:
        type: custom:mini-graph-card
        name: "${ states['sensor.air_quality_living_room'].attributes.room + ' updated (hh:mm:ss) ' + states['sensor.air_quality_living_room'].attributes.update_age_text + ' ago' }"
        icon: mdi:smog
        hours_to_show: 12
        labels: false
        entities:
          - sensor.air_quality_living_room
        aggregate_func: max
        points_per_hour: 8
        bar_spacing: 1
        font_size_header: 16
        upper_bound: 3
        lower_bound: 0
        show_legend: false
        state_map:
          - value: "1"
            label: Good
          - value: "2"
            label: Fair
          - value: "3"
            label: Poor
        show:
          points: false
          state: true
          legend: false
          graph: bar
          labels: false

1 Like

I resorted to using the homebridge plugin for now, but this would be nice directly in HA with all sensors and controls.

1 Like

Glad you have the homebridge solution working. I struggled with getting to operate with my HomeKit setup. I want to get back to my simple bit of code and enable sending commands. I am not sure if you have noticed how the C545 ‘automatic’ mode worked or not… but it monitors the light sensor that is built into the units and when the light sensor goes below ‘10’ the unit goes to sleep until the light sensor goes back above ‘10’. So basically during the night, regardless of the air quality the C545 is off lline and doing NOTHING! Gee, I guess no one wants good air quality while they are asleep!!! WTF!

My Winix units (different models) still function with night mode, they just go to the lowest speed and turn all the lights off. Typical actions that cause bad air quality are generally not occurring when everyone is asleep

Interesting. Not sure here in California we have gotten the forest fires to agree to ‘turn off’ the bad air during the night :wink:

I have the C545 and can confirm that I have the same behaviour as @richieframe. That’s also what the manual states. The LEDs will go off, and the fan speed will be quiet, but not completely off.

I am using homebridge to expose the purifiers back to HA, and then back to homekit which is not ideal, to say the least.

So based on your data, what happens if the air quality move to poor as C545 would report during the period that the unit is ‘quiet’? Does the unit move to higher level of operation as it would do during the period of ‘automatic’ operation when the light sensor is above ‘10’?

I just tried it with perfume. The app reports “Poor” air quality, but the fan will stay on the minimal “Quiet” setting.
It’s annoying but I guess you can always bypass the auto setting if say there’s bad air quality in the area and you want it to filter through the night. I wonder if you can, through the python program, set the filter to manual whenever the sensor reports poor air quality in low light (night mode).

Bingo… now you are seeing the issue which makes it important to create that local control. Now that we have the ability to read the C545’s sensors and state, we can easily control it’s reaction to changes in air quality. I am just floored that the default logic in the machine is so wrong!

P.S. Interesting that your test reported a ‘Poor’ reading from the unit while it was in sleep mode. When I did my test, the Winix cloud seemed to just report the last read from the unit before it went to sleep. I am going to go back and try your perfume test on my units while they are sleeping. It will be good if the units sensors continue to record reading and upload to cloud while in sleep mode.

I agree. There should be an option that seperates LED control and fan control for night mode.

FYI you can also maybe validate if the sensor reads change by looking at “AQI History” in the winix iOS app.

I do not use the auto mode at all, I keep it at setting 2 for sleeping. My method of “night mode” is just to cover most of the light emitting surface with black electrical tape.

I have 4 cats so the air quality is… poor all the time. I have other air filters in other rooms, some of them as loud as jet engines, and my so called once a year air filter for the house furnace is replaced every 3 months, so auto mode for sleeping areas is not necessary.

The VOC sensor that determines air quality to up the fan speed is not going to reduce those by a substantial amount anyway with increased fan speed, there is just not enough surface area of the carbon prefilter to make a difference. What it does though is redirect the VOCs around the sensor due to the pressure differential, so the auto mode is more of a novelty.

I have an Awair Element with a PM2.5 sensor, which could up the speed of air filter fans to actually clean the air, but it never stays high enough due to the sheer volume of air filtration in my house, my main concern now is carbon dioxide mitigation.

@dproffer I didn’t like the way the homebridge method looks in HA. I am using yours to show the sensor reads for now. Do you have plans to bring controls into HA?
I am not versed enough to accomplish that. I did manage to add MQTT username and password to your program, but that’s the furthest my current skills can take me.

Hi @kzaoaai

I made a first pass at updating the Winix C545 cloud to MQTT python 3 program this evening.

It’s pretty rough, but I would be interested in feedback and ideas. I am but frustrated in three areas around this device and integrating it into Home Assistant and Homekit/Homebridge.

  1. My coding skills are pretty limited here, much could be improved and tested.

  2. There is not a good metaphor for this air purifier in Home Assistant. I am not sure what the best route is to follow to integrate into HA and the Lovelace interface. It’s not really a fan, and the ‘fan’ tools are really tough to figure out. Frustrating, when the fan template and fan mqtt seem to work differently and neither are perfect fit for an air purifier. Then there is Lovelace presentation, a real wild west right now. Maybe a custom component would be the way to handle sensor and control of the units. But that is a fairly large undertaking. And still does not offer a good UI component.

  3. The whole issue of no direct control of the unit, only the ability to talk to the Winix cloud and wait and hope the units are talking to the cloud. There are three possible ways the state on a unit can change:

a) Someone operates the front panel
b) Someone uses the native app to operate the unit
c) A command comes from the Winix cloud. This is how this app interfaces to the units.

Interfacing via the cloud has do work on faith. If one of the two other command methods change the state of unit, it requires waiting for the device to communicate state back to the Winix cloud and then a query of the cloud. FAR from optimal!

Additionally, there are the two additional worries. First that Winix will change the API or security in someway. This would be hard for them to do but since it is closed garden, this possibility always hangs over. And second, over calling the API outside their app raises the possibility that they could blacklist the units or calls from outside the mobile apps.

All that said, a small step to controlling a reasonably priced air purifier.
Code update with hooks for MQTT controls. But as I state above, I am not sure how to ‘present’ controlling units on HA UI… The sensor part for the units should continue to publish in same format as the first pass or the program did. But you can change the MQTT topics and run the two in parallel to make sure.

hi guys - really interested in this. Could someone walk me how to integrate into Home Assistant? I don’t think i grasp the big picture. Do I need to download & install the ‘winix-public’ to my raspberry pi running HA?

(1) First make sure you have Winix C545 units, I do not believe any of these projects support other types of Winix air purifiers. But follow their work for changes.

Listed below, these are the smart folks that did all the heavy lifting that I learned from:

(2) Then you get your device keys:

This is probably the most complicated step, so take your time.

Basically you need to these ‘keys’ to query and command each of your C545’s. This key is a long character string that for each device looks something like:

32373252AEC3_3a4d99ew13

One of these for each of your units, put them somewhere safe and DO NOT share them. These are what will allow ANYONE to control your units.

Here is a nice set of instructions for getting your unit keys. You will need the Winix app up and working with your units on a Android or iOS device. Then you will need a Apple Mac, Windows or Linux computer on the same WiFi network as your Winix units and your Android or iOS phone.

(3) Once you have your device keys you can control and query your units with software other than the Winix app. The keys you downloaded work until you remove your device from the Winix app. If you add the same device back, you will have to do the step above to get the new key for the device. Once deleted from the app, the key is no longer valid with the device.

Which points to an important thing to understand about controlling and querying the Winix C545’s. Neither the factory app on your phone nor any software you use with your keys talk directly to the devices on your local WiFi network. Every conversation the devices have goes up to the Winix cloud and then down to the phone app or your software. NO direct conversation or control. So if the cloud is down or your devices are off WiFi, the only way to control the units is from their front panel buttons.

The second part of this important operating model, is that if one of devices disconnects from WiFi, the only information you can get from the device is the last status from the cloud. Or go over to the device and look at the lights.

I have found the Winix C545’s very reliable and quick to respond to changes sent the Winix cloud. So, so far, it has been pretty successful.

(4) The little crude python program I wrote and published is based off the work of the other folks cited above. It basically uses MQTT to interface with the Winix devices via the Winix cloud. You publish MQTT commands to control each of your C545’s and one a regular basis, the program queries the Winix cloud for the status of your units and publishes this information to MQTT.

Since I run Home Assistant and Apple HomeKit in parallel in my home, I don’t try and connect these two home control systems directly, I try and run all my sensors and controllers via MQTT. Since HomeKit has a very nice open source component call HomeBridge, and HomeBridge works very nicely with MQTT devices. As does Home Assistant.

The downside of this design, is that you need to keep this python program running in parallel with your Home Assistant and/or HomeBridge instance. And it requires a MQTT server to be running somewhere.

I use Docker to run my various device programs, MQTT server, Home Assistant and HomeBridge. It does a very nice job of organizing and running these multiple programs. Downside, another thing to learn.

To run my program, you put it in a directory somewhere on your home server. Get a current version of Python 3, and install all the Python 3 requirements listed. Then you edit the winix-02.yaml file and enter the needed info. Then fire up the program. You should see it publish information to MQTT.

The other techie bit of info you will need to get from your WiFi network is the MAC address for each of your units, this is how I reference each of the units. The IP address of the units is NOT used currently.

so to turn on one of your units from the command prompt:
if it’s MAC address is: aa:bb:cc:dd:ee:ff
and your MQTT server is at IP address: 192.168.xxx.yyy
and your MQTT topic is set to ‘winix’ in the YAML file

mosquitto_pub -h 192.168.xxx.yyy -t winix/aa:bb:cc:dd:ee:ff/control/power -m "ON"

(5) Now you have to create some Lovelace UI components to view info about each unit and command each unit. I have had the viewing part working for a number of months now (see prior post). But I am still trying figure out a new set of Lovelace UI components to control the units. TBA, I just upgraded to HA 0.118 and I am hoping some of the new user interface components will offer some good ways to command the Winix air purifiers.

Good luck with your units and keep watching for others to come with some better tools. I see that Costco is offering a fairly good sale on the units again.




1 Like

Any reason this wouldn’t work for the AN90? Seems to be identically spec-ed as the C545. Is it something specific to the API? I’m thinking of setting up the script in a container but don’t want to waste my time if it’s incompatible.

I only have the C545’s so I cannot say anything about any of their other devices. All we are doing is ‘curl’ api command as is showing below. So if you can get the API key using the steps shown (only requires installing the MITProxy software on a computer, and I think this is a good tool to have in your Home Automation quiver regardless of whether your device works), see if you can use your key and get a valid response for your device from the Winix cloud. Also you might check on the issues posts at the GitHub’s I cited, perhaps one of these more trafficked projects might have someone with experience.

status commands:

curl https://us.api.winix-iot.com/common/event/sttus/devices/3F71771348AB_w522zed246


{"statusCode":200,"headers":{"resultCode":"S100","resultMessage":""},"body":{"deviceId":"3F71771348AB_w522zed246","totalCnt":1,"data":[{"apiNo":"A210","apiGroup":"001","deviceGroup":"Air01","modelId":"C545","attributes":{"A02":"1","A03":"02","A04":"01","A05":"01","A07":"1","A21":"4196","S07":"01","S08":"124","S14":"218"},"rssi":"-24","creationTime":1606414635274,"utcDatetime":"2020-11-26 18:17:15","utcTimestamp":1606414635}]}}

Thanks, I think I’ll see if I can get as far as getting the API key and go from there. Appreciate the input!