Configuration

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:

• Lights configuration
• Switches configuration

Covers

Moving on to WHO 2, covers:

  cover:
    living_shutter:
      where: '11'
      name: Living room shutter
      advanced: True
      manufacturer: Legrand
      model: 67557
    kitchen_shutter:
      where: '12'
      interface: '03'
      name: Kitchen shutter
      advanced: True
      manufacturer: Legrand
      model: 67557
    dining_room_shutter:
      where: '13'
      name: Dining room shutter
      advanced: True
      manufacturer: Legrand
      model: 67557

The configuration remains similar to lights and switches.
The specificity is the optional advanced boolean (defaulting to False), you need to set it to True if you have 'advanced' cover modules that keep track of and return position values. (Only "Céliane 67557", "Axolute H4661M2", "Livinglight LN4661M2" and the "F401" DIN module are capable of this)

Binary sensors

Dry contacts and IR sensors are part of WHO 25

  binary_sensor:
    garage_door:
      where: '31'
      name: Garage door
      class: garage_door
      manufacturer: BTicino
      model: 3477

where for these is one of a few special cases, as per specification, they are always "3" followed by the sensor number assigned "[1-201]".
class allows you to specify any supported Home-Assistant binary sensor device_class, this will affect the way the device is presented in the interface.

Motion sensors

The "motion" part of the light and motion sensors on WHO 1 are available if the sensor is configured in "scenario" mode. You need to specify the who:

  binary_sensor:
    office_motion:
      who: '1'
      where: '0312'
      name: Office
      class: motion
      manufacturer: Legrand
      model: 048822

where is the OpenWebNet address of your device (the 'APL').
who must be "1" for these sensors.
class must be "motion" for these sensors.

Auxiliary sensors

Auxiliary sensors from the alarm system can also be added, you just need to specify the who:

  binary_sensor:
    motion_sensor:
      where: '1'
      who: '9'
      name: Motion living room
      class: motion
      manufacturer: BTicino
      model: L4610

where is the auxiliary sensor number "[0-9]".
who must be "9" in the case of Auxiliary sensors.
class allows you to specify any supported Home-Assistant binary sensor device_class, this will affect the way the device is presented in the interface.

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