data_dictionaries

Mapping files

Mapping files for known appliances are located in this directory. Appliances without a mapping file will be still be loaded, but with a warning in the log. Their properties will all be mapped to sensor entities, with hidden set to true and state_class set to measurement (to enable long-term statistics).

Create your own mapping file

To map you 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 two top level items:

• climate: top level Climate configuration.
• properties: list of Property

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 entities with hidden set to true and state_class set to measurement.

Each property is mapped to one entity or one target property. 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.

You need to restart Home Assistant to load mapping changes.

Mapping tips and tricks

• Generate a skeleton file using the connectlife package:

  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 expects boolean (unquoted) values.

• Validate your mapping file with the JSON schema.

• Remember to add translation strings. In the base dir of this repo, run the following command to update strings.json:

  python -m scripts.gen_strings

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

Note that translation keys must be lowercase!

Property

Item	Type	Description
property	string	Name of status/property.
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.
icon	mdi:eye, etc.	Icon to use for the entity.
entity_category	config, diagnostic	Whether the entity should be considered a diagnostics or config entity. Defaults to None. More info in HA docs
binary_sensor	BinarySensor	Create a binary sensor of the property.
climate	Climate	Map the property to a climate entity for the device.
humidifier	Humidifier	Map the property to a humidifier entity for the device.
number	Number	Create a number entity of the property.
select	Select	Create a selector of the property.
sensor	Sensor	Create a sensor of the property. This is the default.
switch	Switch	Create a switch of the property.
water_heater	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 is provided so data dictionaries can be validated.

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.
options	dictionary of integer to boolean

Example:

- 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 attributes: current_humidity, fan_mode, hvac_action, hvac_mode, swing_mode, current_temperature, target_humidity, target_temperature, temperature_unit, or the special target is_on.
options	dictionary of integer to string	Required for fan_mode, hvac_action, hvac_mode, swing_mode, and temperature_unit.
unknown_value	integer	The value used by the API to signal unknown value.
min_value	IntegerOrTemperature	Minimum allowed value. Supported for target_humidity (integer) and target_temperature (temperature).
max_value	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.

hvac_action can only be mapped to pre-defined actions. 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 and swing_mode, remember to add translation strings for the options.

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

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

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. 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 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.
unit	min, °C, °F, etc., or property.<name>	Required if device_class is set, except not allowed when device_class is aqi or ph.

Type Select

Item	Type	Description
options	dictionary of integer to string	Required.

Remember to add 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. For integer properties, defaults to measurement. Not allowed when device_class is enum.
device_class	duration, energy, water, etc.	Name of any SensorDeviceClass enum.
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.
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 for the options.

Type Switch

Item	Type	Description
off	integer	Off value. Defaults to 0.
on	integer	On value. Defaults to 1.

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 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, andtemperature_unit`.
unknown_value	integer	The value used by the API to signal unknown value.
min_value	IntegerOrTemperature	Minimum allowed value. Supported for target_temperature (temperature).
max_value	IntegerOrTemperature	Maximum allowed value. Supported for target_temperature (temperature).

temperature_unit defaults to Celsius.

state can only be mapped to pre-defined state.

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 selecing 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 for the options. Note that you need to add these under state, and not under state_attributes, e.g.:

{
  "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.

min_value: 10

or

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 initialisation, 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:

- 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, and then to any translations files.

For example, given the following data dictionary:

properties:
  - property: Door_status
    sensor:
      device_class: enum
      options:
        0: not_available
        1: closed
        2: open

This goes into strings.json and en.json,

{
  "entity": {
    "sensor": {
      "Door_status": {
        "name": "Door",
        "state": {
          "not_available": "Unavailable",
          "closed": "Closed",
          "open": "Open"
        }
      }
    }
  }
}

Climate and humidifier modes must be registered as state_attributes.

For example, given the following data dictionary:

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 humidifier) goes in strings.json and en.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!