BlogContact

Connecting boneIO Black

How to connect Home Assistant to a boneIO Black controller over MQTT, with the broker on the controller or in Home Assistant.

A boneIO Black controller talks to Home Assistant over MQTT. In Home Assistant you add one integration, MQTT, and the controller announces all its outputs, covers, inputs, sensors and templates by itself. There is no YAML to write.

The MQTT broker, the program through which the two exchange messages, can run in one of two places:

Broker on the controller (recommended)Mosquitto in Home Assistant
Where it runson the boneIO Black, from the startin Home Assistant, as the Mosquitto app
What you install in Home Assistantonly the MQTT integrationthe Mosquitto app and the MQTT integration
When to choose italmost alwayswhen Home Assistant already runs Mosquitto, for example for a large Zigbee2MQTT network, and you want one broker for everything

1. Set the MQTT password on the controller

The broker on the controller has a homeassistant account with a random password, different on every device. Set one you know: in the boneIO Black panel go to Settings → Services on this controller → MQTT broker (local), enter the new password twice on the homeassistant card and click Change password. The details are on Connecting to Home Assistant.

2. Add the MQTT integration in Home Assistant

  1. Go to Settings → Devices & services and click Add integration in the bottom right corner.

    Home Assistant: Devices & services, the Add integration button

  2. Type MQTT and choose MQTT from the list.

    Home Assistant: searching for MQTT in the brand window

  3. Home Assistant lists several integrations with MQTT in their name. Choose the first one, plain MQTT.

    Home Assistant: the What do you want to add? list with MQTT at the top

  4. Choose Manually enter the MQTT broker connection details.

    Home Assistant: choosing between the Mosquitto app and entering a broker by hand

  5. Fill in the form:

    • Broker: the IP address of the boneIO Black controller, e.g. 192.168.1.100 (the controller's OLED screen shows it),
    • Port: 1883,
    • Username: homeassistant,
    • Password: the password set in step 1.

    Click Submit.

    Home Assistant: the form for the broker on the controller

  6. Home Assistant finds the controller straight away and opens a window to name and assign its devices. Every room set up in boneIO is a device of its own, already assigned to the area of the same name. Click Finish.

The connection can be encrypted (TLS, port 8883), which makes sense on a shared network or over a VPN. See Connecting to Home Assistant.

Mosquitto in Home Assistant

Here the broker runs in Home Assistant and the boneIO Black controller connects to it.

  1. Go to Settings → Apps and click Install app.

    Home Assistant: the empty Apps list

  2. In the App store, type Mosquitto and open Mosquitto broker.

    Home Assistant: the App store with Mosquitto broker found

  3. Click Install.

    Home Assistant: the Mosquitto broker app before installing

  4. Once installed, click Start. Start on boot is on, so the broker comes back by itself after Home Assistant restarts.

    Home Assistant: Mosquitto broker installed, the Start button

    Home Assistant: Mosquitto broker running

  5. Create the account the controller signs in to the broker with: Settings → People → Users → Add user, for example with the username boneio and a password of your own.

  6. Home Assistant usually offers the MQTT integration for the new broker by itself, under Settings → Devices & services, in the Discovered part. Click Add next to it and confirm.

  7. In the boneIO Black panel go to Settings → Connections → MQTT and enter the Home Assistant IP address, port 1883 and the account from step 5; see Connecting to Home Assistant. Once saved, the controller connects to the broker in Home Assistant and announces its devices as with the broker on the controller.

In this setup the boneIO Black depends on Home Assistant: while Home Assistant restarts or is off, the controller has no broker and reports no states. Actions set up in boneIO (button → light) keep working, because they need no MQTT.

What you see in Home Assistant

The MQTT integration shows the controller and its devices.

Home Assistant: the MQTT integration with the boneIO Black devices

Settings → Devices & services → Devices lists:

  • boneIO Black 32x10A: the controller itself, with its own sensors and everything that has no room,
  • boneIO Black 32x10A - Salon, - Kuchnia and so on: one device for every room set up in boneIO, in the area of the same name. Rooms are set up in the boneIO panel, on Areas,
  • boneIO templates (thermostat, alarm panel, gate, irrigation) as devices of their own, under their own names.

Home Assistant: the list of boneIO Black devices with their areas

The page of one room gathers everything connected in it: lights, covers and the thermostat under Controls, reed switches and motion sensors under Sensors, buttons under Events.

Home Assistant: the boneIO Black 32x10A - Salon device with its entities

The names in Home Assistant are the ones in the boneIO panel. (The pictures come from a Polish installation, so the rooms are Salon, Kuchnia and so on.)

boneIO updates in Home Assistant

When a new version of the boneIO Black application is out, Home Assistant shows it at the top of Settings, as boneIO Black Firmware with the version number. Do the update itself in the boneIO panel: How to update.

Home Assistant: Settings with the boneIO Black Firmware update at the top

The boneIO panel in Home Assistant

The boneIO app for Home Assistant opens the controller's panel in the Home Assistant menu, without a separate browser tab. It comes from the repository https://github.com/boneio-eu/home-assistant-addons: in Settings → Apps → Install app, click the three dots in the top right corner, choose Repositories, add the address and install the boneIO app. See Connecting to Home Assistant.

First run

The Home Assistant setup wizard step by step, from creating the account to the first dashboard.

Connecting boneIO ESP

How to add a boneIO ESP controller to Home Assistant through the ESPHome integration.

On this page

Broker on the controller (recommended)1. Set the MQTT password on the controller2. Add the MQTT integration in Home AssistantMosquitto in Home AssistantWhat you see in Home AssistantboneIO updates in Home AssistantThe boneIO panel in Home Assistant