Skip to content

Configuration

Jump to bottom
anotherjulien edited this page Feb 17, 2023 · 6 revisions

Once your gateway is integrated in Home-Assistant, you can start adding your different devices.
This configuration needs to take place in the /config/myhome.yaml file. (This means the file is in the same folder as your main Home-Assistant configuration.yaml)

General structure

The overall file is structured as follows:

f454:
  mac: '00:03:50:xx:xx:xx'
  light:
    [...]
  switch:
    [...]
  cover:
    [...]
  climate:
    [...]
  binary_sensor:
    [...]
  sensor:
    [...]
mh202:
  mac: '00:03:50:xx:xx:xx'
  light:
    [...]
  switch:
    [...]
  cover:
    [...]
  climate:
    [...]
  binary_sensor:
    [...]
  sensor:
    [...]

The topmost item in the hierarchy (f454 and mh202 in the above example) is a string to help you identify the gateways in the configuration, their value has no impact on the functioning of the integration.
It is absolutely mandatory and critical that you supply your gateway's correct MAC address, as this is what is used as an identifier and will link the devices in the config to your gateway in Home-Assistant.

Each platform (light, cover, climate, etc...) then follows a similar structure detailed below.
A somewhat complete sample config can be found here

Devices structure

For each device, under each platform, the structure will be similar. Some of the items in the structure are common amongst (almost) all device types:

    <configuration_identifier>:
      who: <str>
      where: <str>
      interface: <str>
      name: <str>
      manufacturer: <str>
      model: <str>

First, the <configuration_identifier>, is a string representing the device, to help you locate it and make sense of the config file, just as the gateway at the top level, its value is not used in the integration.

  • who is generally optional, since only one value is admissible for most device types, only sensor and binary_sensor will accept different values depending on the sensor type.
  • where is mandatory and is the OpenWebNet address of your device (the 'APL'). By OpenWebNet standard, it needs to be either 2 or 4 digits if you used virtual configuration and went beyond the "usual" numbering. It can never be 3 as the bus could not tell if 010 would be "A=01, PL=0" or "A=0, PL=10" for instance.
  • interface is the optional 2 digits Bus interface ID when you use a F422 BUS-BUS Interface (such as the OpenWebNet message address would be <where>#4#<interface>). It is only available for light, switch and cover (WHO 1 and 2 as per OpenWebNet documentation)
  • name is a required "friendly name", this is what will be used as the name of your device and derived entities in Home-Assistant
  • manufacturer and model are optional and purely cosmetic (as they are reported in the device detail in Home-Assistant's interface).

Platforms

For clarity, the configuration details and examples for each platform have been separated on different pages:

Heating

Climate entities are developed for WHO 4

There are 3 distinct ways to configure this part depending on your setup:

99 zones central unit

In a 99 zones setup, the central unit needs to have the address #0, and all subordinate zones have their own number with and are NOT standalone.

  climate:
    central_unit:
      zone: '#0'
      name: Central unit
      heat: True
      cool: False
      standalone: False
      manufacturer: BTicino
      model: 3550
    zone_1:
      zone: '1'
      name: Living room
      heat: True
      cool: False
      standalone: False
      manufacturer: BTicino
      model: F430/4

zone is the zone (equivalent to where)
heat is an optional boolean defaulting to True you can set if your installation supports heating
cool is an optional boolean defaulting to False you can set if your installation supports cooling
standalone is an optional boolean defaulting to False, you can either ignore it or set it manually to False when you have a 99 zones setup

4 zones central unit

When you use a 4 zones central unit, the central unit itself acts as a separate zone, so it has a zone number configured; all subordinate zones are standalone.

  climate:
    central_unit:
      zone: '1'
      name: Central unit Living room
      heat: True
      cool: False
      central: True
      standalone: False
      manufacturer: BTicino
      model: HC4695
    zone_2:
      zone: '2'
      name: Bedroom
      heat: True
      cool: False
      standalone: True
      manufacturer: BTicino
      model: F430/4

zone is the zone (equivalent to where)
heat is an optional boolean defaulting to True you can set if your installation supports heating
cool is an optional boolean defaulting to False you can set if your installation supports cooling
centralis an optional boolean defaulting toFalse that you need to set to True only for the zone that acts as the central unit in your 4 zones setup
standalone is an optional boolean defaulting to False that you need to set to True for all subordinate zones in a 4 zones setup

No central unit

With no central unit, all zones are set as standalone.

  climate:
    zone_1:
      zone: '1'
      name: Living room
      heat: True
      cool: False
      standalone: True
      manufacturer: BTicino
      model: H4691
    zone_2:
      zone: '2'
      name: Bedroom
      heat: True
      cool: False
      standalone: True
      manufacturer: BTicino
      model: H4691

zone is the zone (equivalent to where)
heat is an optional boolean defaulting to True you can set if your installation supports heating
cool is an optional boolean defaulting to False you can set if your installation supports cooling
standalone is an optional boolean defaulting to False that you need to set to True for all zones when you don't have any central unit

Navigation

Device Configuration

Advanced & Examples

Clone this wiki locally