Connecting boneIO ESP

boneIO ESP controllers run ESPHome and connect to Home Assistant with its own fast protocol (the ESPHome API). No MQTT is needed, and no broker either.

Adding the controller

1. Connect the boneIO ESP controller to the network and to power. After a moment Home Assistant finds it by itself.

2. Go to Settings → Devices & services. Under Discovered, the controller has an ESPHome tile with its name, e.g. "boneIO ESP 8x10A Gen2".

   

3. Click Add on the controller and confirm.

4. If Home Assistant asks for an encryption key, enter the key from the api: section of the controller's configuration. A controller with the boneIO factory configuration has no key, and this step does not appear.

5. Assign the controller to an area and click Finish.

If the controller is not under Discovered, add it by hand: Add integration → ESPHome, with the controller's IP address (from the device list in your router). Discovery needs Home Assistant and the controller on the same network.

What you see in Home Assistant

The controller's page under Devices & services → ESPHome shows its outputs, inputs and sensors as entities, ready for dashboards and automations.

Changing the firmware variant

Firmware from boneio.eu/esp lets you switch the controller's variant from Home Assistant, without a USB cable. On the controller's page, in the Configuration section, there is a Firmware variant list with the same variants as in the installer, for example Lights and Lights + web panel. On Dimmer gen2 you also pick the mode: 8 channels, 2x RGBW or 4x CCT, each with or without the panel.

The + web panel variant has a controller page at its IP address (port 80). The page has no password and anyone on your network can switch outputs from it, so pick it only when you need it.

After you pick another entry, the Firmware entity offers an update to that variant. Install it with Update. Changing the list alone switches nothing on the controller — the update does. After a change of Dimmer gen2 mode the output entities have the new layout and the old ones are gone, so fix the automations and dashboards that used them.

A configuration taken over in ESPHome Device Builder does not have this list. There you set the mode and the controller page in the YAML file.

A switch as a light

An output that is a switch (switch) in Home Assistant can be shown as a light, fan, valve and more: in the entity settings, choose Show as. Home Assistant then creates an entity of the new type and hides the switch. It works for each output on its own, without changing the firmware. The other way round — from a light to a switch — Home Assistant cannot do.

Local control

Controllers with inputs and outputs (32x10, 8x10A gen2, Cover, Cover Mix, Dimmer gen2) link each input to an output from the first start: input 1 toggles output 1, and the cover buttons drive the cover. On Dimmer gen2 an input turns the channel with the same number on and off: inputs 1–2 in 2x RGBW mode, inputs 1–4 in 4x CCT mode; the others only report their state. This happens in the controller itself — it works before Home Assistant exists (on a building site, for example) and while Home Assistant is off.

On the controller's page, in the Configuration section, there is a Local control switch:

• on (default) — inputs drive outputs as above;
• off — inputs only report their state to Home Assistant, and you decide what they do in Home Assistant automations. While Home Assistant is down, the buttons do nothing.

The setting survives a restart. The input entities (IN_01…) are in Home Assistant either way. Input24 gen2 has no outputs, so it does not have this switch.

Editing the controller's configuration

The controller's configuration (output names, button actions) is changed in ESPHome Device Builder, an app for Home Assistant or a program on your computer. See Connecting to boneIO ESP.