Home Assistant - AirTouch
Integration to integrate with the Polyaire AirTouch smart air conditioner controller.
Supports the AirTouch 4 and AirTouch 5.
Table Of Contents
- :computer: Installation
- :gear: Configuration
- :bulb: Usage
- :hammer_and_wrench: Automation Blueprints
- :yellow_heart: Say Thank You
:computer: Installation
This custom integration is an alternative to the built-in AirTouch 4 and AirTouch 5 integrations. The built-in integrations are not required for the custom integration to work.
Click to expand installation steps...
### HACS (Preferred) This integration can be added to Home Assistant as a [custom HACS repository](https://hacs.xyz/docs/faq/custom_repositories): 1. From the HACS page, click the 3 dots at the top right corner. 1. Select `Custom repositories`. 1. Add the URL `https://github.com/thenoctambulist/hass-airtouch` 1. Select the category `Integration`. 1. Click the ADD button. 1. Restart Home Assistant 1. Click the button below, or in the HA UI go to "Configuration" -> "Integrations" click "+" and search for "Polyaire AirTouch" [![Add integration][my-hass-add-integration-img]][my-hass-add-integration] ### Manual 1. Download the latest release from [here](https://github.com/thenoctambulist/hass-airtouch/releases). 1. Create a folder called `custom_components` in the same directory as the Home Assistant `configuration.yaml`. 1. Extract the contents of the zip into folder called `airtouch` inside `custom_components`. 1. Restart Home Assistant 1. Click the button below, or in the HA UI go to "Configuration" -> "Integrations" click "+" and search for "Polyaire AirTouch" [![Add integration][my-hass-add-integration-img]][my-hass-add-integration]:gear: Configuration
Configuration of the integration is performed using a config flow in the user interface. Simply follow the steps shown on screen.
Usually the integration will be able to automatically discover any AirTouch systems on the network and integrate them into Home Assistant.
If your AirTouch system cannot be discovered automatically, the integration will prompt you to enter the host name or IP address of the AirTouch wall panel.
Have a firewall?
The following ports are used for communication between Home Assistant and the AirTouch controller. You will need to ensure your firewall allows traffic for these ports. Device | Ports -----------|------- AirTouch 4 | TCP: 9004, UDP: 49004 AirTouch 5 | TCP: 9005, UDP: 49005 For automatic discovery to work your network needs to support UDP broadcast. UDP broadcast may not work if you have installed Home Assistant in a Docker container using the bridge network.:gear: Options
The following options can be modified after set-up via the integration setting page:
| Option | Description |
|---|---|
| Allow AC Mode Changes From Zones | When selected exposes all air-conditioner modes from the zone climate entities. Note: Changing the mode for one zone will change the mode for all zones. If you'd like to automatically turn the AC on when a zone is turned on you can enable the setting "Turn on AC when a zone is being turned on" on the AirTouch console. |
| Minimum Target Temperature Step | The minumum step when changing the target temperature of climate entities. This is a lower bound and the actual temperature step may bigger if the selected value is not supported by the AirTouch system. |
:bulb: Usage
This integration provides several entities depending on the capabilities of your AirTouch system. A custom service is provided to allow changing the HVAC mode without changing the current power state of the air-conditioner.
The entities and services are described in the following sections.
:snowflake: Climate: Air-Conditioner (climate.<ac_name>)
For each air-conditioner in the AirTouch system a climate entity is created.
The climate entity is be named after the air-conditioner, this is often the brand name of the air-conditioner, e.g. Panasonic or Fujitsu.
Use this entity to control the overall state of the system such as the Heating/Coolng Mode, Fan Speed etc.
States and Attributes
#### States State | Description -------------|------------- `off` | When the AC is turned off.Unlike the AirTouch app, the AC mode is not shown when it is turned off. `
Changing the fan mode will not turn the AC on if it is currently off. `last_active_hvac_mode` | The last active HVAC mode.
While the AC is turned on this will match the current state. While the AC is turned off the attribute indicates the mode that will become active if the `climate.turn_on` service is called. `temperature` | The target temperature for the AC.
*Note*: If you have zones with temperature controllers, changing the target temperature will have no effect.
:snowflake: Climate: Zone (climate.<zone_name>)
If you have any zones set up with a temperature sensor, a separate climate entity will be created for each zone.
The climate entities for the zones can be used to:
- see the current temperature of the room
- turn the zone on or off
- change the target temperature
- set the zone to turbo (if supported)
States and Attributes
#### States State | Description -------------|------------- `off` | The zone will be in the off state if:- the AC is off; or
- the zone is off. `
If the AirTouch setting "Turn on AC when a zone is being turned on" is enabled, turning a zone on when the AC is off will automatically turn on the AC (and any other zone's that were left on). #### Attributes Attribute | Description ------------------|------------- `hvac_modes` | If `Allow AC Mode Changes From Zones` has been enabled in the integration options, the available modes will match the Air-Conditioner climate entity. Otherwise, the available HVAC Modes for a zone will dynamically change based on the current AC mode, i.e. the list will always have two values: `off` and the current AC mode. `fan_modes` | `on`, `off`, and `turbo` (if supported).
Fan speed is controlled by the AC climate entity. `fan_mode` | The fan mode will remain `on` if the zone is on even if the AC is turned off.
This can be used to see which zones will be active if the AC is turned on. `temperature` | The target temperature for the zone.
Changing the target temperature when a zone is in damper control will automatically change it back to being temperature controlled. `control_method` | Indicates the current control method for the zone, either `damper` or `temperature`.
:wind_face: Cover: Zone (cover.<zone_name>_damper)
A cover entity is created for all zones (whether they have) to represent the current damper state.
The cover entity for zones can be used to:
- see the current open percentage of the damper
- turn the zone on or off
- change the damper percentage (not recommended for zones with temperature sensors!)
The damper percentage can only be changed in increments of 5% to align with the official app.
States and Attributes
#### States State | Description ----------|------------- `closed` | The zone will be in the closed state if it is turned off. `open` | The zone will be in the open state if it is turned onThis state is retained even if the AC is currently turned off to provide an indication of which zones will be active if the AC is turned on. #### Attributes Attribute | Description -----------|------------- `current_position` | The current open percentage of the damper. 0 is closed, 100 is fully open.
Changing the damper percentage when a zone is in temperature control will automatically change it to a fixed damper position.
*Note:* The current open percentage reflects the AirTouch algorithm's intended position, it will not be accurate for a zone that is being used as a spill.
Using Zones With Thermostat Cards
If you're using the new Thermostat Card in recent versions of Home Assistant and want to enable the Climate HVAC Modes feature, some manual customisation is required to show the available HVAC modes correctly.
First add a thermostat card for the air-conditioner entity, then open the HVAC Climate Modes code editor as shown below. Copy the YAML that is shown, then open the same code view for the thermostat card for each zone and paste in the full list of HVAC Modes. Consider creating one zone card and then copy/pasting it for other zones.
| Step 1 | Step 2 | Step 3 | ||
|---|---|---|---|---|
 |
 |
 |
|
 |
:thermometer: Sensor: Temperature (sensor.<name>_temperature)
A temperature sensor is created for the main AC and each zone with a temperature sensor. Dedicated temperature sensors make it easy to use the current temperature in automations or view the temperature value over time in the Home Assistant history view.
These entities can safely be disabled if you are not using them.
States and Attributes
#### States State | Description -----------|------------- `:large_blue_circle: Sensor: Damper Open Percentage (sensor.<name>_damper_open_percentage)
A sensor is created for the each zone to represent the current open percentage of the damper. A dedicated sensor entity makes it easy to display the current open percentage in entity cards or view the open perctengate over time in the Home Assistant history view.
These entities can safely be disabled if you are not using them.
States and Attributes
#### States State | Description -----------|------------- `The damper open percentage does not take into account spill.
:twisted_rightwards_arrows: Sensor: Spill Percentage (sensor.<name>_spill_percentage)
A sensor is created for the each air-conditioner to represent the current spill percentage.
This entity will only be created if one or more spill zones were selected during the integration configuration. For a system with one spill zone, the actual opening percentage of the zone will be the sum of the spill percentage and the current open percentage.
States and Attributes
#### States State | Description -----------|------------- `:battery: Binary Sensor: Battery (binary_sensor.<zone_name>_battery)
A binary sensor is created for each zone with a temperature sensor to represent the battery state.
States and Attributes
#### States State | Description ------------------|------------- `off` (`Normal`) | The temperature sensor battery is healthy. `on` (`Low`) | The battery in the temperature sensor is getting low and will need to be replaced soon.:twisted_rightwards_arrows: Binary Sensor: Spill/Bypass (binary_sensor.<ac/zone_name>_spill/bypass)
A binary sensor is created for each air-conditioner and each zone to represent the spill or bypass state according to the configuration selected when the integration was set up.
If your system has a bypass damper installed, only the binary_sensor.<ac_name>_bypass sensor for each air-conditioner will be created.
If your system is set up to use one or more zones for spill, you will get a binary_sensor.<ac_name>_spill for each air-conditioner and a binary_sensor.<zone_name>_spill for each spill zone.
Note: The bypass sensor is only created for the AirTouch 5. Bypass state is not available in the AirTouch 4 API.
States and Attributes
#### States State | Description ------------------|------------- `off` (`Closed`) | The AC is not using spill/bypass, or the zone is not active as a spill zone. `on` (`Open`) | The AC is in spill/bypass, or the zone is being used as a spill zone.:arrow_up: Update: Console (update.<airtouch_name>_console)
An update entity is created to represent the software update status of the AirTouch Console.
The AirTouch API doesn't provide information about the version of any updates, so the latest_version attribute just uses a fixed string when an update is available.
States and Attributes
#### States State | Description --------|------------- `off` | The AirTouch software is up to date. `on` | An update is available for the AirTouch software. #### Attributes Attribute | Description ---------------------|------------- `installed_version` | The current version of the AirTouch software. `latest_version` | Matches `installed_version` if the software is update to date.Value will be *"\
:snowflake: Polyaire AirTouch: Set HVAC Mode (airtouch.set_hvac_mode_only)
A service that sets the HVAC mode without changing the current power state.
This service can be used to change the mode of an air-conditioner while it is turned off without causing it to be turned on. It may be useful for time based automations.
If the air-conditioner is turned off, the current HVAC mode can be seen in the last_active_hvac_mode attribute of the climate entity.
Fields
| Field | Description |
|---|---|
target |
An AirTouch air-conditioner climate entity. |
hvac_mode |
The desired mode for the AirTouch air-conditioner. |
Example
service: airtouch.set_hvac_mode_only
data:
hvac_mode: cool
target:
entity_id: climate.panasonic:hammer_and_wrench: Automation Blueprints
Damper to Temperature Control
An automation blueprint to automatically reset AirTouch zones back to temperature control after they have been set to damper control for a configurable period of time.
:yellow_heart: Say Thank You
If you like this integration, please :star: the repository.
If you would like to make a donation as appreciation of my work:
