# Mapping files

Mapping files for known appliances are located in this directory. Appliances without a mapping file will still
be loaded, but with a warning in the log. Their properties will all be mapped to [sensor](#type-sensor) entities,
registered as disabled by default. Users can enable individual ones from the device page in Home Assistant.

## Default mapping files

It is possible to define a default mapping file for each _device type_ (e.g. `006.yaml` for portable air conditioners),
with overrides in _feature_ specific files (e.g. `006-200.yaml` or `006-201.yaml`) for properties that has different
mappings for the different variants.

It's not a problem to add a property that only exists for some feature variants to a default mapping file, they
will just be ignored for feature variants that don't expose that property.

**Note:** The top level `climate` section is not supported in the default mapping files.

### Property inheritance in feature overrides

Any field in a property can be overridden in a feature file; unspecified fields are inherited from the
base type file. Platforms are inherited in two independent groups: the **device-level** platform
(`climate` / `humidifier` / `water_heater`) and the **per-property** platform (`binary_sensor` /
`number` / `select` / `sensor` / `switch`). Changing the platform *within a group* (e.g. `sensor:` to
`select:`) replaces the base's block for that group; an override that touches only one group leaves
the other intact. A property may therefore hold one of each — see [Target fallback](#target-fallback).

The following top-level fields always inherit, even across platform changes:

- `icon`
- `hide`
- `disable`
- `optional`
- `entity_category`
- `translation_key`
- `unavailable`
- `combine` — if you change the platform and want to drop the base's combine sources, clear it with
  `combine: null`.

Collections replace as a whole — there is no per-key merging inside them:

- `options`
- `combine`
- `command`
- dict-valued `min_value` / `max_value`

Set a field to `null` to explicitly unset what the base specified — useful for dropping a `unit:` set
in the base. To suppress an entity entirely, use `disable: true`.

Example: the base specifies the full mapping, the feature override carries only the difference.

```yaml
# 009.yaml (base)
- property: t_temp
  climate:
    target: target_temperature
    min_value: 16
    max_value: 32
```

```yaml
# 009-120.yaml (feature override — caps at 30 °C, inherits target and min_value)
- property: t_temp
  climate:
    max_value: 30
```

Example: a feature variant returns a property as a direct value where the base combines two sources.

```yaml
# 025.yaml (base — virtual sensor combining int and decimal source properties)
- property: StandardElectricitConsumption
  sensor:
    device_class: energy
    unit: kWh
    state_class: total_increasing
  combine:
    - property: StandardElectricitConsumption_int
    - property: StandardElectricitconsumption_decimal
      multiplier: 0.01
```

```yaml
# 025-{feature}.yaml (override — read the property directly, no combine)
- property: StandardElectricitConsumption
  combine: null
```

## Create your own mapping file

To map your device, create a file with the name `<deviceTypeCode>-<deviceFeatureCode>.yaml` in this directory. When done,
or if you need help with the mapping, please open a PR on GitHub with the file!

The file contains these top level items:

- `climate`: top level [`Climate`](#presets) configuration.
- `properties`: list of [`Property`](#property)
- `buttons`: list of [`Button`](#buttons) entities for write-only commands
- `statistics`: opt the device type into [daily energy/water statistics](#statistics) sensors

To make a property visible by default, just add the property to the list. Note that properties you do not map are still
mapped to [sensor](#type-sensor) entities, but registered as disabled by default.

Each property is mapped to _one_ entity or _one_ target property (with one exception: a property may
declare a climate `target` candidacy alongside a per-property platform as a [fallback](#target-fallback)).
In addition, each `climate` preset is mapped to a set of properties and values.

If you disable or change the type of mapping, old entities will be automatically removed from Home Assistant, while
state attributes will change to unavailable.

If you change unit or state class for sensors, you will need to fix the history in
[Home Assistant - Statistics](https://my.home-assistant.io/redirect/developer_statistics/).

You need to restart Home Assistant to load mapping changes.

## Supported Home Assistant entities

ConnectLife properties can be mapped to any of these entity types:

- [Binary sensor](https://developers.home-assistant.io/docs/core/entity/binary-sensor)
- [Climate](https://developers.home-assistant.io/docs/core/entity/climate)
- [Humidifier](https://developers.home-assistant.io/docs/core/entity/humidifier)
- [Number](https://developers.home-assistant.io/docs/core/entity/number)
- [Select](https://developers.home-assistant.io/docs/core/entity/select)
- [Sensor](https://developers.home-assistant.io/docs/core/entity/sensor)
- [Switch](https://developers.home-assistant.io/docs/core/entity/switch)
- [Water heater](https://developers.home-assistant.io/docs/core/entity/water-heater)

### Mapping tips and tricks

- Property keys follow a prefix convention that's a useful starting point when deciding how to map a property:
  - **`t_*`** — writable *target*/control values (e.g. `t_power`, `t_temp`, `t_work_mode`). Usually map to
    `switch`/`select`/`number`, or to a writable `climate`/`humidifier`/`water_heater` target.
  - **`f_*`** — read-only *feedback*/state (e.g. `f_temp_in`, `f_electricity`, the `f_e_*` fault flags). Usually
    map to a `sensor` (with `read_only: true`), a `binary_sensor`, or a `current_*` climate target.

  This is a convention, not a guarantee: a `t_*` control is occasionally better surfaced read-only (e.g. `t_beep`
  as a status `binary_sensor`), and a device may advertise `t_*` controls it doesn't physically have — `disable`
  those in the feature override (see [Property inheritance in feature overrides](#property-inheritance-in-feature-overrides)).
- Generate a skeleton file using the [connectlife](https://pypi.org/project/connectlife/) package:

  ```bash
  pip install connectlife
  python -m connectlife.dump --username <username> --password <password> --format dd
  ```

- Inspect the existing mappings files in this directory.
- Change settings in the ConnectLife app while monitoring value changes in Home Assistant. Take a note of which
  property is changes, what the value is, and what the button or action is named in the ConnectLife app.
- Be aware that `true`, `false`, `yes`, `no`, `on`, and `off` are all interpreted as boolean values in YAML,
  and must be quoted (e.g. `"off"`) to be interpreted as a string, e.g., in option lists. Note that some options
  expect boolean (unquoted) values.
- Validate your mapping file with the [JSON schema](properties-schema.json).
- Remember to add translation strings. In the base dir of this repo, run the following command to update `strings.json`:

  ```bash
  python -m scripts.gen_strings
  ```

  and then edit the added strings. Finally, merge the changes into [translations/en.json](../translations/en.json).

Note that translation keys must be lowercase!

## Property

| Item               | Type                               | Description                                                                                                                                                                                                                                                                                         |
|--------------------|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `property`         | string                             | Name of status/property. Can also be a virtual name when used with `combine`.                                                                                                                                                                                                                       |
| `combine`          | list of [CombineSource](#combine)  | Combine multiple source properties into a single sensor value. See [Combine](#combine).                                                                                                                                                                                                             |
| `disable`          | `true`, `false`                    | If Home Assistant should not create an entity for this property. Defaults to `false`.                                                                                                                                                                                                               |
| `hide`             | `true`, `false`                    | If Home Assistant should initially hide the entity for this property. Defaults to `false`, but is set to `true` for unknown properties.                                                                                                                                                             |
| `optional`         | `true`, `false`                    | If the entity should be registered as disabled by default. The user can enable it from the Home Assistant UI. Use for rarely-useful properties (e.g., per-slot error codes). Defaults to `false`. Only applies to per-property platforms (`binary_sensor`, `number`, `select`, `sensor`, `switch`). |
| `icon`             | `mdi:eye`, etc.                    | Icon to use for the entity.                                                                                                                                                                                                                                                                         |
| `unavailable`      | integer                            | If the property has this value on the device, no entity is created for it. Use for properties that the device reports as "not available" with a sentinel value.                                                                                                                                     |
| `entity_category`  | `config`, `diagnostic`             | Whether the entity should be considered a diagnostics or config entity. Defaults to `None`. [More info in HA docs](https://developers.home-assistant.io/docs/core/entity/#registry-properties:~:text=automatic%20device%20registration.-,entity_category,-EntityCategory%20%7C%20None)              |
| `translation_key`  | string                             | Custom translation key for the entity, used instead of the one derived from the property name. Lets a device-specific mapping name an entity (in `strings.json`/translations). Must be lowercase. Only applies to per-property platforms.                    |
| `binary_sensor`    | [BinarySensor](#type-binarysensor) | Create a binary sensor of the property.                                                                                                                                                                                                                                                             |
| `climate`          | [Climate](#type-climate)           | Map the property to a climate entity for the device.                                                                                                                                                                                                                                                |
| `humidifier`       | [Humidifier](#type-humidifier)     | Map the property to a humidifier entity for the device.                                                                                                                                                                                                                                             |
| `number`           | [Number](#type-number)             | Create a number entity of the property.                                                                                                                                                                                                                                                             |
| `select`           | [Select](#type-select)             | Create a selector of the property.                                                                                                                                                                                                                                                                  |
| `sensor`           | [Sensor](#type-sensor)             | Create a sensor of the property. This is the default.                                                                                                                                                                                                                                               |
| `switch`           | [Switch](#type-switch)             | Create a switch of the property.                                                                                                                                                                                                                                                                    |
| `water_heater`     | [WaterHeater](#type-waterheater)   | Map the property to a water heater entity for the device.                                                                                                                                                                                                                                           |

If an entity mapping is not given, the property is mapped to a sensor entity.

It is not necessary to include items with empty values. A [JSON schema](properties-schema.json) is provided so data dictionaries can be
validated.

## Combine

Some devices split a single value across two properties, e.g., an integer part and a decimal part, or hours and minutes.
The `combine` field creates a single sensor entity from multiple source properties.

The combined value is the sum of each source value multiplied by its multiplier:

```
combined_value = sum(source_value * multiplier)
```

The sensor-level `multiplier` (if set) is applied after the combination.

| Item            | Type    | Description                                                                    |
|-----------------|---------|--------------------------------------------------------------------------------|
| `property`      | string  | Name of a source property.                                                     |
| `multiplier`    | number  | Multiplier for the source value. Default `1`.                                  |
| `unknown_value` | integer | If the source has this value, it is treated as 0 (same as a missing property). |

Properties referenced as combine sources are automatically disabled (no separate entity is created for them).

Combined sensor entities are implicitly read-only.

The `property` name on the combined entry can be a virtual name that does not exist in the device API. In that case, the
entity is created when any of the source properties exist.

If the `property` name matches an actual API property (e.g., when a property exists both as a split value on some devices
and as a single value on others), the entity falls back to the direct API value when no combine sources are available.

### Examples

Combining integer and decimal parts:

```yaml
- property: Electricit_consumption
  icon: mdi:lightning-bolt
  sensor:
    device_class: energy
    unit: kWh
    read_only: true
    state_class: total_increasing
  combine:
    - property: Electricit_consumption_int
    - property: Electricit_consumption_decimal
      multiplier: 0.01
```

Combining hours, minutes, and seconds into a total duration in seconds:

```yaml
- property: Sand_timer_1_duration
  hide: true
  sensor:
    device_class: duration
    unit: s
  combine:
    - property: Sand_timer_1_duration_hours
      multiplier: 3600
      unknown_value: 255
    - property: Sand_timer_1_duration_minutes
      multiplier: 60
      unknown_value: 255
    - property: Sand_timer_1_duration_seconds
      unknown_value: 255
```

## Type `BinarySensor`

Domain `binary_sensor` can be used for read-only properties. By default, `0` and `1` is mapped to off and `2` to on,
as `0` often implies that the sensor state is not available. For other mappings, provide `options`.

| Item           | Type                             | Description                                                                                                                                                           |
|----------------|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `device_class` | `power`, `problem`, etc.         | For domain `binary_sensor`, name of any [BinarySensorDeviceClass enum](https://developers.home-assistant.io/docs/core/entity/binary-sensor#available-device-classes). |
| `options`      | dictionary of integer to boolean |                                                                                                                                                                       |

Example:

```yaml
- property: alarm
  binary_sensor:
    device_class: problem
    options:
      0: off
      1: on
```

## Type `Climate`

Domain `climate` can be used to map the property to a target property in a climate entity. If at least one property has
type `climate`, a climate entity is created for the appliance.

| Item            | Type                                               | Description                                                                                                                                                                                                                                                                                                                                |
|-----------------|----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `target`        | string                                             | Any  of these [climate entity](https://developers.home-assistant.io/docs/core/entity/climate#properties) attributes: `current_humidity`, `fan_mode`, `hvac_action`, `hvac_mode`, `swing_horizontal_mode`, `swing_mode`, `current_temperature`, `target_humidity`, `target_temperature`, `temperature_unit`, or the special target `is_on`. |
| `priority`      | integer                                            | Tie-break when several properties map to the same `target`. Lower = preferred. Defaults to 100. See [Target fallback](#target-fallback).                                                                                                                                                                                                   |
| `options`       | dictionary of integer to string                    | Required for `fan_mode`, `hvac_action`, `hvac_mode`, `swing_horizontal_mode`, `swing_mode`, and `temperature_unit`.                                                                                                                                                                                                                        |
| `unknown_value` | integer                                            | The value used by the API to signal unknown value.                                                                                                                                                                                                                                                                                         |
| `min_value`     | [IntegerOrTemperature](#type-integerortemperature) | Minimum allowed value. Supported for `target_humidity` (integer) and `target_temperature` (temperature).                                                                                                                                                                                                                                   |
| `max_value`     | [IntegerOrTemperature](#type-integerortemperature) | Maximum allowed value. Supported for `target_humidity` (integer) and `target_temperature` (temperature).                                                                                                                                                                                                                                   |

`temperature_unit` defaults to Celsius.

`is_on` is used when setting HVAC mode to on.

`hvac_mode` can only be mapped to [pre-defined modes](https://developers.home-assistant.io/docs/core/entity/climate#hvac-modes),
with one exception: `eco` is accepted as an **alias** for `cool`. A device that reports `eco` as its
`hvac_mode` value then displays as Cool instead of `unknown`. The alias is *display-only* — `eco` is
not added to the selectable mode list, and selecting Cool always writes the canonical raw value (not
the raw Eco value). To let the user switch the device into Eco, expose it as a [preset](#presets),
e.g.:
```yaml
climate:
  presets:
    - preset: eco
      t_work_mode: 5
```

`hvac_action` can only be mapped to [pre-defined actions](https://developers.home-assistant.io/docs/core/entity/climate#hvac-action).
If a value does not have a sensible mapping, leave it out to set `hvac_action` to `None` for that value, or consider
mapping to a sensor `enum` instead.

For `fan_mode`, `swing_horizontal_mode`, and `swing_mode`, remember to add [translation strings](#translation-strings) for the options.

#### Target fallback

Two appliances that share the same `deviceTypeCode`/`deviceFeatureCode` — and therefore the same
data dictionary — can still expose different property sets. To handle this, **several properties may
map to the same climate `target`**. For each target, the integration binds the candidate with the
lowest `priority` *that the device actually exposes*; the others fall back to their own
per-property platform (if they declare one).

A property may carry both a `climate` candidacy **and** a per-property platform (`switch`,
`select`, …). When it wins the target it is exposed through the climate entity; when it loses, it is
exposed through its per-property platform instead. This lets the default mapping describe the full
superset once, with each device resolving to the right control automatically.

For example, vertical swing in `009.yaml`: `t_swing_angle` (multi-position) is the preferred
`swing_mode` control, and `t_up_down` (on/off) is both a `switch` and a lower-priority fallback:

```yaml
- property: t_swing_angle
  climate:
    target: swing_mode
    priority: 1            # preferred
    options: { ... }
- property: t_up_down
  switch:                  # used when t_swing_angle is also present
    device_class: switch
  climate:
    target: swing_mode
    priority: 2            # fallback when t_swing_angle is absent
    options:
      0: "off"
      1: "on"
```

A device exposing both gets `t_swing_angle` as `swing_mode` and `t_up_down` as a switch; a device
exposing only `t_up_down` gets it as `swing_mode`.

When two variants share a `deviceTypeCode`/`deviceFeatureCode` **and** both advertise the
higher-priority candidate, but only one actually honours it (e.g. `t_swing_angle` is present yet
inert on some units), there's no data-dictionary signal to tell them apart. Rather than `disable`
the candidate for the whole feature code (which would regress the variants where it works), the user
pins the property their hardware honours per-device via the integration options (Settings → 
Devices & Services → ConnectLife → Configure → pick device). Each climate target with more than one
exposed candidate gets an "auto / property" select there; `auto` keeps this priority-based binding.

Not yet supported target properties:

- `target_temperature_high`
- `target_temperature_low`

### Presets

Presets are defined on the top level `climate`. Presets are simply a map of device properties to their desired value for
that preset. You may choose to set different properties in different presets. If you do that, the value of the excluded
properties will not be changed when switching to that preset.

E.g.:

```yaml
climate:
  presets:
    - preset: eco
      t_power: 1     # turn on
      t_eco: 1
      t_fan_speed: 0 # auto
    - preset: ai
      t_power: 1     # turn on
      t_tms: 1
```

Remember to add [translation strings](#translation-strings) for preset modes.

Since multiple states may match a given preset, the first matching preset of the list will be displayed in the UI.
E.g., with the above preset definitions, if `t_eco` is 1, `t_fan_speed` is 0, _and_ `t_tms` is 1, `eco` will be displayed
as the selected preset.

Presets only has effect for devices with climate mappings.

## Type `Humidifier`

Domain `humidifier` can be used to map the property to a target property in a humidifier entity. If at least one property has
type `humidifier`, a humidifier entity is created for the appliance.

| Item           | Type                            | Description                                                                                                                                                                                  |
|----------------|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `target`       | string                          | Any  of these [humidifier entity](https://developers.home-assistant.io/docs/core/entity/humidifier#properties) attributes: `action`, `is_on`, `current_humidity`, `target_humidity`, `mode`. |
| `options`      | dictionary of integer to string | Required for `action` and `mode`.                                                                                                                                                            |
| `device_class` | string                          | Name of any [HumidifierDeviceClass enum](https://developers.home-assistant.io/docs/core/entity/humidifier#available-device-classes).                                                         |
| `min_value`    | integer                         | Minimum allowed value for `target_humidity`.                                                                                                                                                 |
| `max_value`    | integer                         | Maximum allowed value for `target_humidity`.                                                                                                                                                 |

It is sufficient to set `device_class` on one property. The value of the first encountered property is used.

`action` can only be mapped to [pre-defined actions](https://developers.home-assistant.io/docs/core/entity/humidifier/#action).
If a value does not have a sensible mapping, leave it out to set `action` to `None` for that value, or consider mapping
to a sensor `enum` instead.

For `mode`, remember to add [translation strings](#translation-strings) for the options.

## Type `Number`

Number entities can be set by the user.

| Item           | Type                                            | Description                                                                                                                       |
|----------------|-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| `min_value`    | integer                                         | Minimum value.                                                                                                                    |
| `max_value`    | integer                                         | Maximum value.                                                                                                                    |
| `device_class` | `duration`, `energy`, `water`, etc.             | Name of any [NumberDeviceClass enum](https://developers.home-assistant.io/docs/core/entity/number/#available-device-classes).     |
| `unit`         | `min`, `°C`, `°F`, etc., _or_ `property.<name>` | Required if `device_class` is set, except not allowed when `device_class` is `aqi` or `ph`.                                       |
| `command`      | [Command](#command)                             | Send writes to a different property than the status property. Only `command.name` is honored for Number. See [Command](#command). |

## Type `Select`

| Item            | Type                            | Description                                                                                                       |
|-----------------|---------------------------------|-------------------------------------------------------------------------------------------------------------------|
| `options`       | dictionary of integer to string | Required.                                                                                                         |
| `unknown_value` | integer                         | The value used by the API to signal unknown value. The entity will be reported as unknown without a warning.      |
| `command`       | [Command](#command)             | Send writes to a different property than the status property, and/or offset the value. See [Command](#command).   |

Remember to add [translation strings](#translation-strings) for the options.

## Type `Sensor`

Sensor entities are usually read-only, but this integration provides a `set_value` service that can be applied on
the `sensor.connectlife` entities, unless the sensor is set to `read_only: true`.

| Item            | Type                                            | Description                                                                                                                                                                                                                                                                                                                                |
|-----------------|-------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `read_only`     | `true`, `false`                                 | If this property is known to be read-only (prevents `set_value` service).                                                                                                                                                                                                                                                                  |
| `state_class`   | `measurement`, `total`, `total_increasing`      | Name of any [SensorStateClass enum](https://developers.home-assistant.io/docs/core/entity/sensor/#available-state-classes). Required to enable [long-term statistics](https://developers.home-assistant.io/docs/core/entity/sensor/#long-term-statistics). Only allowed for integer properties; not allowed when `device_class` is `enum`. |
| `device_class`  | `duration`, `energy`, `water`, etc.             | Name of any [SensorDeviceClass enum](https://developers.home-assistant.io/docs/core/entity/sensor/#available-device-classes).                                                                                                                                                                                                              |
| `unit`          | `min`, `kWh`, `L`, etc., _or_ `property.<name>` | Required if `device_class` is set, except not allowed when `device_class` is `aqi`, `ph` or `enum`.                                                                                                                                                                                                                                        |
| `multiplier`    | number, e.g. `0.1` or `10`                      | Required if the unit in the API is not supported in Home Assistant, e.g. hWh can be multiplied by 0.1 to get kWh.                                                                                                                                                                                                                          |
| `options`       | dictionary of integer to string                 | Required if `device_class` is set to `enum`.                                                                                                                                                                                                                                                                                               |
| `unknown_value` | integer                                         | The value used by the API to signal unknown value.                                                                                                                                                                                                                                                                                         |

For device class `enum`, remember to add [translation strings](#translation-strings) for the options.

## Type `Switch`

| Item           | Type                   | Description                                                                                                                  |
|----------------|------------------------|------------------------------------------------------------------------------------------------------------------------------|
| `off`          | integer                | Off value. Defaults to `0`.                                                                                                  |
| `on`           | integer                | On value. Defaults to `1`.                                                                                                   |
| `device_class` | `outlet`, `switch`     | Name of any [SwitchDeviceClass enum](https://developers.home-assistant.io/docs/core/entity/switch#available-device-classes). |
| `command`      | [Command](#command)    | Send writes to a different property than the status property, and/or offset the value. See [Command](#command).              |

## Command

The `command` field on [Select](#type-select) and [Switch](#type-switch) is used when the API property that reports
state is not the same as the property used to change state, or when the two use different value encodings.
[Number](#type-number) also supports `command.name` for the same redirect (but not `adjust` — number setpoints are
expected to use the same encoding for reads and writes).

| Item     | Type    | Description                                                                                                                             |
|----------|---------|-----------------------------------------------------------------------------------------------------------------------------------------|
| `name`   | string  | Property name to write to. If omitted, writes go to the status property.                                                                |
| `adjust` | integer | Subtracted from the status-space value before writing: `written_value = status_value - adjust`. Defaults to `0`.                        |

Use `adjust` when the write property uses a value encoding offset from the read property. For example, an oven setting
reports `1 = off` and `2 = on` on the status property but expects `0 = off` and `1 = on` on the write property:

```yaml
- property: Adaptive_sense_setting   # status: 1 = off, 2 = on
  switch:
    "off": 1
    "on": 2
    command:
      name: Adaptive_sense_setting_cmd   # write target
      adjust: 1                          # sends 0 for off, 1 for on
```

The same mechanism works for [Select](#type-select): the value written is the integer key from `options` minus `adjust`.

## Buttons

The top-level `buttons` section declares device-level button entities for write-only commands —
properties that don't appear in `status_list`, such as `Actions` on a dishwasher. Each list entry
becomes one HA button entity. A press sends the `write` map to the device in a single request.

| Item             | Type                            | Description                                                                                                                                                                                                                                  |
|------------------|---------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `key`            | string                          | Unique key for this button within the device. Used as the translation key, as part of the entity unique id, and as the merge identity when a feature override changes an inherited button.                                                  |
| `icon`           | `mdi:play`, etc.                | Icon for the button.                                                                                                                                                                                                                         |
| `available_when` | dictionary of string to integer | Optional. Map of property name to required value. The button is only available when every listed property currently has the listed value. Use to gate buttons behind a remote-control-allowed status property.                              |
| `write`          | dictionary of string to integer | Required for non-disabled buttons. Map of property name to value to send when pressed. Multiple entries are sent in a single request — useful for combos like "set delay + start".                                                          |
| `disable`        | `true`, `false`                 | If `true`, suppress this button. Use in a feature override to remove a button inherited from the base when a device variant doesn't support that action code. Defaults to `false`.                                                          |

Feature overrides merge with the base by `key`: matching entries shallow-merge field by field
(`available_when` and `write` replace as a whole), and entries with a new `key` are appended.
A feature override carrying only the differences keeps the override file small.

Remember to add [translation strings](#translation-strings) for button names under `entity.button.<key>.name`.

Example base file declaring start/stop/pause:

```yaml
# 015.yaml (base)
buttons:
  - key: start
    icon: mdi:play
    available_when:
      Remote_control_monitoring_set_commands_actions: 2
    write:
      Actions: 2
  - key: stop
    icon: mdi:stop
    write:
      Actions: 1
  - key: pause
    icon: mdi:pause
    available_when:
      Remote_control_monitoring_set_commands_actions: 2
    write:
      Actions: 3
```

Example feature override disabling pause on a variant that doesn't support `Actions: 3`:

```yaml
# 015-{feature}.yaml (override — drops the pause button, keeps start/stop)
buttons:
  - key: pause
    disable: true
```

## Statistics

The top-level `statistics` block opts the device type into **daily energy and water
consumption** sensors. These are not mapped from `status_list` properties; instead the
integration polls a separate ConnectLife cloud statistics endpoint (every 10 minutes) and
exposes the daily totals. Because the data is cloud-side, these sensors stay available even
when the appliance is offline.

Set this block on the **base** device-type file (e.g. `015.yaml`), not on feature overrides.
Omit the whole block for device types that have no statistics endpoint.

| Item                      | Type                                            | Description                                                                                                                                            |
|---------------------------|-------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| `source`                  | `air_duct_energy`, `energy_consumption_curve`   | Required. Which cloud endpoint to poll: `air_duct_energy` for air conditioners, `energy_consumption_curve` for other appliances (dishwashers, washing machines, dryers, …). |
| `daily_energy_kwh`        | `true`, `false`                                 | Set `true` to create the daily energy sensor (kWh). Defaults to `false`.                                                                                |
| `daily_water_consumption` | `true`, `false`                                 | Set `true` to create the daily water consumption sensor (L), for wet appliances. Defaults to `false`.                                                   |

Both sensor flags default to off, so each must be explicitly enabled with `true`.
`daily_water_consumption` is only meaningful for the `energy_consumption_curve` source.

Example for a dishwasher:

```yaml
# 015.yaml (base)
statistics:
  source: energy_consumption_curve
  daily_energy_kwh: true
  daily_water_consumption: true
```

Example for an air conditioner:

```yaml
# 009.yaml (base)
statistics:
  source: air_duct_energy
  daily_energy_kwh: true
```

## Type `WaterHeater`

Domain `water_heater` can be used to map the property to a target property in a water heater entity. If at least one property has
type `water_heater`, a water heater entity is created for the appliance.

| Item            | Type                                               | Description                                                                                                                                                                                                                                                  |
|-----------------|----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `target`        | string                                             | Any  of these [water heater entity](https://developers.home-assistant.io/docs/core/entity/water-heater#properties) attributes: `current_operation`, `current_temperature`, `state`, `target_temperature`, `temperature_unit`, or the special target `is_on`. |
| `options`       | dictionary of integer to string or boolean         | Required for `current_operation`, `is_away_mode_on`, state`, and`temperature_unit`.                                                                                                                                                                          |
| `unknown_value` | integer                                            | The value used by the API to signal unknown value.                                                                                                                                                                                                           |
| `min_value`     | [IntegerOrTemperature](#type-integerortemperature) | Minimum allowed value. Supported for `target_temperature` (temperature).                                                                                                                                                                                     |
| `max_value`     | [IntegerOrTemperature](#type-integerortemperature) | Maximum allowed value. Supported for `target_temperature` (temperature).                                                                                                                                                                                     |

`temperature_unit` defaults to Celsius.

`state` can only be mapped to [pre-defined state](https://developers.home-assistant.io/docs/core/entity/water-heater#states).

`options` for `is_away_mode_on` is a map of integer to boolean.

`is_on` adds operation `"off"` to the operation list. You may define this option as well on the `current_operation`
target, but will not send in the mapped property or value when selecting the "Off" operation in Home Assistant.
If `current_operation` is not set, `is_on` also adds operation `"on"` to the operation list.

For `current_operation`, remember to add [translation strings](#translation-strings) for the options.
Note that you need to add these under `state`, and **not** under `state_attributes`, e.g.:

```json
{
  "entity": {
    "water_heater": {
      "connectlife": {
        "state": {
          "auto": "Auto"
        }
      }
    }
  }
}
```

Not yet supported target properties:

- `target_temperature_high`
- `target_temperature_low`

## Type `IntegerOrTemperature`

Either just a numeric value or values in Celsius and/or Fahrenheit.

```yaml
min_value: 10
```

or

```yaml
min_value:
  celsius: 0
  fahrenheit: 32
```

## Units

Some devices have support for switching temperature unit between Celsius and Fahrenheit. For _Climate_ and _Water heater_
entities, this is controlled by setting target `temperature_unit`. For _Number_ and _Sensor_ entities, `unit` can be set
to `property.<name>`, where `<name>` must be a property in the same mapping file that is one of:

- A _Climate_ entity with target `temperature_unit`
- A _Select_ entity
- A _Sensor_ entity with `device_type: enum`

When `unit` is mapped to a property, unit is set to the value of the given property _during initialization_, after
mapping the numeric mapping to the translation _key_ (in the YAML mapping file, _not_ `strings.json`).

For example, this will set the unit of `Meat_probe_measured_temperature` to Celsius if `Oven_temperature_unit` is `1`
when the component is loaded:

```yaml
- property: Meat_probe_measured_temperature
  sensor:
    device_class: temperature
    unit: property.Oven_temperature_unit
- property: Oven_temperature_unit
  select:
    options:
      1: celsius
      2: fahrenheit
```

If the temperature unit is changed on the device, the integration must be reloaded, and
long term statistics must be repaired.

Note that units `°C`, `C`, `celsius`, and `Celsius` are normalized to `UnitOfTemperature.CELSIUS`, and units
`°F`, `F`, `fahrenheit`, and `Fahrenheit` are normalized to `UnitOfTemperature.FAHRENHEIT`.

# Translation strings

By default, sensor entities are named by replacing `_` with `` in the property name. However, the property name is also
the translation key for the property, so it is possible to add a different English entity name as well as provide
translations by adding the property to [strings.json](../strings.json), and then to any [translations](../translations)
files.

For example, given the following data dictionary:

```yaml
properties:
  - property: Door_status
    unavailable: 0
    sensor:
      device_class: enum
      options:
        1: closed
        2: open
```

This goes into [strings.json](../strings.json) and [en.json](../translations/en.json),

```json
{
  "entity": {
    "sensor": {
      "Door_status": {
        "name": "Door",
        "state": {
          "closed": "Closed",
          "open": "Open"
        }
      }
    }
  }
}
```

Climate and humidifier modes must be registered as `state_attributes`.

For example, given the following data dictionary:

```yaml
properties:
  - property: t_fan_speed
    climate:
      target: fan_mode
      options:
        0: auto
        5: low
        6: medium_low
        7: medium
        8: medium_high
        9: high
```

Strings not in Home Assistant ([climate](https://github.com/home-assistant/core/blob/dev/homeassistant/components/climate/strings.json)
[humidifier](https://github.com/home-assistant/core/blob/dev/homeassistant/components/humidifier/strings.json)) goes in [strings.json](../strings.json) and [en.json](../translations/en.json):

```json
{
  "entity": {
    "climate": {
      "connectlife": {
        "state_attributes": {
          "fan_mode": {
            "state": {
              "medium_low": "Medium low",
              "medium_high": "Medium high"
            }
          }
        }
      }
    }
  }
}
```

**If your appliance is missing, please make a PR to contribute it!**