Home Assistant - AirTouch

Integration to integrate with the Polyaire AirTouch smart air conditioner controller.

Supports the AirTouch 4 and AirTouch 5.

💻 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:

1. From the HACS page, click the 3 dots at the top right corner.
2. Select Custom repositories.
3. Add the URL https://github.com/thenoctambulist/hass-airtouch
4. Select the category Integration.
5. Click the ADD button.
6. Restart Home Assistant
7. Click the button below, or in the HA UI go to "Configuration" -> "Integrations" click "+" and search for "Polyaire AirTouch"

Manual

1. Download the latest release from here.
2. Create a folder called custom_components in the same directory as the Home Assistant configuration.yaml.
3. Extract the contents of the zip into folder called airtouch inside custom_components.
4. Restart Home Assistant
5. Click the button below, or in the HA UI go to "Configuration" -> "Integrations" click "+" and search for "Polyaire AirTouch"

⚙️ 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.

⚙️ Options

The following options can be modified after set-up via the integration setting page:

Option	Description
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.

💡 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.

❄️ 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 of Fujitsu.

Use this entity to control the overall state of the system such as the Heating/Coolng Mode, Fan Speed etc.

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.
<ac_mode>	Changing the AC mode to one of the on modes will automatically turn the AC and any on zones on in the selected mode.

Attributes

Attribute	Description
hvac_modes	The available HVAC Modes for the AC.
fan_modes	The set of fan modes supported by the AC.
fan_mode	The current fan mode of the AC. It will remain in the last set fan mode even when the AC 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.

❄️ 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

State	Description
off	The zone will be in the off state if: - the AC is off; or - the zone is off.
<ac_mode>	If the zone is turned on the zone's state will be the same as the AC's state. 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	The available HVAC Modes for a zone will dynamically change based on the current AC mode. 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.

🌬️ 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

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 on This 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

🌡️ 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

State	Description
<value>	The current temperature value in °C

🔵 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

State	Description
<value>	The current damper open percentage. Range 0-100% The damper open percentage does not take into account spill.

🔀 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

State	Description
<value>	The current spill percentage. The spill percentage may be >100% if there are multiple spill zones.

🔋 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

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.

🔀 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

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.

⬆️ 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

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 "<Update available>" if an update is available.

❄️ 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

💛 Say Thank You

If you like this integration, please ⭐ the repository.

If you would like to make a donation as appreciation of my work:

---