HiSense Air Conditioners

This program implements the Ayla Networks LAN API to interact with HiSense WiFi Air Conditioner module, models AEH-W4B1 and AEH-W4E1, as well as Fujitsu FGLair.

As discussed here, the program doesn't seem to fit the AEH-W4A1 module, which relies on entirely different protocol (implemented by the apps Hi-Smart Life, AirConnect, Smart Cool, AC WIFI and טורנדו WiFi). Please let me know if you have a different experience, or tried it with other modules.

The module is installed in A/Cs and humidifiers that are either manufactured or only branded by many other companies. These include Beko, Westinghouse, Winia, Tornado, York and more.

This program is not affiliated with Ayla Networks, HiSense, Fujitsu, any of their subsidiaries, or any of their resellers.

Prerequisites

1. Air Conditioner with HiSense AEH-W4B1 or AEH-W4E1 installed, or a Fujitsu FGLair.
2. Have Python 3.10 or above installed. If using Raspberry Pi, either upgrade to Raspbian Buster, or manually install it in Raspbian Stretch.
3. Configure the A/Cs with the dedicated app. Links to each app are available in the table below. Log into the app, associate each A/C and connect it to the network, as described in the app documentation.
4. Once everything has been configured, the A/Cs can be blocked from connecting to the internet, as it will no longer be needed. Set them static IP addresses in the router, and write them down.
   • Note: To avoid the need for manual changes later, make sure the app is aware of the new IP addresses before disconnecting the A/Cs from the internet.

5. Find the code for your app, from the list below:

   Code	App Name	App link
   beko-eu	Beko?
   haxxair	HAXXAIR WIFI REMOTE
   denali-us	Denali Aire
   fglair-eu	FGLair
   field-us	HiSmart Air
   hisense-eu	HiSmart Life
   hisense-us	HiSmart Home
   hismart-eu	Smart-Living
   hismart-us	AI-Home
   huihe-us	SunHome
   mid-eu	WiFi AC
   mid-us	Smiling Air
   oem-eu	Hi-Smart AC
   oem-us	Hisense?
   tornado-us	⁧טורנדו WIFI גרסה 2⁩
   winia-us	위니아 에어컨 홈스마트
   wwh-us	Westinghouse?
   york-us	YORK Smart

Run the A/C control server as a HomeAssistant add-on.

If using HomeAssistant, this is the preferred method.

1. In the HomeAssistant UI, enter Supervisor → Add-on Store.
2. Click ⋮ menu → Repositories.
3. Add https://github.com/deiger/AirCon to the list.
4. Choose HiSense Air Conditioner and install it.
5. Update the configuration as detailed within the add-on.
6. Start the add-on. Do not forget to enable Start on boot and Watchdog.

Run the A/C control server in docker

Use this method if not using HomeAssistant, or if you prefer to set it up outside of HomeAssistant.

1. Download the docker-compose.yaml and options.json. Update all the relevant fields in options.json:

   • For every app (multiple apps are supported), set username and password to your app login credentials, and code to the app code from the list above. These will be used to discover you A/Cs and get their LAN keys, if there are no config files in the config directory (/opt/hisense).
   • Set mqtt_host to the MQTT broker server, use localhost if running on the same host. Leave blank if not using MQTT.
   • Set mqtt_user and mqtt_pass to the MQTT credentials. Leave null (or drop) if no authentication is used.
   • Set port to the port to be used by the web server.
   • Set log_level to your desired verbosity level.

2. Run:

   docker-compose up -d

3. Check the logs and verify that everything is in shape:

   journalctl CONTAINER_NAME=hisense_ac

4. Profit!
   The A/Cs should now be auto-discovered by HomeAssistant or openHAB (using the HomeAssistant MQTT Components Binding). SmartThings requires manual setup, using the groovy file, see below.

Run the A/C control server manually

Use this method if the docker setup above does not work for you.

1. Download and install aircon module:

   python3.10 setup.py install

2. Run discovery command to fetch the LAN keys that will allow connecting to the A/C. Pass it your login credentials, as well as the code for your app from the list below:

   For example:

   python3.10 -m aircon discovery tornado-us foo@example.com my_pass

   The CLI will generate a config file for each A/C, that needs to be passed to the A/C control server below. You can select the A/C that the config is generated for by setting the --device flag to the device name you configured in the app.

• Note: To update the server from head, run git pull on the repository and run setup. You may also need to re-run discovery.

1. Test out that you can run the server, e.g.:

   python3.10 -m aircon run --port 8888 --config config.json --mqtt_host localhost

   Parameters:

   • --port or -p - Port for the web server.
   • --config - The config file with the credentials to connect to the A/C.
   • --mqtt_host - The MQTT broker hostname or IP address. Must be set to enable MQTT.
   • --mqtt_port - The MQTT broker port. Default is 1883.
   • --mqtt_client_id - The MQTT client ID. If not set, a random client ID will be generated.
   • --mqtt_user - <user:password> for the MQTT channel. If not set, no authentication is used.
   • --mqtt_topic - The MQTT root topic. Default is "hisense_ac". The server will listen on topics <{mqtt_topic}/{property_name}/command> and publish to <{mqtt_topic}/{property_name}/status>.
   • --log_level - The minimal log level to send to syslog. Default is WARNING.
   • --local_ip - The local IP address to report to the AC unit(s) as target server. Useful in case the server running this application has multiple IP addresses (e.g. in multiple VLANs), since some/most(?) AC units will refuse to report to an IP address outside of their subnet.
2. Access e.g. using curl:

   curl -ik 'http://localhost:8888/hisense/status'
   curl -ik 'http://localhost:8888/hisense/command?property=t_power&value=ON'

Multiple Air Conditioners

In order to use with multiple Air Conditioners, simply add multiple --config params. MQTT topic will contain your topic defined by flag --mqtt_topic (hisense_ac by default) and device MAC address (for uniqueness).

Run as a service

Assuming your username is "pi"

1. Create a dedicated directory for the script files, and move the files to it. Pass the ownership to root. e.g.:

   sudo mkdir /opt/hisense
   sudo mv config*.json /opt/hisense
   sudo chown pi:pi /opt/hisense/*

2. Create a service configuration file (as root), e.g. /lib/systemd/system/hisense.service:

   [Unit]
   Description=Hisense A/C server
   After=network.target
   
   [Service]
   ExecStart=/usr/bin/python3.10 -m aircon run --port 8888 --config config.json --mqtt_host localhost
   WorkingDirectory=/opt/hisense
   StandardOutput=inherit
   StandardError=inherit
   Restart=always
   User=pi
   
   [Install]
   WantedBy=multi-user.target

3. Link to it from /etc/systemd/system/:

   sudo ln -s /lib/systemd/system/hisense.service /etc/systemd/system/multi-user.target.wants/hisense.service

4. Enable and start the new service:

   sudo systemctl enable hisense.service
   sudo systemctl start hisense.service

5. If you use MQTT for HomeAssistant or openHAB, the broker should now provide the updated status of the A/C, and accepts commands.

Available Properties

Listed here are the properties available through the API for standard A/Cs (FGLair and humidifers have different properties):

SmartThings and HomeAssistant support

You will need a groovy script to enable SmartThings integration with the Air Conditioner, through the control server above. It currently implements the main functionality (turn on/off, AC mode, fan speed, dimmer etc.).

The groovy file is available here, for download and installation through the Groovy IDE. As I'm continuously improving this script, it would be more efficient to use the IDE's github integration, in order to stay up-to-date.

HomeAsststant is now fully supported through MQTT Discovery. Properly configured devices are auto-configured and populated in the Lovelace dashboard.

Code Contributions

Pull requests are always welcome.

Please use YAPF with the style config defined here to style your code. Single quotes are used throughout the code-base. Unfortunately YAPF still doesn't support mandating this (support exists in the fixers branch), so please be mindful.