# boneIO Documentation for LLMs
Source: https://boneio.eu
Language: English only
Configurator rules: https://boneio.eu/llms/en/configurator.md
---
# boneIO Black (/en/docs/black)
## Welcome to the boneIO Black documentation [#welcome-to-the-boneio-black-documentation]
boneIO Black is a DIN-rail controller that **works as soon as it is powered** — out of the box its inputs drive its outputs
(for example IN01 → OUT01), even without a network. Everything else you set up in a web browser: no programming and no editing files.
**Moving to version 1.6?** Start with [What's new in 1.6](/en/docs/black/whats-new-1-6) — what changes for you, and what to do before and after the update.
## From the box to a working controller [#from-the-box-to-a-working-controller]
1. **Mount and power it.** DIN rail, 24 V DC — preferably from a UPS or buffered power supply.
Hardware installation: [32x10A](/en/docs/black/products/black_32x10a/hardware-installation) ·
[Cover](/en/docs/black/products/black_cover/hardware-installation) ·
[Cover Mix](/en/docs/black/products/black_cover_mix/hardware-installation).
2. **Connect it to the network and open the panel.** An Ethernet cable, then `https://:8443` in a browser —
[Connect to your boneIO](/en/docs/black/current/install/how-to-connect).
3. **Go through the short wizard.** An administrator account and a few questions about the controller — [First-time setup](/en/docs/black/current/install/first-run-wizard).
4. **Name your inputs and outputs, assign rooms.** In the panel's forms —
[Naming inputs](/en/docs/black/current/install/naming-inputs), [Areas](/en/docs/black/current/install/configure-areas).
5. **Connect Home Assistant.** The controller announces its entities over MQTT — they appear in Home Assistant with no manual setup,
grouped by room — [Home Assistant connection](/en/docs/black/current/install/home-assistant-connection).
From there you can add actions to buttons, covers, schedules and everything described in [boneIO Black App](/en/docs/black/current).
## Choose your controller [#choose-your-controller]
Inputs and buses are the same on every boneIO Black controller; the outputs and how they are wired differ.
49 digital inputs and 32 relay outputs — whole-home automation.
A dedicated controller for up to 16 blinds or shutters.
8 blinds and 16 lighting circuits.
Have a boneIO Black 24x16A? It is discontinued; its [guide](/en/docs/black/products/black_24x16a/overview) stays available.
## What the app can do [#what-the-app-can-do]
The boneIO app is the same on every boneIO Black controller — only the factory configuration differs.
Outputs, output groups, time-based covers and venetian blinds with tilt, gates.
Single, double and long press, reed switches, motion sensors, temperature, Modbus.
Schedules at a clock time or with the sun, virtual switches, presence simulation.
Alarm, irrigation, thermostat, energy counters, Node-RED, MQTT and Loxone.
The panel over HTTPS, accounts with roles, no default passwords, and a page that tells you what is left to fix.
boneIO and whole-system updates from the panel, backups, diagnostics, recovery mode.
Version 1.6 is our work of adapting boneIO Black towards the EU Cyber Resilience Act (CRA) — details in the [release notes](/en/docs/black/release).
# Release Notes (/en/docs/black/release)
# What's new in the application? [#whats-new-in-the-application]
On this subpage, you will find all the information regarding new versions of the application as well as the changes occurring within them.
🚀 Upgrade Instructions
1. **Use the WebUI auto-update** — navigate to Settings → Maintenance → Software update and click "Update to 1.6.0"
2. Or via SSH: `pip install --upgrade boneio==1.6.0`
3. Restart the application
Coming from 1.5? Update to **1.5.6** first and follow [the checklist](/en/docs/black/current/install/upgrade-1-5-to-1-6).
# boneIO v1.6.0 Release Notes - Newest release! [#boneio-v160-release-notes---newest-release]
1.6 is the work of adapting boneIO Black towards the EU Cyber Resilience Act
(CRA). It is not a declaration of conformity; it is the engineering that has to
exist before one can be made. It closes the findings of an independent security
review of 1.5.0, and each fix ships as something you can see rather than a
silent patch. A new controller is secure from the first start: the panel over
HTTPS only, no default passwords, and an administrator account created in the
wizard. It also adds schedules, virtual switches, presence simulation and
whole-system updates from the panel.
The same release in plain words, with what to do after updating:
[What's new in 1.6](/en/docs/black/whats-new-1-6). Upgrading a 1.5 controller:
[the checklist](/en/docs/black/current/install/upgrade-1-5-to-1-6).
## Before you update [#before-you-update]
* **Update to 1.5.6 first.** Only 1.5.6 hands the browser over to the new panel cleanly; from older
versions the old panel may keep coming back after the update until you press Ctrl+Shift+R.
* **Be able to reach the controller physically** — an SD card reader or a serial console. This update
changes how boneIO gets administrator rights on the system.
* **Keep a copy of your configuration** (the `/home/boneio/boneio` folder).
* **Plan up to an hour, and do not cut the power.** The system migrations that run at start-up can take
that long on a controller coming from 1.5.x; the display and the panel say what is happening.
A [UPS](/en/docs/black/products/black_32x10a/hardware-installation#backup-power-ups--recommended) is recommended.
**The panel now needs an account.** A controller with none answers no API
request until you create one — including a controller upgrading straight from
1.5 to a later version. See [Accounts and access](/en/docs/black/current/basic/accounts).
## ✨ New features [#-new-features]
**Accounts and roles.** A first-run wizard creates the administrator account,
with an optional import of an existing configuration. Two roles: administrator,
and read-only — which can still operate the installation, just not
reconfigure it. Password recovery over SSH with `boneio accounts reset`.
**Security overview.** Settings → Access → Security lists what is still open on
your controller and takes you to the control that fixes each thing. The same
state reaches Home Assistant as `binary_sensor._security`.
**Diagnostics.** The Logs page becomes Diagnostics and gains a support bundle
you can email — configuration, logs and service state in one file, with
passwords removed — plus a capture window that raises logging to DEBUG for a
few minutes and closes itself. The bus scans moved here from Tools.
**One settings tree.** The System tab is gone; everything is in Settings,
grouped by the question you are asking. A filter, folding groups, and settings
that reopen where you left them.
**Schedules.** Settings → Control → Schedules runs actions on its own, at a
clock time or at a sun event (sunrise, sunset, the twilights, golden and blue
hour) with an offset, random spread, conditions and `earliest`/`latest`
bounds. Each schedule shows its next firing, last outcome and run history, and
reaches Home Assistant as a switch plus diagnostic sensors.
See [Schedules](/en/docs/black/current/configuration/schedule).
**Location and sun.** A `location:` section, set in Settings → Device →
Location (by timezone, typed, or on an opt-in map), drives sun conditions and
six sun entities. See [Location](/en/docs/black/current/configuration/location).
**Virtual switches.** On/off flags with no relay, with `on_turn_on` /
`on_turn_off` actions, exposed to Home Assistant as switches.
See [Virtual switches](/en/docs/black/current/configuration/virtual_switch).
**Presence simulation.** A four-question wizard that writes one virtual switch,
a schedule per light and one that switches everything off; `probability:` on actions makes steps occasionally
skip. See [Presence simulation](/en/docs/black/current/configuration/presence_simulation).
**Readable names.** Schedules and virtual switches can be written with `name:` and the identifier is
made from it; `id:` still works.
**HTTPS certificate.** Upload your own certificate, or download the device's own
authority to trust it; the device certificate now lasts six months instead of
twelve hours. See [HTTPS certificate](/en/docs/black/current/advanced/certificate).
**Recovery mode.** A configuration that does not load, or a start that crashes
three times in a row, opens a recovery panel with the error location, an editor,
the log, backup restore and restart — instead of a restart loop.
See [Troubleshooting](/en/docs/black/current/troubleshooting#recovery-mode).
**MQTT broker passwords.** Changing the `boneio` broker password can update
boneIO's own configuration and reconnect, so the device no longer drops
offline.
**NTP servers.** Point the clock at a time server on your own network.
**Hardware revision 1.1, end to end.** Pin maps for 1.1 controllers, which add a buzzer.
A factory reset gives the controller the configuration of its own type and revision.
**Whole-system updates from the panel.** Settings → Maintenance updates the
Debian packages and the kernel as well as boneIO, with an estimate of how long
it takes. See [System](/en/docs/black/current/basic/system).
**MQTT over TLS, in both directions.** boneIO can connect to a broker over TLS,
and the controller's own Mosquitto broker can take encrypted connections. The
MQTT password moves from `mqtt.yaml` to `secrets.yaml` by itself, and saving the
MQTT page keeps it there. MQTT and Loxone (UDP) now have their own settings entries.
**SSH password from the panel.** The Accounts page has an *SSH login password*
card — no need to log in over SSH to change it.
**Panel on a phone.** A bottom navigation bar on phones and tablets. Outputs and
inputs can be grouped into one panel per room.
**Modbus.** A device that stops answering is shown as failing; a device picker
with search and a "Failing only" filter; devices can be grouped by room.
**Diagnostics → Disk.** Shows what fills the controller's storage and lets you
free unused Node-RED images and the package cache.
**Faster start, better survival of a power cut.** After a power cut the page
says "boneIO is starting" and refreshes by itself; a damaged boot partition no
longer stops the start; the display says *Do not power off* while long
migrations run.
**Node-RED requires a boneIO administrator.** The flow editor is code
execution, so it now authenticates against your boneIO accounts and admits
administrators only.
## 🔒 Security [#-security]
The review's findings were published with CERT Polska as CVE-2026-77052 to
CVE-2026-77062 — what each one means and what to do beyond updating:
[security advisories](/en/docs/black/security-advisories).
* Sign-in attempts are throttled — ten in five minutes, per address and per
account. A delay, never a lockout.
* Configured passwords are masked in the API and removed from the log viewer.
* The panel refuses state-changing requests arriving from another site.
* Device discovery accepts only local addresses on the ports those protocols
actually use, and never echoes what it found.
* Embedding the panel in other sites is restricted to this device by default.
The Home Assistant add-on works with that; a dashboard framing the controller
directly adds its address in Settings → Access → Security.
* The MQTT password database is no longer world-readable.
* No shared passwords on new images: the SSH account ships locked and takes the
administrator's password from the first-run wizard once; MQTT accounts get a
random password per device.
* The panel can be moved behind the HTTPS proxy so it no longer answers in the
clear on the network; new images ship that way.
* The panel never asks for the system (sudo) password any more, and the
`boneio` user is no longer in the `docker` group.
* SSH logins are throttled, and guessing an SSH password costs the guesser time.
* Changing a password signs out that account's other sessions. Five wrong
passwords in one session sign it out.
* Account changes, restoring a backup, factory resets, updates and certificates ask for the
password again if it was not typed in the last 10 minutes.
* No standing path to root: privileged work goes through small system helpers
with a fixed list of operations. System migrations are signed when a release
is made and checked on the controller before anything runs.
* Password guessing reaches Home Assistant as a "Security events" entity.
## ⚠️ Breaking changes [#️-breaking-changes]
* The panel and API need an account (see above).
* Covers run about 10% past their full travel time into the endstop (`endstop_overrun`, default 10) and pause 500 ms before reversing. This applies to existing covers too; set `endstop_overrun: 0` for a motor without endstops. See [Covers](/en/docs/black/current/configuration/cover).
* `boneio_output: buzzer` is refused on a controller set to version 1.0, which has
no buzzer.
* The System, Logs and Tools pages and the YAML editor tab moved into Settings
and Diagnostics; old links redirect.
## 🐛 Bug fixes [#-bug-fixes]
* Repeated log lines are folded wherever they occur, not only when adjacent.
* The time zone picker showed a list box squashed to one row, which made most
zones unreachable.
* The panel marks the broker account boneIO actually signs in with, instead of
always marking `boneio`.
* `!secret` no longer breaks the WLED cache migration.
* **Home Assistant:** entities assigned to a room stay under that room's device
(e.g. "boneIO Black 24x16A - Salon"); covers keep their type; `show_in_ha: false` is
honoured; updating does not create duplicates; saving one section (inputs,
outputs, covers) no longer removes entities it does not own.
* GPIO binary sensors publish their state as retained, so Home Assistant knows
it right after a restart.
* System updates on a controller with a small eMMC no longer stop at "not
enough space" because of packages downloaded earlier.
* Covers stop, reverse and reach their end positions more accurately.
* v0.2/v0.3 controllers: `IN_26`, `IN_27` and `IN_28` work again.
## Known limitations [#known-limitations]
* The `boneio` account keeps full sudo through the `admin` group of the stock
BeagleBone image, behind the account password. It is the owner's own way to a
root shell; removing it would leave only the SD card or a serial console for repairs.
* A controller that was compromised before this update is not fixed by it.
# boneIO v1.4.4 Release Notes [#boneio-v144-release-notes]
v1.4.2 (2026-06-03)
## 🐛 Bug Fixes [#-bug-fixes-1]
System Migration Helper (boneio-migrate)
* **Tolerant** `systemctl reload/restart:` Migration helper no longer fails when reloading or restarting a service that isn't currently active. This fixes the critical issue where setup\_boneio.sh failed to apply migrations during image building because mosquitto was stopped at the time.
\##✨ New Features
OLED Shutdown Messages
* **Late-phase shutdown service** (boneio-oled-shutdown.service): New systemd service that displays "System stopped. Safe to unplug." on the OLED screen after the network has gone down during shutdown.
* **Restart-aware ExecStopPost:** boneio.service now only shows "Shutting down..." during actual system shutdown. During systemctl restart boneio, the OLED skips the stop message and goes directly to "is starting...".
## 📦 Migration: v1.4.3 [#-migration-v143]
This release includes migration v1.4.3 which automatically:
1. Installs boneio-oled-shutdown.service (late-phase shutdown OLED message)
2. Updates boneio.service with shutdown-aware ExecStopPost
The migration runs automatically on first startup after upgrade.
## v1.4.2 [#v142]
v1.4.2 (2026-06-03)
Hotfix — TimePeriod object handling in input forms.
## 🐛 Bug Fixes [#-bug-fixes-2]
* **EventForm crash** — `parseMs() called .match() on TimePeriod objects ({milliseconds: 220}) instead of strings, causing Uncaught TypeError: val.match is not a function. Replaced with the existing convertTimeperiodToMilliseconds() utility.`
* **BinarySensorForm** wrong bounce\_time — typeof data.bounce\_time === 'number' always returned false for TimePeriod objects, displaying default 120ms instead of the configured value. Fixed using convertTimeperiodToMilliseconds().
## 🛡️ Improvements [#️-improvements]
* Pre-commit hook — Added tsc --noEmit TypeScript type-check before vitest to catch build-breaking issues (unused variables, type errors) before commit.
## v1.4.1 [#v141]
v1.4.1 (2026-06-03)
Hotfix release with SSL certificate renewal and Modbus chart improvements.
## 🐛 Bug Fixes [#-bug-fixes-3]
* **SSL certificate renewal** — \_cert\_needs\_refresh() was checking file modification time (st\_mtime) instead of the actual X.509 expiry date. If the cert file was touched by backup/copy/rsync, mtime would reset and the certificate would never be renewed even after expiry. Now parses the real Not After date using openssl x509 and refreshes when the cert expires within 14 days.
* **Modbus sparkline** charts for energy meters — shouldRenderHistory() only whitelisted temperature/humidity sensors (by name pattern or unit %, °C, rh%). Energy meters with units like W, kWh, V, A, Hz, VA, var were excluded. Changed to show charts for all numeric read-only sensors that have a unit of measurement.
## v1.4.0 [#v140]
Changelog — v1.4.0
v1.4.0 (2026-06-03)
Major release — remote device support, irrigation overhaul, AI-assisted configuration, system monitoring, and dozens of bug fixes.
## 🔌 Remote Devices [#-remote-devices]
* **Remote Outputs (remote\_outputs)** — register switches and lights from remote ESPHome/MQTT devices as first-class outputs with ON/OFF/TOGGLE, area assignment, and interlock groups.
* **Brightness control** — remote ESPHome lights get a real-time brightness slider with smooth animations and debounced API calls.
* **Remote Binary Sensors** — subscribe to binary sensors on ESPHome devices for use as action triggers.
* **WLED brightness support** — WLED devices support brightness via the remote device API.
* **Remote cover tilt** — tilt actions for venetian blinds on remote boneIO devices.
## 🌿 Irrigation [#-irrigation]
* **Multi-zone irrigation controller** — schedules, per-zone intervals (run\_every\_n), water source management, master valve/pump support, and a full dashboard UI with real-time zone countdown.
* **Sequential water source activation** — water sources with multiple outputs activate in order with configurable delays (output\_start\_delay, output\_stop\_delay). Deactivation in reverse order.
* **Interlock-aware activation** — if an output is blocked by an interlock during water source activation, already-activated outputs are rolled back and a fault notification is sent.
* **Zone enabled toggle** — each zone can be individually enabled/disabled. Reflected in HA dashboard.
* **Zone run\_every\_n skip counter** — zones with run\_every\_n > 1 correctly track their skip counters across multi-cycle runs. next\_run\_iso, next\_run\_pretty, skip\_count published as valve entity attributes in HA.
* **Next Run Time sensor** — device\_class=timestamp sensor showing when the next scheduled run will occur (e.g. "in 19 hours").
* **HA Dashboard YAML generator** — one-click export of a complete Lovelace dashboard per controller, with zones, durations, schedules, and controls.
* **Irrigation AI assistant** — AI-powered configuration wizard for creating irrigation setups from natural language descriptions.
* **Schedule timezone fix** — schedule times are now treated as local time instead of UTC.
* **Dynamic duration max** — zone duration max is based on configured duration + 20 min (clamped to \[30, 120]) instead of hardcoded 1440 min.
* **Single-zone optimization** — controllers with 1 zone skip unnecessary auto\_advance, reverse, and next\_valve entities.
* **Manual start responsiveness** — clicking "Start" responds instantly; pump/valve delays no longer block the UI.
## 📊 System Monitoring [#-system-monitoring]
* **System sensors** (CPU, Disk, Memory)\* — percentage-based sensors with rich attributes:
* Disk: disk\_total\_gib, disk\_used\_gib, disk\_free\_gib
* Memory: memory\_total\_gib, memory\_used\_gib, memory\_available\_gib
* **Instant sensor values on UI load** — system sensors are included in WebSocket initial states, eliminating the 10-60s blank period after opening the UI.
* **Sensor attributes in UI** — GraphCard displays compact attribute chips `(e.g. Total: 28.65 GiB | Used: 2.28 GiB | Free: 25.19 GiB)` with dynamic unit extraction.
* **HA** `json_attributes_topic` — system sensors publish attributes as JSON, visible in HA's "More Info" dialog without extra entities.
## 🏠 Home Assistant Integration [#-home-assistant-integration]
* `suggested_area` in HA discovery — irrigation and other entities auto-assign to the correct area.
* `json_attributes_topic` — system sensors expose detailed metrics as HA entity attributes.
* **Entity category reorganization** — entities placed in proper HA categories (diagnostic, config).
* **Republish states on MQTT reconnect** — ensures HA always has the latest state.
* **Output groups in HA** — groups exposed with member outputs visible.
* **Remote output interlock** — interlock checks enforced for remote outputs and dimmer brightness.
## 🖥️ OLED Display [#️-oled-display]
* **Screensaver timer reset** — screensaver countdown now resets from the last button press instead of the first.
* **Sleep behavior fix** — fixed single-click sleep toggle.
## 🎛️ Covers [#️-covers]
* **Venetian tilt restore** — new `tilt_restore_after_close` option automatically restores the previous tilt angle after moving to an intermediate position. Skipped at extremes (0% / 100%).
* **Cover relay dropdown fix** — filter now accepts outputs with output\_type of cover, none, or missing.
* **Cover position precision** — fixed float/int rounding drift during movement.
## 🤖 AI Configuration Assistant [#-ai-configuration-assistant]
* **Output type awareness** — AI correctly distinguishes between lights (brightness actions) and switches (toggle/on/off).
* **Remote device guidance** — AI knows about remote outputs, covers, and binary sensors.
* **Irrigation valve type filter** — AI explicitly avoids "light" type outputs for irrigation.
## 🧩 UI / UX Improvements [#-ui--ux-improvements]
* **Input type change without restar** — switching between "Event Entity" and "Binary Sensor" takes effect immediately.
* **InputsView navigation fix** — long press on an input correctly navigates to its settings (not areas).
* **Clipboard in HA addon iframe** — fixed navigator.clipboard.writeText() in HA ingress iframe with document.execCommand('copy') fallback.
* **Sidebar section grouping** — remote and restart-required sections visually grouped.
* **Template duplication** — deep-clone templates with adjusted IDs.
* **Irrigation zones** — collapsible accordion with reorder buttons and add-at-bottom.
* **Live graphs** — sparkline charts in sensor/modbus views.
* **Modbus device temporary disable** — turn off a single Modbus device without removing config.
## 🐛 Bug Fixes [#-bug-fixes-4]
* **Irrigation** `run_every_n` *skip counter desync* — \_eligible\_zones() side effects caused counters to diverge. Split into pure filter + single-call counter update.
* **Config cache staleness** — invalidate\_config\_cache() now clears ConfigHelper.\_config\_cache.
* **TimePeriod empty string crash** — frontend-sent "" for optional TimePeriod fields no longer crashes Cerberus.
* **Remote output MQTT state** — remote outputs now publish state to MQTT (previously HA showed "unavailable").
* **Interlock bypass on dimmer brightness** — brightness changes now check interlock before allowing > 0.
* **ESPHome entity type routing** — control\_output() auto-detects entity type instead of always delegating to control\_switch().
* **ESPHome connect-before-lookup** — entity commands no longer silently fail when entities haven't been populated.
* **Output group form ID** — form now uses correct boneio\_output reference.
* **Interlock Groups API** — fixed always-returning-empty due to wrong attribute reference; added config-based fallback.
* **Frontend brightness deduplication** — WebSocket now considers brightness field in deduplication.
* **Frontend slider jump-back** — eliminated stale ESPHome callback processing.
# boneIO Black v1.3.1 Release Notes [#boneio-black-v131-release-notes]
Maintenance release focused on stability, type safety, and Home Assistant integration improvements.
✨ New Features
* 🔧 **Support for legacy 0.2 / 0.3 controllers** — added device definitions for older boneIO Black hardware revisions
* 🏠 **HA Update entity changed to binary sensor** — firmware update entity is now a binary sensor for cleaner HA integration
🐛 Bug Fixes
* **Cover position precision** — fixed inconsistent float/int conversion in cover position calculations, eliminating rounding drift during movement
* **Cover timestamp tracking** — fixed incorrect timestamps in cover state updates
* **HA discovery device\_class** — fixed null device\_class in Home Assistant autodiscovery by storing it directly on the input object
* **HA Update entity state during firmware restart** — update entity now correctly shows 'Updating' state during firmware restart instead of going offline
* **Event form click handling** — fixed click event handling in the WebUI event configuration form
♻️ Refactoring
* **Unified device\_class** — refactored device\_class to be a single source of truth on the input object (GpioBaseClass)
* **Removed gpio\_mode** — deprecated gpio\_mode setting, now handled by kernel overlay
* **Removed CAN System settings** — CAN configuration migrated to system migrations, manual settings no longer needed
* **Type safety improvements** — fixed multiple type checker issues across the codebase
⚠️ Duplicate Entity Fix in Home Assistant
If you see **duplicated entities** for your boneIO Black device in Home Assistant after updating:
1. Go to Home Assistant → **Settings** → **Devices & Services** → **Devices** tab
2. Enter **Selection Mode**, select the boneIO Black devices with duplicated entities, and **delete** them
3. Open the boneIO controller's WebUI → **Settings** → **Communication Protocols** → **MQTT** tab
4. Click **"Delete and resend HA Discovery"**
This will cleanly re-register all entities without duplicates.
# boneIO Black v1.3.0 [#boneio-black-v130]
Spring release — packed with new features, protocol support, and a complete WebUI overhaul!
✨ New Features
* 🌿 Multi-zone irrigation controller — schedules, per-zone intervals, water source management, master valve support, and a full dashboard UI with real-time zone countdown. All controlled also from Home Assistant!
* 🎛️ Conditional actions — time ranges, date ranges, and entity state conditions with AND/OR logic. Actions fire only when conditions are met
* 🎛️ Each output now has individual action capabilities — fine-grained control over what each output can do
* 📊 Live graphs added to the WebUI dashboard for real-time data visualization
* 📊 Simple history view for sensors — see past values at a glance
* ⏱️ Timed output with HA input — change the timer value directly from Home Assistant, no YAML restart needed
* 🔌 LoxUDP protocol — initial integration for Lox UDP communication
* 🔌 CANOpen protocol — initial support for CAN bus industrial devices
* 🏠 Experimental ha\_child\_devices mode for HA discovery — organize entities as child devices
* 🏠 Output groups visible in HA — output groups are now exposed to Home Assistant with their member outputs, so you can see which outputs belong to each group
* 🏠 Entity category reorganization — entities moved into proper HA categories (diagnostic, config) for a cleaner HA UI
* 🏠 Republish states on MQTT autodiscovery resend — ensures HA always has the latest state after reconnects
* 🔧 48×4A legacy controller support — added device type for older 48-output / 4A controllers
* 🔧 Tilt support for remote devices — venetian blinds on remote boneIO devices now support tilt actions
* 📦 Modbus entity naming — custom entity names for Modbus devices
* 📦 Temperature sensor rounding — configurable decimal rounding for temperature readings
* 📦 Serial number in backup filenames — easier identification of backup files across multiple devices
🐛 Bug Fixes
* OLED refresh interval — fixed display refresh timing causing stale or flickering content
* Modbus WebUI loading time — significantly reduced initial load time of Modbus device view
* Modbus communication isolation — other Modbus traffic is now blocked while using WebUI tools, preventing bus conflicts
♻️ UI / UX Improvements
\*Hundreds of UI fixes across the entire WebUI — padding consistency, card styling, shadow standardization, responsive layout improvements
* System Settings overhaul — redesigned Current Version, Available Versions, App Permissions, CAN Permissions, and Migrations sections
* Migrations table — professional table layout with descriptions, status badges, and GitHub source links
# boneIO Black v1.2.0 [#boneio-black-v120]
A lot of new features!
* possibility to register boneIO Black in boneio.app domain
* with that possible to install boneIO Black as PWA app!
* redesigned logger to easier find bugs
* add I2C scanner in webui tools
* add support for more remote devices: WLED presets, WLED brightness,
* add GET/POST /api/log-level endpoints for temporary runtime debug toggle
* add sortable columns to UISettings tables
* add smart toggle option for covers
* add cycle option to long click, so you can cycle across presets, brightness etc while holding button
* add new templates! Alarm Panel and Thermostat
* add possibility to backup boneIO Black from boneIO Black Dashboard
* prepare boneIO Black for boneIO Edge Temp & Humidity sensor
\*mobile improvements for Settings sidebar and RemoteDeviceTable
\*add possibility to shutdown system from OLED + button control!
Bug fixes:
* Cross-debounce: ignore release too close to press
* fix version comparision dev vs non-dev version
* add Modbus inter-device delay and timeout config
# boneIO Black v1.1.0 [#boneio-black-v110]
* add LWE03MW and CT F\&F energy meters
* add N4DSC08 temperature RS485 board
* fix modbus device liquid -sensor extra data inputs
* add support for 32x5A config in boneio.
* add firmware update manager with GitHub release checking and Home Assistant integration
* fix binary sensor loading into HA
* add initial WLED control support
* fix time parsing in UI
* add duration time every 200ms for long click
* add modbus creator helper tool
* add new Ultrasonic distance sensor
* fix webui authentication
# boneIO Black v1.0.0 [#boneio-black-v100]
It's finally ready.
Almost 10 months of our work!
This app is almost rewritten from scrach.
The app need special prepared Debian13 by boneIO. It has device tree prepared for boneIO Black.
This version will work only on Debian 13.
Versions 0.x won't work on Debian13!
Breaking changes:
* new option name for entities which can contain any character
* id is now lowercase, no spaces, it is generated automatically from device perspective (eg device\_id\_input\_id - boneio\_in03)
* change pin option to boneio\_output or boneio\_cover in actions
* topic prefix is no more configurable from settings! It's hardcoded as serial number
Changelog:
* new modular managers of the app, which can reload it's parts without restarting the app
* libgpiod support for inputs
\*new i2c driver
* new rewritten input module
* new One wire module
* new Modbus module
* new cover module
* new events module
* new webui with clickable Settings from User Interface! Almost no more yaml! If boneio: section is present.
* rewritten output group
* new modbus searcher function from webui
* new options for virtual sensors
* add option to provide NodeRed via nginx proxy (port 8443)
* change pin option to boneio\_output or boneio\_cover in actions
* add ability to change Mosquitto password from webui
* start even with bad MCP
* add option to manage areas from boneIO Black UI
* add option to change hostname from webui
* switch from nginx to caddy proxy and let's host https (unsecure)
* add new actions for event entities: triple click and sequence actions! double\_then\_long, single\_then\_long, double\_then\_single
* add autodiscovery of other boneio black's
* show toast in inputs when something is clicked
* add ability to control other Esphome devices in network (light, switch, cover)
* add support for older 0.2 controllers
* add option to go to entity setting if long clicked in Card
* add triple click and possibility to send sequences to mqtt
* add backup to disk
* add option to revert firmware via UI
## 🙏 Acknowledgments [#-acknowledgments]
Thank you to all users who provided feedback and bug reports during the development cycle!
## 📞 Support [#-support]
* **Documentation**: [https://boneio.eu/docs/black](https://boneio.eu/docs/black)
* **GitHub Issues**: [https://github.com/boneIO-eu/app\_black/issues](https://github.com/boneIO-eu/app_black/issues)
* **Community**: Join our Discord server
# Security advisories (/en/docs/black/security-advisories)
Every boneIO Black vulnerability that has a CVE ID is published here: which
versions it affects, which version fixes it, and whether you have to do
anything beyond updating. Newest first.
Handling reports and publishing fixed vulnerabilities is part of adapting
boneIO Black to the requirements of the EU Cyber Resilience Act (CRA). The
rules are in the
[security policy](https://github.com/boneIO-eu/app_black/blob/main/SECURITY.md).
## October 2026 — review of version 1.5.0 (CERT Polska) [#october-2026--review-of-version-150-cert-polska]
An independent security review of boneIO Black 1.5.0 was disclosed in
coordination with CERT Polska on 26 October 2026:
[CERT Polska notice](https://cert.pl/posts/2026/10/CVE-2026-77052/).
All vulnerabilities are fixed in **1.6.0**. Thanks to Mateusz Włodarczak
(s3ga) for the report.
### What to do [#what-to-do]
1. **Update the application to the latest 1.6.x.** From 1.5, go to 1.5.6
first, then follow the [checklist](/en/docs/black/current/install/upgrade-1-5-to-1-6).
2. **Create an administrator account** in the wizard that appears after the
update. Until then the controller refuses API requests.
3. **Change the MQTT broker password** if the controller was updated rather
than freshly flashed. The update deliberately leaves it alone so the
connection to Home Assistant does not break. The panel reports it under
[Settings → Access → Security](/en/docs/black/current/basic/security),
and **Fix** takes you to the change. Then enter the new password in Home
Assistant.
4. **Change the SSH password** if it is still the factory one —
[SSH login password](/en/docs/black/current/basic/accounts#ssh-login-password).
5. **Controllers older than 1.2.0** (Debian 10) cannot be updated. Flash a 1.6
system image — [upgrading to Debian 13](/en/docs/black/upgrade_debian13).
### Vulnerabilities [#vulnerabilities]
| CVE | What it was | Affected | Beyond updating |
| -------------- | ---------------------------------------------------------------------------------- | -------------------- | ------------------------------- |
| CVE-2026-77052 | Node-RED at `/nodered/` without sign-in — deploying flows that run system commands | 1.3.0 – before 1.6.0 | — |
| CVE-2026-77053 | Panel API without authentication by default | 1.0.0 – before 1.6.0 | create an administrator account |
| CVE-2026-77054 | `GET /api/config` returned passwords (MQTT, panel) | 1.2.0 – before 1.6.0 | change the MQTT password |
| CVE-2026-77055 | `boneio` account with passwordless sudo and in the `docker` group (system image) | 1.2.0 – before 1.6.0 | — |
| CVE-2026-77056 | Same published MQTT broker password on every device (system image) | 1.2.0 – before 1.6.0 | **change the MQTT password** |
| CVE-2026-77057 | No limit on sign-in attempts in the panel and SSH, no minimum password length | 1.2.0 – before 1.6.0 | — |
| CVE-2026-77058 | CSRF — another site could send commands to the controller | 1.2.0 – before 1.6.0 | — |
| CVE-2026-77059 | Race when installing the time zone sudoers rule | 1.3.0 – before 1.6.0 | — |
| CVE-2026-77060 | Mosquitto password file readable by every local account (system image) | 1.2.0 – before 1.6.0 | — |
| CVE-2026-77061 | Some API endpoints reachable without sign-in (logs, serial number, file list) | 1.2.0 – before 1.6.0 | — |
| CVE-2026-77062 | Clickjacking — the panel could be framed by another site | 1.2.0 – before 1.6.0 | — |
The system image fixes (77055, 77056, 77060) reach an updated controller
through signed system migrations — except the MQTT password, which you change
yourself. What exactly changed in 1.6.0: [release notes](/en/docs/black/release).
## Reporting a vulnerability [#reporting-a-vulnerability]
Please do not open a public issue. Use
[private reporting on GitHub](https://github.com/boneIO-eu/app_black/security/advisories/new)
or email [security@boneio.eu](mailto:security@boneio.eu) with `SECURITY` in the subject. We acknowledge
within 5 working days. You can also report through
[CERT Polska](https://cert.pl/cvd/).
# Upgrade to Debian 13 (/en/docs/black/upgrade_debian13)
## Upgrade boneIO Black system to Debian 13 [#upgrade-boneio-black-system-to-debian-13]
On this page you will find a step-by-step guide for upgrading the boneIO Black system to Debian 13.
### 📋 Requirements before upgrade [#-requirements-before-upgrade]
Before starting the upgrade process, make sure you have prepared:
* **SD card** - new, reliable SD card with minimum capacity of 16 GB
* **Configuration backup** - backup of your current device configuration
* **Time** - we recommend reserving enough time, as **we recommend configuring everything from scratch** to ensure the best system stability
### ⚠️ Important information - Compatibility [#️-important-information---compatibility]
Upgrading to Debian 13 requires system reinstallation. **The eMMC memory must contain at least Debian 11**.
If for some reason you want to keep the ability to run Debian 10, prepare a Debian 10 installation on a separate SD card.
Although it's possible to restore the previous configuration from backup, **we strongly recommend performing a fresh configuration from scratch**. This way you will ensure optimal performance and system stability, and avoid potential compatibility issues.
### 🔄 Upgrade process [#-upgrade-process]
Upgrading to Debian 13 involves:
* **Upgrading Debian 10 to Debian 11** on the eMMC card. The BeagleBone's eMMC memory contains an old bootloader that needs to be updated.
#### ⚠️ VERY IMPORTANT - Device safety [#️-very-important---device-safety]
**It is necessary to disconnect all input plugs from the device before starting the upgrade!**
**Also disconnect the ethernet cable from the device during the upgrade!**
Without this, the BeagleBone may hang and the upgrade process will fail. Disconnecting all connected input devices and the ethernet cable is crucial for the successful completion of the bootloader upgrade process.
### 📝 Step by step - Bootloader upgrade [#-step-by-step---bootloader-upgrade]
#### Step 1: Network preparation [#step-1-network-preparation]
* **Save the device IP** or set a static IP so you can ping it and check if the computer has started correctly
#### Step 2: Download and preparation [#step-2-download-and-preparation]
* **Download Debian 11 image** from the website [GitHub](https://github.com/boneIO-eu/black_debian_images/releases/tag/debian11) and **flash it to the microSD card** (e.g., using Balena Etcher)
* **Make a backup** of the current configuration
* **Power off the controller**
#### Step 3: Installing Debian 11 on eMMC [#step-3-installing-debian-11-on-emmc]
* **Insert the microSD card** from the top of the device
* **Power on the device** - LED lights will be visible from the bottom near the ethernet port and will light up from left to right in sequence
* **Wait until all LEDs turn off** at the bottom of the device. This takes about 10 minutes! The process may take longer, do not interrupt it and do not disconnect the power. Be patient and do not interrupt the process.
* **Do not disconnect the power until all LEDs at the bottom of the device turn off!**
* **Power off the device** and **remove the microSD card**
**Use the correct image!**
Remember to ALWAYS use the system image prepared by us!
Thanks to this approach, you can be sure that the bootloader has been updated and the new system works stably before making the final installation.
#### Step 4: Preparing Debian 13 [#step-4-preparing-debian-13]
* **Take the microSD card** and flash the Debian 13 image on it from the website [https://github.com/boneIO-eu/black\_debian\_images/releases/latest](https://github.com/boneIO-eu/black_debian_images/releases/latest) (pick the `emmc-flasher` image for your model)
#### Step 5: Bootloader upgrade verification [#step-5-bootloader-upgrade-verification]
* **Power on boneIO Black** with Debian 11 on eMMC
* **Wait for the device to appear on the network** (check with ping)
* **Connect via SSH** and make sure the system has Debian 11 installed. After login there is welcome screen showing which Debian version is installed.
* **You can power off the device**
### 💾 Further steps - Installing Debian 13 [#-further-steps---installing-debian-13]
#### Step 6: Installing Debian 13 on eMMC [#step-6-installing-debian-13-on-emmc]
* **Insert the microSD card** with Debian 13 image
* **Power on the device** - LED lights will be visible from the bottom near the ethernet port and will light up from left to right in sequence
* **Wait until all four LEDs light up and stay on** — that means the installation is done. The display shows the progress (**Flashing eMMC**, then **Setup system**) and finally **Flash complete! … Remove SD card**. **Installation may take up to 20 minutes!** Do not interrupt it and do not disconnect the power.
* **Do not disconnect the power until all four LEDs stay lit and the display says Flash complete!**
* **Power off the device** and **remove the microSD card**
* **Power on the device** - Debian 13 system will boot from eMMC memory
* **The boneIO application should start automatically** after the system loads
After installation on eMMC, you have approximately 1 GB of free memory and built-in Node-RED.
**Use the correct image!**
Remember to ALWAYS use the system image prepared by us!
### ⚙️ After installation [#️-after-installation]
#### System login [#system-login]
* **User:** `boneio`
* **Password:** on images with boneIO 1.6 or later there is no default password — you set it in the first-time setup in the panel (see below). Until then SSH login with a password is not possible. Older images used `Black`.
#### Configuration [#configuration]
After successfully starting the system:
1. Open a web browser and enter `https:// device IP address :8443`
2. Complete the [First-time setup](/en/docs/black/current/install/first-run-wizard) — create the administrator account.
3. If the controller does not match your model, use **Settings** → **Maintenance** → **Factory reset**, selecting your device type and hardware version.
**Device does not start?**
If, despite selecting the correct type and hardware version of the device, the device still does not start - please prepare a log in debug mode using the command `journalctl -u boneio --since "1 hour ago"` and contact technical support on our Discord.
4. Verify the operation of inputs and outputs - we recommend performing a full device test - It is critical to verify that the output numbers in the application correspond to those on the device.
**Outputs do not "match"?**
If, despite selecting the correct type and hardware version of the device, the outputs in the application do not match the physical ones - note the difference and contact technical support on our Discord.
5. **Prepare the configuration from scratch** using the wizard in the web interface - this is the recommended configuration method for the new system version.
### What's next? [#whats-next]
Congratulations! You have just finished the process of updating the system and application to the latest version. We know that the amount of changes you've encountered is huge and may overwhelm you. Therefore, to fully guide you through the process of configuration and application usage, we have prepared appropriate documentation. You will find it in the Application section, as well as the software configuration sub-section in the product section appropriate for your controller model.
# What's new in 1.6 (/en/docs/black/whats-new-1-6)
## In short [#in-short]
Version 1.6 makes the controller **safer**, **easier to find your way around** and **able to do more on its own**:
* the panel now has **accounts and passwords** — nobody on your network can change your controller without signing in,
* all settings are in **one place, in seven groups**, and a new **Security** page tells you what is still worth fixing,
* the controller can run things **by itself**: at a set time or with the sun, in modes such as *Away*, and even simulate someone being at home,
* the whole system — Debian, the kernel and boneIO — **updates from the panel**.
1.6 is our work of adapting boneIO Black towards the EU Cyber Resilience Act (CRA): a new controller is secure from the first start —
the panel over HTTPS only, no default passwords, and an administrator account you create yourself.
Your configuration — outputs, inputs, covers, actions — stays exactly as it is.
## Before the update [#before-the-update]
Coming from 1.5? Update to **1.5.6** first, keep a backup, and plan up to an hour — the first start runs system migrations.
Do not cut the power while it runs; a [UPS](/en/docs/black/products/black_32x10a/hardware-installation#backup-power-ups--recommended)
is recommended. The full list: [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6#1-before-the-update).
## What you need to do after the update [#what-you-need-to-do-after-the-update]
1. **Create an administrator account.** The panel starts with a short wizard. Choose a username and a password (at least 8 characters).
2. **Remember: this password may also become your SSH password.** If the SSH password was still the factory `Black`, the wizard replaces it.
3. **Open the panel at `https://:8443`.** The browser warning about the certificate is expected — click through it.
4. **Look at Settings → Access → Security.** Click **Fix** next to what it lists — usually the old password in `config.yaml` and the factory MQTT password.
5. **Showing the panel in a Home Assistant dashboard card?** Add your Home Assistant address in Security → *Embedding this panel in other sites*, then restart boneIO.
6. **Using Node-RED?** It now asks you to sign in with your boneIO administrator account.
Step-by-step: [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6). New controller? Start at
[Connect to your boneIO](/en/docs/black/current/install/how-to-connect).
## New features [#new-features]
### Safer [#safer]
Sign in to the panel. Add read-only accounts for the rest of the household — they can switch lights but not change settings.
One page with everything still open on the controller, each with an explanation and a Fix button. Also as a sensor in Home Assistant.
Get rid of the browser warning: boneIO Cloud, trusting the controller on your computers, or your own certificate.
New controllers ship with no usable SSH password and a random MQTT password per device. You choose yours in the first-time setup.
Change the SSH login password on the User accounts page — no terminal needed.
Encrypted MQTT both ways: to your broker, and into the controller's own broker. The password lives in secrets.yaml.
### Easier [#easier]
Device, Control, Connections, Services on this controller, Access, Maintenance, Advanced — everything in one tree, with a search filter.
The log, bus tools and a support bundle you can send us — passwords removed — instead of giving out SSH access.
Changing the broker password no longer makes the controller go offline — it updates its own configuration and reconnects.
A mistake in the configuration no longer leaves the controller in a restart loop. A recovery panel shows the error and lets you fix it.
### Does more on its own [#does-more-on-its-own]
Run actions at a set time or with the sun — "close the covers 15 minutes after sunset". With run history, so you can see what happened.
A switch with no relay behind it for modes such as "Away" or "Evening" that other actions can depend on.
Four questions and your empty house looks lived in: lights coming on room by room in the evening.
Tell the controller where it is — needed for everything that follows the sun.
### Smaller improvements [#smaller-improvements]
* **Faster start.** After you change the configuration or update, it loads in about two seconds instead of more than half a minute.
* **Time from your own network.** A controller without internet can take the time from a server in your network (**Settings → Device → Time zone → NTP servers**) — important, because it has no battery clock.
* **Clearer actions.** Lists of actions are shown as one-line rows; less common fields are under **More options**.
* **Restart badge.** Settings that need a restart after saving are marked.
* **Remote devices.** A misbehaving ESPHome or WLED device no longer takes the whole controller down; ESPHome covers can be controlled.
* **Hardware revision 1.1.** New controllers (1.1) have a buzzer, available as an ordinary output. A factory reset restores the configuration for your controller's type and revision.
* **System updates from the panel.** **Settings → Maintenance** updates Debian packages and the kernel too, with an estimate of how long it takes. See [System](/en/docs/black/current/basic/system).
* **On a phone.** A bottom navigation bar on phones and tablets; outputs and inputs can be grouped by room.
* **Modbus at a glance.** A device that stops answering is marked; a picker with search and a *Failing only* filter.
* **Diagnostics → Disk.** What fills the controller's storage, and a button to free unused images and the package cache.
* **Power cuts.** After a cut the page says *boneIO is starting…* and opens the panel by itself; a damaged boot partition no longer stops the start.
* **Home Assistant.** Entities stay under their room's device, covers keep their type, and saving one section no longer removes others' entities.
## Where did things move? [#where-did-things-move]
| In 1.5 | In 1.6 |
| ----------------------------------------------- | ---------------------------------------------------------------- |
| **System** tab → update, available versions | **Settings → Maintenance → Software update** |
| **System** tab → backup | **Settings → Maintenance → Backups** |
| **System** tab → restart, shutdown | **Settings → Maintenance → Restart and shutdown** |
| **System** tab → hardware test, all outputs off | **Settings → Maintenance → Device tools** |
| **System** tab → MQTT passwords | **Settings → Services on this controller → MQTT broker (local)** |
| **System** tab → factory reset | **Settings → Maintenance → Factory reset** |
| **Logs** | **Diagnostics** |
| **Tools** (Modbus helper) | **Diagnostics** |
| **YAML Editor** tab | **Settings → Advanced → YAML editor** |
Old bookmarks still work: the System page opens Software update, Logs and Tools open Diagnostics, and the YAML editor tab opens Settings → Advanced → YAML editor.
## Readable names instead of identifiers [#readable-names-instead-of-identifiers]
Schedules and virtual switches can be written with a readable `name:` instead of an `id:` — the identifier is made from the name automatically:
*Covers at dusk* becomes `covers_at_dusk`. The panel does this for you when you create schedules and virtual switches.
Old configurations with `id:` keep working; **you do not need to change anything**.
## Watch out [#watch-out]
* **Covers run into the endstop.** A full open or close now runs about 10% longer (**Endstop Overrun**), with a 500 ms pause before reversing. This applies to your existing covers too. Motor without endstops? Set the overrun to 0 — [Covers](/en/docs/black/current/configuration/cover).
* **The buzzer on 1.0 controllers.** A 1.0 controller has no buzzer. A configuration that uses `boneio_output: buzzer` on a controller set to version 1.0 no longer loads —
remove that output, or set the right controller version if you have a 1.1 controller.
* **SSH and Docker.** The `boneio` user is no longer in the `docker` group. If you managed containers by hand over SSH, use `sudo`.
* **Access without a password** (`web.auth.allow_anonymous: true`) exists only as an emergency option in `config.yaml` and works only while no account exists.
The panel shows a warning that cannot be dismissed.
* **The panel is for administrators to configure.** A read-only account does not see Settings, Diagnostics or Node-RED.
## The full list [#the-full-list]
Every change, fix and security detail: [Release notes](/en/docs/black/release).
# Edge Series (/en/docs/edge)
## What is boneIO Edge? [#what-is-boneio-edge]
boneIO Edge is a new family of devices, representing a natural evolution of our ecosystem. Listening to the community's voices and the needs of modern installations, we decided to "step out of the distribution board" to provide precise data and control exactly where they are needed most – directly in your rooms.
The Edge series is synonymous with flexibility. We create it with peripheral devices in mind that complement the series of DIN rail-mounted controllers, offering the same reliability in a new, compact form. These are intelligent points of contact with the building that take care of your comfort and safety while remaining a discreet element of the interior.
### What will you find in the Edge family? [#what-will-you-find-in-the-edge-family]
We are constantly developing this line to cover the full spectrum of smart home needs; you will find in it:
* **Precise environmental sensors** - communicating via **Modbus**, providing stable reading of air parameters in the form of **boneIO Edge Temperature & Humidity**.
* **Advanced detection** - including presence sensors and other types of sensors based on **Wi-Fi** or **CAN** connectivity.
* **Interfaces and actuators** - execution devices that we will present in the future.
### **PREMIERE!!!** [#premiere]
The first representative of the new series is **boneIO Edge Temperature & Humidity**. It is an ultra-compact temperature and humidity sensor communicating via the Modbus RTU protocol. It was designed to combine aesthetics (compact dimensions allow for discreet installation!) with the highest measurement accuracy, forming the foundation for heating and air conditioning systems in your home.
### What's next? [#whats-next]
We encourage you to follow our social media and Discord server. There you will find the latest information about planned products.
# ESP Series (/en/docs/esp)
## Welcome to boneIO ESP Documentation! [#welcome-to-boneio-esp-documentation]
On this page, you'll find step-by-step guides and instructions for configuring your boneIO ESP controller.
Whether you have one of our larger models like:
* ESP 32x10A,
* ESP 24x16A,
* ESP Cover,
* ESP Cover Mix,
or it is one of our smaller devices, such as the: Dimmer, or gen2 series devices like: ESP Dimmer gen2, ESP Input24 gen2, or ESP 8x10A gen2, you will find the documentation necessary to get started here.
Your device comes preinstalled with ESPHome and a default configuration. You'll need to adjust it to match your specific requirements. Below are the essential steps to help you configure your boneIO ESP controller.
This documentation will guide you through the initial setup, configuration, and integration with other systems like Home Assistant.
# Security (/en/docs/esp/security)
boneIO ESP controllers run ESPHome. You can use them in two ways, and the
choice decides who looks after updates and security:
* **factory firmware** — you add the controller in Home Assistant and that is
all; boneIO delivers the updates;
* **adoption in ESPHome Builder** — you take over the configuration and compile
it yourself; updates and security are then on your side.
## Factory firmware [#factory-firmware]
This is the firmware a controller ships with, and the one the installer at
[boneio.eu/esp](https://boneio.eu/esp) flashes.
**Updates.** In Home Assistant the controller has a **Firmware** entity. When
boneIO releases a new version the entity shows an available update — install it
with **Update**. The controller checks after every start and every 6 hours.
Controllers running older firmware, without that entity, get it after flashing
once from the installer.
**Security.**
| | Factory firmware |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Connection to Home Assistant (`api`) | Encrypted. Home Assistant sets the key, different for every controller, on its first connection and keeps it |
| Firmware upload over the network (`ota`) | No password — anyone on the network can flash their own firmware. ESPHome requires it: it is how you install your own configuration after adoption |
| Device web page (`web_server`) | None. The installer's **+ web panel** option or the **Firmware variant** list in Home Assistant turns it on — the page on port 80 then has no password and can switch outputs |
| Firmware upload through the browser | None |
Add the controller to Home Assistant as soon as it is on the network: until
then the connection is not encrypted, and whoever connects first sets the key.
Keep the controller on a trusted network, ideally separate from guest devices.
**The key survives reflashing.** The controller keeps its key even after
firmware is flashed over USB. When you sell the controller, move it to another
Home Assistant, or Home Assistant has lost the key (for example a reinstall
without a backup), flash firmware from the installer and accept **erase
device** — only that removes the key.
## After adoption in ESPHome Builder [#after-adoption-in-esphome-builder]
Adoption copies the controller's public configuration — without boneIO updates,
so the **Firmware** entity goes away and you install new firmware by compiling
the configuration in ESPHome Builder. Do it regularly: that is how you get
fixes to ESPHome and to the boneIO packages.
**1. Take control with an API key.** In the **Take control** dialog leave
**Enable API encryption** ticked (ESPHome Builder 2026.10 or newer). If Home
Assistant then asks for the key in the ESPHome integration, copy it from the
`api` block of the device configuration.
In an older ESPHome Builder add the key yourself (32 bytes in base64, Builder
can generate one):
```yaml
api:
reboot_timeout: 0s
encryption:
key: !secret boneio_api_key
```
**2. Close OTA and the device page.** The public configuration has a device
page with no password. Change these blocks and install again:
```yaml
ota:
- platform: esphome
encryption:
web_server:
port: 80
local: true
auth:
type: digest
username: admin
password: !secret boneio_web_password
```
* **`ota.encryption`** — the controller accepts only firmware encrypted with its
API key: nobody else can flash it, and the firmware image (which contains the
key) never crosses the network in plain text. Needs ESPHome 2026.9 or newer;
on older versions set `password: !secret boneio_ota_password` instead of
`encryption:` — a password only checks who is uploading. The two cannot be
combined.
* **`web_server.auth`** protects the device page. If you do not use the page,
remove the whole `web_server` block.
* **A controller adopted earlier** may have a `- platform: web_server` line in
`ota` — that is firmware upload through the browser. Remove it, or keep it
only together with `web_server.auth`.
Keep the password in `secrets.yaml`, different for every controller.
## Reporting a vulnerability [#reporting-a-vulnerability]
Please do not open a public issue. Email [security@boneio.eu](mailto:security@boneio.eu) with `SECURITY`
in the subject — we acknowledge within 5 working days. You can also report
through [CERT Polska](https://cert.pl/cvd/). Report problems in ESPHome itself
to the [ESPHome project](https://github.com/esphome/esphome/security).
# Areas (/en/docs/home-assistant/areas)
## Areas – The Foundation of Order in a Smart Home [#areas--the-foundation-of-order-in-a-smart-home]
When starting your adventure with Home Assistant, it is worth taking care of system "hygiene" from day one. In an extensive home, the number of sensors, switches, and lights (entities) quickly reaches the hundreds. Areas are a tool that allows you to control this chaos by grouping devices according to their physical location.
### Why is it worth using Areas? [#why-is-it-worth-using-areas]
Areas allow you to divide the house into specific rooms or zones. Thanks to this, you assign every input, sensor, or energy meter to a specific place (e.g., "Living Room", "Garage").
#### 1. Clarity of dashboards and automations [#1-clarity-of-dashboards-and-automations]
Instead of searching through a list of 200 lighting entities, you can filter the view only to the "Kitchen". This significantly speeds up the process of creating dashboards and writing automations.
#### 2. Consistent naming (No more long names) [#2-consistent-naming-no-more-long-names]
Without areas, users often create names like `light.main_light_above_the_island_in_the_kitchen` or `sensor.thermometer_childrens_room`. By having a division into areas, Home Assistant intelligently distinguishes entities with the same name in different zones.
Real-life example: Imagine that in every room you have a "Main Light". Thanks to areas, you can name the entities simply `light.main`. HA will know that one belongs to the Living Room area and the other to the Bedroom. This also facilitates voice control – by saying "Turn off the light in the Living Room," the system knows exactly which one is meant.
### How to create Areas? [#how-to-create-areas]
We recommend creating a separate area for each room in the house and external zones (e.g., Garden, Driveway).
1. Go to **Settings** -> Select the **Areas, zones & labels** tab.
2. Click the **+ Create area** button.
3. Fill in the auxiliary data:
* **Name:** e.g., Bathroom Ground Floor.
* **Icon:** choose an appropriate graphic (e.g., mdi:shower).
* **Floor:** assign the room to a floor (e.g., Ground Floor, Floor 1).
* **Image:** you can add a photo of the room, which HA will use on dashboard cards.
* **Aliases:** define alternative names for a given area that will be used by voice assistants.
### Assigning devices to Areas [#assigning-devices-to-areas]
There are two ways to assign hardware to a specific location.
#### A. boneIO Method (Recommended - right now only for Black series) [#a-boneio-method-recommended---right-now-only-for-black-series]
**boneIO** controllers were designed to make your life easier right at the configuration stage.
* When adding inputs or outputs in the controller configuration, you can immediately assign them to a specific area.
* **Effect**: The controller automatically "splits" entities into smaller, logical devices assigned to the correct rooms. Thanks to this, in the "Devices" tab, you don't see one huge controller with 32 outputs, but a clear list of devices in each room.
Read more about this in the technical documentation: Black Series
#### B. Manual moving of entities [#b-manual-moving-of-entities]
If a device (e.g., integrated via Wi-Fi) did not assign itself automatically or you want to change the location of a single entity:
1. Select **Settings** -> **Devices & services** -> **Entities**.
2. Search for the entity you are interested in and click on it.
3. Click the settings icon (gear).
4. Deselect the option "Entity follows device area".
5. An Area dropdown menu will appear, from which you can select the new location.
### Good practices [#good-practices]
* **Group floors**: Use the "Floors" feature. This allows for quick actions like "Turn off everything on the first floor."
* **Aliases**: Add aliases (synonyms) for voice assistants. If an area is named "Living Room", add appropriate aliases so the assistant understands you better.
* **Technical zones**: Create areas such as "Distribution Board" or "Server Room" for system sensors and boneIO statuses.
# Backups (/en/docs/home-assistant/backups)
A Home Assistant backup holds its whole configuration: integrations, automations, dashboards, users and apps. Set it up straight after the [first run](/en/docs/home-assistant/first-run), before you start configuring.
The boneIO controllers keep their configuration themselves and have backups of their own, described [below](#boneio-controllers).
## Home Assistant backups [#home-assistant-backups]
Go to **Settings** → **System** → **Backups**.
1. Click **Set up backups**.
2. Home Assistant shows an **encryption key**. Every backup is encrypted with it, and **without that key no backup can be restored**. Download the **emergency kit** and keep the file off the Home Assistant server: in a password manager, on another computer, printed.
{/* SCREENSHOT: en_ha_backups_encryption_key.webp — the Encryption key window with the key masked and the emergency kit download */}
3. In the next steps choose how often to back up, how many backups to keep and where to store them. Keep a copy off the server too: on network storage (a NAS) or in Home Assistant Cloud. A backup on the same disk does not help when the disk fails.
**Backup now** makes a backup on the spot, for example before a bigger change.
## Restoring [#restoring]
On a new or reinstalled server, the Home Assistant wizard offers **Upload backup** and **Home Assistant Cloud** on its first screen (see [First run](/en/docs/home-assistant/first-run#start)). Choose the backup and enter the encryption key from the emergency kit.
## boneIO controllers [#boneio-controllers]
**boneIO Black.** The configuration lives on the controller. Back it up in the boneIO panel: [Backups](/en/docs/black/current/basic/system#backups). Restoring a Home Assistant backup changes nothing on the controller, and the other way round. After a controller is restored, Home Assistant finds its devices again over MQTT.
**boneIO ESP.** The controller's configuration is a YAML file in ESPHome Device Builder. If Device Builder runs as an app in Home Assistant, that file is in the Home Assistant backup. If it runs on your computer, keep the file yourself.
The most important actions (button → light, button → cover) are in the boneIO controllers' configuration. They work even when Home Assistant has to be rebuilt from scratch.
# Connecting boneIO Black (/en/docs/home-assistant/boneio-black)
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 runs | on the boneIO Black, from the start | in Home Assistant, as the Mosquitto app |
| What you install in Home Assistant | only the MQTT integration | the Mosquitto app and the MQTT integration |
| When to choose it | almost always | when Home Assistant already runs Mosquitto, for example for a large Zigbee2MQTT network, and you want one broker for everything |
## Broker on the controller (recommended) [#broker-on-the-controller-recommended]
### 1. Set the MQTT password on the controller [#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](/en/docs/black/sbs-mqtt-connection#option-1-mqtt-broker-on-boneio-black-default).
### 2. Add the MQTT integration in 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.
2. Type `MQTT` and choose **MQTT** from the list.
3. Home Assistant lists several integrations with MQTT in their name. Choose the first one, plain **MQTT**.
4. Choose **Manually enter the MQTT broker connection details**.
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**.
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](/en/docs/black/sbs-mqtt-connection#encrypting-home-assistants-connection-tls).
## Mosquitto in 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**.
2. In the **App store**, type `Mosquitto` and open **Mosquitto broker**.
3. Click **Install**.
4. Once installed, click **Start**. **Start on boot** is on, so the broker comes back by itself after Home Assistant restarts.
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](/en/docs/black/sbs-mqtt-connection#configuring-mqtt-in-boneio-controller). 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 [#what-you-see-in-home-assistant]
The **MQTT** integration shows the controller and its 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](/en/docs/black/current/configuration/areas),
* boneIO templates (thermostat, alarm panel, gate, irrigation) as devices of their own, under their own names.
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**.
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 [#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](/en/docs/black/sbs-how-to-update).
## The boneIO panel in Home Assistant [#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](/en/docs/black/sbs-mqtt-connection#installation-of-the-boneio-home-assistant-add-on).
{/* SCREENSHOT: en_ha_apps_boneio_repository.webp — the App store after adding the boneio-eu/home-assistant-addons repository, with the boneIO app listed */}
# Connecting boneIO ESP (/en/docs/home-assistant/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 [#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.
{/* SCREENSHOT: en_ha_esphome_confirm.webp — the ESPHome window asking to add the discovered boneIO ESP controller */}
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.
{/* SCREENSHOT: en_ha_esphome_encryption_key.webp — the ESPHome window with the encryption key field (only when the configuration has a key) */}
5. Assign the controller to an area and click **Finish**.
{/* SCREENSHOT: en_ha_esphome_assign.webp — assigning the boneIO ESP controller to an area after adding it */}
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 [#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.
{/* SCREENSHOT: en_ha_esphome_device.webp — the device page of a boneIO ESP (e.g. Dimmer LED) in Home Assistant with its entities */}
## Changing the firmware variant [#changing-the-firmware-variant]
Firmware from [boneio.eu/esp](https://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 [#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 [#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 [#editing-the-controllers-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](/en/docs/esp/how-to-connect).
Actions set up in the boneIO ESP configuration (button → light) run in the controller itself, also while Home Assistant is off.
# Dashboards (/en/docs/home-assistant/dashboards)
This guide shows you how to create beautiful and functional dashboards for controlling your boneIO-powered smart home. We'll use practical examples based on real-world setups.
## Dashboard Structure [#dashboard-structure]
A well-organized dashboard typically has:
1. **Home screen** - Quick access tiles to all categories
2. **Category views** - Dedicated pages for lights, covers, temperatures, etc.
3. **Badges** - Quick status indicators in the header
## Home Screen with Navigation Tiles [#home-screen-with-navigation-tiles]
Create a main screen with tiles that navigate to detailed views:
```yaml
type: grid
columns: 3
square: false
cards:
- type: tile
entity: light.ground_floor
name: Ground Floor
vertical: true
tap_action:
action: navigate
navigation_path: /dashboard/lights-ground
- type: tile
entity: light.first_floor
name: First Floor
vertical: true
tap_action:
action: navigate
navigation_path: /dashboard/lights-first
- type: tile
entity: cover.all_covers
name: Covers
vertical: true
tap_action:
action: navigate
navigation_path: /dashboard/covers
```
Using `tap_action: navigate` turns tiles into navigation buttons. The entity state is still shown, giving you a quick overview.
## Organizing Lights by Room [#organizing-lights-by-room]
Use **Heading Cards** with emoji to visually separate rooms:
```yaml
type: grid
cards:
- type: heading
heading: "🔪 Kitchen"
heading_style: title
badges:
- type: entity
entity: light.kitchen_all
tap_action:
action: toggle
- type: tile
entity: light.kitchen_island
name: Island
tap_action:
action: toggle
- type: tile
entity: light.kitchen_counter
name: Counter
tap_action:
action: toggle
```
### Light Control with Mushroom Cards [#light-control-with-mushroom-cards]
For RGB/WLED lights, **Mushroom Light Card** provides excellent control:
```yaml
type: custom:mushroom-light-card
entity: light.wled_living_room
name: LED Strip
use_light_color: true
show_brightness_control: true
show_color_control: true
show_color_temp_control: true
collapsible_controls: false
tap_action:
action: toggle
hold_action:
action: more-info
```
Mushroom cards require HACS installation. Install from: [https://github.com/piitaya/lovelace-mushroom](https://github.com/piitaya/lovelace-mushroom)
## Cover Control [#cover-control]
### Simple Cover Tiles [#simple-cover-tiles]
```yaml
type: tile
entity: cover.living_room
name: Living Room
vertical: true
features:
- type: cover-open-close
- type: cover-position
```
### Cover with Position Slider [#cover-with-position-slider]
For precise control, use the position feature:
```yaml
type: tile
entity: cover.bedroom
features:
- type: cover-position
state_content:
- state
- current_position
```
## Temperature Monitoring [#temperature-monitoring]
### Mini Graph Card for Temperature History [#mini-graph-card-for-temperature-history]
**Mini Graph Card** is perfect for showing temperature trends:
```yaml
type: custom:mini-graph-card
entities:
- entity: sensor.outdoor_temperature
name: Outside
color: "#03fc24"
name: Temperature
hours_to_show: 24
line_width: 3
points: false
show:
fill: fade
```
Mini Graph Card requires HACS. Install from: [https://github.com/kalkih/mini-graph-card](https://github.com/kalkih/mini-graph-card)
### Multiple Temperatures on One Graph [#multiple-temperatures-on-one-graph]
```yaml
type: custom:mini-graph-card
entities:
- entity: sensor.living_room_temperature
name: Living Room
color: "#ff6384"
- entity: sensor.bedroom_temperature
name: Bedroom
color: "#36a2eb"
- entity: sensor.outdoor_temperature
name: Outside
color: "#4bc0c0"
name: Temperatures
hours_to_show: 24
line_width: 2
points: false
```
## Badges for Quick Status [#badges-for-quick-status]
Add badges to the dashboard header for at-a-glance information:
```yaml
badges:
- type: entity
entity: sensor.outdoor_temperature
show_name: false
- type: entity
entity: weather.home
state_content:
- temperature
- state
name: Forecast
- type: entity
entity: person.john
show_entity_picture: true
show_name: false
```
## Navigation Badge (Home Button) [#navigation-badge-home-button]
Add a home button badge to return to main screen:
```yaml
badges:
- type: custom:mushroom-template-badge
icon: mdi:home
tap_action:
action: navigate
navigation_path: home
```
## Complete Light View Example [#complete-light-view-example]
Here's a complete example of a lights page organized by room:
```yaml
type: sections
max_columns: 4
sections:
- type: grid
cards:
- type: heading
heading: "🛋️ Living Room"
heading_style: title
badges:
- type: entity
entity: light.living_room_all
tap_action:
action: toggle
- type: grid
columns: 2
cards:
- type: tile
entity: light.living_room_main
name: Main
tap_action:
action: toggle
- type: tile
entity: light.living_room_tv
name: TV
tap_action:
action: toggle
- type: custom:mushroom-light-card
entity: light.wled_living_room
name: LED Strip
use_light_color: true
show_brightness_control: true
show_color_control: true
- type: grid
cards:
- type: heading
heading: "🔪 Kitchen"
heading_style: title
badges:
- type: entity
entity: light.kitchen_all
tap_action:
action: toggle
- type: tile
entity: light.kitchen_island
name: Island
tap_action:
action: toggle
- type: tile
entity: light.kitchen_counter
name: Counter
tap_action:
action: toggle
badges:
- type: custom:mushroom-template-badge
icon: mdi:home
tap_action:
action: navigate
navigation_path: home
- type: entity
entity: light.all_lights
name: All
tap_action:
action: toggle
```
## Recommended Custom Cards [#recommended-custom-cards]
| Card | Purpose | HACS Link |
| ------------------- | --------------------------- | ------------------------------------------------------------------------- |
| **Mushroom Cards** | Modern UI components | [piitaya/lovelace-mushroom](https://github.com/piitaya/lovelace-mushroom) |
| **Mini Graph Card** | Temperature/sensor graphs | [kalkih/mini-graph-card](https://github.com/kalkih/mini-graph-card) |
| **Button Card** | Highly customizable buttons | [custom-cards/button-card](https://github.com/custom-cards/button-card) |
## Tips for boneIO Users [#tips-for-boneio-users]
1. **Group lights by room** - Create HA light groups for "all kitchen lights", "all living room lights"
2. **Use entity pictures** - Add photos to person entities for visual identification
3. **Set friendly names** - boneIO Black enforces entity\_id naming like `light.blkf8dc18_out_01` (to avoid conflicts when you have multiple Black devices). Set a friendly display name in HA: "Kitchen Island"
4. **Test on mobile** - Most dashboard use is on phones, design for touch
# Energy Dashboard - What it is and how to configure? (/en/docs/home-assistant/energy-dashboard)
# First Automation (/en/docs/home-assistant/first-automation)
This guide will help you create your first Home Assistant automations. We'll focus on scenarios that **require** Home Assistant - things that boneIO cannot do internally.
Remember: Simple actions like "button toggles light" or "button controls cover" should be configured in boneIO. They work faster and remain functional even when Home Assistant is offline.
## Automation Anatomy [#automation-anatomy]
Every Home Assistant automation consists of three parts:
```yaml
automation:
- alias: "Automation Name"
trigger:
# WHEN should it run?
condition:
# ONLY IF these conditions are met (optional)
action:
# WHAT should happen?
```
## Example 1: Close Covers at Sunset [#example-1-close-covers-at-sunset]
This automation closes all covers 30 minutes after sunset - something boneIO cannot do alone.
```yaml
automation:
- alias: "Close covers at sunset"
trigger:
- platform: sun
event: sunset
offset: "+00:30:00"
action:
- service: cover.close_cover
target:
entity_id: cover.living_room
- service: cover.close_cover
target:
entity_id: cover.bedroom
```
### Using Cover Groups [#using-cover-groups]
If you have many covers, create a group first:
```yaml
# In configuration.yaml
cover:
- platform: group
name: "All Covers"
entities:
- cover.living_room
- cover.bedroom
- cover.kitchen
```
Then use it in automation:
```yaml
automation:
- alias: "Close all covers at sunset"
trigger:
- platform: sun
event: sunset
offset: "+00:30:00"
action:
- service: cover.close_cover
target:
entity_id: cover.all_covers
```
## Example 2: Turn On Light When Motion Detected (Only When Dark) [#example-2-turn-on-light-when-motion-detected-only-when-dark]
This requires conditional logic - turn on light only if it's dark outside.
```yaml
automation:
- alias: "Hallway motion light"
trigger:
- platform: state
entity_id: binary_sensor.hallway_motion
to: "on"
condition:
- condition: numeric_state
entity_id: sun.sun
attribute: elevation
below: 5
action:
- service: light.turn_on
target:
entity_id: light.hallway
- delay:
minutes: 3
- service: light.turn_off
target:
entity_id: light.hallway
```
The `delay` in this automation blocks further triggers. For better behavior, use a separate automation with `wait_for_trigger` or use the `motion_light` blueprint.
## Example 3: Notification When Gate Open Too Long [#example-3-notification-when-gate-open-too-long]
Send a phone notification if the gate has been open for more than 10 minutes.
```yaml
automation:
- alias: "Gate open too long notification"
trigger:
- platform: state
entity_id: binary_sensor.gate
to: "on"
for:
minutes: 10
action:
- service: notify.mobile_app_your_phone
data:
title: "Gate Alert"
message: "Gate has been open for 10 minutes!"
data:
tag: "gate-alert"
```
## Example 4: Turn Off All Lights When Leaving Home [#example-4-turn-off-all-lights-when-leaving-home]
Use person tracking to automate actions when everyone leaves.
```yaml
automation:
- alias: "Turn off lights when leaving"
trigger:
- platform: state
entity_id: person.john
from: "home"
condition:
- condition: state
entity_id: person.jane
state: "not_home"
action:
- service: light.turn_off
target:
entity_id: all
```
## Creating Automations in UI [#creating-automations-in-ui]
You don't have to write YAML - Home Assistant has a visual automation editor:
1. Go to **Settings** → **Automations & Scenes**
2. Click **Create Automation**
3. Choose **Create new automation**
4. Add triggers, conditions, and actions using the visual editor
The UI editor is great for simple automations. For complex logic or templates, YAML gives you more control.
## Tips for boneIO Users [#tips-for-boneio-users]
| Scenario | Where to Configure |
| --------------------------- | ---------------------------- |
| Button → Light toggle | boneIO `click_action` |
| Button → Cover up/down | boneIO `click_action` |
| Double-click → Scene | boneIO `double_click_action` |
| Long-press → All lights off | boneIO `long_click_action` |
| Time-based actions | Home Assistant automation |
| Sun-based actions | Home Assistant automation |
| Conditional logic | Home Assistant automation |
| Notifications | Home Assistant automation |
## Next Steps [#next-steps]
* [Dashboards](/docs/home-assistant/dashboards) - Create beautiful control panels for your smart home
# First run (/en/docs/home-assistant/first-run)
After the [installation](/en/docs/home-assistant/installation), open `http://homeassistant.local:8123` in a browser. Home Assistant takes you through a short wizard: the account, your home's location, analytics and the devices it found. It takes a few minutes.
## Start [#start]
Click **Create my smart home**. If you have a backup of an earlier Home Assistant, choose **Upload backup** or **Home Assistant Cloud** instead. The wizard restores your configuration from it instead of starting a new one.
The language is chosen at the bottom of the page. The wizard remembers it for this browser.
## Account [#account]
Enter a **Name**, a **Username** and the **Password** twice. This is the owner's account, with full rights in Home Assistant. Keep the password somewhere safe.
Click **Create account**.
## Home location [#home-location]
Type an address or town into **Search address** and pick it from the list, or move the pin on the map. Home Assistant uses the location for sunrise and sunset, the weather and "when I leave home" automations. The town is precise enough.
Click **Next**.
## Analytics [#analytics]
Here you decide whether Home Assistant sends its makers anonymous information about the installation. All switches are off by default and can stay off. Nothing in your home depends on them.
Click **Next**.
## Devices found [#devices-found]
Home Assistant shows what it found on your network: TVs, printers, speakers, and **ESPHome** devices, boneIO ESP controllers among them. There is nothing to do here. You add the devices found later, from the list in **Settings** → **Devices & services**.
Click **Finish**.
## Signing in and the first dashboard [#signing-in-and-the-first-dashboard]
After the wizard, Home Assistant may ask you to sign in with the account you just created. Tick **Keep me logged in** if this is your own computer.
You see the **Overview** dashboard. At first it holds the areas the wizard created and summaries, the number of devices found among them.
## What next [#what-next]
* [Connect boneIO Black](/en/docs/home-assistant/boneio-black): the controller over MQTT; all its outputs, inputs and sensors appear by themselves.
* [Connect boneIO ESP](/en/docs/home-assistant/boneio-esp): the controller through ESPHome.
* [Backups](/en/docs/home-assistant/backups): set them up straight away, before you start configuring.
# Introduction to HACS (/en/docs/home-assistant/hacs)
# Introduction to Home Assistant (/en/docs/home-assistant)
Home Assistant is an open-source home automation platform that serves as the central hub for your smart home. Combined with boneIO, it provides a powerful and reliable system for managing your entire home.
## How boneIO Works with Home Assistant [#how-boneio-works-with-home-assistant]
boneIO offers two integration methods with Home Assistant, depending on the device series:
| Series | Integration Method | Description |
| ---------------- | --------------------------------------------------------------- | ------------------------------------------------- |
| **boneIO Black** | [MQTT with autodiscovery](/en/docs/home-assistant/boneio-black) | All entities appear automatically |
| **boneIO ESP** | [ESPHome API](/en/docs/home-assistant/boneio-esp) | Default integration via native Home Assistant API |
Both methods provide:
* Automatic device discovery in Home Assistant
* Real-time status updates
* Full control over lights, covers, sensors, and more
boneIO can perform simple actions (button → light, button → cover) internally without Home Assistant. Use HA for advanced automations that require logic, time conditions, or multiple device coordination.
## Basic Concepts [#basic-concepts]
Before diving into automations and dashboards, let's understand the key Home Assistant concepts:
| Concept | Description | Example |
| -------------- | -------------------------------------- | ----------------------------------------- |
| **Entity** | A single device or sensor in HA | `light.kitchen_main`, `cover.living_room` |
| **State** | Current status of an entity | `on`, `off`, `open`, `closed`, `25°C` |
| **Service** | An action you can call | `light.turn_on`, `cover.open_cover` |
| **Automation** | Rule that triggers actions | "Turn on lights at sunset" |
| **Scene** | Predefined state for multiple entities | "Movie mode" - dim lights, close covers |
| **Script** | Reusable sequence of actions | "Good night" routine |
## When to Use boneIO vs Home Assistant [#when-to-use-boneio-vs-home-assistant]
| Use Case | boneIO Internal | Home Assistant |
| -------------------------------------- | --------------- | -------------- |
| Button toggles light | ✅ | Optional |
| Button controls cover | ✅ | Optional |
| Double-click actions | ✅ | Optional |
| Long-press actions | ✅ | Optional |
| Time-based automation | ❌ | ✅ |
| Sunrise/sunset triggers | ❌ | ✅ |
| Conditional logic (if dark AND motion) | ❌ | ✅ |
| Notifications to phone | ❌ | ✅ |
| Voice control | ❌ | ✅ |
| Energy monitoring dashboards | ❌ | ✅ |
Always configure basic button-to-light/cover actions in boneIO configuration. This ensures they work even if Home Assistant is offline or restarting.
## Next Steps [#next-steps]
1. [Which device to choose?](/en/docs/home-assistant/preparation): what to run Home Assistant on.
2. [Installation](/en/docs/home-assistant/installation): Home Assistant Green or a mini-PC.
3. [First run](/en/docs/home-assistant/first-run): the wizard, from the account to the dashboard.
4. [Connecting boneIO Black](/en/docs/home-assistant/boneio-black) or [boneIO ESP](/en/docs/home-assistant/boneio-esp).
5. [Backups](/en/docs/home-assistant/backups) and [the phone app](/en/docs/home-assistant/remote-access).
6. [First automation](/en/docs/home-assistant/first-automation) and [dashboards](/en/docs/home-assistant/dashboards).
# Installation (/en/docs/home-assistant/installation)
Home Assistant works best as **Home Assistant OS** (HAOS): a small system of its own that does only this and updates itself. Below are the two ways we recommend. Choosing the hardware is covered in [Which device to choose?](/en/docs/home-assistant/preparation).
Home Assistant Green comes with the system already installed. There is nothing to write.
1. Connect the Green to your router with a network cable.
2. Plug in the power supply from the box.
3. Wait a few minutes. The first time, the Green downloads the latest Home Assistant, which can take up to 20 minutes.
4. On a computer or phone on the same network, open `http://homeassistant.local:8123` and go on to the [first run](/en/docs/home-assistant/first-run).
{/* SCREENSHOT: ha_green_connected.webp — photo of a Home Assistant Green with the network cable and power supply plugged in */}
On a mini-PC (for example a Dell Wyse or HP T630 thin client, or a computer with an Intel N100), HAOS is written to the **whole disk**: everything on it is gone. There are two ways; pick one.
### Way 1: the SSD through a USB adapter (simpler) [#way-1-the-ssd-through-a-usb-adapter-simpler]
If the mini-PC's disk can be taken out, write the image onto it from another computer.
1. Download the **Generic x86-64** image from the Home Assistant installation page (`home-assistant.io` → **Getting started** → **Installation** → **Generic x86-64**). It is the file `haos_generic-x86-64-.img.xz`.
2. Take the disk out of the mini-PC and connect it to your computer through a USB adapter (SATA or NVMe, as the disk needs).
3. Install and run **balenaEtcher** (`etcher.balena.io`). Select the downloaded image, then the disk on the adapter, and click **Flash!**. Check twice that the disk on the adapter is selected, not your computer's own disk.
4. Put the disk back into the mini-PC and go on to the [BIOS settings](#bios).
{/* SCREENSHOT: ha_etcher.webp — balenaEtcher with the haos_generic-x86-64 image and the disk on the USB adapter selected, before Flash! */}
### Way 2: an Ubuntu USB stick (the disk stays in the mini-PC) [#way-2-an-ubuntu-usb-stick-the-disk-stays-in-the-mini-pc]
If the disk cannot be taken out, start the mini-PC from an Ubuntu USB stick and write the image to the internal disk from there. You need a USB stick (8 GB or more) and another computer with Windows. The pictures below are of the Polish versions of Rufus and Ubuntu; the buttons are in the same places in English.
**The Ubuntu USB stick**
1. Download Ubuntu Desktop from `ubuntu.com/download/desktop` and Rufus from `rufus.ie`.
2. Run Rufus. Under **Device**, select the USB stick. Everything on it is erased, so make sure it is the right one.
3. Under **Boot selection**, click **SELECT** and choose the downloaded Ubuntu ISO. Click **START**.
4. When asked about an "ISOHybrid image", keep the recommended option and click **OK**, then confirm the data-loss warning.
5. When the bar is full and **READY** shows, close Rufus with **CLOSE**.
**Writing HAOS to the mini-PC's disk**
1. Plug the USB stick into the mini-PC and [set the BIOS](#bios) to start from it.
2. In the Ubuntu menu choose **Try Ubuntu**. Ubuntu then runs from memory only and installs nothing.
3. Connect to the internet (icon in the top right corner), open Firefox and download the **Generic x86-64** image as in way 1.
4. Start the **Disks** app. On the left, select the **mini-PC's internal disk**, not the USB stick.
5. Click the menu (three dots) in the top right corner and choose **Restore Disk Image**.
6. Choose the downloaded HAOS image, click **Start Restoring** and confirm.
7. When it is done, shut Ubuntu down, take the USB stick out and start the mini-PC again.
### BIOS settings [#bios]
1. Switch the mini-PC on and keep pressing the BIOS/UEFI key straight away (usually `F2`, `Del`, `F1` or `F10`).
2. Set:
* **UEFI Boot**: on,
* **Secure Boot**: off (HAOS does not support it),
* **Boot Order**: the disk with HAOS first, or the USB stick if you use way 2 and are only now writing the image.
3. Save (usually `F10`) and restart.
Once HAOS starts from the disk, connect the mini-PC to your router with a network cable. The first time, the system downloads the latest Home Assistant, which takes a few to a dozen or so minutes.
## Opening it for the first time [#opening-it-for-the-first-time]
On a computer or phone on the same network, open one of:
* `http://homeassistant.local:8123`
* `http://homeassistant:8123`
* `http://:8123`, e.g. `http://192.168.1.15:8123` (your router lists the address among the connected devices).
While Home Assistant is getting ready, the page shows a waiting screen. When you see **Welcome!**, go on to the [first run](/en/docs/home-assistant/first-run).
Set up the basic actions (button → light, button → cover) in boneIO, not in Home Assistant. Then they keep working while Home Assistant restarts or is switched off.
# What hardware should i chose? (/en/docs/home-assistant/preparation)
## Which device to install Home Assistant on? [#which-device-to-install-home-assistant-on]
Home Assistant is an open-source system, which gives us incredible freedom – we can install it on almost any hardware, from an old laptop lying in a drawer to dedicated servers. Below, I will introduce you to the most popular options, their pros and cons, so you can make an informed decision.
### 1. Home Assistant Green – Out-of-the-box for everyone [#1-home-assistant-green--out-of-the-box-for-everyone]
This is the official device from the system creators (Nabu Casa). If you don't want to deal with "custom builds" and want a Plug & Play solution, Green is for you.
* *What's inside?* An energy-efficient 4-core ARM processor, 4 GB of RAM, and 32 GB of fast eMMC memory. (MicroSD is used for system recovery).
* *Capabilities:* It has 2 USB ports for connecting dongles (e.g., Zigbee/Z-Wave) and gigabit Ethernet.
* *For whom?* Perfect to start. It will handle a standard home with dozens of sensors and automations. It is silent and consumes next to no power.
### 2. Home Assistant Yellow [#2-home-assistant-yellow]
Yellow is the older but more advanced brother of the Green. This device was designed for users who want absolutely everything in one case, without pendrives and cables sticking out of the back.
* *Integrated radio:* Yellow has a built-in module supporting Zigbee 3.0 and Matter (Thread). You don't have to buy separate USB gateways.
* *Expansion:* What sets it apart is the slot for an NVMe SSD drive. You can forget about memory limitations and enjoy lightning-fast database performance.
* *PoE Power:* Some versions support Power over Ethernet – you can power the server with the same cable you use for the internet.
* *For whom?* For people who want a professional, integrated solution.
### 3. Raspberry Pi – A classic with one flaw [#3-raspberry-pi--a-classic-with-one-flaw]
This is the most popular microcomputer in the world, which most of us started with. Performance-wise (especially model 4 or 5), it beats many dedicated solutions, but it has one "Achilles' heel."
* *SD Card:* Most users install the system on microSD cards. Home Assistant writes data very intensively (logs, databases), which can "wear out" an SD card in a few months, leading to a sudden system failure.
* *Advice:* If you choose the "Pi," be sure to buy a case with SSD support or use a USB-SATA adapter. This will make your system more resistant to potential failures.
### 4. Other hardware – The magic of Open Source [#4-other-hardware--the-magic-of-open-source]
If you have an old terminal at home (e.g., Dell Wyse, HP T630), a laptop with a damaged screen, or a modern NAS server, you can breathe new life into them. Here, you are limited only by your imagination, but it's worth remembering a few golden rules:
* *Appetite grows with eating:* At the beginning, you don't need much. However, when you start adding cameras, face recognition (e.g., Frigate), or advanced multimedia, you will quickly feel the lack of power. It's better to have a slight reserve of RAM (minimum 4GB, recommended 8GB+).
* *Energy consumption (Crucial!):* Remember that this server runs 24/7, 365 days a year. An old PC might consume 50-100W, while a dedicated terminal or MicroPC will settle for 5W. Over a year, the difference in electricity bills can be up to several hundred euro!
* *Reliability and cooling:* Choose solutions that can work under load without overheating. Passive cooling (no fan) is a huge plus – no noise and no dust inside.
* *Component replaceability:* The ability to easily swap the drive for a larger one or add RAM sticks is a huge advantage of x86-type solutions (terminals/PCs) over ARM microcomputers.
### 5. Don't limit yourself to one device! [#5-dont-limit-yourself-to-one-device]
The power of HA is flexibility and freedom of configuration. You don't have to push everything into one machine. You can have the main HA server on an energy-efficient terminal, and a heavy database or video monitoring system on a more powerful server. Such a distribution of load means that if one service fails, the rest of the house (e.g., lights and heating) still works.
### A short conclusion at the end: [#a-short-conclusion-at-the-end]
If you want to start without stress and "right now" - choose Green. If you want hardware that you can modify or want to optimize costs a bit - look for a used x86 terminal or a new micro PC with an Intel N100 processor (or similar).
# App and remote access (/en/docs/home-assistant/remote-access)
## The phone app [#the-phone-app]
The **Home Assistant** app is free on Google Play and the App Store. The first time it finds Home Assistant on your home network by itself, or you enter the address by hand, e.g. `http://homeassistant.local:8123`. Sign in with the same account as in the browser.
The app also reports the phone's data to Home Assistant, such as whether you are at home. That is what automations like "switch everything off when everyone has left" are built on. What the app sends is chosen in its settings.
## Away from home [#away-from-home]
At home, the app connects to Home Assistant directly. Away from home it needs a safe way into the home network. There are two sensible ones:
* **Home Assistant Cloud.** A paid subscription from the makers of Home Assistant: access from outside without setting up your router, plus integration with Alexa and Google Assistant. Turn it on under **Settings** → **Home Assistant Cloud**.
* **Your own VPN.** Many routers have a VPN server (e.g. WireGuard). The phone then joins the home network and the app works as it does at home.
**Do not expose Home Assistant or the boneIO panel to the internet** by forwarding a port on your router. Anyone on the internet could then try to sign in to them. Use Home Assistant Cloud or a VPN.
# Electrical Cabinet and Network Rack (/en/docs/smart-home-guide/cabinet)
In a modern Smart Home installation, the line between "electrical" and "IT" blurs. The electrical cabinet stops being just a fuse box and becomes a command center that must work closely with the network rack.
## 1. Electrical Cabinet (The Heart of boneIO) [#1-electrical-cabinet-the-heart-of-boneio]
This is where all 230V cables, sensor wires, reed switches, and buses converge – this is where we mount the automation (boneIO controllers).
### How to Choose Cabinet Size? [#how-to-choose-cabinet-size]
Choosing the cabinet size is the most common mistake during construction. A Smart Home installation based on star topology and controllers requires significantly more space than a traditional electrical cabinet.
Choosing a cabinet "by eye" always ends with lack of space. You need to perform a simple module calculation (1 module = 17.5 mm):
1. **Count boneIO controllers:**
* **boneIO 32x10A, 24x16A, Cover, CoverMix:** takes **12-15 modules** on DIN rail.
* **boneIO ESP 8x10A, Input24 Gen2** takes **7 modules**.
* **boneIO ESP Dimmer LED:** takes **7 modules**.
2. **Power Supplies and Switch:** DIN rail power supplies (e.g., Mean Well) take 2 to 4 modules. The **automation switch** should also be here to shorten the twisted pair runs from controllers.
3. **Terminal Blocks:** They can consume a lot of space. Assume that one DIN rail row will be entirely dedicated to terminal blocks for incoming cables. To avoid chaos, all cables coming from the house (both 230V and twisted pairs) should first go to **terminal blocks** at the top or bottom of the cabinet. Only from there do we run short connections to controllers and circuit breakers. This ensures aesthetics and easy maintenance.
4. We also can't forget about "twisted pairs" from buttons and sensors. They should also go to an "intermediate point" in the form of popular LSA connectors or so-called reverse patch panels.
For an average house of 120-150 m² with full Smart Home, a cabinet with **144-192 modules** is the absolute minimum to maintain order and proper ventilation.
* **Reserve Rule:** Never choose a cabinet "just right". Assume that after mounting everything you plan, **at least 20-30% of slots should remain free**. Smart systems tend to expand (additional energy meters, extra power supplies).
### Automation Switch (Inside the Cabinet) [#automation-switch-inside-the-cabinet]
We mount a dedicated DIN rail switch in the electrical cabinet.
* **Why here?** All boneIO controllers connect with short patch cables to this switch within one cabinet.
* **Autonomy:** Even if the main router in the network rack fails, boneIO controllers still see each other within this switch, allowing direct bindings to work (e.g., button -> light).
For DHCP connections, set the DHCP server to assign addresses for several hours, so that even a longer router failure won't cause the device to lose its IP address, or use static addressing.
### Key Components [#key-components]
Every Smart Home electrical cabinet should contain:
| Group | Elements |
| :--------------------- | :----------------------------------------------------------------------------------- |
| **Standard Equipment** | Main switch, Phase indicator, Surge protector, RCD and overcurrent circuit breakers. |
| **Smart Section** | **boneIO** controllers (32x10A, CoverMix, Dimmers), 12V/24V DC power supplies. |
| **Energy Metering** | Main energy meter and dedicated meters (e.g., for heat pump). |
| **Organizational** | Distribution blocks, cable ducts, terminal blocks. |
## 2. Network Rack (IT Infrastructure) [#2-network-rack-it-infrastructure]
The stability of the boneIO system depends on your LAN network. Don't rely on the free router from your internet provider – Smart Home requires a more solid foundation.
### The Heart of the Network: Router [#the-heart-of-the-network-router]
A router is not just internet access, it's the "supervisor" directing traffic in your home. What should it feature?
* **VLAN Support:** Must be able to isolate Smart Home devices from your laptops or TVs (security).
* **Stable VPN Server:** So you can securely connect to your home (Home Assistant) from outside without exposing ports to the world.
* **Performance:** Stable operation with a large number of permanent local connections (boneIO, cameras, sensors).
* **Recommendations:** Solutions like MikroTik, Ubiquiti UniFi, or servers based on OPNsense/pfSense.
### Network and Switches [#network-and-switches]
1. **Automation Switch:** A dedicated switch in the control cabinet (described in the electrical cabinet section), to which only boneIO controllers are connected. This makes communication between them (e.g., via ESPHome protocol) autonomous and independent of the rest of the home network.
2. **Main Switch (Managed):** The heart of the network connecting the server, LAN outlets, and APs. It's worth having **PoE** ports (for powering access points). Thanks to PoE, you won't need to run power adapters to every device – just a twisted pair cable.
3. **Monitoring Switch (PoE):** A separate switch for cameras so their high network traffic doesn't burden the main backbone.
4. **Patch Panel:** We can't forget about it - it's where all twisted pairs from rooms terminate, camera connections arrive, or the dedicated cable connecting the electrical cabinet to the network rack. It allows for aesthetic "connection" of outlets to the switch.
### Home Assistant Server [#home-assistant-server]
This is where most logical decisions for your home are made.
* **Hardware:** Mini PC (e.g., Dell Wyse, HP ProDesk, Computer with N100 processor) with x64 processor and SSD drive. This is a much more durable and faster solution than Raspberry Pi with an SD card, which can fail after a few months of intensive writes. An additional advantage is their high energy efficiency, which is crucial for 24/7 operation in a home environment.
If Home Assistant is to support modern features like Voice Assistant and image recognition, consider investing in more modern, faster hardware (or a separate server for image recognition).
## 3. Backup Power (UPS) [#3-backup-power-ups]
Control electronics and servers don't handle sudden power outages well.
* **What to connect to UPS?** The absolute minimum is the network rack (router, switch, HA server).
* **boneIO on UPS:** boneIO controllers are extremely energy-efficient. It's worth powering them from a UPS so the system "sees" events (e.g., flood sensors or window openings) even during power grid failure. This also guarantees that the "brain" of the house won't shut down during a brief power flicker.
* **Integration (NUT):** We recommend choosing a UPS compatible with **Network UPS Tools (NUT)**. This way, the router and Home Assistant will receive information about power failure and can, for example, safely shut down the system or send you a notification on your phone.
**REMEMBER:** The network rack runs at higher temperatures. Ensure proper ventilation (passive or forced) to extend the life of the server and power supplies.
# Electrical Cabinet and Network Rack (/en/docs/smart-home-guide/hvac)
# Introduction - Smart Home Philosophy (/en/docs/smart-home-guide)
Building a smart home is an investment for years to come. In a flood of cheap wireless solutions (Wi-Fi, Zigbee), boneIO documentation promotes the **Wired First** approach. Below you'll find the principles we follow in this project, and an answer to why it's worth spending more time during the construction phase to enjoy peace of mind for decades.
## Why Wired Installation? [#why-wired-installation]
Most problems with Smart Home systems stem from the instability of wireless networks. By choosing a wired installation in a **star topology**, you gain:
* **Reliability:** No radio interference or range issues.
* **Security:** Your data and control don't depend on the manufacturer's cloud or router range.
* **Longevity:** Copper cables in walls will work just as well in 30 or even 50 years.
* **Easy Maintenance:** All control points converge in one place – the electrical cabinet.
## The Role of boneIO in Your Home [#the-role-of-boneio-in-your-home]
boneIO is not just another closed system. It's the **open heart of your installation**, connecting the world of professional automation with the flexibility of Open Source software.
**Our idea:** Create hardware that is as solid as industrial PLC controllers, but at the same time very easy to integrate with the Home Assistant system.
## Good Habits and Error Minimization [#good-habits-and-error-minimization]
This documentation is not a controller manual. It's a **collection of best practices** we've gathered from hundreds of installations. Our goal is to guide you through the construction process so you avoid costly mistakes during design, wiring, and cabinet assembly.
**Remember: Start with the design!** This is the cheapest stage of construction, yet the most important. Every hour spent on the planning sheet now means ten fewer hours with a drill and chisel in the future.
**A well-prepared design is not only your "roadmap" but above all a universal language for communicating with contractors.** Whether you're doing the installation yourself or hiring a "traditional" electrician – clear documentation eliminates guesswork, allows for accurate pricing, and ensures the system is built according to your vision, not the installer's habits.
# Buttons, Sensors and Inputs (/en/docs/smart-home-guide/inputs)
While the relays in boneIO are the "hands" of your home, digital inputs are its "senses". Proper connection of buttons and sensors is key to making your home respond instantly and flawlessly.
## 1. Control Buttons [#1-control-buttons]
In a smart home based on **boneIO**, buttons don't physically interrupt the 230V circuit. They only send a low-voltage signal to the controller, which then executes the programmed action.
* **Button Type:** We recommend using **momentary (bell-press) buttons**.
* **Why?** Thanks to boneIO, one button can handle multiple actions: short click (light), double click (blinds), or long press ("Goodnight" scene – turning everything off in the house).
* **Wiring:** We use **U/FTP Cat. 5e** twisted pair cable. We use one pair of wires per button - one wire as signal to the `IN` input, the other as common ground or + `GND/VCC`. (ground control is recommended as the safer option)
## 2. Presence and Motion Sensors [#2-presence-and-motion-sensors]
These are what make a home truly "smart".
* **Motion Sensor (PIR):** Good practically everywhere. Detects movement in rooms.
* **Presence Sensor (mmWave):** Much more sensitive – can detect a person sitting still on the couch or reading a book. Ideal for living room, office, or bathroom.
* **Connection:** Most sensors require power (usually 12V-24V from the cabinet) and one signal wire returning to a binary input in boneIO.
boneIO will have a presence sensor in the near future.
## 3. Reed Switches (Opening Sensors) [#3-reed-switches-opening-sensors]
These are small magnetic sensors mounted in windows, doors, and locks.
* **Applications:** Alarm, HVAC blocking when window is open, notification about unclosed gate.
* **Important Note (from practice):** Standard reed switches require 2 wires. However, modern window hardware often includes reed switches with **tilt detection** function – such models require a **4-wire** cable.
* **Wiring:** 2x0.5mm wire or a spare pair in twisted cable.
## 4. Communication Buses (CAN and Modbus) [#4-communication-buses-can-and-modbus]
Not everything needs to be connected in a "star". For more advanced sensors (e.g., temperature, humidity, air quality), boneIO offers bus support.
* **CAN Bus:** Works great for connecting many sensors distributed throughout the house with a single cable.
* **How to lay it?** Unlike the star topology, here we run twisted pair **serially** – from sensor to sensor. This saves space in the cabinet and reduces cable usage.
* **Best Practice for Temperature:** We recommend running twisted pair between main temperature measurement points. *If the temperature sensor is to be located under a button, remember that temperature and humidity in a wall box may differ from the central part of the room, so hiding the sensor out of sight is not recommended.*
* **Applications:** Presence sensors, temperature sensors in every room.
## Best Mounting Practices [#best-mounting-practices]
### Box Preparation [#box-preparation]
We recommend using **deep boxes** (or with a side pocket), even if there's no electronics inside. Twisted pair is delicate, and extra space will allow comfortable cable slack placement and prevent kinking.
### Ground (GND) is Fundamental [#ground-gnd-is-fundamental]
With many buttons in one location (e.g., 3-gang frame), you can connect the ground/+ together and use it to "power" individual buttons. This greatly simplifies cabinet wiring.
### Resistance and Interference [#resistance-and-interference]
Because we use shielded twisted pair (FTP) and separate routes from 230V cables (remember the 50cm rule?), we avoid "ghosts" in the system – lights turning on by themselves due to voltage induction in signal cables.
### One Box - One Twisted Pair [#one-box---one-twisted-pair]
You can never have too many wires in a box. It's recommended that when there are 2 boxes in one location, at least 2 twisted pairs should be run to them. This will allow adding sensors in the future.
# External Device Integrations (/en/docs/smart-home-guide/integrations)
## External Device Integration [#external-device-integration]
Although boneIO provides a solid foundation for your wired installation, the true magic happens in the supervision layer, which is performed by Home Assistant. Since it is an Open Source system developed by a global community, it offers the largest integration database on the market.
Often, the user community creates solutions that are better and more functional than those provided by the equipment manufacturers themselves.
### The "Manufacturer's App" Trap [#the-manufacturers-app-trap]
Most modern home devices (robot vacuums, washing machines, coffee makers) tempt with simplicity - you download an app, connect to Wi-Fi, and you're done. However, this solution has several critical drawbacks worth keeping in mind:
* **Fragmentation**: Every new device is another app on your phone. Instead of one Smart Home, you have a "Smart App Collection."
* **Privacy**: Your data ends up in the manufacturer's cloud, and you lose control over it.
* **Internet Dependency**: Problems with the manufacturer's server or a lack of network access mean a lack of control over the device.
* **Subscription Risk**: The manufacturer can introduce fees at any time for features that were previously free.
* **Product Obsolescence**: If the manufacturer goes bankrupt or shuts down their servers, your device becomes "brainless."
### Integration Hierarchy (From Best to Worst) [#integration-hierarchy-from-best-to-worst]
Not every integration is created equal. When planning purchases, it is worth following the division below to ensure your home remains as local and independent as possible.
| Integration Type | Stability | Locality | Description |
| :----------------------- | :-------- | :-------- | :-------------------------------------------------------------------------- |
| **Wired (Modbus/CAN)** | ⭐⭐⭐⭐⭐ | ✅ 100% | The highest standard. Stable cable connection directly to boneIO. |
| **Wireless (ESP Mod)** | ⭐⭐⭐⭐ | ✅ 100% | Replacing factory software with ESPHome/Tasmota. Full control. |
| **Local (Manufacturer)** | ⭐⭐⭐ | ✅ Partial | Uses the manufacturer's API, but communication happens within your network. |
| **Cloud** | ⭐⭐ | ❌ No | Home Assistant talks to the manufacturer's cloud, not the device. |
| **None (App Only)** | ⭐ | ❌ No | Device is "blind" to the Home Assistant system. The worst-case scenario. |
#### 1. Wired Integration (Modbus / CAN) – The Golden Standard [#1-wired-integration-modbus--can--the-golden-standard]
This is the solution where boneIO shines the most. A solid wired connection ensures lightning-fast response times and zero susceptibility to Wi-Fi interference.
* **For ESP series**: Thanks to ESPHome, it is often enough to upload a ready-made configuration prepared by the community.
* **For Black series**: We provide tools for self-configuration of Modbus registers, and our team actively supports users in preparing settings for specific devices.
* **Effect**: Full, two-way communication (status reading and control) takes place entirely inside your home.
**Remember**: Prerequisite - Register List. In order for us to help you prepare an integration for a new device (that is not yet in our database), **you must possess the Modbus register list.** This is technical documentation provided by the device manufacturer (usually a PDF file). Without it, we are unable to identify which data is responsible for specific functions of your device.
#### 2. Controller Modification (ESP32 / ESPHome) [#2-controller-modification-esp32--esphome]
Many manufacturers build their devices based on ESP32 modules. This allows for their "liberation" by flashing your own software (e.g., ESPHome). We then gain local control over Wi-Fi.
**Remember**: Interfering with the factory controller usually voids the warranty, but in return, you receive a device that is 100% yours and independent of external servers.
#### 3. Local Integration via API [#3-local-integration-via-api]
Some devices allow for local control despite having a manufacturer's app. This usually requires creating a cloud account for the initial configuration, but subsequent operation takes place within the LAN.
Tip: Sometimes it pays to be creative – it happens that an integration from one manufacturer allows you to "extract" local control from a device of a completely different brand.
#### 4. Cloud Integration (Cloud-to-Cloud) [#4-cloud-integration-cloud-to-cloud]
The most popular, but also the most temperamental form. Home Assistant connects to the manufacturer's cloud (e.g., through official integrations or HACS).
* **Drawback**: Latency. Data may refresh every few to several seconds, which excludes this solution from fast automations (e.g., turning on a light after detecting motion).
#### 5. Standalone App (No Integration) [#5-standalone-app-no-integration]
Devices that cannot be connected to Home Assistant in any way are "islands." They do not see other sensors and cannot participate in scenes (e.g., turn everything off when leaving the house). Avoid such solutions if you are building a true Smart Home.
# Lighting in Smart Home (/en/docs/smart-home-guide/lighting)
Lighting is the most important element in building the mood and functionality of a home. In a **boneIO**-based system, you have complete freedom – you can combine classic bulbs, modern 24V dimmable systems, and impressive addressable strips.
## 1. 230V AC Lighting (Standard) [#1-230v-ac-lighting-standard]
This is the most universal approach, using traditional bulbs and fixtures.
* **Advantages:** Huge selection of fixtures (ceiling lights, chandeliers, spots), low light source costs, simple installation.
* **Control:** Works on an **On/Off** basis using relays.
* **Dedicated hardware:**
* **boneIO 32x10A:** A true "workhorse" – one controller handles up to 32 independent lighting circuits throughout the house.
* **boneIO 8x10A / CoverMix:** Ideal for smaller zones or when you need to distribute controllers in different parts of the cabinet.
**Tip:** If you want to dim 230V bulbs, remember that standard relays can't do this. In that case, consider switching to a 24V DC system or external dimming modules.
## 2. 24V DC Lighting (Dimmable and Colored) [#2-24v-dc-lighting-dimmable-and-colored]
If you want smooth brightness control or to change the color temperature of light (warm/cool), the 24V system is the best choice.
* **Advantages:** Smooth dimming without flickering, safe low voltage, ability to use RGB/RGBW strips and modern 24V LED bulbs.
* **Applications:** Mood lighting in the living room, countertop backlighting in the kitchen, gentle "night" lighting in hallways and bathrooms.
* **Dedicated hardware:**
* **boneIO Dimmer LED gen2:** Supports up to **8 independent channels**. You can connect 8 single-color strips or, for example, 2 RGBW strips.
## 3. Addressable LEDs (Pixel LED) [#3-addressable-leds-pixel-led]
This is a solution for the most demanding users, where each diode on the strip can light up differently.
* **Advantages:** Amazing visual effects (flowing light), ability to create light notifications (e.g., kitchen strip pulsing red when the gate is open).
* **Applications:** Staircase lighting, ceiling coves, home theaters.
* **Integration:** A controller for this type of lighting is currently in the design phase.
## Summary – Which Lighting to Choose? [#summary--which-lighting-to-choose]
| Feature | 230V AC Lighting | 24V DC Lighting | Addressable LED |
| :-------------------- | :--------------------- | :---------------------------------- | :------------------------ |
| **Main function** | Main lighting (ON/OFF) | Mood and dimming | Effects and notifications |
| **Fixture selection** | Very large | Medium (mainly strips/spots) | LED strips |
| **Costs** | Low | Medium (requires DC power supplies) | Higher |
| **boneIO controller** | Relay series (32x, 8x) | Dimmer LED gen2 | In design phase |
## Best Practices for Lighting [#best-practices-for-lighting]
1. **Mix systems:** The best results come from combining strong main lighting (230V) with gentle accent and mood lighting (24V).
2. **DC Power Supplies:** For 24V systems, choose high-quality power supplies (e.g., HDR or LRS series from Mean Well) and mount them in the cabinet next to boneIO Dimmer controllers.
3. **Loop Rule:** For long 24V LED strips, supply power from both ends of the strip to avoid brightness drops.
# Electrical Installation Planner (/en/docs/smart-home-guide/planner)
# Electrical Installation Planner [#electrical-installation-planner]
The planner is available as a standalone tool:
**[Open Electrical Planner →](/en/electrical-planner)**
The interactive planner helps you plan every circuit of your home electrical installation **before** construction begins. Below you'll find a guide on how the tool works.
## How automatic IDs work [#how-automatic-ids-work]
Every circuit receives a unique identifier in the format:
```
TYPE/FLOOR/NR
```
For example, `OSW/0/05` means:
* **OSW** — circuit type (Interior Lighting)
* **0** — floor code (Ground floor)
* **05** — circuit number within the room
The number is auto-assigned based on the **number range** configured for the room.
## Floors [#floors]
Default floors:
| Code | Name |
| ---- | ------------ |
| `0` | Ground floor |
| `1` | First floor |
| `Z` | Exterior |
You can add and remove floors in the **Legend** tab.
## Rooms [#rooms]
Each room has an assigned **number range**, e.g. Living room = 0–4, Kitchen = 10–19. These numbers form the third part of the circuit ID.
When a range is exhausted (e.g. you add more than 10 circuits in one room), the planner will automatically assign the next available number above the range.
Default rooms can be freely edited in the **Legend** tab — add, remove, and adjust number ranges.
## Cabinets / Distribution boards [#cabinets--distribution-boards]
In larger installations, you may have multiple distribution boards or rack cabinets. The planner allows you to:
* Define a list of cabinets in **Legend** → **Cabinets / Distribution boards**
* Assign each circuit to a specific cabinet via the **Cabinet** column
* View statistics by cabinet in the **Summary** tab
By default, one cabinet is available: "Szafa 1".
## Circuit types [#circuit-types]
Each circuit type has:
* **Abbreviation** (e.g. `OSW`, `GNW`, `PRW`) — used in the ID
* **Default cable** — auto-filled when selecting the type
* **Default I/O** — input, output, or I/O
* **Color** — for visual distinction
Example types:
| Abbr | Name | Default cable |
| ---- | ----------------- | ------------- |
| OSW | Interior Lighting | 3x1,5 |
| GNW | Interior Socket | 3x2,5 |
| PRW | Interior Switch | Cat 5e |
| ROL | Roller shutter | 5x1,5 |
| LAN | LAN Network | Cat 6 |
## Export & Import [#export--import]
* **CSV** — export the circuit table for spreadsheets (`;` separator)
* **JSON** — export/import the full planner state (circuits + legend)
The JSON format contains a complete backup: floors, rooms, cabinets, circuit types, cable types, and all circuits. Perfect for backups or transferring your configuration between devices.
## Auto-save [#auto-save]
Data is saved automatically in your browser's `localStorage`. It is never sent to any server.
Clearing browser data will erase your saved plan. Use
**Export JSON**
to create a backup.
# Needs Analysis and Planning (/en/docs/smart-home-guide/planning)
Before you start buying cables and controllers, you need to answer one key question: **What exactly should my home do?**
Designing a Smart Home installation is not just about convenience, but above all about anticipating events. We divide this process into three stages: the obvious, what you'll discover over time, and what will allow you to actually save money.
## 1. Fundamentals (What you think about from the start) [#1-fundamentals-what-you-think-about-from-the-start]
This is the base that boneIO handles "out of the box". We focus here on comfort and safety:
* **Lighting (ON/OFF):** Every light point you want to control must go to the electrical cabinet. **boneIO 32x10A** or **8x10A** works perfectly here.
* **Mood Lighting (Dimmable LED):** If you're planning dimming or LED strips, plan space for **boneIO dimmer LED**.
* **Window Coverings:** Roller blinds, facade blinds, and awnings. Controllers from the **Cover, CoverMix** series allow precise positioning.
* **Property Access:** Garage door, driveway gate, and garden gate (with notification option when left open).
## 2. Higher Level (What's worth thinking about now) [#2-higher-level-whats-worth-thinking-about-now]
Smart Home spreads its wings where automation takes over repetitive tasks or manages your budget - it works so you don't have to:
* **Climate Management:** Integration with heat recovery ventilation, heat pump, and underfloor heating control (each loop can be controlled separately via boneIO relays).
* **Presence and Motion Sensors:** These make the light "follow you". When planning wiring, don't forget about ceilings in hallways and bathrooms.
* **Failure Protection:** Flood sensors in strategic locations (washing machine, dishwasher) connected to a solenoid valve that will cut off water to the entire house.
* **Passive Security:** Reed switches in windows and doors. Thanks to them, the house "knows" whether it can arm the alarm or turn off heating in a room with an open window.
## 3. Non-obvious Scenarios (Small things, big difference) [#3-non-obvious-scenarios-small-things-big-difference]
We often don't realize the possibilities until we use them. Here are some "gems" worth including in your design:
* **Smart Mailbox:** Notification of new mail straight to your phone.
* **Lock Status Control:** Did you really lock the door before going to sleep?
* **Energy Monitoring:** Not just for the whole house, but for specific power-hungry devices.
* **Light Signals:** Using addressable LEDs for notifications (e.g., pulsing red when the gate has been open too long).
**Critical about Smart Home:** Many solutions we have in our homes turn out to be unnecessary. Our task is to help you filter out those that are "gadgets for
a week" from those that actually improve your quality of life.
## Additional Flexibility (Wireless Integration) [#additional-flexibility-wireless-integration]
Although the core of the system must be wired, it's worth considering using e.g., **Zigbee/Z-Wave** for mobile and non-critical elements, such as portable scene remotes, small humidity sensors in closets, or simple bulbs (when power is always on), to maintain flexibility without compromising the reliability of the main boneIO installation.
## Tool: Project Worksheet [#tool-project-worksheet]
Don't keep the project in your head. To make your work easier, we've prepared a dedicated installation worksheet. Mark on it:
1. All light points.
2. Location of buttons and sensors.
3. Description of each cable (from – to – purpose).
👉 **[Open the Electrical Installation Planner →](./planner)** — our interactive tool for planning every circuit in your home.
# Wiring and Infrastructure (/en/docs/smart-home-guide/wiring)
The way you lay cables during the shell construction phase will determine your home's capabilities for decades to come. In a **boneIO**-based installation, we use a **star topology**. Although it requires more cable than a traditional installation, it's actually simpler to execute and offers incomparably greater flexibility.
## What exactly is a "star" installation? [#what-exactly-is-a-star-installation]
In a traditional electrical installation, cables are run from box to box, creating chains. In the boneIO smart home, we use a star layout. This means that every single point – every button, every roller blind, every lighting circuit – has its own independent cable that runs directly to the central distribution board (the heart of the system).
**Why is it important?**
* **Full flexibility (Software over Hardware)**: What is a light switch today can become a roller blind button or a "Goodnight" scene trigger tomorrow. Changing the function doesn't require tearing down walls – it is done by changing the configuration in the controller.
* **Easy diagnostics**: Each cable can be checked directly in the distribution board. If one cable is damaged, the rest of the house operates without disruption.
* **Scalability**: The distribution board becomes the connection point for all the building's intelligence. Thanks to this, you can easily replace the controller with a newer model in the future without changing the wiring.
## Golden Rules for Installation Layout [#golden-rules-for-installation-layout]
### 1. Route Separation and Interference Elimination [#1-route-separation-and-interference-elimination]
To avoid interference in control signals, it's crucial to physically separate power cables from control cables.
* **The 50 cm Rule:** Try to maintain at least 50 cm distance between parallel runs of high-voltage cables (230V AC) and signal cables (twisted pairs, buses).
* **Right-Angle Crossing:** If a control route must cross a power route, always do so at a **right angle (90°)**. Avoid running signal cables parallel at close distances.
* **Dedicated Cable Trays:** We recommend creating two independent cable routes:
* **AC Route:** For outlet power, lighting, and high-power devices.
* **Control Route:** For buttons, sensors, buses (CAN/Modbus), and LAN network.
### 2. Planning Cabinet Entry [#2-planning-cabinet-entry]
The point where cables converge into the control cabinet is the most critical spot.
* **Side Division:** Plan routes so that **low-voltage signals (DC/twisted pairs) enter the cabinet from one side (e.g., from the top left), and high-voltage cables (AC 230V) from the other.** This will prevent cable tangles inside the cabinet and make boneIO controller installation easier.
* **Cable Slack:** Always leave a minimum of **1.5 - 2 meters of slack** for cable coming out of the wall. This allows for aesthetic cable routing in cable ducts and easy termination on terminal blocks. **This slack should be placed inside the cabinet or dedicated ducts. It absolutely must not be stuffed into the wall.**
## Wire Selection – Quality Matters [#wire-selection--quality-matters]
Saving on cables is the worst decision you can make during construction. The cost of wire relative to the entire investment is small, and replacing it after plastering is impossible.
**NEVER USE CCA CABLES!**
CCA (Copper-Clad Aluminium) cables are aluminum cables only copper-plated on the outside. They're brittle, have worse conductivity, and oxidize at connections over time. Choose only 100% Cu (copper) cables from reputable manufacturers.
### Control and Telecommunications Cables (Star) [#control-and-telecommunications-cables-star]
All control cables are run in a **star topology** – from each point (button, sensor) directly to the electrical cabinet.
| Cable Type | Application | Notes |
| :--------------------------- | :----------------------------- | :-------------------------------------------------------------------------------------- |
| **Cat. 5e FTP Twisted Pair** | Buttons, motion sensors, buses | Shielded and copper. Standard for boneIO digital inputs. |
| **Cat. 6A / 7 Twisted Pair** | LAN network, AP, HA Server | Higher category for reliable network communication and POE cameras. |
| **2x0.5mm Wire** | Window reed switches | Easy to install. Note: reed switches with tilt function require **4 wires**. |
| **Twisted Pair (serial)** | Sensor buses | Between temperature sensors, it's worth running twisted pair in series for the CAN bus. |
### Power Cables (Loads) [#power-cables-loads]
The star principle also applies here: every point you want to control independently must have its own cable running to the electrical cabinet.
* **AC Lighting (230V):** According to standards, we use minimum **3x1.5mm²** cable. Each light point (or group) is run separately to the cabinet.
* **Roller Blinds and Shutters:** Usually a 4-wire cable (L-up, L-down, N, PE), going directly to **boneIO Cover, Cover Mix** controllers.
* **Controlled Outlets:** If you want to measure energy consumption or remotely switch off an outlet (e.g., iron), run a separate **3x2.5mm²** cable directly from the cabinet.
### DC Lighting Specifics (12V / 24V) [#dc-lighting-specifics-12v--24v]
With **boneIO Dimmer LED** controllers, we need to account for voltage drops:
* **Cross-section:** For powerful LED strips or long runs, we recommend **2.5mm²** cable. In many standard cases, **3x1.5mm²** will be sufficient. So if you change concepts at some stage (switching from AC to DC lighting) - **3x1.5mm²** cable will handle it.
* **Solid vs Stranded:** For running through walls, we use solid wire (**YDYp**). However, for connecting the LED strip in the profile, use **stranded wire** – it's flexible and won't damage the strip's solder pads.
### Bus - Serial Communication. [#bus---serial-communication]
**What is a bus and how is it connected?** While most elements are connected in a "star," some devices (e.g., presence sensors or temperature and humidity sensors) communicate via a **bus**.
Unlike a star, a bus is a shared communication line to which devices "attach" one after another. It can be compared to a road where data goes from device to device.
**Why is twisted pair key for the bus?**
When connecting a bus (e.g., CAN or RS485), it is essential to use one pair of wires twisted together (e.g., orange and white-orange from a computer network cable).
**Why must it be a twisted pair?** The bus transmits data using a differential signal. When wires are tightly wrapped around each other (twisted), any external electromagnetic interference affects both wires in the same way. This allows the receiver at the end of the line to easily "cancel out" these interferences and read a clean signal.
**Why won't two regular wires work?** If you use two wires that are not twisted together (e.g., individual single strands run loosely), they will start acting like an antenna. They will pick up noise from the 230V installation, motors, or power supplies. Without twisting, the interference will be so significant that communication will be interrupted, and devices will stop "seeing" each other or start throwing errors.
**How to connect in practice?**
* **Serial (Daisy-Chain)**: The only **correct** way. The cable enters the first device, exits it, and goes to the next. We create one continuous line (chain).
In boneIO systems, we take a practical approach – we run the twisted pair from the distribution board to several points (e.g., temperature sensors) in a loop or a single run, which saves space in cable trays while maintaining signal stability.
**Bus Grounding?**
We always ground the bus from **one side only**. You should not connect the grounding to the home's PE (Protective Earth) in multiple places. It is best to connect the grounding directly to the MET – Main Earthing Terminal. **How to maintain grounding continuity?** It is extremely simple: remember to maintain at each device. How to achieve this? By twisting, soldering, and protecting the ground wire.
**Advantages of the bus**:
* **Wiring savings**: Instead of pulling 10 cables to 10 temperature sensors, we pull one wire that "visits" them all.
* **Standards**: boneIO supports, among others, the CAN bus and RS485 (Modbus), allowing integration with thousands of industrial devices, energy meters, or heat pumps.
# Electrical and Hardware Concepts (/en/docs/basic-concepts/electrical-and-hardware)
## Electrical and Hardware Concepts [#electrical-and-hardware-concepts]
### Relay [#relay]
A remotely controlled, electromechanical switch. Its job is to physically open and close an electrical circuit (e.g., turn a 230V light on and off) in response to a low-voltage control signal from the controller's processor. It's the heart of every output (OUT) on a boneIO device.
### Digital Input [#digital-input]
The "sense" of the controller. A port (e.g., IN01) where you connect a wall switch or a sensor. It registers two states: low (no signal) and high (signal present), informing the processor that a button has been pressed.
### Ground-controlled (GND) [#ground-controlled-gnd]
This is the most common and recommended method for controlling digital inputs on boneIO devices. Activating an input (e.g., by pressing a button) involves **connecting the input pin (IN) to the power supply's ground (GND)**. The device's processor detects this drop in potential as an active signal. This method is very safe and resistant to electrical interference.
### Plus-controlled (+VCC) [#plus-controlled-vcc]
An alternative control method. In this case, activating an input involves **applying the positive supply voltage** (e.g., +12V or +24V, depending on the power supply model) **to the input pin (IN)**. The input is active when a high-potential current flows through it.
### Momentary Switch (Bell-Press) [#momentary-switch-bell-press]
A push-button that returns to its original position after being pressed (like a doorbell). **This is the recommended type of switch for use with boneIO** because it allows the software to recognize single-clicks, double-clicks, and long-presses.
### Bistable Switch (Latching/Toggle) [#bistable-switch-latchingtoggle]
A traditional ON/OFF light switch that has two stable positions. Using it with boneIO is possible but limits its functionality to a simple on/off action.
### Star Topology [#star-topology]
A wiring method where each point (lamp, switch) is connected by a separate cable directly to a central location—the electrical cabinet where the controller is located. This is required for boneIO to function correctly.
### Bus Topology [#bus-topology]
A wiring method where devices (e.g., for Modbus communication) are connected sequentially in a daisy-chain fashion, from one device to the next, using a single continuous cable.
### DIN Rail [#din-rail]
A standardized metal mounting rail used in electrical cabinets worldwide. All main boneIO modules are designed to be mounted on a DIN rail.
# Network and Communication Concepts (/en/docs/basic-concepts/network-and-communication)
## Network and Communication Concepts [#network-and-communication-concepts]
### Web Interface [#web-interface]
A website built into the boneIO controller, accessible via a web browser by entering the device's IP address. It allows for basic configuration and control without needing to install any additional systems.
### IP Address [#ip-address]
A unique number that identifies a device on a computer network (e.g., `192.168.1.55`). It is necessary to access the controller's web interface.
### Modbus RTU [#modbus-rtu]
A communication protocol often used in industrial and building automation to communicate with devices such as heat recovery ventilators (HRVs), heat pumps, or energy meters.
# Software and Automation Concepts (/en/docs/basic-concepts/software-and-automation)
## Software and Automation Concepts [#software-and-automation-concepts]
### Home Assistant (HA) [#home-assistant-ha]
A free and open-source platform for creating a smart home system. It acts as the "brain" of the entire operation, connecting devices from different manufacturers, including boneIO, and allowing you to create advanced rules and automations.
### Integration [#integration]
The process of connecting two different systems or devices so they can work together. In our case, this most often refers to connecting a boneIO controller to the Home Assistant platform.
### Entity [#entity]
A basic "object" in Home Assistant that represents a single device, sensor, or piece of information. For example, a lamp connected to output OUT01 will appear in HA as a `light.living_room_lamp` entity, which you can control.
### Automation [#automation]
A set of rules that execute automatically when specific conditions are met. A simple example: **IF** the sun has set **AND** the motion sensor detects motion, **THEN** turn on the hallway light.
### Scene [#scene]
A saved state of one or more entities. Unlike an automation, a scene has no trigger—it simply sets devices to a predefined state. Example: A "Movie Night" scene might set the main light to 20% brightness and the LED strip to blue.
# boneIO Black vs ESP (/en/docs/introduction/comparison)
# boneIO Black vs ESP [#boneio-black-vs-esp]
Wondering which controller version to choose? boneIO Black? ESP? Or maybe both? The following comparison focuses on showing the key differences between the controllers, as well as highlighting the strongest points of each series.
## Introduction [#introduction]
Both versions of boneIO controllers are independent home automation platforms that can operate completely autonomously – without the need for a Home Assistant server connection. Although they have different architectures and capabilities, their purpose is very similar. Below is a detailed comparison of their capabilities.
## Comparison Table [#comparison-table]
| Feature | boneIO Black | boneIO ESP |
| :-------------------------------- | :------------------------------------------------- | :------------------------------------------------------- |
| **Software base** | Dedicated - modified Debian 13 system (Linux) | Compiled program from ESPHome |
| **Configuration method** | Graphical Interface (Web UI / PWA) | Text editor (YAML files) |
| **Boot speed** | Slower (loading Debian OS) | Instant |
| **Network and connectivity** | Ethernet | Ethernet and WiFi\* |
| **Width on DIN rail** | 15 DIN modules | 12 DIN modules |
| **Number of physical inputs** | 49 inputs | 35 inputs |
| **Application in HA** | Yes (configuration, management, and backups) | Yes (ESPHome Device Builder) |
| **Modbus** | Significantly more devices, predefined in code\*\* | Fewer devices, but ability to manually add your own YAML |
| **Additional logic environments** | Built-in Node-Red, Mosquitto | None |
| **Schedules and sun events** | Built in, set in the panel, with run history | In YAML (`time`, `sun`), recompile after each change |
| **Presence simulation** | Built-in wizard | No ready-made feature |
| **Alarm, irrigation, thermostat** | Ready-made, configured in the panel | ESPHome components, written in YAML |
| **Applying a change** | Seconds, nothing to compile | Compile and upload the firmware |
| **Accounts and security** | Admin and read-only accounts, HTTPS, Security page | Web server password, API encryption key |
| **Updates** | boneIO, Debian and kernel from the panel | Firmware over the air from ESPHome Device Builder |
| **Loxone** | Lox UDP (experimental) | Through custom components available online |
*\* Using a WiFi connection in a closed metal distribution board or electrical cabinet is not recommended due to strong signal attenuation.*\
*\*\* The device is equipped with an application that allows for preparing your own Modbus configurations. After preparing the configuration, adding it to the software should not take more than 48 business hours.*
***
## Architecture and Software [#architecture-and-software]
* **System and compilation:** **boneIO Black** is based on a specially prepared Linux distribution (Debian 13) – which has been additionally modified by us. Unnecessary elements were removed, leaving a lightweight, coherent core and essential packages – ensuring incredible stability. Using the Debian system translates into vast capabilities, at the cost of a noticeably longer device boot time from the moment power is applied (a fully advanced operating system must load: inputs and outputs work after about a minute, the panel shortly after).
The **boneIO ESP** version relies on uploading firmware from ESPHome. Its compilation and flashing (uploading to the microprocessor) on a computer is somewhat time-consuming, but this pays off with nearly instant device startup! After a power restart, the controller is ready for immediate action almost instantly (about 5 seconds).
* **Open Source:** The **ESP** solution on the logic side is based on an Open Source project – **ESPHome**, backed by a massive community. What is extremely important from a potential user's perspective, all original boneIO software managing the **boneIO Black** model, built on the Linux system architecture (as well as our operating system itself), also remains 100% free and fully Open Source software!
* **Independence from Home Assistant:** Both controllers are fully intelligent and autonomous, capable of executing rules set on them locally without the requirement of maintaining a connection to the Home Assistant server.
## Configuration and Management [#configuration-and-management]
* **User Interface:** All configuration and management of the **boneIO Black** series takes place through an extensive and extremely intuitive **graphical interface**. Additionally, the application managing boneIO Black supports the PWA standard, which means you can easily pin the controller interface as a native application to your smartphone's home screen for easy access. Interacting with the controller is very simple and straightforward. On the other hand, the **ESP** platform is based on YAML code syntax; although this can be more complicated for a layman, in large and complex installations, it allows ESP to implement ready-made logic templates and repeatable entities of various types much more simply and flexibly.
* **Management via HA:** The **boneIO Black** platform has its own, officially prepared **Application** within the Home Assistant ecosystem, which allows for easy controller management. It brings our proprietary application inside HA. From within it, you can also **create backups of the controller** – without this Application, the user must manually take care of downloading and storing backups. For the **ESP** platform, the configuration is always stored on the ESPHome Device Builder server, so it is important to regularly back up that application.
* **Multiclick Function:** Due to higher performance and design differences, multiclick functions react and work noticeably faster in the **boneIO Black** model. Additionally, it offers sequences as well as a much easier configuration process.
* **Output grouping:** **boneIO Black** natively supports grouping outputs into light and switch groups, which are immediately visible as separate entities in Home Assistant. This allows easy control of, for example, an entire group of lights in a room with a single button. The **ESP** platform does not support output grouping within the device – this kind of logic must be handled on the Home Assistant side.
## Ready out of the box, without programming [#ready-out-of-the-box-without-programming]
What would be a YAML project on ESP is a form in the **boneIO Black** panel — saved in seconds, with nothing to compile or upload:
* **Schedules and the sun** — actions at a clock time or at sunrise, sunset and the twilights, with an offset, a random spread, conditions and earliest/latest bounds. Each schedule shows its next run and its history, and appears in Home Assistant as a switch. See [Schedules](/en/docs/black/current/configuration/schedule).
* **Presence simulation** — answer four questions and an empty house looks lived in: in the evening the lights go on room by room. See [Presence simulation](/en/docs/black/current/configuration/presence_simulation).
* **Virtual switches** — modes such as *Away* or *Evening* that other actions depend on, with no relay behind them.
* **Alarm, irrigation, thermostat, energy counters** — ready-made functions configured in the panel.
* **Secure from the first start** — the panel over HTTPS, accounts with an administrator and a read-only role, no default passwords, and a Security page that says what is still worth fixing. 1.6 is our work of adapting boneIO Black towards the EU Cyber Resilience Act (CRA).
* **Looks after itself** — boneIO, Debian and the kernel update from the panel; backups, a diagnostics bundle you can send us, and a recovery mode when a configuration does not load.
## Communication and Ecosystem [#communication-and-ecosystem]
* **Control between devices:** As a kind of central controller, the **boneIO Black** model can control other boneIO Black series controllers by sending them notifications via the MQTT broker, as well as control other modules from the ESP world by communicating with them directly through the native, local ESPHome API interface. Furthermore, it can also natively control devices dedicated to controlling addressable LED strips with WLED software (effectively allowing, for example, a "single click" of a wall button to be assigned to an instant scene initiation action from the WLED controller). Meanwhile, simple and single-task-focused controllers from the ESP family can freely communicate with each other thanks to UDP. ESP series devices cannot issue control commands to boneIO Black controllers.
* **Built-in Node-Red:** The **boneIO Black** system comes equipped with Node-Red as standard, providing a visual, full-featured, powerful tool that enables the creation of extremely complex automations within the controller itself. It is extremely useful in situations where we want to make part of the automation independent of HA. It can also be an alternative approach for the installer, making a large part of the system independent of "higher" control layers.
* **Network Connections:** boneIO Black series devices communicate exclusively via a wired Ethernet port. ESP optionally allows for WiFi connectivity. However, due to the conditions in metal electrical distribution boards, it is used very rarely.
## Modbus and Hardware Dimensions [#modbus-and-hardware-dimensions]
* **Case size:** Due to a much more powerful SOC, as well as a larger number of inputs in **boneIO Black** models, they take up slightly more space in the distribution board – 15 DIN standard poles. For those with less space, the ESP model taking up 12 DIN may prove to be a better choice.
* **Signal connectors (IO Peripherals):** Naturally, the case size translates into a larger number of available digital inputs. boneIO Black allows for connecting up to 49 of them, whereas in the case of the ESP model, we are talking about 35 inputs.
* **Modbus RS485 bus performance:** **boneIO Black** is able to handle a larger number of devices with a higher polling frequency. Thanks to the processor's multithreading, it is able to maintain high performance of other functions while polling Modbus devices.
***
## Hybrid Installations – unlock the potential! [#hybrid-installations--unlock-the-potential]
When creating the architecture of a modern smart home, it is worth considering a **hybrid** model. Creating a hybrid installation is the most optimal solution in terms of reliability and resource balance:
* Core – managing the smart home system, lights, and buttons should be moved towards the more efficient and versatile **boneIO Black** model.
* The remaining parts of the system, e.g., reading states from motion sensors, reed switches, motor control – moving gates, window shutters, garden sprinklers – are worth moving to the **ESP** platform.
# Hardware Installation (/en/docs/introduction/din-rail-mounting)
## DIN Rail Mounting [#din-rail-mounting]
The boneIO ESP controller is designed for mounting on a standard DIN rail (TS35).
1. Hook the upper clips of the enclosure onto the top edge of the DIN rail.
2. Press the lower part of the enclosure firmly until the latches lock onto the rail with a distinct click.
3. Ensure the module is securely mounted.
# System and Installation Requirements (/en/docs/introduction/requirements)
Before you proceed with the installation, please review the list of requirements below. This will ensure a smooth setup process for your boneIO controller and allow you to use all of its features. Most importantly, **remember that your controller works immediately after connecting the power, even without a network connection!**
## 1. Electrical Requirements [#1-electrical-requirements]
This is the most critical section, essential for the safety and proper operation of the device.
* **Power Supply:** A stabilized DC voltage of 12V (Dimmer only) or 24V DC (check the exact value in your model's specification). The power supply should have sufficient current capacity.
* **Mounting Location:** A dry space, protected from moisture, most commonly a DIN rail within an electrical cabinet (distribution board).
### Wiring Topology [#wiring-topology]
A correct wiring layout is the foundation of a stable system.
* **Power Installation (230V/110V):** The power circuits for loads (e.g., lighting, controlled outlets) must be laid out in a **star topology**. This means each circuit is run as a separate cable directly from the electrical cabinet to the endpoint.
* **Input Installation (Switches/Sensors):** The signal cables for the inputs must also be laid out in a **star topology**. Each switch or sensor should be connected with a separate cable back to the electrical cabinet.
* **Recommended Cable for Inputs:** We recommend using **twisted-pair cable (e.g., Cat 5e or Cat 6)** to connect your switches and sensors. The controller's inputs operate on safe, low voltage.
* **Modbus RTU Installation:** If you plan to connect devices via Modbus, the wiring for this connection must be laid out in a **bus topology (daisy-chain)**.
* **Separation from Power Cables (Avoiding Interference):** To ensure error-free communication and system stability, strictly avoid running signal wires (Modbus, buttons, sensors) parallel to 230V power cables.
* Maintain a minimum distance of 30 cm when running them in parallel.
* If the cable paths must cross, do so only at a right angle (90°).
### Recommended Switches (Push-Buttons) [#recommended-switches-push-buttons]
For controlling lights and other functions, **we strongly recommend using momentary (monostable or bell-press) switches**.
**Why?** Only this type of switch allows you to take full advantage of the boneIO software's capabilities and enables **multi-click functionality**. The controller can then differentiate between various types of presses, which opens the door to advanced automations:
* **Single-click:** Standard on/off for a light.
* **Double-click:** Trigger a lighting scene, e.g., "movie mode" (30% brightness).
* **Long-press:** Smoothly dim the light up or down (for Dimmer modules) or trigger any other custom automation.
Using traditional bistable (latching ON/OFF) switches is technically possible, but it limits control to the basic on/off function and makes multi-click actions completely impossible.
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> In accordance with applicable regulations and to ensure complete safety, all activities related to the electrical installation **must be performed exclusively by a qualified electrician holding the appropriate certifications**.
# Safety and Installation Requirements (/en/docs/introduction/safety-edge)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
# Safety and Installation Requirements (/en/docs/introduction/safety)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
# Hardware Installation (/en/docs/products/hw-guide-comm-1-wire)
### 1-Wire Bus [#1-wire-bus]
Popular for connecting temperature sensors (e.g., DS18B20).
* Connect the `DATA` line to the `1-Wire` terminal.
* Also, connect `VCC` and `GND` power.
The maximum length of the bus cable is 20m.
# Hardware Installation (/en/docs/products/hw-guide-comm-can)
### CAN [#can]
Used for communication with industrial HVAC devices and sensors.
* Connect the `L` line of the bus to the `L` terminal on the boneIO.
* Connect the `H` line of the bus to the `H` terminal on the boneIO.
# Hardware Installation (/en/docs/products/hw-guide-comm-i2c)
### I2C Bus [#i2c-bus]
For connecting additional sensors and expanders over short distances.
* Connect the `SDA` line to the `SDA` terminal.
* Connect the `SCL` line to the `SCL` terminal.
* Also, connect the `VCC` and `GND` power for the sensor.
# Hardware Installation (/en/docs/products/hw-guide-comm-modbus-esp)
### Modbus RS485 [#modbus-rs485]
Used for communication with industrial and HVAC devices.
* Connect the `A` line of the bus to the `A` terminal on the boneIO.
* Connect the `B` line of the bus to the `B` terminal on the boneIO.
> ESP series devices have undergone Modbus RTU bus testing with 5 connected devices. Using a larger number of Modbus devices connected to an ESP series controller may cause delays in the controller's response (both inputs and outputs). This is due to the specifics of the processor used. In the case of extensive Modbus buses, we recommend splitting them across several devices.
# Hardware Installation (/en/docs/products/hw-guide-comm-modbus)
### Modbus RS485 [#modbus-rs485]
Used for communication with industrial and HVAC devices.
* Connect the `A` line of the bus to the `A` terminal on the boneIO.
* Connect the `B` line of the bus to the `B` terminal on the boneIO.
# Hardware Installation (/en/docs/products/hw-guide-inputs)
## Connecting Digital Inputs [#connecting-digital-inputs]
Digital inputs are used to connect buttons and sensors. To change the potential used to control the inputs, use the switch on the casing marked `INPUTS`. By default, the inputs are controlled by ground (GND).
> **IMPORTANT: If you want to change the position of the switch - make sure you do it while the device is turned off!**
1. Connect one of the wires from a momentary switch to the common `GND` (ground) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will short the input to ground, which will be interpreted as an "on" signal.
### Logical diagram of connecting digital input [#logical-diagram-of-connecting-digital-input]
# System and Installation Requirements (/en/docs/products/hw-guide-lan)
## Connect Ethernet [#connect-ethernet]
The device communicates with the network using a built-in Ethernet port, which guarantees a stable and reliable connection. To establish connectivity, connect the module to your network switch using a standard Ethernet (RJ45) cable.
1. Connect ethernet cable to LAN port on your controller.
2. Connect other side of ethernet cable to your network switch.
# Connecting outputs (/en/docs/products/hw-guide-outputs-24)
## Connecting Relay Outputs (16A) [#connecting-relay-outputs-16a]
The key feature of the 24x16A model is that **each of the 24 relays has its own, galvanically isolated `COM` terminal**. This provides tremendous flexibility and allows for controlling circuits powered from different phases or protected by different residual-current devices (RCDs).
### Protection and Correct Wiring Order [#protection-and-correct-wiring-order]
**It is critical that all overcurrent protection (Miniature Circuit Breakers, MCBs) and residual-current devices (RCDs) are installed in the circuit *before* the boneIO controller.**
The current rating (in Amps) of the overcurrent protection must be sized appropriately for the planned load of the circuit (e.g., the wattage of the loads), but at the same time, it **must not exceed the maximum rated current of the relay, which is 16A**.
The correct current flow for the phase (L) wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> OUT terminal in boneIO
-> Load`
### Example 1: Controlling a standard circuit [#example-1-controlling-a-standard-circuit]
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 16A), to the `COM` terminal of the selected output (e.g., `COM 1`).
2. Connect the wire leading to the **load** (e.g., an outlet) to the `NO` (Normally Open) terminal of the same output (e.g., `OUT 1`).
3. Run the **neutral wire (N)** directly to the load.
### Logical Diagram [#logical-diagram]
### Example 2: Controlling circuits from different phases / RCDs [#example-2-controlling-circuits-from-different-phases--rcds]
Thanks to the separation of the `COM` terminals, you can safely connect circuits from different sources.
### Logical Diagram [#logical-diagram-1]
### Safe Connecting of COM and OUT Terminals [#safe-connecting-of-com-and-out-terminals]
In the boneIO controller, version Cover **every two outputs (e.g., Cover 01 UP and DOWN) share a single common power terminal `COM`**. This means that the phase wire (L) from a single circuit breaker supplies a pair of relays - with hardware interlock.
1. **REMEMBER**, ensure that the relevant circuit breakers in the electrical cabinet **are turned off**.
2. Connect the **phase wire (L)**, coming from the overcurrent protection, to the appropriate COM terminal - tighten it with adequate force.
3. Connect the wire leading to your load (e.g., socket) to **its corresponding output terminal** - tighten it with adequate force.
4. Run the neutral (N) wire directly from the neutral bar to the load.
# Connecting outputs (/en/docs/products/hw-guide-outputs-32)
## Connecting Relay Outputs (10A) [#connecting-relay-outputs-10a]
The key feature of the 32x10A model is its high output density, integrating 32 relays of 10A each into a remarkably compact form factor. This provides tremendous possibilities for controlling a large number of independent circuits from a single device, saving both space and complexity.
### Protection and Correct Wiring Order [#protection-and-correct-wiring-order]
**It is critical that all overcurrent protection (Miniature Circuit Breakers, MCBs) and residual-current devices (RCDs) are installed in the circuit *before* the boneIO controller.**
The current rating (in Amps) of the overcurrent protection must be sized appropriately for the planned load of the circuit (e.g., the wattage of the lights), but at the same time, it **must not exceed the maximum rated current of the relay, which is 10A**.
The correct current flow for the phase (L) wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> OUT terminal in boneIO
-> Load`
### Example 1: Controlling a standard circuit [#example-1-controlling-a-standard-circuit]
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 10A), to the `COM` terminal of the selected output (e.g., `COM 1` or `COM 2`).
2. Connect the wire leading to the **load** (e.g., an outlet) to the `NO` (Normally Open) terminal of the same output (e.g., `OUT 1`).
3. Run the **neutral wire (N)** directly to the load.
### Logical Diagram [#logical-diagram]
### Safe Connecting of COM and OUT Terminals [#safe-connecting-of-com-and-out-terminals]
In the boneIO controller, version 32x10A **every two outputs (e.g., OUT1 and OUT2) share a single common power terminal `COM`**. This means that the phase wire (L) from a single circuit breaker supplies a pair of relays.
1. **REMEMBER**, ensure that the relevant circuit breakers in the electrical cabinet **are turned off**.
2. Connect the **phase wire (L)**, coming from the overcurrent protection, to the appropriate COM terminal - tighten it with adequate force.
3. Connect the wire leading to your load (e.g., a light bulb) to **its corresponding output terminal** - tighten it with adequate force.
4. Run the neutral (N) wire directly from the neutral bar to the load.
# Connecting outputs (/en/docs/products/hw-guide-outputs-cover)
## Connecting Relay Outputs (Cover Motors) [#connecting-relay-outputs-cover-motors]
The key feature of the Cover version is that it has 32 relays, which are paired to control up to 16 roller shutter motors. Each pair of relays (e.g., Cover 01`UP`/`DOWN`, Cover 02 `UP`/`DOWN`) is protected by a hardware interlock to prevent simultaneous 'up' and 'down' signals, which protects the motor from damage.
### Protection and Correct Wiring Order [#protection-and-correct-wiring-order]
**It is critical that all overcurrent protection (Miniature Circuit Breakers, MCBs) and residual-current devices (RCDs) are installed in the circuit *before* the boneIO controller.**
The current rating (in Amps) of the overcurrent protection must be sized appropriately for the planned load of the circuit (in this case - cover motors), but at the same time, it **must not exceed the maximum rated current of the relay, which is 10A**.
The correct current flow for the phase (L) wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> UP/DOWN terminal in boneIO
-> COVER`
### Example 1: Controlling a standard cover circuit [#example-1-controlling-a-standard-cover-circuit]
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 10A), to the `COM` terminal of the selected Cover output (e.g., `Cover 01 COM`).
2. Connect the wire leading to the **Cover motor UP** to the `UP` terminal of the same output (e.g., `Cover 01 UP`).
3. Connect the wire leading to the **Cover motor DOWN** to the `DOWN` terminal of the same output (e.g., `Cover 01 DOWN`).
4. Run the **neutral wire (N)** directly to the load (cover engine).
### Logical Diagram [#logical-diagram]
### Safe Connecting of COM and OUT Terminals [#safe-connecting-of-com-and-out-terminals]
In the boneIO controller, version Cover **every two outputs (e.g., Cover 01 UP and DOWN) share a single common power terminal `COM`**. This means that the phase wire (L) from a single circuit breaker supplies a pair of relays - with hardware interlock.
1. **REMEMBER**, ensure that the relevant circuit breakers in the electrical cabinet **are turned off**.
2. Connect the **phase wire (L)**, coming from the overcurrent protection, to the appropriate COM terminal - tighten it with adequate force.
3. Connect the wire leading to your load (e.g., a cover motor) to **its corresponding output terminal** - tighten it with adequate force.
4. Run the neutral (N) wire directly from the neutral bar to the load.
# Connecting outputs (/en/docs/products/hw-guide-outputs-covermix)
## Connecting Relay Outputs [#connecting-relay-outputs]
The key feature of the Covermix version is that it has 32 relays in total, but half of them (16) are are paired to control up to 8 roller shutter motors. Each pair of relays (e.g., Cover 01`UP`/`DOWN`, Cover 02 `UP`/`DOWN`) is protected by a hardware interlock to prevent simultaneous 'up' and 'down' signals, which protects the motor from damage. The rest of relays (16) are classic 10A relays which are usually used in lighting circuits. This provides tremendous possibilities for controlling a large number of independent circuits from a single device, saving both space and complexity.
### Protection and Correct Wiring Order [#protection-and-correct-wiring-order]
**It is critical that all overcurrent protection (Miniature Circuit Breakers, MCBs) and residual-current devices (RCDs) are installed in the circuit *before* the boneIO controller.**
The current rating (in Amps) of the overcurrent protection must be sized appropriately for the planned load of the circuit (e.g. cover motors, lighting), but at the same time, it **must not exceed the maximum rated current of the relay, which is 10A**.
The correct current flow for the phase (L) for covers - wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> UP/DOWN terminal in boneIO
-> COVER`
The correct current flow for the phase (L) for relays - wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> OUT terminal in boneIO
-> Load`
### Part 1: Connecting Cover Outputs (OUT1 - OUT16) Cover 1-8 [#part-1-connecting-cover-outputs-out1---out16-cover-1-8]
These outputs are designed to control bidirectional 230V AC motors for roller shutters or blinds. They are grouped in pairs (e.g., OUT1/OUT2, OUT3/OUT4) and feature a **hardware interlock** to prevent the motor from being damaged.
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 10A), to the `COM` terminal of the selected Cover output (e.g., `Cover 01 COM`).
2. Connect the wire leading to the **Cover motor UP** to the `UP` terminal of the same output (e.g., `Cover 01 UP`).
3. Connect the wire leading to the **Cover motor DOWN** to the `DOWN` terminal of the same output (e.g., `Cover 01 DOWN`).
4. Run the **neutral wire (N)** directly to the load (cover engine).
### Logical diagram: [#logical-diagram]
### Part 2: Connecting Relay Outputs (OUT17 - OUT32) [#part-2-connecting-relay-outputs-out17---out32]
These are standard relay outputs for general-purpose use, such as controlling lighting.
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 10A), to the `COM` terminal of the selected output (e.g., `COM9` for `OUT17` and `OUT18`).
2. Connect the wire leading to the **load** (e.g., a lamp) to the corresponding output terminal (e.g., `OUT17`).
3. Run the **neutral wire (N)** directly to the load.
### Logical Diagram [#logical-diagram-1]
### Safe Connecting of COM and OUT Terminals [#safe-connecting-of-com-and-out-terminals]
In the boneIO controller, version Covermix **every two outputs (e.g., Cover 01 UP, DOWN) and also outputs dedicated for lights (e. g. OUT17, OUT18) share a single common power terminal `COM`**. This means that the phase wire (L) from a single circuit breaker supplies a pair of relays - with hardware interlock.
1. **REMEMBER**, ensure that the relevant circuit breakers in the electrical cabinet **are turned off**.
2. Connect the **phase wire (L)**, coming from the overcurrent protection, to the appropriate COM terminal - tighten it with adequate force.
3. Connect the wire leading to your load (e.g., cover motor, a light bulb) to **its corresponding output terminal** - tighten it with adequate force.
4. Run the neutral (N) wire directly from the neutral bar to the load.
# Power supply connection (/en/docs/products/hw-guide-power-supply-connection)
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 24V DC power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+24V` output of the power supply to the `+` screw terminal on the boneIO.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO.
4. Double-check the connections and polarity before turning on the power supply.
# Backup power (UPS) (/en/docs/products/hw-guide-power-ups-black)
## Backup power (UPS) — recommended [#backup-power-ups--recommended]
**Power boneIO Black from a 24 V DC supply with battery backup** — a UPS or a buffered (DC-UPS) power supply. boneIO Black should see uninterrupted 24 V, even when the mains drops for a moment.
boneIO Black is a small Linux computer. It writes its configuration, logs and — during an update — system packages to its memory card or eMMC, and it has no battery-backed clock. Most of its unexpected restarts are caused by short brownouts on the mains. A few minutes on a battery covers them.
What a UPS gives you:
* **No restart on a mains blip.** Outputs, inputs and automations keep working through short cuts and voltage dips.
* **The right time.** After a power cut the controller does not know the time until its network is up and a time server answers. Until then schedules, sun events and time windows in conditions wait.
* **Safe updates.** A system update can take up to an hour on a controller that has not been updated for a long time. The display and the panel say *Do not power off* — a power cut in the middle of it is the one case that may need hands on the device to repair.
The choice of the unit is yours or your installer's. Two common setups:
* a **DIN-rail 24 V DC-UPS module** (or a power supply with a buffer and battery) in the cabinet, between the power supply and boneIO Black,
* a **230 V UPS** feeding the 24 V power supply.
Either way the wiring to boneIO Black is the one in the picture above: `+24V` to `+` and `GND` to `GND` on the POWER terminal, coming from the UPS side.
Size it for everything on the same 24 V line, not just boneIO Black — relay coils, sensors and other devices powered from it count too.
boneIO Black copes better with a power cut since 1.6: it checks and repairs its file system at start, a damaged boot partition no longer stops it, and an interrupted package install is finished on the next boot. A UPS is still the recommendation — the controller does not shut itself down when the battery runs out, so the UPS is what keeps it running.
# SERVICE port (/en/docs/products/hw-guide-service-port-black)
## SERVICE port [#service-port]
From version 1.0, boneIO Black controllers have a **SERVICE** terminal with three pins: **TX**, **RX** and **GND**. It is the controller's serial console (UART) — a terminal into its Linux system, used for diagnostics and repair when the network or the panel does not answer.
**Do not connect anything to it permanently.** It is for servicing only. There is no **+3.3V** pin: the port does not power the adapter you connect.
# Why name outputs (/en/docs/software_setup/why-name-outputs)
## Why should you name them? [#why-should-you-name-them]
Naming your outputs will make working with the controller much easier. It's much easier to remember "Bedroom light" than "OUT\_17", right?
In our examples, we focus on a part of the configuration, which you can then adjust to your entire configuration.
Let's get started!
# Events vs Binary Sensors (/en/docs/black/sbs-binary-or-events)
In boneIO Black you have two types of inputs to choose from: **Events** and **Binary Sensors**. The choice depends on what device you're connecting.
## Events - for buttons [#events---for-buttons]
Events are the best choice for **wall switches**. They allow detection of different click types:
| Click Type | Description |
| ------------- | ---------------------------------- |
| **Single** | Single click |
| **Double** | Double click |
| **Triple** | Triple click |
| **Long** | Long press |
| **Sequences** | Combinations (e.g., double → long) |
**Example**: One button can turn on the main light (single), bedside lamp (double), and turn off all lights (long).
**Events have a minimal delay** for single clicks. The controller waits a short time (\~220ms) to check if another click will follow (double/triple). If you need immediate response, use a binary sensor.
## Binary Sensors - for sensors [#binary-sensors---for-sensors]
Binary sensors are the best choice for devices with two states:
| Device | States |
| ------------------ | --------------------------- |
| **Motion sensor** | Motion detected / No motion |
| **Reed switch** | Open / Closed |
| **Flood sensor** | Dry / Wet |
| **Smoke detector** | OK / Alarm |
**Advantages of binary sensors:**
* ✅ Immediate response (no delay)
* ✅ Actions on press (pressed) and release (released)
* ✅ Different device classes (motion, door, window, smoke, etc.)
## Which to choose? [#which-to-choose]
| Device | Input Type |
| ------------------------- | ------------------------------ |
| Wall switch | **Event** |
| Doorbell | **Event** or **Binary Sensor** |
| Motion sensor | **Binary Sensor** |
| Reed switch (door/window) | **Binary Sensor** |
| Flood sensor | **Binary Sensor** |
| Smoke detector | **Binary Sensor** |
## Input limitations [#input-limitations]
Some inputs on boneIO Black **cannot be active at controller startup**. We do not recommend connecting reed switches or motion sensors to them, as they may be active during startup.
| Inputs with limitations |
| ---------------------------------------------- |
| IN\_01, IN\_02 |
| IN\_09, IN\_10 |
| IN\_19, IN\_20, IN\_21 |
| IN\_29, IN\_30, IN\_31, IN\_32, IN\_33, IN\_34 |
For reed switches and motion sensors, use the remaining inputs (IN\_03 to IN\_08, IN\_11 to IN\_18, IN\_22 to IN\_28, and IN\_35 onwards).
# Configure areas (/en/docs/black/sbs-configure-areas)
Areas are rooms or zones that group devices in Home Assistant. The area configuration in boneIO must match the configuration in Home Assistant.
With properly configured areas, you can automatically create a simple dashboard in Home Assistant divided by these areas - all devices from a given area will be automatically grouped together.
## Important information [#important-information]
**Every area name change in Home Assistant requires a name change in the boneIO application!**
Area names must be identical 1:1 with the names in Home Assistant. It's worth configuring areas carefully from the very beginning to avoid problems later.
## How to configure areas? [#how-to-configure-areas]
1. Go to the **Settings** tab
2. Find the **Areas** section
3. Click the **Add area** button or edit an existing one
4. Enter the area name **exactly the same** as in Home Assistant
5. Click **Save**
6. Wait for the application to reload
## Synchronization with Home Assistant [#synchronization-with-home-assistant]
### Before configuring in boneIO [#before-configuring-in-boneio]
1. Open Home Assistant
2. Go to **Settings** → **Areas & zones**
3. Note down the exact names of all areas (case sensitive!)
4. Use the same names in boneIO configuration
### After changing the name in Home Assistant [#after-changing-the-name-in-home-assistant]
If you change an area name in Home Assistant:
1. Open the boneIO interface
2. Go to **Settings** → **Device** → **Areas/Rooms**
3. Edit the corresponding area
4. Change the name to the new one (same as in HA)
5. Save and wait for reload
## Export and Import areas [#export-and-import-areas]
You can transfer area configuration between devices:
1. On the first device: click **Export** in the Areas section
2. Save the YAML file
3. On the second device: click **Import** in the Areas section
4. Load the saved YAML file
5. Save and wait for reload
## Best practices [#best-practices]
* **Plan ahead** - think through area names before starting configuration
* **Use simple names** - avoid special characters and diacritics
* **Be consistent** - use the same naming convention across all devices
* **Document changes** - save an export after each major change as a backup
# Configure binary sensors (/en/docs/black/sbs-configure-binary-sensors)
Binary sensors are ideal for devices with two states: motion sensors, reed switches, flood sensors, etc.
## How to add or edit a binary sensor? [#how-to-add-or-edit-a-binary-sensor]
1. Go to **Settings** → **Control** → **Local Inputs**
2. Click **Add New** or the edit icon next to an existing sensor
3. Fill in the configuration form
## Basic settings [#basic-settings]
### Display Name [#display-name]
Friendly name for the sensor, e.g.:
* `Living Room Motion Sensor`
* `Front Door`
* `Bedroom Window`
This name will be visible in the interface and Home Assistant.
### BoneIO Input [#boneio-input]
Select the physical input from the dropdown:
* `IN_01`, `IN_02`, `IN_03`, ... `IN_56` (depending on model)
**Avoid inputs with limitations** (IN\_01, IN\_02, IN\_09, IN\_10, IN\_19, IN\_20, IN\_21, IN\_29–IN\_34) for reed switches and motion sensors that may be active at controller startup.
### Area / Room [#area--room]
Select an area from the dropdown - the sensor will be automatically assigned to this area in Home Assistant.
### Bounce Time [#bounce-time]
Contact debounce time (default: 120ms). For motion sensors and reed switches, usually no change is needed.
### Device Class [#device-class]
Device class in Home Assistant - affects icon and behavior:
| Device Class | Icon | Use Case |
| ------------- | --------- | ----------------------- |
| **motion** | Motion | Motion sensors |
| **door** | Door | Door reed switches |
| **window** | Window | Window reed switches |
| **opening** | Opening | General opening sensors |
| **moisture** | Water | Flood sensors |
| **smoke** | Smoke | Smoke detectors |
| **gas** | Gas | Gas detectors |
| **occupancy** | Occupancy | Occupancy sensors |
| **vibration** | Vibration | Vibration sensors |
| **tamper** | Tamper | Tamper sensors |
## Options [#options]
### Show in HA [#show-in-ha]
Enable to make the sensor visible in Home Assistant (enabled by default).
### Inverted [#inverted]
Invert sensor logic:
* Normal: active input = sensor ON
* Inverted: active input = sensor OFF
Useful when a reed switch is mounted in reverse.
### Initial Send [#initial-send]
Send sensor state at controller startup.
## Actions - Pressed and Released [#actions---pressed-and-released]
Binary sensors have two action tabs:
### Pressed [#pressed]
Actions executed when the sensor changes to active state (e.g., motion detected, door opened).
### Released [#released]
Actions executed when the sensor changes to inactive state (e.g., no motion, door closed).
## How to add an action? [#how-to-add-an-action]
1. Go to the **Pressed** or **Released** tab
2. Click **Add Action**
3. Select the action type and configure parameters
### Action types [#action-types]
| Action Type | Description |
| ---------------------- | -------------------------------------- |
| **output** | Control an output (light, switch) |
| **cover** | Control a cover |
| **virtual\_switch** | Set a virtual switch (ON, OFF, TOGGLE) |
| **mqtt** | Send an MQTT message |
| **output\_over\_mqtt** | Control an output via MQTT |
| **cover\_over\_mqtt** | Control a cover via MQTT |
| **remote\_output** | Control an output on a remote device |
| **remote\_cover** | Control a cover on a remote device |
Every action can also have conditions (time, date, state, sun) and, on binary sensors, a delay. The full list of types, values and options is in [Actions](/en/docs/black/current/configuration/event#actions).
## Configuration examples [#configuration-examples]
### Example 1: Hallway motion sensor [#example-1-hallway-motion-sensor]
1. **Display Name**: `Hallway Motion Sensor`
2. **BoneIO Input**: `IN_05` (avoid inputs with limitations)
3. **Area / Room**: `Hallway`
4. **Device Class**: `motion`
**Actions:**
* **Pressed**: ON `Hallway Light`
* **Released**: OFF `Hallway Light`
### Example 2: Front door reed switch [#example-2-front-door-reed-switch]
1. **Display Name**: `Front Door`
2. **BoneIO Input**: `IN_06`
3. **Area / Room**: `Entrance`
4. **Device Class**: `door`
5. **Inverted**: ✅ (if reed switch shows reversed)
No actions - just state monitoring in Home Assistant.
### Example 3: Flood sensor [#example-3-flood-sensor]
1. **Display Name**: `Bathroom Flood Sensor`
2. **BoneIO Input**: `IN_07`
3. **Area / Room**: `Bathroom`
4. **Device Class**: `moisture`
**Actions:**
* **Pressed**: OFF `Main Water Valve` (automatic valve closure when water detected)
After saving, the sensor will appear in the table and be available in Home Assistant with the appropriate icon and device class.
# Configure events (/en/docs/black/sbs-configure-events)
Events allow you to assign different actions to a single button depending on the click type.
## How to add or edit an event? [#how-to-add-or-edit-an-event]
1. Go to **Settings** → **Control** → **Local Inputs**
2. Click **Add New** or the edit icon next to an existing event
3. Fill in the configuration form
## Basic settings [#basic-settings]
### Display Name [#display-name]
Friendly name for the event, e.g.:
* `Living Room Button`
* `Bedroom Switch`
* `Doorbell`
This name will be visible in the interface and Home Assistant.
### BoneIO Input [#boneio-input]
Select the physical input from the dropdown:
* `IN_01`, `IN_02`, `IN_03`, ... `IN_56` (depending on model)
Inputs already used by other events or binary sensors are automatically hidden from the list.
### Area / Room [#area--room]
Select an area from the dropdown - the event will be automatically assigned to this area in Home Assistant.
## Actions - click tabs [#actions---click-tabs]
The form has separate tabs for each click type:
### Single (Single click) [#single-single-click]
Actions executed after a single button click.
### Double (Double click) [#double-double-click]
Actions executed after a quick double click.
### Triple (Triple click) [#triple-triple-click]
Actions executed after a triple click.
Triple click must be enabled in advanced settings (disabled by default).
### Long (Long press) [#long-long-press]
Actions executed after holding the button for a specified time.
## How to add an action? [#how-to-add-an-action]
1. Go to the appropriate tab (Single, Double, Triple, Long)
2. Click **Add Action**
3. Select the action type and configure parameters
### Action types [#action-types]
| Action Type | Description |
| ---------------------- | -------------------------------------- |
| **output** | Control an output (light, switch) |
| **cover** | Control a cover |
| **virtual\_switch** | Set a virtual switch (ON, OFF, TOGGLE) |
| **mqtt** | Send an MQTT message |
| **output\_over\_mqtt** | Control an output via MQTT |
| **cover\_over\_mqtt** | Control a cover via MQTT |
| **remote\_output** | Control an output on a remote device |
| **remote\_cover** | Control a cover on a remote device |
Every action can also have conditions (time, date, state, sun). The full list of types, values and options is in [Actions](/en/docs/black/current/configuration/event#actions).
### Output action [#output-action]
The most commonly used action - control an output:
| Parameter | Description |
| ---------- | --------------------------------------------- |
| **Output** | Select output from the list |
| **Action** | TOGGLE (toggle), ON (turn on), OFF (turn off) |
### Cover action [#cover-action]
Control a cover:
| Parameter | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Cover** | Select cover from the list |
| **Action** | TOGGLE, OPEN, CLOSE, STOP, TOGGLE\_OPEN, TOGGLE\_CLOSE, SMART\_TOGGLE; for venetian blinds also TILT, TILT\_OPEN, TILT\_CLOSE |
## Sequences [#sequences]
Sequences are advanced click combinations:
| Sequence | Description |
| ------------------- | ------------------------- |
| **Double → Long** | Double click, then hold |
| **Single → Long** | Single click, then hold |
| **Double → Single** | Double click, then single |
Each sequence can have its own actions and optionally send an MQTT event.
## Advanced settings [#advanced-settings]
Click the **Advanced Settings** tab to access additional options:
### Bounce Time [#bounce-time]
Contact debounce time (default: 30ms). Increase if the button generates false clicks.
### Double Click Duration [#double-click-duration]
Maximum time between clicks for a double click (default: 220ms).
This parameter affects single click delay - the controller waits this time to check if a second click will follow.
### Long Press Duration [#long-press-duration]
Hold time for a long click (default: 400ms).
### Sequence Window Duration [#sequence-window-duration]
Time window for sequences (default: 500ms).
### Sequence Mode [#sequence-mode]
| Mode | Description |
| ------------- | ---------------------------------------------- |
| **Immediate** | Actions executed immediately upon detection |
| **Exclusive** | Waits for sequence completion before executing |
### Enable Triple Click [#enable-triple-click]
Enable triple click support (disabled by default).
## Configuration example [#configuration-example]
**Scenario**: A button in the living room controlling lighting.
1. **Display Name**: `Living Room Button`
2. **BoneIO Input**: `IN_04`
3. **Area / Room**: `Living Room`
**Actions:**
* **Single**: Toggle `Living Room Main Light`
* **Double**: Toggle `Living Room Lamp`
* **Long**: OFF `Living Room Main Light`, OFF `Living Room Lamp` (turn off everything)
After saving, the event will appear in the table and be available in Home Assistant.
# Actions (/en/docs/black/sbs-create-action)
## What it's all about? [#what-its-all-about]
Actions are best way to made some simple core automations inside of your controller. With them its possible to made some cricital automations
inside of your boneIO Black.
To make it easy i will give you some example and will describe it:
```yaml
- id: IN_01_living_room1
boneio_input: IN_01
actions:
single:
- action: output
pin: OUT_01_living_room_light_1
double:
- action: output
pin: OUT_02_living_room_light_2
long:
- action: output
pin: OUT_03_living_room_light_3
- id: IN_02_living_room2
boneio_input: IN_02
actions:
single:
- action: output
pin: OUT_04_living_room_light_4
long:
- action: output
pin: OUT_01_living_room_light_1
action_output: off
- action: output
pin: OUT_02_living_room_light_2
action_output: off
- action: output
pin: OUT_03_living_room_light_3
action_output: off
- action: output
pin: OUT_04_living_room_light_4
action_output: off
```
What have we achived? By using just 2 buttons we can independly turn on 4 lights, an by single long click of one of them you can turn all of them off.
In the case of `IN_01_living_room1` its really simple, we define each action fo each action type, in our case for `single` click Living room light 1
for `double` Living room light 2 and for `long` click Living room light 3. The default action for `- action: output` type its `toogle`
So by simple click of the button you will change the state of light from on to off etc.
In the case of button 2 - `IN_02_living_room2` with single click you will change state of Living room light 4. But intresting thing will happen if
you `long` click that button. That will turn off all 4 defined lights in living room. There are many possibilities with actions!
If you want to know more - please check documentation.
# Edit configuration (/en/docs/black/sbs-edit-configuration)
The **Settings** tab contains forms for configuring all controller functions. Here you can configure outputs, inputs, areas, events, and many other options.
## Important configuration rules [#important-configuration-rules]
### Saving changes [#saving-changes]
**Each edit in a given section requires saving and waiting for reload or restart of the application before you start working on the next section.**
After saving changes:
1. Click the **Save** button in the given section
2. Wait for save confirmation
3. Wait for the application to reload or restart
4. Only then proceed to edit the next section
### Export and Import [#export-and-import]
Each configuration section has **Export** and **Import** buttons:
* **Export** - saves the configuration of the given section to a YAML file
* **Import** - loads the configuration from a YAML file
This allows you to:
* Manually copy configuration sections
* Transfer created configurations between devices
* Create backups of individual sections
## Configuration sections [#configuration-sections]
In the Settings tab you will find the following sections:
* **Areas** - defining areas compatible with Home Assistant
* **Outputs** - relay output configuration
* **Covers** - cover and blind configuration
* **Inputs** - digital input configuration
* **Events** - event and automation definitions
* **Binary Sensors** - binary sensor configuration
* **Actions** - action definitions
* And more...
# First-time setup (/en/docs/black/sbs-first-run-wizard)
The first time you open the panel of a new controller, you do not see the panel yet but the **First-time setup** wizard.
It creates the administrator account — the username and password you will sign in with from now on — and helps you get going.
The whole wizard takes a few minutes.
There is no way to skip the wizard. Until it is completed, the controller answers nothing except the wizard itself, so nobody can
change its configuration without a password.
The bar at the top shows how far you are (**Step 2 of 6**, for example). Not every controller sees every step:
| Step | When you see it |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| Start | Always. |
| Account | Always. |
| Which controller is this? | Only if the controller does not yet know which model it is. |
| Import | Only on a controller that still has its factory configuration. |
| Devices | Only on a controller that still has its factory configuration, and only if you did not import a backup. |
| Cloud | Only if boneIO Cloud registration is not already on, and only if you did not import a backup. |
| Done | Always. |
## Start [#start]
The wizard explains that the device has no administrator account yet, and under **What's ahead** lists the steps this controller will go through.
Click **Get started**.
## Account [#account]
Choose the **Username** and **Password** for the panel and type the password again under **Confirm password**.
* the password must be **at least 8 characters** long,
* it must **not contain the username** — the username is visible on the sign-in screen, so a password built from it is easy to guess.
Click **Create account**. From here on there is no way back to this step — the account exists.
The same account also opens the **Node-RED** editor: Node-RED has no accounts of its own, and only panel administrators get in.
**This password is also your SSH password.** On a new controller the wizard sets the same password for the `boneio` user.
Over SSH you always log in as `boneio` (for example `ssh boneio@192.168.1.100`) — the username you typed here is for the panel only.
This happens only once: changing the panel password later does not change the SSH password. For that, use the
[SSH login password](/en/docs/black/current/basic/accounts#ssh-login-password) card in **Settings → Access → User accounts**, or run `passwd` over SSH.
Write the password down somewhere safe.
## Which controller is this? [#which-controller-is-this]
You only see this step if the controller was not told at the factory which model it is. Until you answer, it has no outputs configured.
Pick your model — **32x10A**, **24x16A**, **Cover** or **Cover Mix** — and click **Apply**.
The controller restarts with that model's configuration, which takes up to a minute; the wizard waits and then carries on by itself.
The wizard does not come back to this step, so check the label on the controller first.
{/* SCREENSHOT: en_wizard_board.webp — "Which controller is this?" step with the four models */}
## Import (optional) [#import-optional]
If you are replacing an older boneIO and have a configuration backup from it (a `.tar.gz` file downloaded from
**Settings → Maintenance → Backups** on the old device), drop the file on **Choose a file or drag it here**, or click it to pick the file,
then click **Import configuration**. The controller will take over that configuration after a restart.
Setting up from scratch? Click **Skip**.
If you imported a backup, the Devices and Cloud steps are skipped — the imported configuration already decides them.
## Devices [#devices]
The outputs are already set up for your model. Here you decide what the inputs should do with them:
* **Inputs control outputs** — each input switches one output (a push button turns on a light),
* **Inputs control covers** — pairs of inputs open and close covers,
* **Inputs control covers and outputs** — a mix, on models that have both,
* **Wire nothing — I will do it myself** — leave the inputs empty and configure them later.
Leave **Restore relay and cover state after a restart** on (it is by default) if lights and covers should come back to where they were after a power cut.
Click **Apply**, or **Skip** to leave everything as it is. You can change all of it later in **Settings → Control → Local Inputs**.
## Cloud (optional) [#cloud-optional]
You can register the controller with **boneIO Cloud**. It then gets its own address with a trusted certificate — the browser stops
warning about the connection, and you can install the panel as an app on your phone.
* Registration sends the controller's serial number to boneIO Cloud.
* The controller is still reachable **only on your own network** — nothing is exposed to the internet.
* Your router must not block so-called *DNS rebinding*; if the new address does not open, that is usually the reason.
Click **Enable registration**, or **Skip**. You can turn it on later in **Settings → Access → Web Server**.
After **Enable registration** the controller restarts its HTTPS server with the new certificate. The wizard shows
**Switching the HTTPS server** and holds **Next** while it waits — usually about half a minute, at most three minutes. There is nothing to do, the controller keeps running.
When it is ready, the notice gives you the new address as a link.
If the controller does not know its own network address yet, the wizard says **Registration is saved** instead:
registration starts on the next boot.
## Done [#done]
The wizard confirms **The controller has an owner**, names the account it created, and reminds you that Node-RED takes the same login.
It also says what happened to the SSH password. If it says **The SSH password could not be set**,
SSH login with a password stays closed — contact us on Discord.
How you leave depends on the Cloud step:
* **Without cloud registration**, click **Go to the panel**.
* **With cloud registration**, click **Go to blk….black.boneio.app:8443**. The panel opens at its new address in a new tab.
Sign in there once more with the same password — the browser keeps sign-ins separately for each address.
**Stay at this address** keeps you where you are.
* **If the new address did not answer** (usually DNS rebinding protection on the router), the wizard says so and offers
**Open blk….black.boneio.app:8443 anyway**. The panel keeps working at the current address.
If you imported a configuration or clicked **Apply** in Devices, restart the controller once:
**Settings → Maintenance → Restart and shutdown**. Until then the controller still runs the old configuration.
## Updating from version 1.5? [#updating-from-version-15]
A controller that was already configured before sees a **shorter wizard: Start → Account → Cloud → Done**.
The Cloud step is left out too if cloud registration was already on.
If the 1.5 panel already had a password (`web.auth` in `config.yaml`), there is no wizard at all — sign in with that password.
The wizard only creates the account — your outputs, inputs and actions stay exactly as they were.
If the SSH password of the `boneio` user was still the factory `Black`, the wizard replaces it with your new password too;
if you had already changed it, it is left alone and the wizard says so.
See [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6) for the rest of the checklist.
## Forgot the password? [#forgot-the-password]
Log in over SSH and reset it — see [Accounts and access](/en/docs/black/current/basic/accounts#forgotten-password).
## What's next? [#whats-next]
* [Home Assistant connection](./home-assistant-connection) - connect the controller to Home Assistant
* [Interface navigation](./interface-navigation) - learn about the menu and tabs
* [Accounts and access](/en/docs/black/current/basic/accounts) - add a read-only account for the rest of the household
# Connect to your boneIO (/en/docs/black/sbs-how-to-connect)
After connecting your controller to the local network, you can access the boneIO web interface through a web browser. This is the most convenient way to configure and monitor your controller.
## Prerequisites [#prerequisites]
* boneIO controller connected to local network via Ethernet cable
* Network with DHCP service enabled (enabled by default on most routers)
* Computer or mobile device on the same local network
* Web browser (Chrome, Firefox, Safari, Edge)
## Step 1: Connect the controller to the network [#step-1-connect-the-controller-to-the-network]
1. Connect an Ethernet cable to the network port of your boneIO controller
2. Connect the other end of the cable to your router or switch
3. Make sure the controller is powered on
The controller will automatically receive an IP address from the DHCP server on your network.
## Step 2: Find the controller's IP address [#step-2-find-the-controllers-ip-address]
There are two ways to find the controller's IP address:
### Option A: Display on the controller [#option-a-display-on-the-controller]
Press the button next to the display on the controller to scroll through the screens:
* the **network** screen shows the controller's **IP address** (plus the network mask and MAC address),
* the **last screen** shows a **QR code** — scan it with your phone and the panel opens straight away, at the right `https://…:8443` address
(or at the controller's own boneIO Cloud address, if you registered it; on a controller upgraded from 1.5 it is `http://…:8090` until you move the panel behind the proxy).
{/* SCREENSHOT: oled_network.webp — photo of the OLED network screen with the IP address */}
{/* SCREENSHOT: oled_qr.webp — photo of the OLED QR code screen */}
Which screens are shown is set in **Settings** → **Device** → **OLED Display**. Both are on in the factory configuration.
### Option B: Router admin panel [#option-b-router-admin-panel]
Log in to your router's admin panel and find the list of connected devices. The boneIO controller will be visible under a name corresponding to its serial number, starting with `blk`, e.g., `blk8c7df0`.
## Step 3: Open the web interface [#step-3-open-the-web-interface]
1. Open a web browser
2. In the address bar, type the controller's IP address with port 8443, e.g., `https://192.168.1.100:8443`
3. Press Enter
Always type `https://` at the start — without it the page will not open.
### The browser warns about the connection — this is expected [#the-browser-warns-about-the-connection--this-is-expected]
The first time you open the panel, the browser shows a warning such as **"Your connection is not private"**.
The connection **is** encrypted; the browser only warns because the certificate was issued by the controller itself,
not by a company the browser knows.
* **Chrome / Edge**: click **Advanced**, then **Proceed to 192.168.1.100 (unsafe)**
* **Firefox**: click **Advanced…**, then **Accept the Risk and Continue**
* **Safari**: click **Show Details**, then **visit this website**
The controller's certificate is valid for six months, so the browser does not ask again every day.
To get rid of the warning for good, see [HTTPS certificate](/en/docs/black/current/advanced/certificate).
## Step 4: Create your administrator account [#step-4-create-your-administrator-account]
A new controller has no owner yet. Instead of the panel you will see the **First-time setup** wizard.
Until the account exists, the controller's display says so: it shows **Setup required**, **Onboarding needed.**,
**Open in a browser:** and the panel's address. The display does not go dark while that notice is up, and the address
appears as soon as the controller gets one from the router (until then the line reads `http://:8090`, which is only a placeholder). The button still steps through the other screens;
after a minute the notice comes back. Once the account is created, the notice goes away by itself within a few seconds.
{/* SCREENSHOT: oled_setup_required.webp — photo of the OLED showing "Setup required" with the panel address */}
For a moment right at power-on, before that notice, the display may show `SETUP REQUIRED - open :8090` —
ignore the port there and use the address from the notice, or `https://…:8443`.
In the wizard you choose a username and password for the panel. It takes about a minute — see
[First-time setup](./first-run-wizard) for every step.
Do this right away. Until an account exists, **whoever on your network completes the wizard first becomes the owner** of the controller.
After the wizard you land in the main panel showing the controller status.
## Troubleshooting [#troubleshooting]
### I can't find the IP address [#i-cant-find-the-ip-address]
* Make sure the Ethernet cable is properly connected
* Check if the network LED on the controller is lit or blinking
* Restart the controller and wait about 30 seconds to obtain an IP address
### The page won't load [#the-page-wont-load]
* Check if your computer is on the same network as the controller
* Make sure you type `https://` before the IP address and `:8443` after it
* Try clearing your browser cache or use incognito mode
* A warning about the certificate is not an error — see Step 3
### The controller doesn't receive an IP address [#the-controller-doesnt-receive-an-ip-address]
If your network doesn't have a DHCP server, you can connect to the controller via USB cable:
1. Connect a USB cable to the USB port of the controller and to your computer
2. Your computer will receive an IP address from the `192.168.7.x` range
3. The controller will be available at `192.168.7.2` — the panel opens at `http://192.168.7.2:8090`
(if it does not open, restart the controller with the cable plugged in)
4. Connect via SSH and configure a static IP address for the `eth0` interface
This guide does not cover the exact network configuration commands.
## What's next? [#whats-next]
After connecting to the controller, you can proceed to:
* [First-time setup](./first-run-wizard) - every step of the wizard explained
* [Home Assistant connection](./home-assistant-connection) - connect the controller to Home Assistant
* [Interface navigation](./interface-navigation) - learn about the menu and tabs in the web interface
* [Update controller](./update-controller) - check if you have the latest software version
* [Configure controller](./edit-configuration) - configure the controller according to your needs
# Update controller (/en/docs/black/sbs-how-to-update)
The controller checks for a new version by itself every few hours. You install it with one click —
from Home Assistant or from the controller's own panel.
## Requirements [#requirements]
* The controller must have an internet connection
* You must be signed in to the panel as an **administrator**
* To update from Home Assistant, the controller must be connected to Home Assistant over MQTT
## How to update? [#how-to-update]
### From Home Assistant [#from-home-assistant]
1. In Home Assistant, open **Settings** — available updates are listed at the top,
2. Click the **boneIO Black Firmware** update,
3. Press **Update**,
4. That's all!
### From the web interface [#from-the-web-interface]
1. Open the controller's web interface in your browser
2. Go to **Settings** → **Maintenance** → **Software update**
3. Click **Check for Updates**
4. If a new version is available, read what it changes (**View Release Notes**), then click **Update to \** (for example **Update to 1.6.0**)
The update starts on its own. When it finishes, the application on the controller restarts and the panel reloads.
While the controller is installing and restarting, the panel shows **Update in progress** with the time since it started,
and comes back by itself once the new version is running. If the controller comes back on the old version, the panel says
**The update failed** — the details are in [Diagnostics](/en/docs/black/current/basic/logs).
If your browser shows the old panel after the update, it reloads the new one on its own (**Loading the new version of the panel**);
if it cannot, it asks you to press **Ctrl+Shift+R** (**Cmd+Shift+R** on a Mac).
{/* SCREENSHOT: en_panel_update_in_progress.webp — the "Update in progress" screen with "The controller is installing version …" and the elapsed time */}
**The update does not back up your configuration.** Download a backup first in **Settings → Maintenance → Backups**.
If something is wrong after the update, open **Available Versions** on the same page and install the previous version (the button is **Install**).
## After the update: system migrations [#after-the-update-system-migrations]
Some versions also change settings of the operating system underneath the app — for example firewall rules or SSH hardening.
These changes are called **system migrations**. They run by themselves on the first start after the update; you do not need to do anything.
You can see them in **Settings** → **Maintenance** → **System migrations**.
If a red banner says that **a system update was refused**, the page shows the reason — send it to us
(see [Diagnostics](/en/docs/black/current/basic/logs) for the support bundle).
## Updating from version 1.5? [#updating-from-version-15]
**Update to 1.5.6 first**, then to 1.6. Only 1.5.6 hands the browser over to the new panel cleanly; from older 1.5
versions the old panel may keep coming back after the update until you press **Ctrl+Shift+R**.
Version 1.6 adds accounts, so after the update the panel asks you to create an administrator account first
(unless the 1.5 panel already had a password — then you simply sign in with it).
Follow [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6).
## Important information [#important-information]
* **Do not turn off the controller's power during the update.** A backup power supply is worth having for exactly this — see
[Backup power (UPS)](/en/docs/black/products/black_32x10a/hardware-installation#backup-power-ups--recommended).
* A small update takes a few minutes. Jumping several versions can take over ten minutes, and coming from 1.5 up to an hour,
because the system migrations run on the first start.
* While migrations run, the display shows **Updating** and **Do not power off.** with how far it has got
(**Updating system** with a percentage, if the display is not set up in the configuration). The panel does
not answer until they finish.
* After the update, the application on the controller restarts by itself.
{/* SCREENSHOT: oled_updating.webp — photo of the OLED showing "Updating", "Do not power off." and the percentage */}
## Updating the operating system [#updating-the-operating-system]
Updating boneIO does not update the Debian system and the kernel underneath it. That is a separate card on the same page,
**Operating system** — see [Maintenance → Operating system](/en/docs/black/current/basic/system#operating-system).
Unlike a boneIO update, it does not restart the controller by itself.
## Update via SSH [#update-via-ssh]
If you need to update the controller manually via SSH (e.g., when the web interface update doesn't work), see the [SSH update guide](/en/docs/black/advanced/update-via-ssh).
# Interface navigation (/en/docs/black/sbs-interface-navigation)
After connecting to the controller, you will see the web interface with a top navigation bar. Below you'll find a description of all available tabs.
On a phone or tablet the same tabs move to a bar at the bottom of the screen — see [On a phone or tablet](#on-a-phone-or-tablet).
## Main menu [#main-menu]
| Tab | Description |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Outputs** | Control relay outputs, covers, and view relay states. |
| **Inputs** | View the state of digital inputs. |
| **Sensors** | Readings from onboard sensors: temperature, current consumption, memory usage, CPU, disk, and Dallas sensors (if connected). |
| **Modbus** | List of connected and configured Modbus devices. |
| **Templates** | Ready-made building blocks such as irrigation. |
| **Diagnostics** | The log, the support bundle and the bus tools (Modbus, I2C, CAN). See [Diagnostics](/en/docs/black/current/basic/logs). |
| **Settings** | Everything you configure, in seven groups — from outputs and schedules to software update, backups and restart. See [Settings](/en/docs/black/current/basic/settings). |
| **Node-RED** | The pre-installed visual automation tool. Shown only when Node-RED is running. |
| **Help** | Link to Discord community and documentation. |
**Where did System, Logs and the YAML editor go?** Since version 1.6 they are all inside the two tabs above:
the old **System** tab is now **Settings → Maintenance**, **Logs** and **Tools** are **Diagnostics**,
and the **YAML editor** is **Settings → Advanced → YAML editor**. Old bookmarks still work — they redirect.
A **read-only** account sees only the first five tabs. Diagnostics, Settings and Node-RED are for administrators — see [Accounts and access](/en/docs/black/current/basic/accounts).
## On a phone or tablet [#on-a-phone-or-tablet]
On a phone, a tablet or a narrow browser window the top bar shows only the
controller's name, and the tabs move to a bar at the bottom, under your thumb:
| Slot | What it opens |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Outputs** | The outputs view |
| **Inputs** | The inputs view |
| **Sensors** or **Templates** | Sensors — or Templates, once you have any; Sensors then moves under **More** |
| **Modbus** | The Modbus view |
| **More** | Everything else: Diagnostics, Settings, Node-RED, Help, and below them the version, serial number and the account you are signed in with |
### Inside the boneIO Dashboard add-on [#inside-the-boneio-dashboard-add-on]
When you open the panel through the **boneIO Dashboard** add-on in Home
Assistant, the bottom bar gets one more slot on the left: **Devices**. It opens
the add-on's device list. To make room, **Sensors** moves under **More**. Opened
through plain Home Assistant ingress, the bar stays as above.
{/* SCREENSHOT: en_bottom_nav_dashboard.webp — the panel inside the boneIO Dashboard add-on on a phone, Devices slot on the left of the bottom bar */}
## Language change [#language-change]
In the top right corner, you'll find flags to change the interface language. Available languages are Polish (PL) and English (EN).
# Home Assistant Connection (/en/docs/black/sbs-mqtt-connection)
The boneIO Black controller communicates with Home Assistant via the MQTT protocol. There are two configuration methods: using a local broker or a remote one (located on HA itself).
Additionally, to make managing the controller from Home Assistant easier, we have prepared a special Add-on for you, which gives you instant access to your boneIO.
## Option 1: MQTT Broker on boneIO Black (default) [#option-1-mqtt-broker-on-boneio-black-default]
**This is the easiest way** - the controller has a built-in Mosquitto MQTT broker that is already configured and running.
### Default configuration [#default-configuration]
By default, the controller is connected to the local MQTT broker:
* **Host**: `localhost`
* **Port**: `1883`
* **Username**: `boneio`
* **Topics**: `boneio/` — set automatically
The broker has three accounts: `boneio` (the one the controller itself uses), `homeassistant` and `mqtt` (for your integrations).
On a controller installed with version 1.6 or later **each account has its own random password**, different on every device — there is no shared default password any more.
That means before you connect Home Assistant you **set a password you know** for the `homeassistant` account.
**Set the MQTT password first.** Go to **Settings** → **Services on this controller** → **MQTT broker (local)**,
in the `homeassistant` card type the new password twice (at least 8 characters) and click **Change Password**.
This is the password you will type into Home Assistant below.
If you change the password of the `boneio` user, leave **Also update boneIO's own configuration** switched on —
the controller then saves the new password in its own configuration and reconnects on its own.
Without it, the controller keeps using the old password and goes offline.
### Connecting Home Assistant to the broker on boneIO [#connecting-home-assistant-to-the-broker-on-boneio]
1. **No Mosquitto add-on needed** — with this option the broker already runs on the controller,
so in Home Assistant you only add the MQTT integration.
2. **Add MQTT integration in Home Assistant**:
* Go to **Settings** → **Devices & Services**
* Click **Add Integration** → search for **MQTT**
* Enter the details:
* **Broker**: boneIO controller IP (e.g., `192.168.1.100`)
* **Port**: `1883`
* **Username**: `homeassistant`
* **Password**: the password you just set for `homeassistant`
* Click **Submit**
Every step with Home Assistant screenshots is in [Connecting boneIO Black](/en/docs/home-assistant/boneio-black) in the Home Assistant guide.
3. **Automatic discovery**:
* The boneIO controller will automatically register all devices with Home Assistant
* Devices will appear in **Settings** → **Devices & Services** → **MQTT**
### Encrypting Home Assistant's connection (TLS) [#encrypting-home-assistants-connection-tls]
Optional. By default Home Assistant talks to the broker on boneIO in plain text on port 1883, password included.
On your own home network that is often fine. If the network is shared, or the traffic crosses a VPN, have the broker accept encrypted connections on port **8883**.
Go to **Settings** → **Services on this controller** → **MQTT broker (local)** and scroll to the **Broker encryption (TLS)** card, below the accounts.
1. **Get a certificate.** Click **Make a certificate on this controller**. It is valid for ten years and covers the controller's names, listed under **Valid for**.
Then click **Download the CA (ca.crt) for clients** — Home Assistant needs that file.
If you would rather use your own certificate, open **Upload my own certificate** (the page shows the openssl commands under **How to make certificates with openssl**).
2. **Pick a mode** under **Mode**:
* **Off** — plain MQTT on port 1883 only, as before.
* **TLS beside plain** — TLS on 8883, and 1883 keeps working. Start here.
* **TLS only on the network** — from the network only TLS on 8883. Plain 1883 stays only for programs on the controller itself, boneIO included.
3. **Move Home Assistant to TLS.** In the MQTT integration, choose **Reconfigure**, set port **8883**, open the advanced options,
enable certificate validation with a custom broker certificate and upload `ca.crt`.
As the broker address use the controller's name exactly as it appears under **Valid for**, for example `boneio-1234.local`.
An IP address works only if it is on that list, and an address from DHCP can change.
4. Once Home Assistant and everything else connects on 8883, switch to **TLS only on the network** if you want plain MQTT closed to the network.
**What it costs:**
* **Every mode change restarts the broker**, which briefly disconnects everyone, Home Assistant included. If the broker does not come back with the new settings, the panel puts the previous ones back and says so.
* **TLS only on the network** cuts off anything still on port 1883 from another machine until you move it to 8883. The panel refuses this mode while boneIO itself connects to this broker in plain text by the controller's network address: first set boneIO's MQTT host to `localhost`, or turn on TLS for its own connection.
* **Node-RED on the controller** reaches the broker from Docker's network, not from `localhost`. Before **TLS only on the network**, move its broker node to port 8883 with TLS and `ca.crt`.
* **A new certificate means a new CA.** Every client that trusts the current `ca.crt` must be given the new one, or it refuses the broker.
If the card says this controller's system helper does not manage the broker's TLS yet, go to **Settings** → **System migrations**,
click **Apply pending migrations** and come back.
## Option 2: MQTT Broker on Home Assistant [#option-2-mqtt-broker-on-home-assistant]
You can connect the controller to an MQTT broker located on Home Assistant or another device.
### Configuring the broker in Home Assistant [#configuring-the-broker-in-home-assistant]
1. **Install Mosquitto Broker** (if you don't have it yet):
* Go to **Settings** → **Apps** → **Install app**
* Search for **Mosquitto broker**
* Click **Install** and **Start**
2. **Create an MQTT user**:
* Go to **Settings** → **People** → **Users**
* Click **Add User**
* Fill in the details:
* **Name**: `boneio`
* **Username**: `boneio`
* **Password**: choose a secure password
* Click **Create**
3. **Add MQTT integration** (if you don't have it yet):
* Go to **Settings** → **Devices & Services**
* MQTT should be automatically detected
* If not, click **Add Integration** → **MQTT**
### Configuring MQTT in boneIO controller [#configuring-mqtt-in-boneio-controller]
1. Go to **Settings** → **Connections** → **MQTT**
2. Enter the broker details:
* **Host**: Home Assistant IP (e.g., `192.168.1.50`)
* **Port**: `1883`
* **Username**: `boneio`
* **Password**: password of the created user
3. Click **Save**. A change of only these four fields needs no restart: boneIO reconnects to the new broker straight away
4. Devices will automatically appear in Home Assistant
If that broker accepts TLS, switch on **Encrypt the connection (TLS)** on the same page.
See [Encryption (TLS)](/en/docs/black/current/configuration/communication#encryption-tls).
### Installation of the boneIO Home Assistant Add-on [#installation-of-the-boneio-home-assistant-add-on]
1. Go to **Settings** → **Apps** → **Install app**
2. Click the three dots in the top right corner
3. Select Repositories
4. Add this URL: [https://github.com/boneio-eu/home-assistant-addons](https://github.com/boneio-eu/home-assistant-addons)
5. Click Add
6. Find the desired add-on and click Install
## Communication between boneIO controllers [#communication-between-boneio-controllers]
If you have multiple boneIO Black controllers and want them to execute commands on each other (e.g., a button on one controller turns on a light on another), **all controllers must be connected to the same MQTT broker**.
### Example configuration for multiple controllers: [#example-configuration-for-multiple-controllers]
1. Choose one MQTT broker (e.g., on Home Assistant or on one of the controllers)
2. Connect all controllers to the same broker
3. Each controller publishes under its own serial number (`boneio/blk…`), so there is nothing to set to keep them apart
4. In actions, you can use **Control Remote Output** and **Control Remote Cover** to control devices on other controllers
## Connection verification [#connection-verification]
After proper configuration:
1. In Home Assistant, go to **Settings** → **Devices & Services** → **MQTT**
2. You should see the **boneIO Black** device with all configured outputs, covers, inputs, and sensors
3. All entities will be automatically available in Home Assistant
The controller uses **MQTT Discovery** - all devices are automatically detected by Home Assistant without the need for manual configuration.
# Name your Inputs (/en/docs/black/sbs-name-binary-and-events)
# Why should you name them? [#why-should-you-name-them]
Naming your inputs will make working with the controller much easier. It's a lot easier to remember "Bedroom Button1" than "IN\_04", right?
## Events – event entities [#events--event-entities]
Let's start with event entities. Below is the default configuration from the file:
```
~/boneio/event.yaml
```
```yaml
- id: IN_04
boneio_input: IN_04
actions:
single:
- action: output
pin: OUT_04
- id: IN_05
boneio_input: IN_05
actions:
single:
- action: output
pin: OUT_05
- id: IN_06
boneio_input: IN_06
actions:
single:
- action: output
pin: OUT_06
```
How do you name your input? It's very simple!
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | This part of the configuration is the input name, and you can change it freely. There are many naming approaches. For example, you can change the name to `BedroomButton1` or `IN_04_BedroomButton_1`. |
| `boneio_input` | This is the input number that your name refers to. For now, ignore `actions:` – we'll discuss them later. |
Our example looks like this:
```yaml
- id: IN_04_BedroomButton_1
boneio_input: IN_04
actions:
single:
- action: output
pin: OUT_04
```
## Binary (Binary sensor) [#binary-binary-sensor]
Below is the default configuration from the file:
```
~/boneio/binary_sensor.yaml
```
```yaml
- id: IN_01
boneio_input: IN_01
actions:
pressed:
- action: output
pin: OUT_01
- id: IN_02
boneio_input: IN_02
actions:
pressed:
- action: output
pin: OUT_02
```
| Parameter | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | This part of the configuration is the input name, and you can change it freely. There are many naming approaches. For example, you can change the name to `MotionBedroom` or `IN_01_MotionBedroom`. |
| `boneio_input` | This is the input number that your name refers to. For now, ignore `actions:` – we'll discuss them later. |
Our example looks like this:
```yaml
- id: IN_01_MotionBedroom
boneio_input: IN_01
actions:
pressed:
- action: output
pin: OUT_01
```
# Upgrading from 1.5 to 1.6 (/en/docs/black/sbs-upgrade-1-5-to-1-6)
Version 1.6 is the biggest change to the panel so far: it gets accounts and passwords, the settings are reorganised and
several security settings are switched on. Your configuration — outputs, inputs, covers, actions — **stays as it is**.
Going through this list takes about ten minutes, plus the update itself — which can take up to an hour.
Not sure what is new? See [What's new in 1.6](/en/docs/black/whats-new-1-6) first.
## 1. Before the update [#1-before-the-update]
1. **Update to 1.5.6 first.** Only 1.5.6 hands the browser over to the new panel cleanly. From an older 1.5 the old panel
may keep coming back after the update until you press **Ctrl+Shift+R**.
2. **Take a backup.** In the 1.5 panel open the **System** tab, find the **Backup** section and download a backup to your computer.
The update itself does not make one. If you can, also copy the `/home/boneio/boneio` folder over SSH.
3. **Plan up to an hour, and keep the power on.** On a controller coming from 1.5 the update runs system migrations at
start-up. The display and the panel say what is happening. Do not cut the power while it runs — a
[UPS](/en/docs/black/products/black_32x10a/hardware-installation#backup-power-ups--recommended) is the safe way.
4. **Be able to reach the controller physically** — an SD card reader or a serial console. 1.6 changes how boneIO gets
administrator rights on the system. It has been run on our own controllers, but a mistake at this step is the kind
that needs hands on the device to repair.
## 2. Install the update [#2-install-the-update]
In the 1.5 panel: **System** → **Check for Updates** → **Update to 1.6.0**, or install the boneIO update in Home Assistant.
Wait for the controller to restart and finish its migrations — the display shows *Do not power off* and the progress
while they run. See [Update controller](./update-controller).
## 3. Open the panel again — now over HTTPS [#3-open-the-panel-again--now-over-https]
Open `https://:8443` and use this address from now on. An old `http://…:8090` bookmark may still open the panel,
but without encryption — step 5 switches that off.
If the browser warns about the certificate, that is expected — see
[Connect to your boneIO](./how-to-connect#the-browser-warns-about-the-connection--this-is-expected).
## 4. Create the administrator account [#4-create-the-administrator-account]
What you see depends on whether the 1.5 panel had a password:
* **You had a password in `config.yaml` (`web.auth`)** — there is **no wizard**. That account is moved over automatically:
sign in with your old username and password. The SSH password is not changed in this case; step 5 tells you if it is still `Black`.
* **You had no password** — the panel starts with a **short wizard: Start → Account → Done**. Choose a username and password for the panel
(see [First-time setup](./first-run-wizard#account) for the rules). If the SSH password of the `boneio` user was still the factory `Black`,
it becomes your new password as well.
Either way your configuration is not touched.
{/* SCREENSHOT: en_wizard_upgraded.webp — the short wizard on an upgraded controller ("This device already has its configuration…") */}
## 5. Review the security list [#5-review-the-security-list]
Right after signing in the panel shows **Security recommendations** with the number of things to look at.
Click **Review security** (or later: **Settings** → **Access** → **Security**). Each item has a short explanation and,
where the panel can fix it, a button that does it. On a controller upgraded from 1.5 you will usually see:
| Item | What to do |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Old credentials in config.yaml** | Click **Remove it** and confirm — the old password block is removed (a copy of `config.yaml` is kept first). You keep signing in as before. |
| **MQTT broker password** | The controller still connects to its broker with the factory password. Click **Fix**, set a new password for the `boneio` user and leave **Also update boneIO's own configuration** on — the controller reconnects by itself. |
| **SSH login password** | If it is still the factory one, change it in **Settings** → **Access** → **User accounts** → **SSH login password**, with the factory password as the current one. Or log in over SSH as `boneio` and run `passwd`. |
| **Panel served in the clear** | Click **Move behind the proxy** and confirm. After the next restart the panel answers only at `https://…:8443` (and still at `http://192.168.7.2:8090` over a USB cable). The change is refused if HTTPS is not working yet, so you cannot lock yourself out. |
| **HTTPS certificate** | Optional — see [HTTPS certificate](/en/docs/black/current/advanced/certificate) to get rid of the browser warning. |
{/* SCREENSHOT: en_security_after_upgrade.webp — Settings → Access → Security on a controller just upgraded from 1.5, with several outstanding items */}
Not ready now? **Remind me tomorrow** puts the prompt off by a day. Details: [Security](/en/docs/black/current/basic/security).
## 6. Check Home Assistant [#6-check-home-assistant]
* **Entities keep working** — the controller talks to Home Assistant over MQTT, and the update does not change that.
* **Changing the `boneio` broker password (step 5) does not affect Home Assistant** — Home Assistant signs in with its own account, usually `homeassistant`.
* **Worth doing:** the `homeassistant` and `mqtt` accounts on a controller from before 1.6 still have the factory password too.
Change them in **Settings** → **Services on this controller** → **MQTT broker (local)**, and then type the new password in Home Assistant:
**Settings** → **Devices & Services** → **MQTT** → **Configure**. Until you do, Home Assistant shows the boneIO entities as unavailable.
* **The boneIO Black add-on** works without any change.
* **Showing the panel in a dashboard card (iframe)?** Add your Home Assistant address in **Settings** → **Access** → **Security** →
**Embedding this panel in other sites** → **One more address you trust**. Without it the card stays empty.
## 7. Node-RED asks for a password now [#7-node-red-asks-for-a-password-now]
If you use Node-RED, it now asks you to sign in with your **boneIO administrator account**. Your flows are unchanged.
This starts once Node-RED restarts — after the next controller restart, or restart it in **Settings → Services on this controller → Node-RED**.
## 8. Things that moved [#8-things-that-moved]
The **System** tab is gone. Update, backups, restart and factory reset are in **Settings → Maintenance**;
logs and bus tools are in **Diagnostics**; the YAML editor is in **Settings → Advanced**.
See [Interface navigation](./interface-navigation) for the full map.
## 9. Optional: readable names in YAML [#9-optional-readable-names-in-yaml]
In 1.6 entries in the configuration can have a `name:` instead of an `id:` — the identifier is made from the name.
Old files with `id:` keep working, so you do not need to change anything. If you edit YAML by hand and want to switch,
see [What's new in 1.6](/en/docs/black/whats-new-1-6#readable-names-instead-of-identifiers).
## Something went wrong? [#something-went-wrong]
* **Cannot sign in / forgot the password** — reset it over SSH: [Accounts and access](/en/docs/black/current/basic/accounts#forgotten-password).
* **The controller does not start after the update** — the panel opens in recovery mode; see [Troubleshooting](/en/docs/black/current/troubleshooting#recovery-mode).
* **You want to go back** — **Settings** → **Maintenance** → **Software update** → **Available Versions** lets you install an older version.
Talk to us on Discord first: the system changes 1.6 made (for example SSH hardening) stay in place.
# Connecting Digital Inputs (/en/docs/black/advanced/connecting-digital-inputs)
## Momentary Switch [#momentary-switch]
Digital inputs are used for connecting switches and sensors. By default, they are ground-controlled.
1. Connect one of the wires from a momentary switch to the common `VDD` terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will close the circuit, which will be interpreted as an "on" signal.
### Kod yaml [#kod-yaml]
```yaml
event:
- id: MyName
boneio_input: IN_29
actions:
single:
- action: output
pin: light
action_output: toggle
```
* Simple singleclick configuration which changes light state.
## Reed switch [#reed-switch]
1. Connect one of the wires from a momentary switch to the common `VDD` (ground or +) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN03`). Do not use an input from the [list of limitations](/en/docs/black/sbs-binary-or-events#input-limitations): a reed switch may be closed when the controller starts.
3. When the reed switch is closed, the circuit will be closed, which will be interpreted as an "on" signal.
## Motion sensor [#motion-sensor]
1. Connect one wire from VDD to one of the NC terminal in motion sensor.
2. Connect second wire from NC terminal to the desired input terminal (e.g., `IN03`, not one from the [list of limitations](/en/docs/black/sbs-binary-or-events#input-limitations))
3. Connect 12V power supply to the motion sensor terminals.
4. When the motion sensor is triggered, the circuit will be closed, which will be interpreted as "motion" signal.
# SSH Connection (/en/docs/black/advanced/ssh-connection)
SSH connection allows for advanced controller configuration, access to configuration files, and executing system commands. It's useful for:
* Manual editing of YAML configuration files
* Troubleshooting
* Network configuration (e.g., static IP address)
* Operating system updates
## Prerequisites [#prerequisites]
* Controller's IP address (you can find it on the controller's display or in your router's admin panel)
* SSH client (built into Windows 10+, Linux, and macOS)
## Connection via Ethernet [#connection-via-ethernet]
### Windows [#windows]
1. Press the **Start** button
2. Type `cmd` and press **Enter**
3. In the terminal window, type:
```bash
ssh boneio@CONTROLLER_IP_ADDRESS
```
You can also use Windows Terminal: [https://github.com/microsoft/terminal](https://github.com/microsoft/terminal)
### Linux / macOS [#linux--macos]
1. Open a terminal (e.g., GNOME Terminal, XFCE Terminal, Terminal.app)
2. Type:
```bash
ssh boneio@CONTROLLER_IP_ADDRESS
```
### First connection [#first-connection]
On the first connection, you'll be asked to accept the SSH key:
```
The authenticity of host '192.168.1.100 (192.168.1.100)' can't be established.
ED25519 key fingerprint is SHA256:...
Are you sure you want to continue connecting (yes/no/[fingerprint])?
```
Type `yes` and press **Enter**.
### Login credentials [#login-credentials]
* **Username:** `boneio`
* **Password:**
* on a controller set up with version **1.6 or later** — the password you chose for the administrator account in the [first-time setup](/en/docs/black/current/install/first-run-wizard). Until the wizard is completed, SSH login with a password is not possible at all.
* on an older controller — `Black`, unless you have changed it. Change it (see below): the `boneio` user can become root.
Changing the panel password later does **not** change the SSH password — see [Changing password](#changing-password).
Logging in directly as `root` over SSH is switched off.
After three wrong passwords the connection is closed. Your computer then has to wait **five minutes** before the controller lets it connect again (the same goes for any connection you close after a wrong password), and the wait grows, up to an hour, if it keeps happening. That is what makes guessing the password hopeless. A typo followed by the right password in the same connection costs nothing.
The wait applies to your address, so everyone behind the same router waits with you. The web panel is not affected — you can still sign in there in the meantime.
## Connection via USB [#connection-via-usb]
If the controller doesn't have a network connection, you can connect via USB cable:
1. Connect a USB cable to the USB port of the controller and to your computer
2. Wait for the computer to recognize the network device
3. Your computer will receive an IP address from the `192.168.7.x` range
4. The controller will be available at `192.168.7.2`
```bash
ssh boneio@192.168.7.2
```
## Basic commands [#basic-commands]
After logging in, you can use the following commands:
### Navigate to configuration directory [#navigate-to-configuration-directory]
```bash
cd ~/boneio
```
### List configuration files [#list-configuration-files]
```bash
ls -la ~/boneio/
```
### Edit configuration file [#edit-configuration-file]
```bash
nano ~/boneio/config.yaml
```
### Restart boneIO service [#restart-boneio-service]
```bash
sudo systemctl restart boneio
```
### Check service status [#check-service-status]
```bash
sudo systemctl status boneio
```
### View logs [#view-logs]
```bash
journalctl -u boneio -f
```
## Changing password [#changing-password]
The simplest way is the panel: **Settings → Access → User accounts**, the **SSH login password** card, **Change SSH password**. It asks for the current SSH password and the new one twice — see [SSH login password](/en/docs/black/current/basic/accounts#ssh-login-password).
Over SSH, the same thing is:
```bash
passwd
```
You'll be prompted to enter the current password, then type the new password twice. If the `boneio` login has no password at all, this is the only way — the panel has no current password to check.
## Troubleshooting [#troubleshooting]
### Connection refused [#connection-refused]
* Check if the controller is powered on and connected to the network
* Make sure you're entering the correct IP address
* Check if the SSH service is running on the controller
### Connection closed at once, after earlier wrong passwords [#connection-closed-at-once-after-earlier-wrong-passwords]
If the connection is closed before you are even asked for a password, and you mistyped it shortly before, the controller is making your address wait — see [Login credentials](#login-credentials). Wait five minutes and connect again.
### Connection timeout [#connection-timeout]
* Check if your computer and the controller are on the same network
* Check your computer's firewall settings
### SSH key error [#ssh-key-error]
If you get an error related to SSH key change (e.g., after reinstalling the system on the controller):
```bash
ssh-keygen -R CONTROLLER_IP_ADDRESS
```
Then try connecting again.
# Update via SSH (/en/docs/black/advanced/update-via-ssh)
This guide describes manual controller update via SSH. It's useful when:
* You want to install a specific software version
* The web interface update doesn't work
* You need more control over the update process
**We highly recommend updating via the WebUI.** The built-in update manager in **Settings → Maintenance → Software update** provides a one-click update, and lets you install an earlier version from **Available Versions** if something goes wrong. Use SSH updates only when the WebUI is not available or you need to install a specific version.
## Requirements [#requirements]
* SSH connection to the controller (see [SSH connection guide](/en/docs/black/advanced/ssh-connection))
* Internet access on the controller
## Update process [#update-process]
### Step 1: Stop the boneIO service [#step-1-stop-the-boneio-service]
```bash
sudo systemctl stop boneio
```
Enter the SSH password of the `boneio` user. On a controller set up with version 1.6 or later, this is the password you chose in the [first-time setup](/en/docs/black/current/install/first-run-wizard).
### Step 2: Activate the virtual environment [#step-2-activate-the-virtual-environment]
```bash
source ~/boneio/venv/bin/activate
```
### Step 3: Update pip [#step-3-update-pip]
```bash
pip3 install --upgrade pip
```
### Step 4: Update boneIO [#step-4-update-boneio]
```bash
pip3 install --upgrade boneio
```
### Step 5: Start the boneIO service [#step-5-start-the-boneio-service]
```bash
sudo systemctl start boneio
```
## Simplified version [#simplified-version]
You can execute all commands in three sequences:
```bash
sudo systemctl stop boneio
```
```bash
source ~/boneio/venv/bin/activate && pip3 install --upgrade pip && pip3 install --upgrade boneio
```
```bash
sudo systemctl start boneio
```
## Installing a specific version [#installing-a-specific-version]
To install a specific version:
```bash
pip3 install boneio==1.6.0
```
Replace `1.6.0` with the desired version.
## Checking the version [#checking-the-version]
To check the currently installed version:
```bash
pip3 show boneio | grep Version
```
## Important changes [#important-changes]
When introducing important changes to the application, we always inform about them in the release notes. Please read this information carefully before updating.
## Troubleshooting [#troubleshooting]
### Error during pip installation [#error-during-pip-installation]
If you get an error related to pip, try:
```bash
python3 -m pip install --upgrade pip
```
### Application doesn't start after update [#application-doesnt-start-after-update]
Check the logs:
```bash
journalctl -u boneio -f
```
If there are configuration errors, you may need to adjust the `config.yaml` file for the new version.
Since 1.6 a controller with a broken configuration does not keep restarting — the panel opens in recovery mode instead,
where you can see the error and fix it. See [Troubleshooting](/en/docs/black/current/troubleshooting#recovery-mode).
### Upgrading from 1.5 over SSH [#upgrading-from-15-over-ssh]
After the first start of 1.6 open the panel at `https://:8443` — it asks you to create an administrator account
(if the 1.5 panel had a password in `web.auth`, sign in with it instead).
System migrations run by themselves on that first start. See [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6).
# Hardware Installation (/en/docs/black/hw-guide-comm-adc-legacy)
#### Controllers before version 1.0 (no SERVICE port) [#controllers-before-version-10-no-service-port]
On these controllers the terminals go straight to the BeagleBone Black processor. **Never apply more than 1.8 V** — a higher voltage
damages it. A sensor with a higher output needs an external voltage divider.
* The sensor takes its power from the **ADC PWR** terminal: **+** is the 1.8 V ADC reference, **GNDA** the analog ground.
The terminal marked **X** is not connected.
* The default filter (**multiply** by 1.8) shows the voltage on the terminal.
The diagram below is for controllers before 1.0.
# Hardware Installation (/en/docs/black/hw-guide-comm-adc)
### Analog Inputs ADC [#analog-inputs-adc]
Analog inputs read sensors that give a voltage instead of on/off — level, humidity or pressure transmitters and the like.
boneIO Black has 7 of them, **ADC 1**–**ADC 7**. How they are wired depends on the controller version: controllers from **1.0** have a
**SERVICE** port next to **POWER**, older ones do not.
#### Controllers from version 1.0 (with a SERVICE port) [#controllers-from-version-10-with-a-service-port]
* Every input has its own protected, buffered input stage, so it takes **0–13.8 V** on the terminal — a 0–10 V transmitter
connects without an external divider.
* The terminal marked **X** next to **ADC 1** is **AGND**, the analog ground. Connect the sensor's ground there.
* These controllers have no **ADC PWR** terminal.
* The default filter (**multiply** by 1.8) shows the voltage after the input stage, about 0.13 of the voltage on the terminal.
To read the voltage on the terminal itself, set **multiply** to **13.8**. See [ADC](/en/docs/black/current/configuration/adc).
**Examples:**
* **0–10 V transmitter** (humidity, pressure, level…): **+24V** from the **POWER** terminal to the transmitter's supply,
its output to an ADC terminal, its ground to **X (AGND)**. With **multiply** set to **13.8** the panel shows 0–10 V.
* **NTC 10 kΩ thermometer:** from **+3.3V** (the I²C terminal) through the NTC to an ADC terminal, and a 10 kΩ resistor
from that terminal to **X (AGND)**. The terminal never sees more than 3.3 V. The panel shows a voltage, not a temperature —
the app has no thermistor curve, so convert it in Home Assistant. With **multiply** at **13.8**, the NTC's resistance is
`R = 9.2 kΩ × (3.3 − U) / U`, where `U` is the reading in volts and 9.2 kΩ is the 10 kΩ resistor in parallel with the
input's own 115 kΩ. The temperature follows from the NTC's B value in its datasheet.
* **The same thermometer from +5V:** the NTC takes **+5V** from the **1-WIRE** block instead, the 10 kΩ resistor stays.
A higher supply gives a larger swing per degree, so a finer reading. The terminal never sees more than 5 V, and the
resistance is `R = 9.2 kΩ × (5 − U) / U`. That +5V also powers the 1-Wire sensors; the NTC draws about 0.3 mA.
Ground the sensor on **X (AGND)** rather than on any GND terminal: it is the same ground, but on its own path, so the
current of the relays and the processor does not flow through the wire the voltage is measured against.
# boneIO Black App (/en/docs/black/current)
## Introduction [#introduction]
In this section, you will find the application documentation for your boneIO Black. To help you easily step into the world of boneIO Black, we have divided the documentation into several segments. On this page, you will find a brief description of each. The documentation consists of 4 parts:
* Quick Start
* Operation
* Configuration
* Advanced
It is extremely important to read through all of it before starting the device configuration. This will significantly speed up the entire process and help you avoid many potential mistakes during the controller deployment.
At the very end of this document, you will find information on what our application actually is.
## Quick Start [#quick-start]
Here you will find short, quick, step-by-step instructions for getting your controller up and running in no time – the same instructions can be found on the controller's product page. This is the place where you should start your journey with the controller.
Configuring the connection to the controller
Configuring the connection to Home Assistant
Description of menus and tabs in the boneIO web interface
Learn how to update the boneIO Black controller.
How to use the configuration forms in the Settings tab
How to properly configure areas/rooms in boneIO
Which one to choose and what are the main differences?
How to configure events and actions in boneIO Black.
How to configure binary sensors in boneIO Black
## Operation [#operation]
This section contains an overview and description of the entire controller interface. Here you will find an overview of what can be found in individual webui segments. Thanks to it, you will know what and where you should look for.
MQTT connection configuration
Web interface configuration
Basic configuration of the boneIO controller
Logging configuration
OLED display configuration
Modbus protocol configuration
MCP23017 expander configuration
PCF8575 expander configuration
PCA9685 expander configuration
## Configuration [#configuration]
This section describes the configuration process. Here you will find all the controller modules and guides on how to approach their setup process.
Controller Application configuration
Areas/Rooms configuration
Binary sensors configuration
Event entities configuration
Outputs configuration
Output groups configuration
Covers configuration
Remote devices configuration
Templates setup
Irrigation template configuration
Modbus sensors configuration
Onewire sensors configuration
Virtual energy sensors configuration
Logging configuration
Basic configuration of the boneIO controller
MQTT connection configuration
Web interface configuration
Modbus protocol configuration
MCP23017 expander configuration
### Advanced [#advanced]
# Modbus helper (/en/docs/black/current/modbus_helper)
Modbus helper is builtin tool in boneio to:
* read any register from connected modbus device
* in CWT sensors to set correct baudrate or set new device address as all of the devices by default comes with address 1.
Note:
remember to always use installed venv
```bash
source ~/boneio/venv/bin/activate
```
## Main command [#main-command]
Always use help. As we use Python 3.7 command is nested.
```
# boneio --help
usage: boneio [-h] [--version] {run,modbus} ...
boneIO app for BeagleBone Black.
positional arguments:
{run,modbus}
```
There are 3 main modbus commands.
GET, SET and SEARCH
Before you give this positional argument set arguments named optional (even though those aren't optional).
```
# boneIO modbus --help
usage: boneio modbus [-h] [--debug] --uart {uart1,uart4} --address ADDRESS
--baudrate {2400,4800,9600,19200} --bytesize BYTESIZE
--stopbits STOPBITS --parity {P,E,N}
{set,get} ...
positional arguments:
{set,get}
optional arguments:
-h, --help show this help message and exit
--debug, -d Start boneIO in debug mode
--uart {uart1,uart4} Choose UART
--address ADDRESS Current device address (hex or integer)
--baudrate {1200,2400,4800,9600,19200}
Current baudrate
--bytesize BYTESIZE Bytesize
--stopbits STOPBITS stopbits
--parity {P,E,N} Parity
```
### Get command help [#get-command-help]
```bash
usage: boneio modbus get [-h] --register-address REGISTER_ADDRESS
--register-type {input,holding} --value-type
{U_WORD,S_WORD,U_DWORD,S_DWORD,U_DWORD_R,S_DWORD_R,U_QWORD,S_QWORD,U_QWORD_R,FP32,FP32_R}
optional arguments:
-h, --help show this help message and exit
--register-address REGISTER_ADDRESS
Register address
--register-type {input,holding}
Register type
--value-type {U_WORD,S_WORD,U_DWORD,S_DWORD,U_DWORD_R,S_DWORD_R,U_QWORD,S_QWORD,U_QWORD_R,FP32,FP32_R}
Value types
```
Example GET command:
```bash
boneio modbus --address 61 --baudrate 9600 --uart uart4 -dd get --register-address 0 --register-type holding --value-type S_WORD
```
### Set command help [#set-command-help]
```bash
usage: boneio modbus set [-h] [--custom-value CUSTOM_VALUE]
[--custom-register-address CUSTOM_REGISTER_ADDRESS]
--device {cwt,r4dcb08,liquid-sensor,sht20,custom}
[--new-address NEW_ADDRESS | --new-baudrate {1200,2400,4800,9600,19200}]
optional arguments:
-h, --help show this help message and exit
--custom-value CUSTOM_VALUE
Set Custom value
--custom-register-address CUSTOM_REGISTER_ADDRESS
Register address for custom value
--device {cwt,r4dcb08,liquid-sensor,sht20,custom}
Choose device to set modbus address/baudrate. For
custom you must provide --custom-value and --custom-
register-address
--new-address NEW_ADDRESS
Set new address (hex or integer / 1 - 253/)
--new-baudrate {1200,2400,4800,9600,19200}
Choose new baudrate to set. CWT doesn't work on 1200.
```
Example command to set new baudrate to 9600
```bash
boneio modbus --address 61 --baudrate 4800 --uart uart4 set --device cwt --new-baudrate 9600
```
Example command to set new address
```bash
boneio modbus --address 1 --baudrate 9600 --uart uart4 set --device cwt --new-address 61
```
### Search for Modbus device [#search-for-modbus-device]
You'd need to know at least specification of the device and register address on which it responds and type of this register.
```bash
usage: boneio modbus search [-h] --register-address REGISTER_ADDRESS
--register-type {input,holding}
optional arguments:
-h, --help show this help message and exit
--register-address REGISTER_ADDRESS
Register address
--register-type {input,holding}
Register type
```
Example command:
```bash
boneio modbus -dd --baudrate 9600 --uart uart4 search --register-address 1 --register-type input
```
**Always reboot device by powering it down and up after set operation**
# Troubleshooting (/en/docs/black/current/troubleshooting)
Most useful command to check boneio app running with systemd.
boneIO won't start.
```bash title="Check if service is running"
systemctl status boneio
```
There are some logs which might indicate what the problem is.
Always check your config, if yaml is properly formatted.
```bash title="Check service logs"
journalctl -u boneio --all
```
```bash title="Check service logs live"
journalctl -u boneio --all -f
```
You might need to customize logger.
Check [Logger page](./configuration/logger) and then press reload logger button in Home Assistant.
## Common problems since version 1.6 [#common-problems-since-version-16]
### The browser warns that the connection is not private [#the-browser-warns-that-the-connection-is-not-private]
This is expected: the controller uses a certificate it issued itself. Click through the warning (see
[Connect to your boneIO](/en/docs/black/current/install/how-to-connect)), or get rid of it for good — see [HTTPS certificate](/en/docs/black/current/advanced/certificate).
### I see a wizard instead of the panel [#i-see-a-wizard-instead-of-the-panel]
The controller has no administrator account yet — complete the [First-time setup](/en/docs/black/current/install/first-run-wizard).
Until then the display briefly shows `SETUP REQUIRED` every time the controller starts.
### I cannot sign in / I forgot the password [#i-cannot-sign-in--i-forgot-the-password]
Wait a few minutes if you have tried many times — repeated wrong passwords are slowed down (ten attempts per five minutes).
To reset a password, log in over SSH and run `boneio accounts reset ` — see [Accounts and access](/en/docs/black/current/basic/accounts#forgotten-password).
### I do not see Settings or Diagnostics [#i-do-not-see-settings-or-diagnostics]
You are signed in with a **read-only** account. Sign in as an administrator.
### Home Assistant shows the boneIO entities as unavailable after I changed an MQTT password [#home-assistant-shows-the-boneio-entities-as-unavailable-after-i-changed-an-mqtt-password]
Home Assistant still uses the old password. In Home Assistant open **Settings** → **Devices & Services** → **MQTT** → **Configure**
and type the new one. See [Home Assistant connection](/en/docs/black/current/install/home-assistant-connection).
### The panel card in my Home Assistant dashboard is empty [#the-panel-card-in-my-home-assistant-dashboard-is-empty]
Since 1.6 only the controller itself may show the panel in a frame. Add your Home Assistant address under **One more address you trust** in **Settings** → **Access** → **Security** →
**Embedding this panel in other sites**, save, and restart boneIO. The boneIO Black add-on does not need this.
### A red banner says a system update was refused [#a-red-banner-says-a-system-update-was-refused]
The reason is printed in the banner and in **Settings** → **Maintenance** → **System migrations** (the banner's button opens Software update, not the migrations). Download the support bundle
(**Diagnostics** → **Support** → **Download diagnostics**) and send it to us on Discord.
### After a power cut the page says "boneIO is starting…" [#after-a-power-cut-the-page-says-boneio-is-starting]
That is normal: the controller is still starting. The page refreshes itself every few seconds and opens the panel on its
own — usually within a minute or two of power coming back. You do not need to press anything.
### The display says "Updating" and "Do not power off." [#the-display-says-updating-and-do-not-power-off]
Or **Updating system** with a percentage, if the display is not set up in the configuration. The controller is applying system migrations after an update, and shows how far it has got. On a controller several
versions behind this can take many minutes; the panel does not answer meanwhile. Let it finish — do not unplug it.
### A system update was interrupted [#a-system-update-was-interrupted]
If the power went off or the controller restarted during an operating system update, the **Operating system** card says
**The system update was interrupted**. Do not restart the controller; click **Update system** again — see
[Maintenance → Operating system](/en/docs/black/current/basic/system#operating-system).
## Recovery mode [#recovery-mode]
If the configuration contains an error, or boneIO crashes three times in a row while starting, the controller does not keep restarting.
It opens a small **recovery panel** instead, at the usual address. The display shows **Recovery mode** and the address to open.
{/* SCREENSHOT: en_recovery_panel.webp — the recovery panel: "boneIO could not start" with the error location and the Config files tab */}
{/* SCREENSHOT: recovery_oled.webp — photo of the OLED showing "Recovery mode" */}
Sign in with your administrator account. The recovery panel shows **what went wrong** — for a configuration error, the file, line and column — and offers:
* **Config files** — the YAML files in an editor, opened at the faulty line; **Check config** tests your fix the same way a start would, **Save** stores it,
* **Log** — the service log (passwords removed),
* **Backups** — restore an earlier configuration; the current files are archived as a new backup first,
* **Restart boneIO** — try a normal start again.
Your outputs, buses and the MQTT broker are left alone while the recovery panel is open. If the recovery panel opened because boneIO kept crashing, the controller tries a normal start by itself after ten minutes with nobody using the panel.
A configuration error is not retried: fix it and click **Restart boneIO**.
The recovery panel needs an administrator account; on a controller that has none, fix the configuration over SSH.
The recovery panel is in English only.
# Basic Concepts (Glossary) (/en/docs/black/introduction/basic-concepts)
Welcome to the world of the smart home! Below you will find explanations of the most important concepts that will help you understand how our devices work and how to use them to their full potential.
## Electrical and Hardware Concepts [#electrical-and-hardware-concepts]
### Relay [#relay]
A remotely controlled, electromechanical switch. Its job is to physically open and close an electrical circuit (e.g., turn a 230V light on and off) in response to a low-voltage control signal from the controller's processor. It's the heart of every output (OUT) on a boneIO device.
### Digital Input [#digital-input]
The "sense" of the controller. A port (e.g., IN01) where you connect a wall switch or a sensor. It registers two states: low (no signal) and high (signal present), informing the processor that a button has been pressed.
### Ground-controlled (GND) [#ground-controlled-gnd]
This is the most common and recommended method for controlling digital inputs on boneIO devices. Activating an input (e.g., by pressing a button) involves **connecting the input pin (IN) to the power supply's ground (GND)**. The device's processor detects this drop in potential as an active signal. This method is very safe and resistant to electrical interference.
### Plus-controlled (+VCC) [#plus-controlled-vcc]
An alternative control method. In this case, activating an input involves **applying the positive supply voltage** (e.g., +12V or +24V, depending on the power supply model) **to the input pin (IN)**. The input is active when a high-potential current flows through it.
### Momentary Switch (Bell-Press) [#momentary-switch-bell-press]
A push-button that returns to its original position after being pressed (like a doorbell). **This is the recommended type of switch for use with boneIO** because it allows the software to recognize single-clicks, double-clicks, and long-presses.
### Bistable Switch (Latching/Toggle) [#bistable-switch-latchingtoggle]
A traditional ON/OFF light switch that has two stable positions. Using it with boneIO is possible but limits its functionality to a simple on/off action.
### Star Topology [#star-topology]
A wiring method where each point (lamp, switch) is connected by a separate cable directly to a central location—the electrical cabinet where the controller is located. This is required for boneIO to function correctly.
### Bus Topology [#bus-topology]
A wiring method where devices (e.g., for Modbus communication) are connected sequentially in a daisy-chain fashion, from one device to the next, using a single continuous cable.
### DIN Rail [#din-rail]
A standardized metal mounting rail used in electrical cabinets worldwide. All main boneIO modules are designed to be mounted on a DIN rail.
## Software and Automation Concepts [#software-and-automation-concepts]
### Home Assistant (HA) [#home-assistant-ha]
A free and open-source platform for creating a smart home system. It acts as the "brain" of the entire operation, connecting devices from different manufacturers, including boneIO, and allowing you to create advanced rules and automations.
### Integration [#integration]
The process of connecting two different systems or devices so they can work together. In our case, this most often refers to connecting a boneIO controller to the Home Assistant platform.
### Entity [#entity]
A basic "object" in Home Assistant that represents a single device, sensor, or piece of information. For example, a lamp connected to output OUT01 will appear in HA as a `light.living_room_lamp` entity, which you can control.
### Automation [#automation]
A set of rules that execute automatically when specific conditions are met. A simple example: **IF** the sun has set **AND** the motion sensor detects motion, **THEN** turn on the hallway light.
### Scene [#scene]
A saved state of one or more entities. Unlike an automation, a scene has no trigger—it simply sets devices to a predefined state. Example: A "Movie Night" scene might set the main light to 20% brightness and the LED strip to blue.
## Network and Communication Concepts [#network-and-communication-concepts]
### Web Interface [#web-interface]
A website built into the boneIO controller, accessible via a web browser by entering the device's IP address. It allows for basic configuration and control without needing to install any additional systems.
### IP Address [#ip-address]
A unique number that identifies a device on a computer network (e.g., `192.168.1.55`). It is necessary to access the controller's web interface.
### Modbus RTU [#modbus-rtu]
A communication protocol often used in industrial and building automation to communicate with devices such as heat recovery ventilators (HRVs), heat pumps, or energy meters.
# boneIO Black vs ESP (/en/docs/black/introduction/comparison)
# boneIO Black vs ESP [#boneio-black-vs-esp]
Wondering which controller version to choose? boneIO Black? ESP? Or maybe both? The following comparison focuses on showing the key differences between the controllers, as well as highlighting the strongest points of each series.
## Introduction [#introduction]
Both versions of boneIO controllers are independent home automation platforms that can operate completely autonomously – without the need for a Home Assistant server connection. Although they have different architectures and capabilities, their purpose is very similar. Below is a detailed comparison of their capabilities.
## Comparison Table [#comparison-table]
| Feature | boneIO Black | boneIO ESP |
| :-------------------------------- | :------------------------------------------------- | :------------------------------------------------------- |
| **Software base** | Dedicated - modified Debian 13 system (Linux) | Compiled program from ESPHome |
| **Configuration method** | Graphical Interface (Web UI / PWA) | Text editor (YAML files) |
| **Boot speed** | Slower (loading Debian OS) | Instant |
| **Network and connectivity** | Ethernet | Ethernet and WiFi\* |
| **Width on DIN rail** | 15 DIN modules | 12 DIN modules |
| **Number of physical inputs** | 49 inputs | 35 inputs |
| **Application in HA** | Yes (configuration, management, and backups) | Yes (ESPHome Device Builder) |
| **Modbus** | Significantly more devices, predefined in code\*\* | Fewer devices, but ability to manually add your own YAML |
| **Additional logic environments** | Built-in Node-Red, Mosquitto | None |
| **Schedules and sun events** | Built in, set in the panel, with run history | In YAML (`time`, `sun`), recompile after each change |
| **Presence simulation** | Built-in wizard | No ready-made feature |
| **Alarm, irrigation, thermostat** | Ready-made, configured in the panel | ESPHome components, written in YAML |
| **Applying a change** | Seconds, nothing to compile | Compile and upload the firmware |
| **Accounts and security** | Admin and read-only accounts, HTTPS, Security page | Web server password, API encryption key |
| **Updates** | boneIO, Debian and kernel from the panel | Firmware over the air from ESPHome Device Builder |
| **Loxone** | Lox UDP (experimental) | Through custom components available online |
*\* Using a WiFi connection in a closed metal distribution board or electrical cabinet is not recommended due to strong signal attenuation.*\
*\*\* The device is equipped with an application that allows for preparing your own Modbus configurations. After preparing the configuration, adding it to the software should not take more than 48 business hours.*
***
## Architecture and Software [#architecture-and-software]
* **System and compilation:** **boneIO Black** is based on a specially prepared Linux distribution (Debian 13) – which has been additionally modified by us. Unnecessary elements were removed, leaving a lightweight, coherent core and essential packages – ensuring incredible stability. Using the Debian system translates into vast capabilities, at the cost of a noticeably longer device boot time from the moment power is applied (a fully advanced operating system must load: inputs and outputs work after about a minute, the panel shortly after).
The **boneIO ESP** version relies on uploading firmware from ESPHome. Its compilation and flashing (uploading to the microprocessor) on a computer is somewhat time-consuming, but this pays off with nearly instant device startup! After a power restart, the controller is ready for immediate action almost instantly (about 5 seconds).
* **Open Source:** The **ESP** solution on the logic side is based on an Open Source project – **ESPHome**, backed by a massive community. What is extremely important from a potential user's perspective, all original boneIO software managing the **boneIO Black** model, built on the Linux system architecture (as well as our operating system itself), also remains 100% free and fully Open Source software!
* **Independence from Home Assistant:** Both controllers are fully intelligent and autonomous, capable of executing rules set on them locally without the requirement of maintaining a connection to the Home Assistant server.
## Configuration and Management [#configuration-and-management]
* **User Interface:** All configuration and management of the **boneIO Black** series takes place through an extensive and extremely intuitive **graphical interface**. Additionally, the application managing boneIO Black supports the PWA standard, which means you can easily pin the controller interface as a native application to your smartphone's home screen for easy access. Interacting with the controller is very simple and straightforward. On the other hand, the **ESP** platform is based on YAML code syntax; although this can be more complicated for a layman, in large and complex installations, it allows ESP to implement ready-made logic templates and repeatable entities of various types much more simply and flexibly.
* **Management via HA:** The **boneIO Black** platform has its own, officially prepared **Application** within the Home Assistant ecosystem, which allows for easy controller management. It brings our proprietary application inside HA. From within it, you can also **create backups of the controller** – without this Application, the user must manually take care of downloading and storing backups. For the **ESP** platform, the configuration is always stored on the ESPHome Device Builder server, so it is important to regularly back up that application.
* **Multiclick Function:** Due to higher performance and design differences, multiclick functions react and work noticeably faster in the **boneIO Black** model. Additionally, it offers sequences as well as a much easier configuration process.
* **Output grouping:** **boneIO Black** natively supports grouping outputs into light and switch groups, which are immediately visible as separate entities in Home Assistant. This allows easy control of, for example, an entire group of lights in a room with a single button. The **ESP** platform does not support output grouping within the device – this kind of logic must be handled on the Home Assistant side.
## Ready out of the box, without programming [#ready-out-of-the-box-without-programming]
What would be a YAML project on ESP is a form in the **boneIO Black** panel — saved in seconds, with nothing to compile or upload:
* **Schedules and the sun** — actions at a clock time or at sunrise, sunset and the twilights, with an offset, a random spread, conditions and earliest/latest bounds. Each schedule shows its next run and its history, and appears in Home Assistant as a switch. See [Schedules](/en/docs/black/current/configuration/schedule).
* **Presence simulation** — answer four questions and an empty house looks lived in: in the evening the lights go on room by room. See [Presence simulation](/en/docs/black/current/configuration/presence_simulation).
* **Virtual switches** — modes such as *Away* or *Evening* that other actions depend on, with no relay behind them.
* **Alarm, irrigation, thermostat, energy counters** — ready-made functions configured in the panel.
* **Secure from the first start** — the panel over HTTPS, accounts with an administrator and a read-only role, no default passwords, and a Security page that says what is still worth fixing. 1.6 is our work of adapting boneIO Black towards the EU Cyber Resilience Act (CRA).
* **Looks after itself** — boneIO, Debian and the kernel update from the panel; backups, a diagnostics bundle you can send us, and a recovery mode when a configuration does not load.
## Communication and Ecosystem [#communication-and-ecosystem]
* **Control between devices:** As a kind of central controller, the **boneIO Black** model can control other boneIO Black series controllers by sending them notifications via the MQTT broker, as well as control other modules from the ESP world by communicating with them directly through the native, local ESPHome API interface. Furthermore, it can also natively control devices dedicated to controlling addressable LED strips with WLED software (effectively allowing, for example, a "single click" of a wall button to be assigned to an instant scene initiation action from the WLED controller). Meanwhile, simple and single-task-focused controllers from the ESP family can freely communicate with each other thanks to UDP. ESP series devices cannot issue control commands to boneIO Black controllers.
* **Built-in Node-Red:** The **boneIO Black** system comes equipped with Node-Red as standard, providing a visual, full-featured, powerful tool that enables the creation of extremely complex automations within the controller itself. It is extremely useful in situations where we want to make part of the automation independent of HA. It can also be an alternative approach for the installer, making a large part of the system independent of "higher" control layers.
* **Network Connections:** boneIO Black series devices communicate exclusively via a wired Ethernet port. ESP optionally allows for WiFi connectivity. However, due to the conditions in metal electrical distribution boards, it is used very rarely.
## Modbus and Hardware Dimensions [#modbus-and-hardware-dimensions]
* **Case size:** Due to a much more powerful SOC, as well as a larger number of inputs in **boneIO Black** models, they take up slightly more space in the distribution board – 15 DIN standard poles. For those with less space, the ESP model taking up 12 DIN may prove to be a better choice.
* **Signal connectors (IO Peripherals):** Naturally, the case size translates into a larger number of available digital inputs. boneIO Black allows for connecting up to 49 of them, whereas in the case of the ESP model, we are talking about 35 inputs.
* **Modbus RS485 bus performance:** **boneIO Black** is able to handle a larger number of devices with a higher polling frequency. Thanks to the processor's multithreading, it is able to maintain high performance of other functions while polling Modbus devices.
***
## Hybrid Installations – unlock the potential! [#hybrid-installations--unlock-the-potential]
When creating the architecture of a modern smart home, it is worth considering a **hybrid** model. Creating a hybrid installation is the most optimal solution in terms of reliability and resource balance:
* Core – managing the smart home system, lights, and buttons should be moved towards the more efficient and versatile **boneIO Black** model.
* The remaining parts of the system, e.g., reading states from motion sensors, reed switches, motor control – moving gates, window shutters, garden sprinklers – are worth moving to the **ESP** platform.
# Philosophy (/en/docs/black/introduction/philosopy)
Welcome to the world of boneIO! If you're here, it means that, like us, you believe a smart home should be truly *yours*. Not just convenient, but also reliable, private, and fully customized to your needs.
Our mission is to provide a solid foundation for your smart home. Our philosophy is built on four core pillars:
## 1. Local First Control [#1-local-first-control]
Your data, your rules, your home. boneIO devices are designed to work 100% within your local network. Communication is based on the universal **MQTT** protocol, which ensures full compatibility with the most popular and advanced Smart Home system – **Home Assistant** – our controller provides this "out of the box." Internal automations and **Home Assistant** compatibility mean that even if you lose your internet connection, your home will still function, and your privacy will remain intact.
## 2. Power and Openness [#2-power-and-openness]
Our boneIO Black series controllers are based on the powerful **BeagleBone Black** industrial computer. This gives you enormous flexibility and processing power. We provide open communication via MQTT, allowing integration with **Home Assistant** and other smart home platforms. For the most demanding users, we offer the ability to run **Node-RED** directly on the device, enabling the creation of complex automations in the unit itself.
## 3. Centralization and Reliability [#3-centralization-and-reliability]
Simplicity and power - thats our goals. A single **boneIO** controller, with its high number of inputs and outputs, is capable of handling the automation for an entire house. This centralized approach, based on professional DIN rail mounting, not only guarantees reliability and ease of maintenance but also significantly simplifies your entire smart home setup.
## 4. Support and Community [#4-support-and-community]
We believe that a great product is just the beginning. Our passion is helping our users bring their smart home vision to life, and we don't leave you on your own after the purchase. We are always happy to share our knowledge, answer questions, and help solve problems—from simple setups to complex automation scenarios.
Join our active community to get help and share your experiences:
* **Forum:** [https://forum.boneio.eu](https://forum.boneio.eu)
* **Discord:** [https://discord.gg/Hm2CzSjvtu](https://discord.gg/Hm2CzSjvtu)
With **boneIO**, you are building a system that is stable, centralized, and perfectly tailored to your needs. It's also sync with **Home Assistant** perfectly!
Let's dive in!
# System and Installation Requirements (/en/docs/black/introduction/requirements)
Before you proceed with the installation, please review the list of requirements below. This will ensure a smooth setup process for your boneIO controller and allow you to use all of its features. Most importantly, **remember that your controller works immediately after connecting the power, even without a network connection!**
## 1. Electrical Requirements [#1-electrical-requirements]
This is the most critical section, essential for the safety and proper operation of the device.
* **Power Supply:** A stabilized DC voltage of 24V DC. The power supply should have sufficient current capacity.
* **Backup power (recommended):** Power boneIO Black from a 24 V UPS or a buffered power supply with a battery. It keeps the controller running through short mains cuts and brownouts, keeps its clock right (boneIO Black has no battery-backed clock) and protects a system update from a power cut. See *Backup power (UPS)* on your product's Hardware Installation page.
* **Mounting Location:** A dry space, protected from moisture, most commonly a DIN rail within an electrical cabinet (distribution board).
### Wiring Topology [#wiring-topology]
A correct wiring layout is the foundation of a stable system.
* **Power Installation (230V/110V):** The power circuits for loads (e.g., lighting, controlled outlets) must be laid out in a **star topology**. This means each circuit is run as a separate cable directly from the electrical cabinet to the endpoint.
* **Input Installation (Switches/Sensors):** The signal cables for the inputs must also be laid out in a **star topology**. Each switch or sensor should be connected with a separate cable back to the electrical cabinet.
* **Recommended Cable for Inputs:** We recommend using **twisted-pair cable (e.g., Cat 5e or Cat 6)** to connect your switches and sensors. The controller's inputs operate on safe, low voltage.
* **Modbus RTU Installation:** If you plan to connect devices via Modbus, the wiring for this connection must be laid out in a **bus topology (daisy-chain)**.
* **Separation from Power Cables (Avoiding Interference):** To ensure error-free communication and system stability, strictly avoid running signal wires (Modbus, buttons, sensors) parallel to 230V power cables.
* Maintain a minimum distance of 30 cm when running them in parallel.
* If the cable paths must cross, do so only at a right angle (90°).
### Recommended Switches (Push-Buttons) [#recommended-switches-push-buttons]
For controlling lights and other functions, **we strongly recommend using momentary (monostable or bell-press) switches**.
**Why?** Only this type of switch allows you to take full advantage of the boneIO software's capabilities and enables **multi-click functionality**. The controller can then differentiate between various types of presses, which opens the door to advanced automations:
* **Single-click:** Standard on/off for a light.
* **Double-click:** Trigger a lighting scene, e.g., "movie mode" (30% brightness).
* **Long-press:** Trigger any other custom automation.
Using traditional bistable (latching ON/OFF) switches is technically possible, but it limits control to the basic on/off function and makes multi-click actions completely impossible.
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> In accordance with applicable regulations and to ensure complete safety, all activities related to the electrical installation **must be performed exclusively by a qualified electrician holding the appropriate certifications**.
## 2. Network Requirements [#2-network-requirements]
A network connection is not required for basic operation, but it is essential for configuration and remote control.
* **LAN Connection:** A free Ethernet port on your router or switch is required for operation.
* **Wi-Fi Connection (Optional):** Access to a stable 2.4 GHz Wi-Fi network.
* **Router Access:** The ability to log in to your router's admin panel to find the controller's IP address.
**Construction Time Tip:** Don't have your final internet connection yet? No problem. The controller does not require a permanent network connection for basic operation. For remote management and on-site configuration, it's enough to create a temporary Wi-Fi hotspot on your phone and connect the controller to it.
## 3. Required Tools [#3-required-tools]
* A precision screwdriver, a wire stripper, and wire cutters.
* A wire ferrule crimper.
* **A Multimeter**.
* A computer or phone for configuration.
## 4. System Requirements [#4-system-requirements]
The boneIO Black series operates based on the **MQTT** protocol out-of-the-box, allowing it to work with almost any smart home system that supports MQTT.
* **Recommended Platform: Home Assistant**
For the best experience, we recommend **Home Assistant**, as it supports auto-discovery for boneIO Black devices, making integration seamless.
* **Other Platforms**
You can integrate with any other system (like openHAB, Domoticz, etc.) by manually configuring MQTT entities based on the topics provided in the device documentation.
* **Loxone (experimental)**
boneIO Black also supports, experimentally, the **Lox UDP** protocol, compatible with Loxone devices: it sends the state of outputs and inputs to a Loxone Miniserver and takes commands from it, with a template ready to import into Loxone Config. See [MQTT and Loxone](/en/docs/black/current/configuration/communication#loxone-udp).
## 5. Required Skills [#5-required-skills]
* **User:** Basic computer skills and an understanding of networks and the MQTT protocol.
* **Installer (Electrician):** Full certification to work with electrical installations, the ability to read schematics, and knowledge of safety principles.
# Safety and Installation Requirements (/en/docs/black/introduction/safety)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
# Philosophy (/en/docs/edge/introduction/philosopy)
Welcome to the world of boneIO! If you're here, it means that, like us, you believe a smart home should truly be *yours*. Not just convenient, but also reliable, private, and fully tailored to your needs.
Edge series devices allow your boneIO ecosystem to extend beyond the electrical panel. Listening to the expectations of our users, we created devices you've been waiting for! When designing these devices, we followed our unwavering philosophy, which is based on four main pillars:
## 1. Local Control First [#1-local-control-first]
Your data, your rules, your home. boneIO Edge devices are designed to work 100% within your local network.
## 2. Openness [#2-openness]
Our Edge series devices communicate using universal protocols such as RS485 and an ISO 11898-2 compliant interface (connector labeled CAN), ensuring seamless compatibility with our controllers as well as a wide range of other systems. Instead of locking you into one system, we provide open communication that allows integration with any smart home platform.
## 3. Reliability [#3-reliability]
We believe in simplicity. A single boneIO Edge series device, thanks to its simple and well-thought-out design, perfectly complements the boneIO ecosystem in places where a binary signal is not enough. This approach, based on professional communication buses, not only guarantees reliability but also significantly simplifies the entire smart home configuration.
## 4. Support and Community [#4-support-and-community]
We believe that a great product is just the beginning. Our passion is helping users realize their vision of a smart home, and we don't leave you on your own after purchase. We are always happy to share knowledge, answer questions, and help solve problems — from simple configurations to complex automation scenarios.
Join our active community to get help and share your experiences:
* **Forum:** [https://forum.boneio.eu](https://forum.boneio.eu)
* **Discord:** [https://discord.gg/Hm2CzSjvtu](https://discord.gg/Hm2CzSjvtu)
With boneIO, you build a system that is stable, can operate within a single ecosystem, and at the same time perfectly adapts to your needs. Additionally, it is perfectly integrated with your Home Assistant.
Let's get started!
# System and Installation Requirements (/en/docs/edge/introduction/requirements)
Before you begin installation, review the requirements below. This will ensure a smooth configuration process for your boneIO Edge devices and allow you to take advantage of all their features.
Addressing????
## 1. Electrical Requirements [#1-electrical-requirements]
This is the most important section, crucial for safety and proper device operation.
* **Power Supply:** Edge series devices are powered by low voltage, i.e., depending on the device, 5-24V DC. The power supply should have adequate current capacity.
* **Installation Location:** Unlike the "large" boneIO devices, Edge devices can be installed outside the control cabinet area.
### Wiring Topology [#wiring-topology]
Proper wiring layout is the foundation of a stable system.
* **5-24 VDC Power Installation:** Power circuits for Edge devices can be run in either a **bus** or **star** topology. This means each circuit in the power area can be routed with a separate cable directly from the distribution panel to the endpoint, or in series as a bus. Keep in mind the potential **voltage drop** if the power supply is also in a bus configuration.
* **Recommended Cable for Edge Devices:** We recommend using **twisted pair cable (e.g., Cat 5e or Cat 6)** for connection.
* **Communication — Modbus RTU, ISO 11898-2 Compliant Interface:** Edge series devices use wiring for communication that must be run in a **bus (daisy-chain) topology**.
* **Separation from Power Cables (Avoiding Interference):** To ensure error-free communication and system stability, strictly avoid running signal cables (Modbus, ISO 11898-2 compliant interface) parallel to 230V power cables.
* Maintain a minimum distance of 30 cm when running in parallel.
* If cable routes must cross, do so only at a right angle (90°).
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> In accordance with applicable regulations and to ensure full safety, all electrical installation work **must be performed exclusively by a qualified electrician with appropriate certifications**. Although Edge series devices are powered by so-called safe voltage, they are in the direct vicinity of dangerous 230V AC voltage!
## 2. Network Requirements [#2-network-requirements]
A network connection is not required for basic operation but is essential for configuration and remote control.
to change address etc.
* **LAN Connection:** A free Ethernet port on your router or switch is required for operation.
* **Wi-Fi Connection (optional):** Access to a 2.4 GHz wireless network.
* **Router Access:** Ability to log into the router's admin panel to find the controller's IP address.
> **Tip for construction time:** Don't have your final internet connection yet? No problem. The controller does not require a permanent network connection for basic operation. For remote management and on-site configuration, simply create a temporary **Wi-Fi hotspot on your phone** and connect the controller to it.
## 3. Required Tools [#3-required-tools]
* Precision screwdriver, wire stripper, side cutters.
* Ferrule crimping tool.
* **Multimeter**.
* Computer or phone for configuration.
## 4. System Requirements [#4-system-requirements]
Edge series devices operate based on open serial communication protocols, working right out of the box, allowing immediate cooperation with other boneIO devices.
* **Recommended Platform: boneIO Black, boneIO ESP**
Configuration of Edge series devices ??? **Home Assistant**, as it supports auto-discovery for boneIO Black devices, making integration seamless.
* **Other Platforms**
You can integrate with any other system (such as openHAB, Domoticz, etc.) by manually configuring MQTT entities based on the topics provided in the device documentation.
## 5. Required Skills [#5-required-skills]
* **User:** Basic computer skills and understanding of networking and the MQTT protocol.
* **Installer (Electrician):** Full qualifications for working with electrical installations, ability to read schematics, and knowledge of safety principles.
# Internal Automations (/en/docs/esp/create-automations-dimmer)
## What are Internal Automations? [#what-are-internal-automations]
Internal automations are a powerful way to create simple, core automations that run directly on your boneIO ESP controller. This means they will work even if your main smart home hub (like Home Assistant) is offline. They are perfect for critical functions, like turning on a light with a wall switch.
### Basic Automation: Toggling a Light [#basic-automation-toggling-a-light]
Let's start with a default configuration that links a button press to a light.
```yaml
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_press: # This is our automation trigger
then:
- light.toggle: chl_01 # This is the action to perform
light:
- platform: monochromatic
output: chl01
name: 'CHL 01'
id: chl_01
default_transition_length: 2s
gamma_correct: 0
```
In the `on_press:` section, we define what happens when the button is pressed.\
The action `- light.toggle: chl_01` will toggle the state of the light with the ID `chl_01`.
## Advanced Automation: Multi-Click [#advanced-automation-multi-click]
ESPHome allows you to define multiple actions for a single button based on how it's pressed (single, double, or long press). This is done using the `on_multi_click` component.
Let's configure one button (`in_01`) to control three different lights.
### 1. The Goal [#1-the-goal]
* **Single Click**: Toggle `chl_01`.
* **Double Click**: Toggle `chl_02`.
* **Long Press**: Toggle `chl_03`.
### 2. The Configuration [#2-the-configuration]
First, ensure you have your lights defined. Then, in your `binary_sensor` configuration, replace `on_press` with `on_multi_click`.
```yaml
# Ensure these lights are defined elsewhere in your config
light:
- platform: monochromatic
output: chl01
name: 'CHL 01'
id: chl_01
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl02
name: 'CHL 02'
id: chl_02
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl03
name: 'CHL 03'
id: chl_03
default_transition_length: 2s
gamma_correct: 0
# Now, configure the multi-click automation
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_multi_click:
# Note: The order matters! ESPHome checks from top to bottom.
# It's best to define the most complex patterns (longest clicks) first.
# 1. Long Click Action
- timing:
- ON for at least 1.4s
then:
- logger.log: 'Long Click Detected, toggling Light 1'
- light.toggle: chl_01
# 2. Double Click Action
- timing:
- ON for at most 1s
- OFF for at most 0.5s
- ON for at most 1s
- OFF for at least 0.2s
then:
- logger.log: 'Double Click Detected, toggling Light 2'
- light.toggle: chl_02
# 3. Single Click Action
- timing:
- ON for at most 1s
- OFF for at least 0.5s
then:
- logger.log: 'Single Click Detected, toggling Light 3'
- light.toggle: chl_03
```
### 3. How It Works [#3-how-it-works]
The `on_multi_click` automation checks a sequence of `timing` blocks from top to bottom. The first one that matches the user's button press pattern is executed.
* `timing`: This defines the pattern of ON (pressed) and OFF (released) states. You can adjust the time values (e.g., `at most 1s`, `at least 0.5s`) to fine-tune the responsiveness, but the defaults are usually a good starting point.
* `then`: This block contains the actions to be performed when the `timing` pattern is matched. We've included a `logger.log` action, which is very helpful for debugging your automations in the device logs.
By arranging the clicks from most complex (long press) to least complex (single press), you ensure that a long press doesn't also trigger the single press action.
## Brightening lights with a button hold [#brightening-lights-with-a-button-hold]
```yaml
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs
number: 1
mode:
input: true
inverted: true
on_press:
then:
- while:
condition:
binary_sensor.is_on: in_01
then:
- if:
condition:
lambda: 'return id(chl_01).current_values.get_brightness() >= 0.90f;'
then:
- light.control:
id: chl_01
brightness: 0%
- light.turn_off:
id: chl_01
else:
- light.dim_relative:
id: chl_01
relative_brightness: 5%
transition_length: 0.2s
- delay: 200ms
```
### How it works [#how-it-works]
* **`on_press` trigger**: Starts the automation when the button is pressed and immediately enters a `while` loop.
* **`while` with condition**: `binary_sensor.is_on: in_01` keeps looping for as long as the button remains physically pressed.
* **Brightness threshold**: `lambda: 'return id(chl_01).current_values.get_brightness() >= 0.90f;'` reads the current brightness of `chl_01` (0.0–1.0). Once it reaches ≥ 90%, it executes a shutdown sequence:
* `light.control: brightness: 0%` sets brightness to 0 without a transition,
* `light.turn_off` ensures the light is OFF.
* **Step brightening**: If the threshold is not reached, `light.dim_relative: relative_brightness: 5%` increases brightness by 5% with a short `0.2s` transition.
* **Update cadence**: `delay: 200ms` sets the step frequency (every 200 ms) until the button is released or the threshold is reached.
#### Tips [#tips]
* Ensure a light with `id: chl_01` exists in your `light:` configuration (see examples above).
* Want to dim instead of brighten? Use a negative value, e.g. `relative_brightness: -5%`.
* Adjust `5%`, `0.2s`, and `200ms` to change step size, smoothness, and responsiveness.
## Multi-Click: Single click — toggle, short hold — dimming [#multi-click-single-click--toggle-short-hold--dimming]
This code hasn't been tested in real life — it may not work without additional fixes.
```yaml
binary_sensor:
- platform: gpio
name: 'IN_01_MultiClick_Dim'
id: in_01
pin:
pcf8574: pcf_inputs
number: 1
mode:
input: true
inverted: true
on_multi_click:
# 1. Short hold: dim while holding
- timing:
- ON for at least 0.6s
then:
- while:
condition:
binary_sensor.is_on: in_01
then:
- light.dim_relative:
id: chl_01
relative_brightness: -5%
transition_length: 0.2s
- delay: 200ms
# 2. Single click: toggle the light
- timing:
- ON for at most 0.5s
- OFF for at least 0.2s
then:
- light.toggle: chl_01
```
### How it works [#how-it-works-1]
* **Pattern order**: The shorter single-click pattern is placed last so it doesn't intercept the hold gesture.
* **Dim while holding**: After `ON for at least 0.6s`, a loop reduces brightness by `5%` every `200ms` until release.
* **Tuning thresholds**: Adjust `0.6s`, `0.5s`, and `0.2s` to fine-tune gesture detection based on your button hardware and responsiveness needs.
## Change RGBW color on click [#change-rgbw-color-on-click]
This code hasn't been tested in real life — it may not work without additional fixes.
This example cycles through a predictable color palette on each click, so it's easy to reach common presets and return to white.
```yaml
# Color palette exposed as a select (visible in Home Assistant)
select:
- platform: template
name: "RGBW Color Preset"
id: rgbw_palette
optimistic: true
options:
- White
- Red
- Green
- Blue
- Cyan
- Magenta
- Yellow
- Amber
- Purple
set_action:
# White (uses W channel)
- if:
condition:
lambda: 'return id(rgbw_palette).state == "White";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
white: 100%
red: 0%
green: 0%
blue: 0%
# Red
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Red";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 100%
green: 0%
blue: 0%
white: 0%
# Green
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Green";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 0%
green: 100%
blue: 0%
white: 0%
# Blue
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Blue";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 0%
green: 0%
blue: 100%
white: 0%
# Cyan
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Cyan";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 0%
green: 100%
blue: 100%
white: 0%
# Magenta
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Magenta";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 100%
green: 0%
blue: 100%
white: 0%
# Yellow
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Yellow";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 100%
green: 100%
blue: 0%
white: 0%
# Amber
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Amber";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 100%
green: 60%
blue: 0%
white: 0%
# Purple
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Purple";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 60%
green: 0%
blue: 100%
white: 0%
# Click = next color in the palette
binary_sensor:
- platform: gpio
id: in_01
name: "IN_01_Color_Next"
pin:
pcf8574: pcf_inputs
number: 1
mode:
input: true
inverted: true
on_press:
then:
- select.next: rgbw_palette
```
### How it works [#how-it-works-2]
* **Palette as `select`**: Lets you view and choose the current color from Home Assistant as well.
* **`select.next` on click**: Each press advances to the next preset and applies it to `rgbw_l`.
* **Predictable set**: A fixed list (White, Red, Green, …) makes operation simple and returning to White easy.
#### Tips [#tips-1]
* Make sure a `rgbw_l` RGBW light is defined in your `light:` configuration.
* Optionally add double-click to jump to White, or a hold to dim/brighten.
# Internal Automations (/en/docs/esp/create-automations)
## What are Internal Automations? [#what-are-internal-automations]
Internal automations are a powerful way to create simple, core automations that run directly on your boneIO ESP controller. This means they will work even if your main smart home hub (like Home Assistant) is offline. They are perfect for critical functions, like turning on a light with a wall switch.
### Basic Automation: Toggling a Light [#basic-automation-toggling-a-light]
Let's start with a default configuration that links a button press to a light.
```yaml
binary_sensor:
- platform: gpio
name: 'IN_01_Bedroom_Button1'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_press: # This is our automation trigger
- if:
condition:
switch.is_on: local_control # the Local control switch in Home Assistant
then:
- light.toggle: light_01 # This is the action to perform
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
```
In the `on_press:` section, we define what happens when the button is pressed.\
The action `- light.toggle: light_01` will toggle the state of the light with the ID `light_01`.
The `switch.is_on: local_control` condition is the **Local control** switch the
boneIO configuration shows in Home Assistant — turned off, inputs only report
their state ([more](/en/docs/home-assistant/boneio-esp#local-control)). In your
own automation that should always run, you can leave the condition out.
The same logic applies to switches. The only difference is that the action would be `- switch.toggle: switch_01`. Simple!
## Advanced Automation: Multi-Click [#advanced-automation-multi-click]
ESPHome allows you to define multiple actions for a single button based on how it's pressed (single, double, or long press). This is done using the `on_multi_click` component.
Let's configure one button (`in_01`) to control three different lights.
### 1. The Goal [#1-the-goal]
* **Single Click**: Toggle `light_01`.
* **Double Click**: Toggle `light_02`.
* **Long Press**: Toggle `light_03`.
### 2. The Configuration [#2-the-configuration]
First, ensure you have your lights defined. Then, in your `binary_sensor` configuration, replace `on_press` with `on_multi_click`.
```yaml
# Ensure these lights are defined elsewhere in your config
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
- platform: binary
name: 'Light 02'
output: out_02
id: light_02
- platform: binary
name: 'Light 03'
output: out_03
id: light_03
# Now, configure the multi-click automation
binary_sensor:
- platform: gpio
name: 'IN_01_Multi_Click_Button'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_multi_click:
# Note: The order matters! ESPHome checks from top to bottom.
# It's best to define the most complex patterns (longest clicks) first.
# 1. Long Click Action
- timing:
- ON for at least 1.4s
then:
- logger.log: 'Long Click Detected, toggling Light 3'
- light.toggle: light_03
# 2. Double Click Action
- timing:
- ON for at most 1s
- OFF for at most 0.5s
- ON for at most 1s
- OFF for at least 0.2s
then:
- logger.log: 'Double Click Detected, toggling Light 2'
- light.toggle: light_02
# 3. Single Click Action
- timing:
- ON for at most 1s
- OFF for at least 0.5s
then:
- logger.log: 'Single Click Detected, toggling Light 1'
- light.toggle: light_01
```
### 3. How It Works [#3-how-it-works]
The `on_multi_click` automation checks a sequence of `timing` blocks from top to bottom. The first one that matches the user's button press pattern is executed.
* `timing`: This defines the pattern of ON (pressed) and OFF (released) states. You can adjust the time values (e.g., `at most 1s`, `at least 0.5s`) to fine-tune the responsiveness, but the defaults are usually a good starting point.
* `then`: This block contains the actions to be performed when the `timing` pattern is matched. We've included a `logger.log` action, which is very helpful for debugging your automations in the device logs.
By arranging the clicks from most complex (long press) to least complex (single press), you ensure that a long press doesn't also trigger the single press action.
# Final Checks (/en/docs/esp/final-checks)
## Final Checks [#final-checks]
After completing the installation:
1. Double-check all connections.
2. Ensure there are no short circuits.
3. Turn on the main power (24V DC power supply).
4. The device's OLED screen should light up, indicating it has started successfully.
# Connect your boneIO ESP (/en/docs/esp/how-to-connect)
# Let's install the ESPHome Device Builder! [#lets-install-the-esphome-device-builder]
There are 3 options to connect to your boneIO ESP:
1. [Using Home Assistant addon](#using-home-assistant-addon)
2. [Using Esphome Device Builder on your PC](#using-esphome-device-builder-on-your-pc)
## ESPHome Device Builder in Home Assistant [#esphome-device-builder-in-home-assistant]
Installing the ESPHome Device Builder add-on is pretty simple. Just follow these steps:
1. Go to the **Settings > Add-ons** section in your Home Assistant.
2. Click the **Add-on Store** button in the bottom right corner.
3. In the search bar, type `ESPHome` and select the add-on from the official repository. Make sure you don't use beta or dev versions, as they are for testing purposes only.
4. Click **Install**.
After the installation is complete, go to the **Configuration** tab and enable the **Start on boot** and **Show in sidebar** options. This will make it easier to access ESPHome Device Builder in the future.
Finally, go to the **Info** tab and click **Start** to run the add-on. You will now see ESPHome Device Builder in your sidebar!
## ESPHome Device Builder on Your PC [#esphome-device-builder-on-your-pc]
If you don't use Home Assistant (HA), you can still edit your boneIO ESP's configuration.
Editing Esphome config without HA, just on your PC is also possible. Similar instruction is here: [https://esphome.io/guides/getting\_started\_command\_line](https://esphome.io/guides/getting_started_command_line)
On your PC, you will need one of the following:
* for Linux: Docker,
* for Windows: Python 3.13 installed.
### Windows [#windows]
We assume that you are running Windows 10 or 11 - its important to have your administrative privileges, also you need internet connection.
Let's do it step by step!
1. Download Python installer from Python download page for Windows Choose Windows installer according to your operating system version (most common is 64-bit).
2. Choose both options available in installer. “Use admin priviliges when installing py.exe” and “Add python.exe to PATH”. Click “Install now”.
3. Verify Python installation Open Powershell or CMD and type:
```powershell
python --version
```
If properly installed output would look like (with your Python version):
```powershell
Python 3.13.2
```
4. Prepare Esphome for Python. In Powershell prompt type:
```powershell
mkdir $env:USERPROFILE\esphome
cd $env:USERPROFILE\esphome
pip3 install wheel esphome pillow==10.2.0
```
in CMD:
```cmd
mkdir %USERPROFILE%\esphome
cd %USERPROFILE%\esphome
pip3 install wheel esphome pillow==10.2.0
```
5. ESPHome should work now - lets test it! Do it by typeing:
```powershell
esphome version
```
The output should looks like:
```powershell
Version: 2025.x.x
```
The version will differ for you. It's depends on your current version.
Now you’re good to execute next steps.
#### Run ESPHome Dashboard \[!toc] [#run-esphome-dashboard-toc]
In powershell type:
```powershell
cd $env:USERPROFILE\esphome
esphome dashboard .
```
or in CMD
```cmd
cd %USERPROFILE%\esphome
esphome dashboard .
```
Check it out opening page in your web browser [http://127.0.0.1:6052](http://127.0.0.1:6052) If it’s loaded then you can go to next section: [Connect with Esphome Addon](#connect-with-esphome-addon) or if you prefer USB installation go to [USB Only installation](#usb-only-installation).
#### Upgrade ESPHome \[!toc] [#upgrade-esphome-toc]
To upgrade your ESPHome in windows you need to:
```powershell
pip3 install --upgrade esphome
```
### Linux [#linux]
Fetch Esphome docker image / Linux / Mac OS
Run following command in terminal:
```bash
docker pull ghcr.io/esphome/esphome
```
Run Esphome dashboard
Now let’s start Esphome dashboard. Make directory where your config would be stored eg /home/me/esphome
In Linux based system:
```bash
docker run --rm --privileged --network host -v "/home/me/esphome":/config -it ghcr.io/esphome/esphome dashboard .
```
Now in Chrome open website:
under Linux [http://0.0.0.0:6052/](http://0.0.0.0:6052/)
## Connect with ESPHome Device Builder [#connect-with-esphome-device-builder]
**Note**: For this to work your home network must support mDNS. Your PC and boneIO is in same subnet (same VLAN) in most cases it’d work. boneIO has to be connected to your network and working.
1. Find your new boneIO device in the dashboard.
2. Click Adopt
3. Choose name for our new device
4. Click Adopt
5. Now it will prompt for install new software
6. After install there will be logs visible, you can click stop now
Next, set a password and an encryption key on the controller: until you do, anyone on your network can flash it. See [Security](/en/docs/esp/security#after-adoption-in-esphome-builder).
It’s ready, you can edit your config by clicking Edit on your boneIO device.
### Running boneIO without Home Assistant [#running-boneio-without-home-assistant]
If you don’t have HA, then in config find line:
```yaml
api:
```
and add `reboot_timeout: 0s` to it, so it’d look like:
`reboot_timeout: 0s` is default option in our precompiled binaries.
```yaml
api:
reboot_timeout: 0s
```
## USB-Only Installation [#usb-only-installation]
If you don’t want to setup network in boneIO then go with those steps. You'd need to have Esphome dashboard running. For Esphome firmware installation you’d need internet connection on your PC!
1. Go to [https://boneio.eu/esp](https://boneio.eu/esp)
2. Choose your board and choose option "Download yaml for this firmware" in the end.
3. In the top right corner choose Download raw file
4. Copy it to your Esphome directory eg C:/Users/me/esphome. After pasting it, it should appear in Esphome dashboard.
5. Now you can Edit and Install firmware using "Plug into this computer" option. If you need to install some drivers, then Esphome website should show what to download to get it work.
# Edit config file (/en/docs/esp/how-to-edit-config)
# Configuration file [#configuration-file]
The configuration file might look big and complicated, but it's really not. The file itself is separated into sections, which we will describe below.
For our example, we will use `boneio-32x10_lights_v0_7.yaml`.
So let's begin. Here is the whole config file:
```yaml
substitutions:
name: boneio-32-l-07
friendly_name: 'BoneIO ESP 32x10 Lights'
serial_prefix: 'esp' #Don't change it.
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.32x10-lights
version: '0.7'
esp32:
board: nodemcu-32s
ethernet:
id: eth
type: LAN8720
mdc_pin: GPIO23
mdio_pin: GPIO18
clk_mode: GPIO0_IN
phy_addr: 1
power_pin: GPIO16
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-32x10_lights_v0_7.yaml@latest
import_full_config: true
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.6.0
files: [
'devices/buzzer.yaml',
'devices/serial_no.yaml',
'devices_v0_7/display.yaml',
'devices_v0_7/i2c.yaml',
'devices_v0_7-v0_9/ina219.yaml',
'devices_v0_7-v0_9/lm75b.yaml',
'devices_v0_7-v0_9/pcf.yaml',
'boards/output/out01_02.yaml',
'boards/output/out03_04.yaml',
'boards/output/out05_06.yaml',
'boards/output/out07_08.yaml',
'boards/output/out09_10.yaml',
'boards/output/out11_12.yaml',
'boards/output/out13_14.yaml',
'boards/output/out15_16.yaml',
'boards/output/out17_18.yaml',
'boards/output/out19_20.yaml',
'boards/output/out21_22.yaml',
'boards/output/out23_24.yaml',
'boards/output/out25_26.yaml',
'boards/output/out27_28.yaml',
'boards/output/out29_30.yaml',
'boards/output/out31_32.yaml',
# 'devices_v0_7-v0_9/one_wire.yaml',
]
logger:
api:
reboot_timeout: 0s
ota:
- platform: esphome
web_server:
port: 80
local: true
version: 3
time:
- platform: homeassistant
timezone: Europe/Warsaw
id: homeassistant_time
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_press:
- if:
condition:
switch.is_on: local_control
then:
- light.toggle: light_01
######################
### MODBUS SECTION ###
######################
# UNCOMMENT BELOW TO USE MODBUS
# uart:
# id: uart_pin14_15
# rx_pin: GPIO14
# tx_pin: GPIO15
# baud_rate: 9600
# stop_bits: 1
# modbus:
# send_wait_time: 200ms
# uart_id: uart_pin14_15
# id: boneio_modbus
# modbus_controller:
# - id: YOURDEVICE ID
# address: 0x09
# modbus_id: mod_bus
# setup_priority: -10
# update_interval: 60s
```
### substitutions [#substitutions]
```yaml
substitutions:
name: boneio-32-l-07
friendly_name: 'BoneIO ESP 32x10 Lights'
serial_prefix: 'esp' #Don't change it.
```
This part is mainly responsible for the name of your controller.\
You should focus on `friendly_name`. You should write the exact name of your boneIO here. The name depends on your needs.\
It could be "boneIO ESP" if you have one boneIO ESP controller, or for example, "boneIO ESP 1st-floor".
### esphome [#esphome]
```yaml
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.32x10-lights
version: '0.7'
```
There are definitions for your controller. You shouldn't change `name` or `friendly_name`. The line `name_add_mac_suffix:` will add a MAC suffix to the controller's name, which is useful for identifying your controller. `project:` is the place where you define the type and version of your controller.
### esp32 [#esp32]
```yaml
esp32:
board: nodemcu-32s
```
Definition of the ESP32 board.
### Ethernet [#ethernet]
```yaml
ethernet:
id: eth
type: LAN8720
mdc_pin: GPIO23
mdio_pin: GPIO18
clk_mode: GPIO0_IN
phy_addr: 1
power_pin: GPIO16
```
This part is responsible for the description of your controller's Ethernet port - you shouldn't change anything here.
### dashboard\_import [#dashboard_import]
```yaml
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-32x10_lights_v0_7.yaml@latest
import_full_config: true
```
This is the place where the address for our GitHub repository is defined. The config and all additional packages are downloaded from there. There is nothing to change here.
### packages [#packages]
```yaml
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.7.1
files: [
'devices/buzzer.yaml',
'devices/serial_no.yaml',
'devices_v0_7/display.yaml',
'devices_v0_7/i2c.yaml',
'devices_v0_7-v0_9/ina219.yaml',
'devices_v0_7-v0_9/lm75b.yaml',
'devices_v0_7-v0_9/pcf.yaml',
'boards/output/out01_02.yaml',
'boards/output/out03_04.yaml',
'boards/output/out05_06.yaml',
'boards/output/out07_08.yaml',
'boards/output/out09_10.yaml',
'boards/output/out11_12.yaml',
'boards/output/out13_14.yaml',
'boards/output/out15_16.yaml',
'boards/output/out17_18.yaml',
'boards/output/out19_20.yaml',
'boards/output/out21_22.yaml',
'boards/output/out23_24.yaml',
'boards/output/out25_26.yaml',
'boards/output/out27_28.yaml',
'boards/output/out29_30.yaml',
'boards/output/out31_32.yaml',
# 'devices_v0_7-v0_9/one_wire.yaml',
]
```
Here are definitions of all packages used by boneIO, with the address to our GitHub. One thing that might interest you is uncommenting the `# 'devices_v0_7-v0_9/one_wire.yaml'` section if you would like to use a one-wire sensor.
### logger [#logger]
```yaml
logger:
```
In case of troubleshooting, you can increase the log level to `INFO` or `WARN` or `DEBUG`. This can be very useful in some cases.
### api [#api]
```yaml
api:
reboot_timeout: 0s
```
Here, the reboot timeout is defined for when the controller loses connection with HA.
If you want your boneIO to restart after losing connection with Home Assistant, you should enter a value that suits you here.
For WiFi connections, the value should not be zero. For LAN connections, not rebooting does not negatively affect the connection with Home Assistant in most cases.
### ota [#ota]
```yaml
ota:
- platform: esphome
```
Part responsible for Over The Air updates.
### web\_server [#web_server]
```yaml
web_server:
port: 80
local: true
version: 3
```
Part responsible for enabling the web server of the controller.
### time [#time]
```yaml
time:
- platform: homeassistant
timezone: Europe/Warsaw
id: homeassistant_time
```
This section is responsible for selecting your controller's time zone. Adjust it to your location.
### Modbus Section [#modbus-section]
```yaml
######################
### MODBUS SECTION ###
######################
# UNCOMMENT BELOW TO USE MODBUS
# uart:
# id: uart_pin14_15
# rx_pin: GPIO14
# tx_pin: GPIO15
# baud_rate: 9600
# stop_bits: 1
# modbus:
# send_wait_time: 200ms
# uart_id: uart_pin14_15
# id: boneio_modbus
```
This section is responsible for Modbus. If you plan to use it, you should first uncomment it.
```yaml
######################
### MODBUS SECTION ###
######################
# UNCOMMENT BELOW TO USE MODBUS
uart:
id: uart_pin14_15
rx_pin: GPIO14
tx_pin: GPIO15
baud_rate: 9600
stop_bits: 1
modbus:
send_wait_time: 200ms
uart_id: uart_pin14_15
id: boneio_modbus
```
Then, please check our Modbus tutorial: [Modbus with Esphome packages](/docs/esp/advanced/esphome-packages)
# Software setup GRID (/en/docs/esp/introduction-grid)
# Software setup (/en/docs/esp/introduction)
## You've just received your boneIO ESP! [#youve-just-received-your-boneio-esp]
Here are some steps witch will help you to handle it!
Device will come to you with alredy preinstalled ESPHome. boneIO is provided with default configuration, you need to adjust it for your needs.
Software installed on the device might be outdated. It's always good thing to update it.
Below you will find some necessary steps to start with boneiO ESP:
# Naming the Inputs (/en/docs/esp/naming-binary)
## Why should you name your inputs? [#why-should-you-name-your-inputs]
Naming your inputs makes working with the controller much easier. It's simpler to remember "Bedroom Button 1" than "IN\_01", right?
### Binary Sensors [#binary-sensors]
Let's look at the default configuration for your inputs, which are defined as `binary_sensor` components.
Here is a complete example of a single input configuration. The most important line for you is `name: 'My First Button'`.
```yaml
binary_sensor:
- platform: gpio
name: 'My First Button'
"This is the friendly name for your input"
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_press:
then:
```
### Configuration Explained [#configuration-explained]
| Section | Description |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `binary_sensor:` | This is the main header for all your binary sensor (input) definitions. |
| `- platform: gpio` | This specifies that the sensor is connected to a General Purpose Input/Output pin. |
| `name: 'My First Button'` | This is the friendly name for your input. It will be visible in Home Assistant and is much easier to identify. You can change it to something descriptive like `'Bedroom Button 1'` or `'IN_01_Living_Room_Motion'`. This is the most important part for you to customize. |
| `id: in_01` | This is a unique identifier used within ESPHome. It's essential for referring to this input in automations, such as the `on_press` action. |
| `pin:` | This section defines the physical pin the sensor is connected to. This part is pre-configured for the boneIO hardware and should not be changed. |
| `inverted: true` | This inverts the logic of the input. It's useful for certain devices like motion sensors, which might have a normally open or normally closed state. |
| `on_press:` | This is an automation that defines what happens when the input is triggered (e.g., a button is pressed). We will cover this in more detail in the automations guide. |
# Naming the outputs (/en/docs/esp/naming-outputs)
## What are outputs? [#what-are-outputs]
Outputs are the executive parts of our controller. Depending on its type, you can control:
* [32 relays 10A](#32x10a),
* [24 relays 16A](#24x16a),
* [16 covers with the Cover module](#cover),
* [with the Covermix module – 8 covers and 16 relays 10A](#covermix).
## Why should you name them? [#why-should-you-name-them]
Naming your outputs will make working with the controller much easier. It's much easier to remember "Bedroom light" than "Light 01", right?
In our examples, we focus on a part of the configuration, which you can then adjust to your entire configuration.
Let's get started!
### 32x10A [#32x10a]
We prepared for you two types of the configuration file, what you should choose depends on what you will use as your outputs. Usually 32x10A controller its used for lights, so we prepared for you configuration with 32 light outputs! But if you want to use it as controling device for some sort of switches etc? No problem! We got also version with 32 switches! But what if you want to use 20 outputs as lights and 12 as switches? We dont have configuration for you... But we will explain how you can prepare one for yourself!
Below is a part of the default configuration in the file:
```
boneio-32x10_lights_v0_7.yaml
```
We are looking for part with header `light:`
```yaml
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
- platform: binary
name: 'Light 02'
output: out_02
id: light_02
- platform: binary
name: 'Light 03'
output: out_03
id: light_03
- platform: binary
name: 'Light 04'
output: out_04
id: light_04
- platform: binary
name: 'Light 05'
output: out_05
id: light_05
- platform: binary
name: 'Light 06'
output: out_06
id: light_06
```
* `- platform: binary` - Definition of output type - it could take two states.
* `name: 'Light 01'` – this part of the configuration is the output name, and you can change it freely. There are many naming approaches. For example, you can change the name to `Bedroom` or `OUT_01_Bedroom`.
* `output: out_01` – this is the relay number that your name refers to.
* `id: light_01` – this part its the definition
```
boneio-32x10_switches_0_7.yaml
```
We are looking for part with header `switch:`
```yaml
switch:
- platform: output
name: 'Switch 01'
output: out_01
id: switch_01
- platform: output
name: 'Switch 02'
output: out_02
id: switch_02
- platform: output
name: 'Switch 03'
output: out_03
id: switch_03
- platform: output
name: 'Switch 04'
output: out_04
id: switch_04
- platform: output
name: 'Switch 05'
output: out_05
id: switch_05
- platform: output
name: 'Switch 06'
output: out_06
id: switch_06
```
* `- platform: output` - Definition of output type - it could take two states.
* `name: 'Switch 01'` – this part of the configuration is the output name, and you can change it freely. There are many naming approaches. For example, you can change the name to `Circulation_pump` or `Switch_01_Circulation_pump`.
* `output: out_01` – this is the relay number that your name refers to.
* `id: switch_01` – this part its the definition of the
### Id like to get 10 switches and 22 lights! [#id-like-to-get-10-switches-and-22-lights]
You need to adjust your configuration file a little bit. Its really simple, and really usefull. Lets make a assumption that we to change from our `boneio-32x10_lights_v0_7.yaml` 10 lights to switche's.
As you can learn from this tutorial, the header its what describes the oputput, we are useing `switch` and `light here`. If you look at the standard lights configuration, you will notice that its start with header `lights:`, then there are definitions of our relays. For our tutorial we gonna change last 10 lights to relays. Below the configuration:
```yaml
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
- platform: binary
name: 'Light 02'
output: out_02
id: light_02
...
...
...
- platform: binary
name: 'Light 21'
output: out_21
id: light_21
- platform: binary
name: 'Light 22'
output: out_22
id: light_22
switch:
- platform: binary
name: 'Switch 01'
output: out_23
id: switch_01
- platform: binary
name: 'Switch 02'
output: out_24
id: switch_02
...
...
...
- platform: binary
name: 'Switch 09'
output: out_31
id: switch_0
- platform: binary
name: 'Switch 10`
output: out_32
id: switch_32
```
So what have we done? FIrst part its the same as in the default lights configuration, but before `out_23` we wrote `switch:` header, and we adjusted names and id, so they match everything. In the end we got lights from relay 1 to 22, and switches from relays 23 to 32!
### 24x16A [#24x16a]
Below is a part of the default configuration in the file:
```
boneio-24x16_switches_v0_7.yaml
```
```yaml
switch:
- platform: output
name: 'Switch 01'
output: out_01
id: switch_01
- platform: output
name: 'Switch 02'
output: out_02
id: switch_02
- platform: output
name: 'Switch 03'
output: out_03
id: switch_03
- platform: output
name: 'Switch 04'
output: out_04
id: switch_04
- platform: output
name: 'Switch 05'
output: out_05
id: switch_05
- platform: output
name: 'Switch 06'
output: out_06
id: switch_06
```
* `- platform: output` - Definition of output type - it could take two states.
* `name: 'Switch 01'` – this part of the configuration is the output name, and you can change it freely. There are many naming approaches. For example, you can change the name to `Circulation_pump` or `Switch_01_Circulation_pump`.
* `output: out_01` – this is the relay number that your name refers to.
* `id: switch_01` – this part its the definition of the
### Cover [#cover]
Below is a part of the default configuration in the file:
```
boneio-cover_v0_7.yaml
```
```yaml
cover:
- platform: time_based
name: 'Cover 01'
id: cover_01
open_action:
- switch.turn_on: cover_open_01_out01
open_duration: 10s
close_action:
- switch.turn_on: cover_close_01_out02
close_duration: 10s
stop_action:
- switch.turn_off: cover_open_01_out01
- switch.turn_off: cover_close_01_out02
```
* `- platform: time_based` –
* `name: 'Cover 01'` - this part of the configuration is the cover name, and you can change it freely. There are many naming approaches. For example, you can change the name to `Bedroom` or `Cover01_Bedroom`.
* `open_action:` `- switch.turn_on: cover_open_01_out01` and `close_action:` `- switch.turn_on: cover_close_01_out02`
are the relays responsible for your cover.
* The rest of the section is for advanced cover configuration – if you want to learn more, see the documentation.
Our example looks like this:
```yaml
cover:
- platform: time_based
name: 'Cover01_Bedroom'
id: cover_01
open_action:
- switch.turn_on: cover_open_01_out01
open_duration: 10s
close_action:
- switch.turn_on: cover_close_01_out02
close_duration: 10s
stop_action:
- switch.turn_off: cover_open_01_out01
- switch.turn_off: cover_close_01_out02
```
### Covermix [#covermix]
For the Covermix controller version, we also prepared same as for 32x10A version - configuration witch 16 lights, or switches.
We begin with covermix with lights version.
To change the name of a specific cover and light, you must edit the file:
```
boneio-cover_mix_lights_v0_7.yaml
```
Below is a part of the default configuration in the file:
```yaml
cover:
- platform: time_based
name: 'Cover 01'
id: cover_01
open_action:
- switch.turn_on: cover_open_01_out01
open_duration: 10s
close_action:
- switch.turn_on: cover_close_01_out02
close_duration: 10s
stop_action:
- switch.turn_off: cover_open_01_out01
- switch.turn_off: cover_close_01_out02
light:
- platform: binary
name: 'Light 17'
output: out_17
id: light_17
```
Part responsible for cover:
* `- platform: time_based` –
* `name: 'Cover 01'` - this part of the configuration is the cover name, and you can change it freely. There are many naming approaches. For example, you can change the name to `Bedroom` or `Cover01_Bedroom`.
* `open_action:` `- switch.turn_on: cover_open_01_out01` and `close_action:` `- switch.turn_on: cover_close_01_out02`
are the relays responsible for your cover.
* The rest of the section is for advanced cover configuration – if you want to learn more, see the documentation.
Part responsible for lights:
* `- platform: binary` - Definition of output type - it could take two states.
* `name: 'Light 17'` – this part of the configuration is the output name, and you can change it freely. There are many naming approaches. For example, you can change the name to `Bedroom` or `Light_17_Bedroom`.
* `output: out_17` – this is the relay number that your name refers to.
* `id: light_17` – this part its the definition of the
Our example looks like this:
```yaml
cover:
- platform: time_based
name: 'Cover01_Bedroom'
id: cover_01
open_action:
- switch.turn_on: cover_open_01_out01
open_duration: 10s
close_action:
- switch.turn_on: cover_close_01_out02
close_duration: 10s
stop_action:
- switch.turn_off: cover_open_01_out01
- switch.turn_off: cover_close_01_out02
light:
- platform: binary
name: 'Light_17_Bedroom'
output: out_17
id: light_17
```
here is the covermix with switches version.
To change the name of a specific cover and light, you must edit the file:
```
boneio-cover_mix_lights_v0_7.yaml
```
Below is a part of the default configuration in the file:
```yaml
cover:
- platform: time_based
name: 'Cover 01'
id: cover_01
open_action:
- switch.turn_on: cover_open_01_out01
open_duration: 10s
close_action:
- switch.turn_on: cover_close_01_out02
close_duration: 10s
stop_action:
- switch.turn_off: cover_open_01_out01
- switch.turn_off: cover_close_01_out02
switch:
- platform: binary
name: 'switch 17'
output: out_17
id: light_17
```
Part responsible for cover:
* `- platform: time_based` –
* `name: 'Cover 01'` - this part of the configuration is the cover name, and you can change it freely. There are many naming approaches. For example, you can change the name to `Bedroom` or `Cover01_Bedroom`.
* `open_action:` `- switch.turn_on: cover_open_01_out01` and `close_action:` `- switch.turn_on: cover_close_01_out02`
are the relays responsible for your cover.
* The rest of the section is for advanced cover configuration – if you want to learn more, see the documentation.
Part responsible for lights:
* `- platform: binary` - Definition of output type - it could take two states.
* `name: 'switch 17'` – this part of the configuration is the output name, and you can change it freely. There are many naming approaches. For example, you can change the name to `Circulation_Pump` or `Switch_17_Circulation_pump`.
* `output: out_17` – this is the relay number that your name refers to.
* `id: switch_17` – this part its the definition of the
Our example looks like this:
```yaml
cover:
- platform: time_based
name: 'Cover01_Bedroom'
id: cover_01
open_action:
- switch.turn_on: cover_open_01_out01
open_duration: 10s
close_action:
- switch.turn_on: cover_close_01_out02
close_duration: 10s
stop_action:
- switch.turn_off: cover_open_01_out01
- switch.turn_off: cover_close_01_out02
switch:
- platform: binary
name: 'Switch_17_Circulation_pump'
output: out_17
id: light_17
```
# Final Checks (/en/docs/esp/final-checks_g2)
## Final Checks [#final-checks]
After completing the installation:
1. Double-check all connections.
2. Ensure there are no short circuits.
3. Turn on the main power (24V DC power supply).
# Hardware Installation (/en/docs/esp/hw-guide-comm-adc)
## Connecting Analog Inputs [#connecting-analog-inputs]
Analog inputs allow you to read values from sensors that do not operate in a binary (on/off) manner.
### Analog Inputs ADC [#analog-inputs-adc]
The boneIO controller is equipped with three analog inputs, utilizing integrated voltage dividers to support a variety of voltage ranges for connecting different sensors.
| Input Name | ESP32 GPIO Number | Voltage |
| :--------: | :---------------: | :-----: |
| A\_1 | GPIO39 | 0 - 5V |
| A\_2 | GPIO36 | 0 - 10V |
| A\_3 | GPIO35 | 0 - 25V |
# Hardware Installation (/en/docs/esp/hw-guide-inputs-small)
## Connecting Digital Inputs [#connecting-digital-inputs]
Digital inputs are used for connecting switches and sensors. By default, they are ground-controlled.
1. Connect one of the wires from a momentary switch to the common `GND` (ground) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will short the input to ground, which will be interpreted as an "on" signal.
### Logical diagram of connecting digital input [#logical-diagram-of-connecting-digital-input]
### GND or + [#gnd-or-]
Input behavior can be changed via the internal switch. Please see the switch location below.
* Down: GND control.
* Up: High-potential control.
# Power supply connection (/en/docs/esp/hw-guide-led-strips)
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 24V DC power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+24V` output of the power supply to the `+` screw terminal on the boneIO.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO.
4. Double-check the connections and polarity before turning on the power supply.
# Power supply connection (/en/docs/esp/hw-guide-power-supply-connection_g2)
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 12-24V DC power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+` output of the power supply to the `+` screw terminal on the boneIO.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO.
4. Double-check the connections and polarity before turning on the power supply.
# Basic Concepts (Glossary) (/en/docs/esp/introduction/basic-concepts)
Welcome to the world of the smart home! Below you will find explanations of the most important concepts that will help you understand how our devices work and how to use them to their full potential.
## Electrical and Hardware Concepts [#electrical-and-hardware-concepts]
### Relay [#relay]
A remotely controlled, electromechanical switch. Its job is to physically open and close an electrical circuit (e.g., turn a 230V light on and off) in response to a low-voltage control signal from the controller's processor. It's the heart of every output (OUT) on a boneIO device.
### Digital Input [#digital-input]
The "sense" of the controller. A port (e.g., IN01) where you connect a wall switch or a sensor. It registers two states: low (no signal) and high (signal present), informing the processor that a button has been pressed.
### Ground-controlled (GND) [#ground-controlled-gnd]
This is the most common and recommended method for controlling digital inputs on boneIO devices. Activating an input (e.g., by pressing a button) involves **connecting the input pin (IN) to the power supply's ground (GND)**. The device's processor detects this drop in potential as an active signal. This method is very safe and resistant to electrical interference.
### Plus-controlled (+VCC) [#plus-controlled-vcc]
An alternative control method. In this case, activating an input involves **applying the positive supply voltage** (e.g., +12V or +24V, depending on the power supply model) **to the input pin (IN)**. The input is active when a high-potential current flows through it.
### Momentary Switch (Bell-Press) [#momentary-switch-bell-press]
A push-button that returns to its original position after being pressed (like a doorbell). **This is the recommended type of switch for use with boneIO** because it allows the software to recognize single-clicks, double-clicks, and long-presses.
### Bistable Switch (Latching/Toggle) [#bistable-switch-latchingtoggle]
A traditional ON/OFF light switch that has two stable positions. Using it with boneIO is possible but limits its functionality to a simple on/off action.
### Star Topology [#star-topology]
A wiring method where each point (lamp, switch) is connected by a separate cable directly to a central location—the electrical cabinet where the controller is located. This is required for boneIO to function correctly.
### Bus Topology [#bus-topology]
A wiring method where devices (e.g., for Modbus communication) are connected sequentially in a daisy-chain fashion, from one device to the next, using a single continuous cable.
### DIN Rail [#din-rail]
A standardized metal mounting rail used in electrical cabinets worldwide. All main boneIO modules are designed to be mounted on a DIN rail.
## Software and Automation Concepts [#software-and-automation-concepts]
### Home Assistant (HA) [#home-assistant-ha]
A free and open-source platform for creating a smart home system. It acts as the "brain" of the entire operation, connecting devices from different manufacturers, including boneIO, and allowing you to create advanced rules and automations.
### Integration [#integration]
The process of connecting two different systems or devices so they can work together. In our case, this most often refers to connecting a boneIO controller to the Home Assistant platform.
### Entity [#entity]
A basic "object" in Home Assistant that represents a single device, sensor, or piece of information. For example, a lamp connected to output OUT01 will appear in HA as a `light.living_room_lamp` entity, which you can control.
### Automation [#automation]
A set of rules that execute automatically when specific conditions are met. A simple example: **IF** the sun has set **AND** the motion sensor detects motion, **THEN** turn on the hallway light.
### Scene [#scene]
A saved state of one or more entities. Unlike an automation, a scene has no trigger—it simply sets devices to a predefined state. Example: A "Movie Night" scene might set the main light to 20% brightness and the LED strip to blue.
### ESPHome [#esphome]
An open-source firmware project that is the heart of the boneIO ESP series controllers. It manages the entire device and is responsible for its integration with Home Assistant.
## Network and Communication Concepts [#network-and-communication-concepts]
### Web Interface [#web-interface]
A website built into the boneIO controller, accessible via a web browser by entering the device's IP address. It allows for basic configuration and control without needing to install any additional systems.
### IP Address [#ip-address]
A unique number that identifies a device on a computer network (e.g., `192.168.1.55`). It is necessary to access the controller's web interface.
### Modbus RTU [#modbus-rtu]
A communication protocol often used in industrial and building automation to communicate with devices such as heat recovery ventilators (HRVs), heat pumps, or energy meters.
# boneIO ESP vs Black (/en/docs/esp/introduction/comparison)
# boneIO Black vs ESP [#boneio-black-vs-esp]
Wondering which controller version to choose? boneIO Black? ESP? Or maybe both? The following comparison focuses on showing the key differences between the controllers, as well as highlighting the strongest points of each series.
## Introduction [#introduction]
Both versions of boneIO controllers are independent home automation platforms that can operate completely autonomously – without the need for a Home Assistant server connection. Although they have different architectures and capabilities, their purpose is very similar. Below is a detailed comparison of their capabilities.
## Comparison Table [#comparison-table]
| Feature | boneIO Black | boneIO ESP |
| :-------------------------------- | :------------------------------------------------- | :------------------------------------------------------- |
| **Software base** | Dedicated - modified Debian 13 system (Linux) | Compiled program from ESPHome |
| **Configuration method** | Graphical Interface (Web UI / PWA) | Text editor (YAML files) |
| **Boot speed** | Slower (loading Debian OS) | Instant |
| **Network and connectivity** | Ethernet | Ethernet and WiFi\* |
| **Width on DIN rail** | 15 DIN modules | 12 DIN modules |
| **Number of physical inputs** | 49 inputs | 35 inputs |
| **Application in HA** | Yes (configuration, management, and backups) | Yes (ESPHome Device Builder) |
| **Modbus** | Significantly more devices, predefined in code\*\* | Fewer devices, but ability to manually add your own YAML |
| **Additional logic environments** | Built-in Node-Red, Mosquitto | None |
| **Schedules and sun events** | Built in, set in the panel, with run history | In YAML (`time`, `sun`), recompile after each change |
| **Presence simulation** | Built-in wizard | No ready-made feature |
| **Alarm, irrigation, thermostat** | Ready-made, configured in the panel | ESPHome components, written in YAML |
| **Applying a change** | Seconds, nothing to compile | Compile and upload the firmware |
| **Accounts and security** | Admin and read-only accounts, HTTPS, Security page | Web server password, API encryption key |
| **Updates** | boneIO, Debian and kernel from the panel | Firmware over the air from ESPHome Device Builder |
| **Loxone** | Lox UDP (experimental) | Through custom components available online |
*\* Using a WiFi connection in a closed metal distribution board or electrical cabinet is not recommended due to strong signal attenuation.*\
*\*\* The device is equipped with an application that allows for preparing your own Modbus configurations. After preparing the configuration, adding it to the software should not take more than 48 business hours.*
***
## Architecture and Software [#architecture-and-software]
* **System and compilation:** **boneIO Black** is based on a specially prepared Linux distribution (Debian 13) – which has been additionally modified by us. Unnecessary elements were removed, leaving a lightweight, coherent core and essential packages – ensuring incredible stability. Using the Debian system translates into vast capabilities, at the cost of a noticeably longer device boot time from the moment power is applied (a fully advanced operating system must load: inputs and outputs work after about a minute, the panel shortly after).
The **boneIO ESP** version relies on uploading firmware from ESPHome. Its compilation and flashing (uploading to the microprocessor) on a computer is somewhat time-consuming, but this pays off with nearly instant device startup! After a power restart, the controller is ready for immediate action almost instantly (about 5 seconds).
* **Open Source:** The **ESP** solution on the logic side is based on an Open Source project – **ESPHome**, backed by a massive community. What is extremely important from a potential user's perspective, all original boneIO software managing the **boneIO Black** model, built on the Linux system architecture (as well as our operating system itself), also remains 100% free and fully Open Source software!
* **Independence from Home Assistant:** Both controllers are fully intelligent and autonomous, capable of executing rules set on them locally without the requirement of maintaining a connection to the Home Assistant server.
## Configuration and Management [#configuration-and-management]
* **User Interface:** All configuration and management of the **boneIO Black** series takes place through an extensive and extremely intuitive **graphical interface**. Additionally, the application managing boneIO Black supports the PWA standard, which means you can easily pin the controller interface as a native application to your smartphone's home screen for easy access. Interacting with the controller is very simple and straightforward. On the other hand, the **ESP** platform is based on YAML code syntax; although this can be more complicated for a layman, in large and complex installations, it allows ESP to implement ready-made logic templates and repeatable entities of various types much more simply and flexibly.
* **Management via HA:** The **boneIO Black** platform has its own, officially prepared **Application** within the Home Assistant ecosystem, which allows for easy controller management. It brings our proprietary application inside HA. From within it, you can also **create backups of the controller** – without this Application, the user must manually take care of downloading and storing backups. For the **ESP** platform, the configuration is always stored on the ESPHome Device Builder server, so it is important to regularly back up that application.
* **Multiclick Function:** Due to higher performance and design differences, multiclick functions react and work noticeably faster in the **boneIO Black** model. Additionally, it offers sequences as well as a much easier configuration process.
* **Output grouping:** **boneIO Black** natively supports grouping outputs into light and switch groups, which are immediately visible as separate entities in Home Assistant. This allows easy control of, for example, an entire group of lights in a room with a single button. The **ESP** platform does not support output grouping within the device – this kind of logic must be handled on the Home Assistant side.
## Ready out of the box, without programming [#ready-out-of-the-box-without-programming]
What would be a YAML project on ESP is a form in the **boneIO Black** panel — saved in seconds, with nothing to compile or upload:
* **Schedules and the sun** — actions at a clock time or at sunrise, sunset and the twilights, with an offset, a random spread, conditions and earliest/latest bounds. Each schedule shows its next run and its history, and appears in Home Assistant as a switch. See [Schedules](/en/docs/black/current/configuration/schedule).
* **Presence simulation** — answer four questions and an empty house looks lived in: in the evening the lights go on room by room. See [Presence simulation](/en/docs/black/current/configuration/presence_simulation).
* **Virtual switches** — modes such as *Away* or *Evening* that other actions depend on, with no relay behind them.
* **Alarm, irrigation, thermostat, energy counters** — ready-made functions configured in the panel.
* **Secure from the first start** — the panel over HTTPS, accounts with an administrator and a read-only role, no default passwords, and a Security page that says what is still worth fixing. 1.6 is our work of adapting boneIO Black towards the EU Cyber Resilience Act (CRA).
* **Looks after itself** — boneIO, Debian and the kernel update from the panel; backups, a diagnostics bundle you can send us, and a recovery mode when a configuration does not load.
## Communication and Ecosystem [#communication-and-ecosystem]
* **Control between devices:** As a kind of central controller, the **boneIO Black** model can control other boneIO Black series controllers by sending them notifications via the MQTT broker, as well as control other modules from the ESP world by communicating with them directly through the native, local ESPHome API interface. Furthermore, it can also natively control devices dedicated to controlling addressable LED strips with WLED software (effectively allowing, for example, a "single click" of a wall button to be assigned to an instant scene initiation action from the WLED controller). Meanwhile, simple and single-task-focused controllers from the ESP family can freely communicate with each other thanks to UDP. ESP series devices cannot issue control commands to boneIO Black controllers.
* **Built-in Node-Red:** The **boneIO Black** system comes equipped with Node-Red as standard, providing a visual, full-featured, powerful tool that enables the creation of extremely complex automations within the controller itself. It is extremely useful in situations where we want to make part of the automation independent of HA. It can also be an alternative approach for the installer, making a large part of the system independent of "higher" control layers.
* **Network Connections:** boneIO Black series devices communicate exclusively via a wired Ethernet port. ESP optionally allows for WiFi connectivity. However, due to the conditions in metal electrical distribution boards, it is used very rarely.
## Modbus and Hardware Dimensions [#modbus-and-hardware-dimensions]
* **Case size:** Due to a much more powerful SOC, as well as a larger number of inputs in **boneIO Black** models, they take up slightly more space in the distribution board – 15 DIN standard poles. For those with less space, the ESP model taking up 12 DIN may prove to be a better choice.
* **Signal connectors (IO Peripherals):** Naturally, the case size translates into a larger number of available digital inputs. boneIO Black allows for connecting up to 49 of them, whereas in the case of the ESP model, we are talking about 35 inputs.
* **Modbus RS485 bus performance:** **boneIO Black** is able to handle a larger number of devices with a higher polling frequency. Thanks to the processor's multithreading, it is able to maintain high performance of other functions while polling Modbus devices.
***
## Hybrid Installations – unlock the potential! [#hybrid-installations--unlock-the-potential]
When creating the architecture of a modern smart home, it is worth considering a **hybrid** model. Creating a hybrid installation is the most optimal solution in terms of reliability and resource balance:
* Core – managing the smart home system, lights, and buttons should be moved towards the more efficient and versatile **boneIO Black** model.
* The remaining parts of the system, e.g., reading states from motion sensors, reed switches, motor control – moving gates, window shutters, garden sprinklers – are worth moving to the **ESP** platform.
# Philosophy (/en/docs/esp/introduction/philosopy)
Welcome to the world of boneIO! If you're here, it means that, like us, you believe a smart home should be truly *yours*. Not just convenient, but also reliable, private, and fully customized to your needs.
Our mission is to provide a solid foundation for your smart home. Our philosophy is built on four core pillars:
## 1. Local Control First [#1-local-control-first]
Your data, your rules, your home. boneIO devices are designed to work 100% within your local network. Thanks to the native integration with Home Assistant, all communication happens directly, with no reliance on external cloud servers. This means that even if your internet goes down, your home will still function, and your privacy remains intact.
## 2. Deep Integration and Openness [#2-deep-integration-and-openness]
Our ESP series controllers are powered by the open-source **ESPHome** project. We equally **value the philosophy of openness that Home Assistant represents**. The combination of these two open-source worlds allows us to create a product that is not only powerful but also fully transparent for the user. Instead of superficial compatibility with many systems, we chose the deepest possible integration with one, which provides a seamless experience.
## 3. Centralization and Reliability [#3-centralization-and-reliability]
Simplicity and power - thats our goals. A single boneIO controller, with its high number of inputs and outputs, is capable of handling the automation for an entire house. This centralized approach, based on professional DIN rail mounting, not only guarantees reliability and ease of maintenance but also significantly simplifies your entire smart home setup.
## 4. Support and Community [#4-support-and-community]
We believe that a great product is just the beginning. Our passion is helping our users bring their smart home vision to life, and we don't leave you on your own after the purchase. We are always happy to share our knowledge, answer questions, and help solve problems—from simple setups to complex automation scenarios.
Join our active community to get help and share your experiences:
* **Forum:** [https://forum.boneio.eu](https://forum.boneio.eu)
* **Discord:** [https://discord.gg/Hm2CzSjvtu](https://discord.gg/Hm2CzSjvtu)
With boneIO, you are building a system that is stable, centralized, and perfectly tailored to your needs. It's also sync with Home Assistant perfectly!
Let's dive in!
# System and Installation Requirements (/en/docs/esp/introduction/requirements)
Before you proceed with the installation, please review the list of requirements below. This will ensure a smooth setup process for your boneIO controller and allow you to use all of its features. Most importantly, **remember that your controller works immediately after connecting the power, even without a network connection!**
## 1. Electrical Requirements [#1-electrical-requirements]
This is the most critical section, essential for the safety and proper operation of the device.
* **Power Supply:** A stabilized DC voltage of 12V (Dimmer only) or 24V DC (check the exact value in your model's specification). The power supply should have sufficient current capacity.
* **Mounting Location:** A dry space, protected from moisture, most commonly a DIN rail within an electrical cabinet (distribution board).
### Wiring Topology [#wiring-topology]
A correct wiring layout is the foundation of a stable system.
* **Power Installation (230V/110V):** The power circuits for loads (e.g., lighting, controlled outlets) must be laid out in a **star topology**. This means each circuit is run as a separate cable directly from the electrical cabinet to the endpoint.
* **Input Installation (Switches/Sensors):** The signal cables for the inputs must also be laid out in a **star topology**. Each switch or sensor should be connected with a separate cable back to the electrical cabinet.
* **Recommended Cable for Inputs:** We recommend using **twisted-pair cable (e.g., Cat 5e or Cat 6)** to connect your switches and sensors. The controller's inputs operate on safe, low voltage.
* **Modbus RTU Installation:** If you plan to connect devices via Modbus, the wiring for this connection must be laid out in a **bus topology (daisy-chain)**.
* **Separation from Power Cables (Avoiding Interference):** To ensure error-free communication and system stability, strictly avoid running signal wires (Modbus, buttons, sensors) parallel to 230V power cables.
* Maintain a minimum distance of 30 cm when running them in parallel.
* If the cable paths must cross, do so only at a right angle (90°).
### Recommended Switches (Push-Buttons) [#recommended-switches-push-buttons]
For controlling lights and other functions, **we strongly recommend using momentary (monostable or bell-press) switches**.
**Why?** Only this type of switch allows you to take full advantage of the boneIO software's capabilities and enables **multi-click functionality**. The controller can then differentiate between various types of presses, which opens the door to advanced automations:
* **Single-click:** Standard on/off for a light.
* **Double-click:** Trigger a lighting scene, e.g., "movie mode" (30% brightness).
* **Long-press:** Smoothly dim the light up or down (for Dimmer modules) or trigger any other custom automation.
Using traditional bistable (latching ON/OFF) switches is technically possible, but it limits control to the basic on/off function and makes multi-click actions completely impossible.
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> In accordance with applicable regulations and to ensure complete safety, all activities related to the electrical installation **must be performed exclusively by a qualified electrician holding the appropriate certifications**.
## 2. Network Requirements [#2-network-requirements]
A network connection is not required for basic operation, but it is essential for configuration and remote control.
* **LAN Connection (Recommended):** A free Ethernet port on your router or switch.
* **Wi-Fi Connection (Optional):** Access to a stable 2.4 GHz Wi-Fi network.
* **Router Access:** The ability to log in to your router's admin panel to find the controller's IP address.
**Construction Time Tip:** Don't have your final internet connection yet? No problem. The controller does not require a permanent network connection for basic operation. For remote management and on-site configuration, it's enough to create a temporary Wi-Fi hotspot on your phone and connect the controller to it.
## 3. Required Tools [#3-required-tools]
* A precision screwdriver, a wire stripper, and wire cutters.
* A wire ferrule crimper.
* **A Multimeter**.
* A computer or phone for configuration.
## 4. System Requirements [#4-system-requirements]
* **Recommended Platform: Home Assistant**
The ESP series is specifically designed for deep integration with **Home Assistant**. Thanks to the native ESPHome integration, the connection is automatic, extremely stable, and provides access to all device features out-of-the-box.
* **Alternative Platform: Loxone**
While Home Assistant is the primary recommended system, integration with **Loxone** is also possible via a custom component that enables communication between the boneIO controller and the Loxone Miniserver.
## 5. Required Skills [#5-required-skills]
* **User:** Basic computer skills and an understanding of networks.
* **Installer (Electrician):** Full certification to work with electrical installations, the ability to read schematics, and knowledge of safety principles.
# Safety and Installation Requirements (/en/docs/esp/introduction/safety)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
# Connecting Digital Inputs (/en/docs/esp/advanced/connecting-digital-inputs)
## Momentary Switch [#momentary-switch]
Digital inputs are used for connecting switches and sensors. By default, they are ground-controlled.
1. Connect one of the wires from a momentary switch to the common `VDD` terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will close the circuit, which will be interpreted as an "on" signal.
### Esphome snippet [#esphome-snippet]
```yaml
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_press:
then:
- light.toggle: light_01
```
* Multi-click configuration can be found on the [multi-click](./multi-click) page.
## Reed switch [#reed-switch]
1. Connect one of the wires from a momentary switch to the common `VDD` (ground or +) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN02`).
3. When the reed switch is closed, the circuit will be closed, which will be interpreted as an "on" signal.
## Motion sensor [#motion-sensor]
1. Connect one wire from VDD to one of the NC terminal in motion sensor.
2. Connect second wire from NC terminal to the desired input terminal (e.g., `IN01`)
3. Connect 12V power supply to the motion sensor terminals.
4. When the motion sensor is triggered, the circuit will be closed, which will be interpreted as "motion" signal.
# Modbus Integration with ESPHome Packages (/en/docs/esp/advanced/esphome-packages)
# Modbus Integration with ESPHome Packages [#modbus-integration-with-esphome-packages]
One of the most powerful features of boneIO is its ability to communicate with advanced external devices, such as **heat pumps, heat recovery ventilators (HRVs), or energy meters**. These devices often use the **Modbus RTU** protocol for communication.
Manually configuring Modbus in ESPHome can be complicated. To simplify this process as much as possible, we have prepared **ESPHome Packages**—ready-made configuration templates that do all the complex work for you.
### How does it work? [#how-does-it-work]
An ESPHome package is simply a YAML file with pre-built logic. Instead of writing dozens of lines of code, you just need to include our package and fill in a few simple variables in the `substitutions` section, such as the Modbus address of your device. That's it!
***
## Step-by-Step Configuration [#step-by-step-configuration]
The following example shows how to read temperatures from a Modbus device (e.g., a heat pump) and expose them as sensors in Home Assistant.
### Prerequisites [#prerequisites]
* A working ESPHome add-on installed.
* Your boneIO device is adopted in the ESPHome dashboard.
* You know how to edit the YAML configuration file.
### Step 1: Include the Modbus Package [#step-1-include-the-modbus-package]
In your YAML configuration file for the boneIO device, add the `packages` section and point it to our eg `sdm630.yaml` file. This will import all the necessary logic for handling the RS485 bus.
```yaml
packages:
remote_package:
url: https://github.com/boneIO-eu/esphome-packages
ref: main
files: [sdm630.yaml]
```
### Step 2: Fill in the `substitutions` section [#step-2-fill-in-the-substitutions-section]
Now, add the `substitutions` section. This is where you "fill out a form" with the details of your Modbus device. You don't need to understand the complex code—just provide values for the variables below.
```yaml
substitutions:
# --- Basic Modbus Bus Configuration ---
modbus_update_interval: "60s" # How often to query the device, e.g., every 60 seconds.
modbus_address: "1" # The Modbus address of your device (check its manual).
# --- Example Sensor Configuration (find the registers in your device's manual) ---
temp_co_name: "Central Heating Temp" # Sensor name in Home Assistant
temp_co_register: "30005" # The Modbus register number for the CH temperature
temp_cwu_name: "Hot Water Temp"
temp_cwu_register: "30006"
temp_zewnetrzna_name: "Outdoor Temp"
temp_zewnetrzna_register: "30007"
```
### Step 3: Save and Upload [#step-3-save-and-upload]
After saving the file, upload the new configuration to your boneIO device. After a successful restart, new entities with the read temperatures will automatically appear in Home Assistant, ready to be used in automations and dashboards!
Full code examples can be found in the Readme of our repository [https://github.com/boneIO-eu/esphome\_packages](https://github.com/boneIO-eu/esphome_packages).
# Home Assistant Dashboard (/en/docs/esp/advanced/home-assisttant-dashboard)
# Home Assistant Dashboard [#home-assistant-dashboard]
# Firmware Installation and Reset (/en/docs/esp/advanced/installing-fresh-firmware)
Firmware is the operating system of your boneIO controller. Thanks to our modern web installer, uploading or updating the software is incredibly simple and doesn't require installing any additional tools on your computer.
The entire process is done directly from your web browser.
## Requirements [#requirements]
* A computer with Windows, macOS, or Linux.
* A web browser: **Google Chrome** or **Microsoft Edge**.
* A **USB-C** cable to connect the computer to the controller.
***
## Step-by-Step Installation [#step-by-step-installation]
### Step 1: Connect the Controller to Your Computer [#step-1-connect-the-controller-to-your-computer]
Connect your boneIO ESP controller to your computer using a USB-C cable.
> **Important:** The controller does not need to be connected to its 24V power supply at this time. The power from your computer's USB port is sufficient for the installation process.
### Step 2: Open the Web Installer [#step-2-open-the-web-installer]
In your Chrome or Edge browser, go to:
**[https://boneio.eu/esp](https://boneio.eu/esp)**
### Step 3: Choose Your Configuration [#step-3-choose-your-configuration]
On the installer page, you will see a simple configurator to help tailor the software to your needs.
1. **Choose your device version:** Select the model you have from the dropdown list (e.g., `boneIO ESP`).
2. **Choose your board version:** If there have been multiple hardware revisions for your model, an additional list will appear. Select the one you own.
3. **Configure the default output type:** Decide whether you want most of your outputs to appear in Home Assistant as `light` or `switch` entities by default. Remember, you can always change this for each output individually later.
4. **Web panel (optional):** The default firmware has no controller page — you control it from Home Assistant. The **+ web panel** variant adds a page at the controller's IP address (port 80). The page has no password and anyone on your network can switch outputs from it, so choose it only if you need it. Later you can also turn it on or off from Home Assistant (the **Firmware variant** list). See [Security](/en/docs/esp/security).
### Step 4: Start the Installation [#step-4-start-the-installation]
1. Click the **INSTALL** button.
2. A system window will pop up asking you to select a COM port. Choose the port that corresponds to your controller from the list (there is usually only one available option).
3. The installation process will begin automatically. You will see a progress bar and logs in a console window. **Do not disconnect the USB-C cable during this process!**
4. You will see a success message upon completion.
## Resetting the Device to Factory Settings [#resetting-the-device-to-factory-settings]
If you want to completely wipe the controller and install the firmware from scratch (e.g., after a failed configuration or to update to the latest version), simply **repeat the exact same steps as for the initial installation**.
The web installer will first completely erase the device's memory and then install a clean copy of the latest firmware.
***
# Multi-click Configuration (/en/docs/esp/advanced/multi-click)
# Multi-click Configuration in ESPHome [#multi-click-configuration-in-esphome]
The **multi-click** feature is one of the most powerful automation capabilities. It allows a single physical wall switch to trigger different actions depending on how it's pressed.
**Example Use Cases:**
* **Single-click:** Turn the main room light on/off.
* **Double-click:** Activate a "relax" scene (e.g., main light at 30%, turn on a floor lamp).
* **Long-press:** Smoothly dim the lights up or down.
This guide will show you how to configure this in two different ways.
### Prerequisites [#prerequisites]
Before you begin, make sure you have:
1. A working ESPHome add-on installed.
2. Your boneIO device is adopted in your ESPHome dashboard.
3. You know how to edit your device's YAML configuration file.
4. You are using **momentary (bell-press) switches**, which are required for multi-click to work.
***
## Method 1: Logic Directly in ESPHome (Recommended for Simple Actions) [#method-1-logic-directly-in-esphome-recommended-for-simple-actions]
This method is the quickest and is ideal when the actions you want to trigger involve entities available directly within ESPHome (e.g., toggling relays on the same device).
### Step 1: Prepare Your `light` Entities [#step-1-prepare-your-light-entities]
For this example, let's assume you have three lighting circuits connected to outputs `OUT01`, `OUT02`, and `OUT03`. Your configuration should include a block similar to this:
```yaml
light:
- platform: binary
name: 'Main Light'
output: out_01
id: light_01
- platform: binary
name: 'Wall Sconce'
output: out_02
id: light_02
- platform: binary
name: 'Floor Lamp'
output: out_03
id: light_03
```
### Step 2: Find and Modify Your binary\_sensor [#step-2-find-and-modify-your-binary_sensor]
In your configuration, find the input (`binary_sensor`) you want to program, for example, `IN_01`. A standard configuration looks like this:
```yaml
binary_sensor:
- platform: gpio
name: 'Living Room Switch'
pin:
# ... (pcf8574, number, mode, inverted)
# This section handles a simple click
on_press:
then:
- light.toggle: light_01
```
Delete the entire `on_press` section. It's too basic for our needs. We need to replace it with more advanced logic.
### Step 3: Add the `on_multi_click` Action [#step-3-add-the-on_multi_click-action]
In place of the deleted `on_press` section, add a new one called `on_multi_click`. This is where we'll define our actions.
```yaml
binary_sensor:
- platform: gpio
name: 'Living Room Switch'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0 # Corresponds to IN01
mode:
input: true
inverted: true
# The new, advanced section
on_multi_click:
# IMPORTANT: Order matters! ESPHome evaluates conditions from top to bottom.
# Define the most complex clicks (e.g., triple, double) first.
- timing: # Double-click
- ON for at most 1s # The press lasted less than 1 second
- OFF for at most 0.5s # The release lasted less than 0.5 seconds
- ON for at most 1s # The second press lasted less than 1 second
- OFF for at least 0.2s# The final release
then:
- light.toggle: light_02 # Action: toggle the wall sconce
- timing: # Long-press
- ON for at least 1s # The press lasted LONGER than 1 second
then:
- light.toggle: light_03 # Action: toggle the floor lamp
- timing: # Single-click
- ON for at most 1s # The press lasted less than 1 second
- OFF for at least 0.5s# The release lasted LONGER than 0.5 seconds
then:
- light.toggle: light_01 # Action: toggle the main light
```
**Tip:** You can adjust the timing values (e.g., 1s, 0.5s) to your preference to make the clicks more or less sensitive.
After saving the file, upload the new configuration to your device. Your switch now supports three different actions!
## Method 2: Sending Events to Home Assistant (For Advanced Users) [#method-2-sending-events-to-home-assistant-for-advanced-users]
This method is perfect when you want a button press to trigger a complex automation in Home Assistant that controls many different devices (not just those connected to the boneIO).
### Step 1: Create an event Entity in ESPHome [#step-1-create-an-event-entity-in-esphome]
First, we need to create a "channel" to send events to Home Assistant. Add the following code to the top of your YAML configuration.
```yaml
event:
- platform: template
name: "living room button events"
id: "in_01_events"
event_types:
- "single"
- "double"
- "long"
```
### Step 2: Modify the `on_multi_click` Actions [#step-2-modify-the-on_multi_click-actions]
Now, in addition to toggling the light, we'll add an action to send an event to Home Assistant for each click type.
```yaml
# ... (the binary_sensor section remains the same, we only modify the 'then' sections)
on_multi_click:
- timing: # Double-click
# ... (timing definition is unchanged)
then:
- light.toggle: light_02 # Local action (optional)
- event.trigger:
id: in_01_events
event_type: "double" # Send a "double" event
- timing: # Long-press
# ... (timing definition is unchanged)
then:
- light.toggle: light_03
- event.trigger:
id: in_01_events
event_type: "long" # Send a "long" event
- timing: # Single-click
# ... (timing definition is unchanged)
then:
- light.toggle: light_01
- event.trigger:
id: in_01_events
event_type: "single" # Send a "single" event
```
### Step 3: Create an Automation in Home Assistant [#step-3-create-an-automation-in-home-assistant]
After uploading the new configuration, a new entity `event.in01_events` will appear in Home Assistant. You can now use this to trigger automations.
Go to `Settings > Automations & Scenes > Create Automation` and choose "Create new automation." In YAML mode, the trigger will look like this:
```yaml
# Example automation for a double-click
trigger:
- platform: event
event_type: esphome.in_01_events # Event name, matches the ID in ESPHome
event_data:
type: "double" # Listen only for the "double" event
condition: []
action:
# Define what should happen in Home Assistant here
- service: scene.turn_on
target:
entity_id: scene.movie_night
mode: single
```
# Splitting into devices in Home Assistant (/en/docs/esp/advanced/sub-devices)
By default a boneIO ESP controller is one device in Home Assistant with all its
outputs and inputs. ESPHome can split it into **sub-devices** (`devices`), for
example one per output together with the input that drives it. Each sub-device
gets its own area (room) and its own page in Home Assistant, and the device list
shows it as connected through the controller.
Firmware from [boneio.eu/esp](https://boneio.eu/esp) does not do this — you set
up the split yourself in a configuration taken over in ESPHome Device Builder.
## Requirements [#requirements]
* The controller taken over in ESPHome Device Builder — see
[Connecting to boneIO ESP](/en/docs/esp/how-to-connect).
* ESPHome 2025.7 or newer.
## Step 1: define the devices [#step-1-define-the-devices]
Add a `devices` list to the `esphome:` section. Leave the rest of the section
as it is.
```yaml
esphome:
name: '${name}'
# ... rest of the section unchanged
devices:
- id: out_01_device
name: Out01
- id: out_02_device
name: Out02
```
`id` is the name used in YAML, `name` is the device name in Home Assistant. You
can rename the device in Home Assistant later.
## Step 2: assign the entities [#step-2-assign-the-entities]
Add `device_id` to the output and the input that belong to the device:
```yaml
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
device_id: out_01_device
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
device_id: out_01_device
pin:
# ... unchanged
```
Entities without `device_id` stay on the main device. Then upload the
configuration with **Install**.
**Do not change entity names (`name`) when you add `device_id`.** Home
Assistant recognises a moved entity by its name and keeps its `entity_id`,
history and automations. An entity with a new name or with `name: None` shows
up as a new one, and automations that used the old one stop working.
Home Assistant shows the entity with the device name in front, for example
"Out01 Light 01". When you rename the device in Home Assistant to "Living room
lamp", the entity becomes "Living room lamp Light 01".
## What to put in one device [#what-to-put-in-one-device]
With [local control](/en/docs/home-assistant/boneio-esp#local-control) on,
input `IN_01` toggles output 1, `IN_02` output 2 and so on. Such pairs are
usually in the same room, so put them in one device. On Cover and Cover Mix,
assign both inputs of a cover — up and down — to that cover's device.
A button that drives something other than the output with the same number goes
to the device it drives, or stays on the main device.
## Areas (optional) [#areas-optional]
The simplest way to set the area is in Home Assistant: open the sub-device and
pick an area. You can also set it in YAML:
```yaml
esphome:
areas:
- id: living_room
name: Living room
devices:
- id: out_01_device
name: Out01
area_id: living_room
```
# Changing Entity Type (Light / Switch) (/en/docs/esp/advanced/switch-lights)
# Changing Entity Type (Light / Switch) [#changing-entity-type-light--switch]
Sometimes the default configuration of an output as a `light` doesn't fit its actual use. For example, when you connect an outlet, a fan, or a pump to it. In such cases, it's a good idea to change the entity type to a `switch` so that Home Assistant categorizes it more appropriately.
* **Light:** The entity appears in the `light` domain, is controlled by voice commands like "turn on all the lights," and is intended for light sources.
* **Switch:** A more generic on/off entity. Perfect for outlets, fans, solenoid valves, and other non-illuminating devices.
> **Note:** In YAML files, indentation is critical. Always use spaces, not tabs, and maintain proper alignment.
***
## Prerequisites [#prerequisites]
* A working ESPHome add-on installed.
* Your boneIO device is adopted in the ESPHome dashboard.
* You know how to edit the YAML configuration file.
***
## Changing from `light` to `switch` [#changing-from-light-to-switch]
In this example, we will change `light_02` into a `switch_02` entity. The process consists of two simple steps.
### Step 1: Change the output definition [#step-1-change-the-output-definition]
We need to move the output definition from the `light` section to the `switch` section and modify it slightly.
**BEFORE:**
```yaml
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
- platform: binary
name: 'Light 02'
output: out_02
id: light_02
```
**AFTER:**
```yaml
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
# New section for switches
switch:
- platform: output # Change 'binary' to 'output'
name: 'Living Room Outlet' # New, more fitting name
output: out_02
id: switch_02 # New ID
```
### Step 2: Update the button action [#step-2-update-the-button-action]
Now, we must tell the button to control the new switch (`switch_02`), not the old light (`light_02`), otherwise the configuration will be invalid.
**BEFORE:**
```yaml
binary_sensor:
- platform: gpio
name: 'IN_02'
# ... rest of the pin configuration
on_press:
then:
- light.toggle: light_02 # This line refers to the old ID
```
**AFTER:**
```yaml
binary_sensor:
- platform: gpio
name: 'IN_02'
# ... rest of the pin configuration
on_press:
then:
- switch.toggle: switch_02 # Updated domain (switch) and ID (switch_02)
```
After these changes, save the file and upload the new configuration. You're done!
***
## Changing from `switch` to `light` [#changing-from-switch-to-light]
The process is almost identical, just in reverse. In this example, we will change `switch_02` to `light_02`.
### Step 1: Change the output definition [#step-1-change-the-output-definition-1]
**BEFORE:**
```yaml
switch:
- platform: output
name: 'Switch 01'
output: out_01
id: switch_01
- platform: output
name: 'Living Room Outlet'
output: out_02
id: switch_02
```
**AFTER:**
```yaml
switch:
- platform: output
name: 'Switch 01'
output: out_01
id: switch_01
# Moved element to the light section
light:
- platform: binary # Change 'output' to 'binary'
name: 'Living Room Sconce' # New name
output: out_02
id: light_02 # New ID
```
### Step 2: Update the button action [#step-2-update-the-button-action-1]
**BEFORE:**
```yaml
binary_sensor:
- platform: gpio
name: 'IN_02'
# ... rest of the pin configuration
on_press:
then:
- switch.toggle: switch_02
```
**AFTER:**
```yaml
binary_sensor:
- platform: gpio
name: 'IN_02'
# ... rest of the pin configuration
on_press:
then:
- light.toggle: light_02
```
Save the file and upload the configuration. The `OUT02` output will now appear in Home Assistant as a light.
# UDP Communication Between Devices (/en/docs/esp/advanced/udp-communication)
# UDP Communication Between Devices [#udp-communication-between-devices]
The ESPHome [UDP](https://esphome.io/components/udp/) component, combined with [Packet Transport](https://esphome.io/components/packet_transport/), allows two (or more) boneIO ESP devices to communicate directly over the local network. This is useful when you want one device to react to an input or sensor state from another device — **without going through Home Assistant or any other broker**.
Common use cases:
* A wall switch on **Dimmer A** controls a light on **Dimmer B**
* A temperature sensor on one device is displayed or used on another
* Synchronizing binary sensor states between devices
***
## How It Works [#how-it-works]
1. **Provider** — the device that broadcasts its sensor/binary sensor states over UDP.
2. **Consumer** — the device that receives those states and can act on them.
A single device can be both a provider and a consumer at the same time.
The data is sent via UDP broadcast on the local network (default port `18511`). No IP configuration is needed for basic setups — all devices on the same subnet will receive the broadcast.
***
## Prerequisites [#prerequisites]
* Two (or more) boneIO ESP devices on the **same network**.
* ESPHome **2025.6.0** or newer (UDP + Packet Transport support).
* Access to the ESPHome dashboard to edit YAML configs.
***
## Example: Two boneIO Dimmer Gen2 Devices [#example-two-boneio-dimmer-gen2-devices]
In this scenario, we have two boneIO Dimmer Gen2 devices. We want **Input 1 on Dimmer A** to toggle **Light CHL 01 on Dimmer B**, and vice versa.
### Network Diagram [#network-diagram]
```
┌──────────────────┐ UDP broadcast ┌──────────────────┐
│ Dimmer A │ ◄──────────────────────────► │ Dimmer B │
│ │ (port 18511) │ │
│ IN_01 ──► toggle│ │ IN_01 ──► toggle│
│ light on B │ │ light on A │
│ │ │ │
│ CHL 01 (light) │ │ CHL 01 (light) │
└──────────────────┘ └──────────────────┘
```
***
### Dimmer A Configuration [#dimmer-a-configuration]
Add the following sections to your Dimmer A YAML config. The key parts are `udp`, `packet_transport`, and the `binary_sensor` with `platform: packet_transport`.
```yaml title="Dimmer A — boneio-dimmer-a.yaml"
substitutions:
name: boneio-dimmer-a
friendly_name: "BoneIO Dimmer A"
# ... (standard esphome, esp32, ethernet, i2c, output, light sections)
# ──────────────────────────────────────────────
# UDP transport — broadcasts and receives on LAN
# ──────────────────────────────────────────────
udp:
# ──────────────────────────────────────────────
# Packet Transport — what to send and from whom to receive
# ──────────────────────────────────────────────
packet_transport:
platform: udp
update_interval: 5s
# Broadcast these binary sensors to other devices
binary_sensors:
- in_01_state_dimmer_a
# Declare providers we want to receive data from
providers:
- name: boneio-dimmer-b # must match the ESPHome 'name' of Dimmer B
# ──────────────────────────────────────────────
# Template binary sensor — mirrors IN_01 state for broadcasting
# ──────────────────────────────────────────────
binary_sensor:
# Physical input
- platform: gpio
name: "IN_01"
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_press:
then:
- light.toggle: chl_01
# Template sensor that mirrors IN_01 — this gets broadcast via UDP
- platform: template
id: in_01_state_dimmer_a
lambda: "return id(in_01).state;"
# Receive IN_01 state from Dimmer B — toggle local light
- platform: packet_transport
provider: boneio-dimmer-b
id: in_01_state_dimmer_b # must match the broadcast id on Dimmer B
on_press:
then:
- light.toggle: chl_01
```
### Dimmer B Configuration [#dimmer-b-configuration]
The configuration is symmetrical — Dimmer B broadcasts its own `in_01_state_dimmer_b` and listens for `in_01_state_dimmer_a` from Dimmer A.
```yaml title="Dimmer B — boneio-dimmer-b.yaml"
substitutions:
name: boneio-dimmer-b
friendly_name: "BoneIO Dimmer B"
# ... (standard esphome, esp32, ethernet, i2c, output, light sections)
# ──────────────────────────────────────────────
# UDP transport
# ──────────────────────────────────────────────
udp:
# ──────────────────────────────────────────────
# Packet Transport
# ──────────────────────────────────────────────
packet_transport:
platform: udp
update_interval: 5s
binary_sensors:
- in_01_state_dimmer_b
providers:
- name: boneio-dimmer-a # must match the ESPHome 'name' of Dimmer A
# ──────────────────────────────────────────────
# Binary sensors
# ──────────────────────────────────────────────
binary_sensor:
# Physical input
- platform: gpio
name: "IN_01"
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_press:
then:
- light.toggle: chl_01
# Template sensor — broadcast via UDP
- platform: template
id: in_01_state_dimmer_b
lambda: "return id(in_01).state;"
# Receive from Dimmer A
- platform: packet_transport
provider: boneio-dimmer-a
id: in_01_state_dimmer_a # must match the broadcast id on Dimmer A
on_press:
then:
- light.toggle: chl_01
```
***
## Multi-Click over UDP [#multi-click-over-udp]
When using `on_multi_click` with UDP, **always process the timing on the source device** (Dimmer A). The source device detects the click pattern locally and pulses a template binary sensor for each event type. The remote device (Dimmer B) receives these pulses via `packet_transport` and controls its lights accordingly.
> **Why not send the raw button state?** Multi-click detection relies on precise timing. Sending raw press/release events over UDP would introduce network jitter and unreliable detection on the remote side. By resolving the click pattern locally, Dimmer B gets a clean, instant signal.
### Dimmer A — detects multi-click, broadcasts results [#dimmer-a--detects-multi-click-broadcasts-results]
```yaml title="Dimmer A — boneio-dimmer-a.yaml"
udp:
packet_transport:
platform: udp
update_interval: 5s
binary_sensors:
- single_click_dimmer_a_in_01
- double_click_dimmer_a_in_01
- long_press_dimmer_a_in_01
providers:
- name: boneio-dimmer-b
light:
- platform: monochromatic
output: chl01
name: "CHL 01"
id: chl_01
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl02
name: "CHL 02"
id: chl_02
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl03
name: "CHL 03"
id: chl_03
default_transition_length: 2s
gamma_correct: 0
binary_sensor:
# Physical input with multi-click detection
- platform: gpio
name: "IN_01"
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_multi_click:
# Long press
- timing:
- ON for at least 1.4s
then:
- logger.log: "Long press detected"
- light.toggle: chl_01
- binary_sensor.template.publish:
id: long_press_dimmer_a_in_01
state: ON
- delay: 200ms
- binary_sensor.template.publish:
id: long_press_dimmer_a_in_01
state: OFF
# Double click
- timing:
- ON for at most 1s
- OFF for at most 0.5s
- ON for at most 1s
- OFF for at least 0.2s
then:
- logger.log: "Double click detected"
- light.toggle: chl_02
- binary_sensor.template.publish:
id: double_click_dimmer_a_in_01
state: ON
- delay: 200ms
- binary_sensor.template.publish:
id: double_click_dimmer_a_in_01
state: OFF
# Single click
- timing:
- ON for at most 1s
- OFF for at least 0.5s
then:
- logger.log: "Single click detected"
- light.toggle: chl_03
- binary_sensor.template.publish:
id: single_click_dimmer_a_in_01
state: ON
- delay: 200ms
- binary_sensor.template.publish:
id: single_click_dimmer_a_in_01
state: OFF
# Template binary sensors — pulse ON/OFF to broadcast click events via UDP
- platform: template
id: single_click_dimmer_a_in_01
- platform: template
id: double_click_dimmer_a_in_01
- platform: template
id: long_press_dimmer_a_in_01
```
### Dimmer B — receives multi-click events, controls lights [#dimmer-b--receives-multi-click-events-controls-lights]
```yaml title="Dimmer B — boneio-dimmer-b.yaml"
udp:
packet_transport:
platform: udp
providers:
- name: boneio-dimmer-a
light:
- platform: monochromatic
output: chl01
name: "CHL 01"
id: chl_01
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl02
name: "CHL 02"
id: chl_02
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl03
name: "CHL 03"
id: chl_03
default_transition_length: 2s
gamma_correct: 0
binary_sensor:
# Receive click events from Dimmer A
- platform: packet_transport
provider: boneio-dimmer-a
id: long_press_dimmer_a_in_01
on_press:
then:
- light.toggle: chl_01
- platform: packet_transport
provider: boneio-dimmer-a
id: double_click_dimmer_a_in_01
on_press:
then:
- light.toggle: chl_02
- platform: packet_transport
provider: boneio-dimmer-a
id: single_click_dimmer_a_in_01
on_press:
then:
- light.toggle: chl_03
```
> **How it works:** Dimmer A detects the click pattern and briefly pulses (ON → 200ms → OFF) the corresponding template binary sensor. `packet_transport` broadcasts the state change. Dimmer B receives it and uses `on_press` to toggle the appropriate light.
***
## Example: Input24 Gen2 → 32x10 Lights [#example-input24-gen2--32x10-lights]
A common setup — the **boneIO Input24 Gen2** has 24 inputs but no light outputs, while the **boneIO 32x10 Lights** has 32 relay outputs but may not have enough local inputs. Using UDP you can press a button on Input24 and toggle a light on 32x10.
### Network Diagram [#network-diagram-1]
```
┌──────────────────┐ UDP broadcast ┌──────────────────┐
│ Input24 Gen2 │ ─────────────────────────► │ 32x10 Lights │
│ (ESP32-S3) │ (port 18511) │ (ESP32) │
│ │ │ │
│ IN_01 ──► sends │ │ receives ──► │
│ state via UDP │ │ light.toggle │
│ │ │ Light 01 │
└──────────────────┘ └──────────────────┘
```
### Input24 Gen2 — full configuration (broadcasts all 24 inputs) [#input24-gen2--full-configuration-broadcasts-all-24-inputs]
```yaml title="Input24 Gen2 — boneio-input24-gen2-01.yaml"
substitutions:
name: boneio-input24-gen2-01
friendly_name: "boneIO ESP Input24 Gen2"
serial_prefix: "esp24"
firmware_manifest: "https://boneio.eu/fwesp/boneio-input24-gen2-01.json"
esphome:
name: "${name}"
friendly_name: "${friendly_name}"
name_add_mac_suffix: true
project:
name: boneio.input24-gen2
version: "0.1"
esp32:
board: esp32-s3-devkitc-1
framework:
type: esp-idf
ethernet:
id: eth
type: W5500
clk_pin: GPIO13
mosi_pin: GPIO39
miso_pin: GPIO38
cs_pin: GPIO12
interrupt_pin: GPIO2
reset_pin: GPIO1
clock_speed: 25MHz
i2c:
sda: GPIO10
scl: GPIO11
scan: true
frequency: 400kHz
uart:
id: boneio_uart
rx_pin: GPIO21
tx_pin: GPIO14
baud_rate: 9600
stop_bits: 1
modbus:
send_wait_time: 80ms
uart_id: boneio_uart
id: boneio_modbus
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: packages-v2.0.0
files: ["packages/devices/serial_no.yaml"]
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-input24_gen2-v0_1.yaml@latest
import_full_config: true
pcf8574:
- id: pcf_inputs_1_to_8
address: 0x38
- id: pcf_inputs_9_to_24
address: 0x20
pcf8575: true
logger:
hardware_uart: UART0
api:
reboot_timeout: 0s
ota:
- platform: esphome
- platform: web_server
web_server:
port: 80
version: 3
local: true
sensor:
- platform: lm75b
id: boneIO_temp
name: "Temperature"
update_interval: 30s
entity_category: diagnostic
on_value_range:
- above: 70.0
then:
- switch.turn_on: buzzer
- below: 70.0
then:
- switch.turn_off: buzzer
switch:
- platform: gpio
id: buzzer
name: "Buzzer"
pin:
number: GPIO9
mode:
output: true
inverted: false
# ──────────────────────────────────────────────
# UDP + Packet Transport — broadcast all 24 inputs
# ──────────────────────────────────────────────
udp:
packet_transport:
platform: udp
update_interval: 5s
binary_sensors:
- in_01_state_input24
- in_02_state_input24
- in_03_state_input24
- in_04_state_input24
- in_05_state_input24
- in_06_state_input24
- in_07_state_input24
- in_08_state_input24
- in_09_state_input24
- in_10_state_input24
- in_11_state_input24
- in_12_state_input24
- in_13_state_input24
- in_14_state_input24
- in_15_state_input24
- in_16_state_input24
- in_17_state_input24
- in_18_state_input24
- in_19_state_input24
- in_20_state_input24
- in_21_state_input24
- in_22_state_input24
- in_23_state_input24
- in_24_state_input24
# ──────────────────────────────────────────────
# Physical inputs (IN_01 to IN_08 — pcf_inputs_1_to_8)
# ──────────────────────────────────────────────
binary_sensor:
- platform: gpio
name: "IN_01"
id: in_01
pin:
pcf8574: pcf_inputs_1_to_8
number: 0
mode:
input: true
inverted: true
- platform: gpio
name: "IN_02"
id: in_02
pin:
pcf8574: pcf_inputs_1_to_8
number: 1
mode:
input: true
inverted: true
- platform: gpio
name: "IN_03"
id: in_03
pin:
pcf8574: pcf_inputs_1_to_8
number: 2
mode:
input: true
inverted: true
- platform: gpio
name: "IN_04"
id: in_04
pin:
pcf8574: pcf_inputs_1_to_8
number: 3
mode:
input: true
inverted: true
- platform: gpio
name: "IN_05"
id: in_05
pin:
pcf8574: pcf_inputs_1_to_8
number: 4
mode:
input: true
inverted: true
- platform: gpio
name: "IN_06"
id: in_06
pin:
pcf8574: pcf_inputs_1_to_8
number: 5
mode:
input: true
inverted: true
- platform: gpio
name: "IN_07"
id: in_07
pin:
pcf8574: pcf_inputs_1_to_8
number: 6
mode:
input: true
inverted: true
- platform: gpio
name: "IN_08"
id: in_08
pin:
pcf8574: pcf_inputs_1_to_8
number: 7
mode:
input: true
inverted: true
# ──────────────────────────────────────────────
# Physical inputs (IN_09 to IN_24 — pcf_inputs_9_to_24)
# ──────────────────────────────────────────────
- platform: gpio
name: "IN_09"
id: in_09
pin:
pcf8574: pcf_inputs_9_to_24
number: 7
mode:
input: true
inverted: true
- platform: gpio
name: "IN_10"
id: in_10
pin:
pcf8574: pcf_inputs_9_to_24
number: 6
mode:
input: true
inverted: true
- platform: gpio
name: "IN_11"
id: in_11
pin:
pcf8574: pcf_inputs_9_to_24
number: 5
mode:
input: true
inverted: true
- platform: gpio
name: "IN_12"
id: in_12
pin:
pcf8574: pcf_inputs_9_to_24
number: 4
mode:
input: true
inverted: true
- platform: gpio
name: "IN_13"
id: in_13
pin:
pcf8574: pcf_inputs_9_to_24
number: 3
mode:
input: true
inverted: true
- platform: gpio
name: "IN_14"
id: in_14
pin:
pcf8574: pcf_inputs_9_to_24
number: 2
mode:
input: true
inverted: true
- platform: gpio
name: "IN_15"
id: in_15
pin:
pcf8574: pcf_inputs_9_to_24
number: 1
mode:
input: true
inverted: true
- platform: gpio
name: "IN_16"
id: in_16
pin:
pcf8574: pcf_inputs_9_to_24
number: 0
mode:
input: true
inverted: true
- platform: gpio
name: "IN_17"
id: in_17
pin:
pcf8574: pcf_inputs_9_to_24
number: 15
mode:
input: true
inverted: true
- platform: gpio
name: "IN_18"
id: in_18
pin:
pcf8574: pcf_inputs_9_to_24
number: 14
mode:
input: true
inverted: true
- platform: gpio
name: "IN_19"
id: in_19
pin:
pcf8574: pcf_inputs_9_to_24
number: 13
mode:
input: true
inverted: true
- platform: gpio
name: "IN_20"
id: in_20
pin:
pcf8574: pcf_inputs_9_to_24
number: 12
mode:
input: true
inverted: true
- platform: gpio
name: "IN_21"
id: in_21
pin:
pcf8574: pcf_inputs_9_to_24
number: 11
mode:
input: true
inverted: true
- platform: gpio
name: "IN_22"
id: in_22
pin:
pcf8574: pcf_inputs_9_to_24
number: 10
mode:
input: true
inverted: true
- platform: gpio
name: "IN_23"
id: in_23
pin:
pcf8574: pcf_inputs_9_to_24
number: 9
mode:
input: true
inverted: true
- platform: gpio
name: "IN_24"
id: in_24
pin:
pcf8574: pcf_inputs_9_to_24
number: 8
mode:
input: true
inverted: true
# ──────────────────────────────────────────────
# Template sensors — mirror each input for UDP broadcast
# ──────────────────────────────────────────────
- platform: template
id: in_01_state_input24
lambda: "return id(in_01).state;"
- platform: template
id: in_02_state_input24
lambda: "return id(in_02).state;"
- platform: template
id: in_03_state_input24
lambda: "return id(in_03).state;"
- platform: template
id: in_04_state_input24
lambda: "return id(in_04).state;"
- platform: template
id: in_05_state_input24
lambda: "return id(in_05).state;"
- platform: template
id: in_06_state_input24
lambda: "return id(in_06).state;"
- platform: template
id: in_07_state_input24
lambda: "return id(in_07).state;"
- platform: template
id: in_08_state_input24
lambda: "return id(in_08).state;"
- platform: template
id: in_09_state_input24
lambda: "return id(in_09).state;"
- platform: template
id: in_10_state_input24
lambda: "return id(in_10).state;"
- platform: template
id: in_11_state_input24
lambda: "return id(in_11).state;"
- platform: template
id: in_12_state_input24
lambda: "return id(in_12).state;"
- platform: template
id: in_13_state_input24
lambda: "return id(in_13).state;"
- platform: template
id: in_14_state_input24
lambda: "return id(in_14).state;"
- platform: template
id: in_15_state_input24
lambda: "return id(in_15).state;"
- platform: template
id: in_16_state_input24
lambda: "return id(in_16).state;"
- platform: template
id: in_17_state_input24
lambda: "return id(in_17).state;"
- platform: template
id: in_18_state_input24
lambda: "return id(in_18).state;"
- platform: template
id: in_19_state_input24
lambda: "return id(in_19).state;"
- platform: template
id: in_20_state_input24
lambda: "return id(in_20).state;"
- platform: template
id: in_21_state_input24
lambda: "return id(in_21).state;"
- platform: template
id: in_22_state_input24
lambda: "return id(in_22).state;"
- platform: template
id: in_23_state_input24
lambda: "return id(in_23).state;"
- platform: template
id: in_24_state_input24
lambda: "return id(in_24).state;"
```
> **Note:** Input24 Gen2 has no light outputs, so it only acts as a provider. It does not need a `providers` section.
### 32x10 Lights — consumer (receives IN\_01 from Input24, toggles Light 01) [#32x10-lights--consumer-receives-in_01-from-input24-toggles-light-01]
On the 32x10 side, only the UDP/Packet Transport sections need to be added to the existing configuration. The rest of the config (lights, local inputs) stays unchanged.
```yaml title="32x10 Lights — add to boneio-32-l-07.yaml"
# ──────────────────────────────────────────────
# UDP + Packet Transport
# ──────────────────────────────────────────────
udp:
packet_transport:
platform: udp
providers:
- name: boneio-input24-gen2-01 # must match the ESPHome 'name' of Input24
# Add this to your existing binary_sensor section:
binary_sensor:
# ... (keep all existing local inputs IN_01..IN_32 unchanged)
# Receive IN_01 from Input24 Gen2 — toggle Light 01
- platform: packet_transport
provider: boneio-input24-gen2-01
id: in_01_state_input24
on_press:
then:
- light.toggle: light_01
```
> **Scaling up:** To react to more inputs from Input24, add more `packet_transport` binary sensors on 32x10 — e.g. `in_02_state_input24` → `light.toggle: light_02`, etc. All 24 inputs are already being broadcast.
***
## Sharing Sensor Data (e.g. Temperature) [#sharing-sensor-data-eg-temperature]
You can also share sensor values between devices. For example, broadcasting the onboard temperature sensor from Dimmer A so Dimmer B can display it:
```yaml title="Dimmer A — provider"
packet_transport:
platform: udp
update_interval: 30s
sensors:
- boneIO_temp # id of the lm75b temperature sensor
```
```yaml title="Dimmer B — consumer"
packet_transport:
platform: udp
providers:
- name: boneio-dimmer-a
sensor:
- platform: packet_transport
provider: boneio-dimmer-a
id: boneIO_temp # same id as on Dimmer A
name: "Dimmer A Temperature"
```
***
## Adding Encryption [#adding-encryption]
For added security, you can encrypt the UDP communication. Both sides must use the **same encryption key**:
```yaml title="Both devices"
packet_transport:
platform: udp
encryption: "my-secret-key-here"
rolling_code_enable: true
# ... rest of config
providers:
- name: boneio-dimmer-b
encryption: "my-secret-key-here"
```
> **Tip:** Store the encryption key in your `secrets.yaml` file and reference it with `!secret udp_encryption_key`.
***
## Important Notes [#important-notes]
> **Packet Transport supports only `sensor` and `binary_sensor`!**
> The `packet_transport` component can **only** broadcast and receive `sensor` and `binary_sensor` entities. It does **not** support lights, switches, covers, events, or any other entity types. This is why we use template binary sensors as "signal carriers" to transmit click events between devices (see the Multi-Click example above).
* **Same network required** — UDP broadcast works only within the same subnet. If your devices are on different VLANs, you need to specify explicit IP addresses in the `udp` → `addresses` list.
* **No delivery guarantee** — UDP does not guarantee delivery. The `packet_transport` component re-sends data periodically (controlled by `update_interval`) to mitigate this.
* **Device names matter** — the `provider: name` must exactly match the `esphome: name` of the other device. If the provider has `name_add_mac_suffix: true`, the actual device name will have a MAC address suffix appended (e.g. `boneio-input24-gen2-01-a1b2c3`). You can find the full name in the ESPHome logs at boot or in the Home Assistant device name. Use that full name in `provider: name`.
* **Unique IDs** — each device should broadcast under a unique id (e.g. `in_01_state_dimmer_a`, `in_01_state_dimmer_b`) to avoid confusion. The consumer references the remote id by matching the provider name + id.
* **ESPHome version** — make sure both devices run ESPHome **2025.6.0+** for full UDP + Packet Transport support.
***
## See Also [#see-also]
* [ESPHome UDP Component](https://esphome.io/components/udp/)
* [ESPHome Packet Transport Component](https://esphome.io/components/packet_transport/)
* [Packet Transport Binary Sensor](https://esphome.io/components/binary_sensor/packet_transport/)
* [Packet Transport Sensor](https://esphome.io/components/sensor/packet_transport/)
# Welcome (/en/docs/esp/troubleshooting)
## Welcome to boneIO ESP Documentation! [#welcome-to-boneio-esp-documentation]
On this page, you'll find step-by-step guides and instructions for configuring your boneIO ESP controller. Whether you have one of our larger models like ESP 32x10, 24x16, Cover, or Cover Mix, or one of our smaller devices like the Dimmer or 8x10A, you'll find the documentation you need to get started.
Your device comes preinstalled with ESPHome and a default configuration. You'll need to adjust it to match your specific requirements. Below are the essential steps to help you configure your boneIO ESP controller:
# HTTPS certificate (/en/docs/black/current/advanced/certificate)
The panel is always served over an encrypted connection, at `https://:8443`.
By default it uses a certificate **the controller issued itself**. The connection is just as encrypted, but browsers do not know
that issuer, so they warn on every visit. The certificate is valid for six months, so the browser exception you accept lasts that long
(on a controller upgraded from 1.5, from its next restart).
Clicking through the warning is fine on your own network. If you would rather not see it, there are three ways. Options 2 and 3 are on the **Certificate** card in
**Settings** → **Access** → **Security**; option 1 is in **Settings** → **Access** → **Web Server**.
## Option 1: boneIO Cloud — the easiest [#option-1-boneio-cloud--the-easiest]
Register the controller with boneIO Cloud (in the [first-time setup](/en/docs/black/current/install/first-run-wizard#cloud-optional)
or later in **Settings** → **Access** → **Web Server**). The controller gets its own address with a certificate every browser trusts.
* It sends the controller's serial number to boneIO Cloud.
* The address points at the controller's local IP, so it still works **only in your own network**.
* Your router must not block *DNS rebinding*, otherwise the new address does not open.
If you do not want this, tick **Not interested in cloud registration** in **Settings** → **Access** → **Web Server** — the panel then stops recommending it.
## Option 2: trust the controller on your computers [#option-2-trust-the-controller-on-your-computers]
Click **Download this device's authority** and install the downloaded file on each computer and phone you open the panel from,
as a *trusted root certificate authority*:
* **Windows** — double-click the file → **Install Certificate** → *Local Machine* → *Place all certificates in the following store* → **Trusted Root Certification Authorities**
* **macOS** — double-click the file to add it to *Keychain Access*, open it there and set *When using this certificate* to **Always Trust**
* **Android / iOS** — open the file and install it as a CA certificate (on iOS then enable it in *Settings → General → About → Certificate Trust Settings*)
* **Firefox** uses its own list: *Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import*
Then open the panel at the name shown under **Open the panel at** — a name, not the IP address, because the address can change with the next DHCP lease.
A computer that trusts this authority will believe it about **any** name, not only this controller. Install it only on your own devices.
## Option 3: your own certificate [#option-3-your-own-certificate]
If you have a certificate for a domain of your own (for example from your company or from Let's Encrypt), upload it:
1. **Certificate** — PEM file, preferably the full chain
2. **Private key** — PEM file, **without a passphrase** (the controller starts unattended and has nobody to ask for it)
3. Click **Upload and use**
The page tells you if the certificate does not cover the names the controller is reached by. **Remove and go back** returns to the controller's own certificate.
## Ports [#ports]
| Port | What |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `8443` | The panel over HTTPS — use this one |
| `8090` | The panel without encryption. On controllers installed with 1.6 it answers only locally and over the USB cable (`http://192.168.7.2:8090`). On controllers upgraded from 1.5 it may still answer on the network until you follow the **Panel served in the clear** item in Security. |
# Advanced (/en/docs/black/current/advanced)
# NodeRED (/en/docs/black/current/advanced/nodered)
**Since 1.6** the Node-RED editor asks you to sign in with your **boneIO administrator account** — read-only accounts are refused.
Node-RED itself (status, restart, backups, updates) is managed in **Settings** → **Services on this controller** → **Node-RED** — see [Updating Node-RED](/en/docs/black/current/basic/node-red#updating-node-red).
## Node-RED in boneIO Black: Advanced Local Logic (v1.2.0) [#node-red-in-boneio-black-advanced-local-logic-v120]
With application version 1.2.0, the boneIO Black controller has gained a powerful tool: full, native support for the Node-RED environment. It is a flow-based programming platform that has been integrated directly into the device's operating system.
The Node-RED editor is available directly via a web browser through the boneIO web UI, allowing for convenient logic creation without the need to install additional software.
### A new dimension of automation! [#a-new-dimension-of-automation]
boneIO has always offered lightning-fast handling of inputs and outputs as well as basic hardware functions (like double-click or long press). However, the integration with Node-RED takes the device's capabilities to a completely different level – it transforms from a fast execution controller into an autonomous building logic manager.
The introduction of Node-RED allows for the creation of advanced automation scenarios that are processed internally by the controller, without the involvement of Home Assistant or other external servers.
1. **Conditional and multi-stage logic:** You can create dependencies that go beyond simple "press – turn on" actions. Node-RED enables combining multiple conditions (e.g., the status of several sensors simultaneously, time of day, counters) before taking action.
2. **Timer and schedule support:** Native support for nodes such as delay, trigger, or bigtimer allows for the implementation of time-based automations (e.g., delayed turn-offs, cyclic pump control) directly on boneIO.
3. **Advanced sensor support:** Utilize motion, contact, or temperature sensors connected directly to boneIO not just for status reporting but for direct control of outputs with logic in mind (e.g., thermostat hysteresis, motion detector time locks).
4. **Full autonomy (Standalone):** Complex automations (such as lighting control in corridors or shutter logic) work independently of the LAN. A Home Assistant or router failure does not affect the home's functionality – the "brain" of the operation is located in the distribution board.
### Application example: Intelligent hallway lighting [#application-example-intelligent-hallway-lighting]
The following scenario illustrates the advantage of Node-RED over simple input mapping. Assume a momentary button and a wired motion detector are connected to boneIO.
**Scenario in Node-RED implemented locally:**
* **Motion**: When the detector senses motion, the light turns on, but only for 2 minutes (a simple timer). Every subsequent motion resets the timer.
* **Lock**: If a resident presses the physical button on the wall, the system enters "Permanent On" mode (e.g., for cleaning) – it ignores the timer and motion detector, keeping the light on until the button is clicked again.
* **Night**: The automation can additionally check the time of day condition (based on the boneIO system clock) so that at night, the light turns on at only 20% power (if using a dimmer) or does not turn on at all.
Thanks to Node-RED, all this logic – including timers, status flags, and conditions – is executed in a fraction of a second inside boneIO Black, guaranteeing reliability regardless of the rest of the Smart Home system.
### Advantages of Node-RED [#advantages-of-node-red]
**Stability Architecture: Home Assistant as Visualization, Node-RED as the Heart**
The introduction of Node-RED on board boneIO Black allows for the implementation of a professional division between the **Execution Layer (boneIO)** and the **Supervision Layer (Home Assistant)**.
While Home Assistant is an incredibly powerful, stable, and dynamically developing system, its role in a modern smart home should evolve:
**Continuity of operation (Uptime)**: Home Assistant often requires restarts (e.g., during system updates, add-on updates, or YAML configuration changes). Moving key logic (lighting, heating, shutters) to Node-RED in boneIO ensures the home "lives" uninterrupted. While you are updating Home Assistant, your family can still use the automation, motion sensors, and timers without any disruption.
**Critical Safety**: Functions key to building safety (e.g., closing a water valve upon leak detection, controlling heating pumps) should operate at the lowest possible hardware level. Node-RED on boneIO eliminates intermediaries – the decision and action happen within a single control cabinet.
**Optimal division of tasks:**
**boneIO + Node-RED**: Performs critical tasks requiring immediate response and reliability ("hard real-time" logic).
**Home Assistant**: Serves as an extensive visual interface, executor of very complex automations – those requiring the cooperation of several integrated devices, historical data aggregator, gateway to cloud services (weather, voice integrations), and the end-user control panel.
Such an architecture provides what is most important in building automation: the reliability of the main controller (boneIO) combined with the modernity and convenience of Home Assistant.
# Accounts and access (/en/docs/black/current/basic/accounts)
From 1.6 the panel has accounts. A controller with no account answers no API
request at all until one is created.
This applies whichever version you upgrade from. A controller going straight
from 1.5 to 1.7 behaves the same as one going to 1.6 — the rule is about the
state of the device, not about the version it came from.
## First run [#first-run]
A controller with no account shows a wizard:
1. Start
2. Account — create the administrator account
3. Import — optionally restore a configuration backup
4. Devices — optionally wire the inputs to the outputs or covers
5. Cloud — optionally register with boneIO Cloud
6. Done
A controller that was configured before the update sees only Start, Account and
Done, so its existing input actions are not replaced. The step-by-step guide is
[First-time setup](/en/docs/black/current/install/first-run-wizard).
Until you finish it, the panel and the API are closed. The OLED display and
the application log both say `SETUP REQUIRED`, so a device that skipped several
versions is not silently unreachable.
The wizard sets the administrator's password as the SSH password of the
`boneio` user **once**, when that account is still locked from the factory, has
the factory password `Black` or has none. A password somebody already chose is
left alone, and the wizard says which happened. After that the two are
separate: changing the panel password does not change the SSH password. That
is what the [SSH login password](#ssh-login-password) card is for.
## Two roles [#two-roles]
| | Administrator | Read-only |
| ----------------------------------------------------- | ------------- | ----------------------- |
| View the device | yes | yes |
| Operate it — outputs, covers, irrigation, thermostats | yes | yes |
| Change the configuration | yes | no |
| Accounts, backups, updates, restart | yes | no |
| Own password | yes | set by an administrator |
A read-only account is meant for someone who should be able to use the
installation without being able to reconfigure it. It can press buttons —
an account that cannot is just a dashboard.
Anything not explicitly allowed requires an administrator, so a new feature is
closed to read-only accounts until someone decides otherwise.
Accounts are managed in **Settings → Access → User accounts**. The last
administrator cannot be deleted or demoted.
## SSH login password [#ssh-login-password]
Over SSH you always log in as `boneio`, whatever your panel username is. That
user can become root, so its password matters more than any panel password.
The **SSH login password** card, at the bottom of **User accounts**, changes it
without opening a terminal.
1. Click **Change SSH password**.
2. Type the current SSH password, then the new one twice. It needs at least 8
characters and must not contain `boneio`.
3. Confirm. The panel passwords stay as they are.
The new password is used from the next SSH login, and for `sudo`. It is the
same as running `passwd` over SSH, and like `passwd` it wants the current
password — the panel cannot set an SSH password nobody knows. A forgotten one
is recovered with a flasher card prepared with `BONEIO_RESET_ACCOUNTS=1`: the
configuration stays, and the panel accounts are created again in the wizard.
What the card shows depends on how the login stands:
| The card says | What to do |
| ---------------------------------------------- | ------------------------------------------------------------------------------- |
| The shipped password is still in use | Change it now — the current password is the factory one, `Black` |
| A **Change SSH password** button, nothing else | The password is your own; change it whenever you like |
| The login has no password at all | Anyone who reaches SSH can log in. Log in over SSH as `boneio` and run `passwd` |
| The login is locked | No password logs in yet. The first-run wizard sets it once |
| Migration 1.6.29 is missing | Apply the pending system migrations, or use `passwd` until then |
Only administrators see the card. After five wrong current passwords within
fifteen minutes the card refuses every try, the right one included, until the
oldest is fifteen minutes old — it tells you how many minutes are left. Each
wrong one also counts towards your session being
[signed out](#too-many-wrong-passwords).
Changing the SSH password is one of the actions that ask for your
[panel password again](#actions-that-ask-for-the-password-again). If you
signed in more than ten minutes ago, **Confirm your password** appears after
you submit the SSH form; type your panel password and the change goes
through.
## Forgotten password [#forgotten-password]
Password recovery is done over SSH, on the controller:
```bash
boneio accounts list
boneio accounts reset
```
The password is asked for interactively — it is never passed as an argument,
so it does not end up in your shell history.
Run these as the `boneio` user, not with `sudo`. Under `sudo` the account file
ends up owned by root and the application can no longer read it; the command
warns you if that happens.
Changes take effect immediately — the running application notices the file
changed and does not need restarting.
## Sessions [#sessions]
Signing in keeps you signed in for 30 days on that browser. The sign-in is
sent with each request rather than kept in a cookie, which is also why a page
in another tab cannot act on your behalf.
Deleting an account or changing its role takes effect at once — an account
removed today cannot keep working until its sign-in expires.
### Changing a password signs out the other sessions [#changing-a-password-signs-out-the-other-sessions]
When an account's password changes, every place that account is signed in is
signed out — other browsers, phones, a tablet on the wall:
* **Your own password** (**Change password** on your own row in **User
accounts**): this browser stays signed in, everything else is signed out.
* **Someone else's password**, set by an administrator: all of that account's
sessions end.
* **`boneio accounts reset`** over SSH: all of that account's sessions end.
A signed-out browser goes to the login screen and says why — the password was
changed, or the account was deleted. A wall tablet signed in with that
account needs the new password too.
### Actions that ask for the password again [#actions-that-ask-for-the-password-again]
Signing in is enough to look at the controller, operate it and — for an
administrator — edit its configuration. A short list of actions that cannot easily be undone also want
the password typed in the last 10 minutes:
* accounts — adding or deleting one, changing a role or a password, and the
SSH login password
* replacing the configuration — importing a backup archive, restoring a
backup, a full or partial factory reset, restoring Node-RED flows
* changing the software — an application update or rollback, the system
update, switching automatic security updates, updating Caddy (the web
proxy) or changing how it is installed
* certificates — uploading or removing the panel's own HTTPS certificate,
and the certificates and mode in **Encryption (TLS)** and **Broker
encryption (TLS)** on the MQTT pages
If it has been longer, the panel shows **Confirm your password** and carries
on with what you asked once you type it. You will not be asked again for the
next 10 minutes; signing in also counts. Restart, reboot, the file editor and
saving a configuration section never ask — an everyday prompt is one people learn
to type through without reading.
{/* SCREENSHOT: en_reauth_dialog.webp — the Confirm your password dialog over a factory reset */}
### Too many wrong passwords [#too-many-wrong-passwords]
Signing in is throttled: ten failed attempts in five minutes, counted per
address and per account name. It is a delay, not a lockout — the window
slides, so nobody can lock you out of your own controller by guessing at it.
Once signed in, a session gets **five** wrong passwords in total, across the
**Confirm your password** prompt, the change-your-own-password form and the
SSH login password card. The fifth signs that session out. It protects a
browser left signed in from someone guessing the real password on it. Only
that session goes — the account's other devices carry on — and the right
password resets the count. The count survives a restart of the controller.
Repeated guessing is also reported to Home Assistant — see
[Security events](/en/docs/black/current/basic/security#security-events-in-home-assistant).
## Running without accounts [#running-without-accounts]
There is an escape hatch, deliberately not in the panel:
```yaml
web:
auth:
allow_anonymous: true
```
A controller configured this way serves everything to anyone on the network.
It works **only while no account exists** — copying the flag onto a device that
has users will not open it. The application logs a warning at every start and
the panel shows a banner that cannot be dismissed.
It is in `config.yaml` rather than in the panel on purpose. A warning is a
notice, not a control, and a "skip" button in the first-run wizard would make
the unauthenticated state a normal outcome of the intended setup.
# Help (/en/docs/black/current/basic/help)
## Looking for support? [#looking-for-support]
If you've encountered problems with the controller or its configuration, use our support channels!
We encourage you to join our Discord — [https://discord.gg/Hm2CzSjvtu](https://discord.gg/Hm2CzSjvtu)
Repository containing the application: [https://github.com/boneIO-eu/app\_black](https://github.com/boneIO-eu/app_black)
Application documentation: [https://boneio.eu/docs/black](https://boneio.eu/docs/black)
System image for your device: [https://github.com/boneIO-eu/black\_debian\_images](https://github.com/boneIO-eu/black_debian_images)
# Modbus and I2C tools (/en/docs/black/current/basic/helper-tool)
Since 1.6 these tools are in **Diagnostics** → **Buses** → **Modbus** / **I2C** (administrators only). The old Tools tab is gone; `/tools` still redirects there.
Section containing additional controller tools.
## Modbus Helper [#modbus-helper]
Tool for working with the Modbus bus. Offers many useful functions.
### Read [#read]
After providing the device address, register address, type, and value type — allows reading a specific register. Very useful for debugging Modbus devices and for creating and adding new device configurations.
### Write [#write]
After providing the device address, register address, and value — allows writing to a specific register. Very useful for debugging Modbus devices.
### Search [#search]
The search function scans the entire bus looking for devices. Very useful when the address of a connected device is unknown. By specifying start and end addresses, the search can be narrowed. Additionally, register address, type, and timeout must be provided.
### Configuration [#configuration]
Configurator enabling remote address and speed changes for devices on the bus. Select the device model from a predefined list (currently: CWT, SHT30, DYP-A12) and the specific UART.
### Creator [#creator]
The Modbus creator is an extremely powerful tool. It enables preparation of configuration for a Modbus device. With the device's register documentation, you can create a configuration that enables boneIO to support the device.
***
## I2C Scanner [#i2c-scanner]
Tool for scanning the I2C bus for connected devices. The scanner automatically recognizes devices from the boneIO ecosystem.
### Bus Selection [#bus-selection]
The controller provides 3 I2C buses:
| Bus | Description |
| ----- | ------------------------ |
| I2C-0 | First I2C bus. |
| I2C-1 | Second I2C bus. |
| I2C-2 | Third I2C bus (default). |
### Scanning [#scanning]
After selecting a bus and clicking **Scan** — the tool scans the selected bus and displays a list of detected devices.
### Scan Results [#scan-results]
Results are presented in a table containing:
| Column | Description |
| ---------------- | ---------------------------------------------------------------------------------------- |
| Address (HEX) | Device address in hexadecimal format. |
| Address (DEC) | Device address in decimal format. |
| Possible Devices | List of recognized devices at the address. BoneIO devices are marked with a green badge. |
Raw scan output is also available with clipboard copy — useful for diagnostics and sharing on support channels.
# Operation (/en/docs/black/current/basic)
## Main View Overview [#main-view-overview]
Immediately after logging into the controller, the main view of the application appears. The application's design is extremely simple. It features a main selection menu where you choose the aspects you are interested in, and a working area where they are displayed. Depending on the width of the browser window, the menu is either permanently displayed at the top of the screen or accessible via a button in the top-left corner.
In this section, we will cover the individual segments of the application menu.
In the top-left corner of the application (or bottom-left after opening the menu, depending on the view), you will find basic information about your controller:
| Option Name | Description |
| ----------- | -------------------------------------------------------- |
| boneIO | The name assigned to our controller. |
| v | The current version of the installed boneIO application. |
| S/N | The serial number of our controller. |
Next, the individual menu sections are located:
Diagnostics, Settings and Node-RED are shown to administrators only. Inside Settings you will also find
[Accounts](basic/accounts), [Security](basic/security), [Maintenance](basic/system) (formerly the System tab)
and the [YAML editor](basic/yaml). On a phone or tablet the menu is a bar at the bottom of the screen, with **More** for the rest.
Following these, you will find 3 icons:
* Sun / Moon - Allowing you to switch the page mode between light and dark.
* PL / GB Flag - Allowing you to change the interface language.
* Door - A button for safely logging out of the website.
# Inputs (/en/docs/black/current/basic/inputs)
## Inputs and their states [#inputs-and-their-states]
The **Inputs** view shows every input, its type (**Event entity** or **Binary
sensor**) and the last event it registered, with the time. It is the quickest
way to check wiring: press a wall button and watch its tile.
Local inputs and inputs taken from other devices are listed separately, under
**Local Inputs** and **Remote Inputs**. As on [Outputs](./outputs) you can
switch between tiles and a list, sort with **Sort by Name** or **Sort by
Recent Event**, and — once areas exist — turn on **Group by area** to get one
panel per area.
## Long press: quick action and settings [#long-press-quick-action-and-settings]
Hold an input's tile (on a computer, right-click it) to open its card with the
recent events. Under **⋮** you find:
* **Quick Action** — pick a click type and an output or cover, and the input
gets that action straight away. Administrators only.
* **MQTT Reference** — the topics the input publishes on.
* **Go to Settings** — opens this input in **Settings → Local Inputs** (or
**Remote Inputs**). Administrators only.
## Changing an input: one Save [#changing-an-input-one-save]
In **Settings → Local Inputs**, the input's dialog saves straight to the
controller. Add an action, press **Save Changes** — the button shows
**Saving...**, the dialog stays open until the controller has the change, and
then it closes. The input works the new way at once: no second save in the
section bar, no restart.
Other sections, **Remote Inputs** among them, still collect your edits and
save them with the section's own **Save** button.
{/* SCREENSHOT: en_input_dialog_saving.webp — Settings → Local Inputs, an input's dialog with the Save Changes button showing Saving... */}
How to set up the inputs themselves is in
[Configure events](/en/docs/black/current/install/configure-events) and
[Configure binary sensors](/en/docs/black/current/install/configure-binary-sensors).
# Diagnostics (/en/docs/black/current/basic/logs)
**Diagnostics** is where you find out what the device is doing and why. It was
called Logs until 1.6, when the support bundle and the bus scans joined it.
## The log [#the-log]
Search is the full-width field at the top. Below it, the toolbar carries the
level filters, module filters, a date range and auto-refresh.
### Repeated lines are folded [#repeated-lines-are-folded]
A controller with a failing Modbus device writes the same pair of lines every
few seconds for days. Identical messages are collapsed into one row with a
count — `×97` — wherever they occur, not only when they are next to each
other. Hovering the count shows when the message was first and last seen.
A row sits at its most recent occurrence, so a message that starts repeating
moves down to where you are looking rather than ticking a counter out of
sight.
Device numbers and addresses are kept apart: "device 1 is failing" and "device
10 is failing" stay two rows, because they are two problems. Only thread names
and elapsed times are ignored.
### Levels [#levels]
| Level | Meaning |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| ERROR | Something failed |
| WARNING | Something may be about to |
| INFO | Normal operation |
| DEBUG | Detail: while a capture window is open, or permanently for a module set to DEBUG in [Logger](/en/docs/black/current/configuration/logger) |
Filtering by level happens on the server, so only the lines you asked for are
fetched.
### Module filtering and dates [#module-filtering-and-dates]
Logs can be narrowed to one component — `boneio.modbus.client`,
`boneio.webui.app` — with the module list built from the logs themselves. The
date range narrows to a period, which is what you want when the fault was
yesterday.
**Show modules** keeps only the components you pick, **Hide modules** everything except them.
On a phone the filters fold behind a **Filters** button; its badge says how many are in effect.
When you scroll up to read older lines, the log stays put — new entries are added at the bottom and the older
pages you loaded are not lost. Scroll back to the very bottom and the log follows new lines again.
### Selecting and sharing [#selecting-and-sharing]
Click rows to select them; **Shift+click** takes a range, and dragging selects
several. Selected lines can be copied as text, or copied in a Discord code
block ready to paste on the boneIO channel.
## The capture window [#the-capture-window]
Most controllers run at INFO, so a log read after the fact rarely explains a
fault — the detail was never written down.
**Support → Open a capture window** raises the level to DEBUG for the number
of minutes you choose, then puts it back on its own. Reproduce the problem
while it is open.
It closes itself on purpose. An idle controller logs around twenty MQTT
messages a second at DEBUG level, so a window left open fills the journal and
pushes out the history you will want tomorrow.
The remaining time shows on the Support button, so a window left open is
visible without opening the menu to look for it. The bug button in the log
toolbar is the same control.
## The support bundle [#the-support-bundle]
**Support → Download diagnostics** collects into one file what support will
ask for. You can email it; nobody needs access to your controller.
Inside:
* your YAML configuration
* the device log — the capture window's, if one was open
* MQTT, Mosquitto, Docker, system and network state
Not inside: `secrets.yaml` and the account file are never read, and passwords
from the configuration are replaced with a placeholder everywhere they appear,
including in the log.
The file still contains your device names, MQTT topics and network addresses.
Send it to someone you are asking for help, not to a public forum.
The useful order is: open a capture window, reproduce the fault, then
download. A bundle collected cold usually shows that the device is running and
little else.
## Bus scans [#bus-scans]
In the sidebar under **Buses**: **Modbus**, **I2C**, and — when CAN is enabled — **CAN network** and **CAN sniffer**. They report
what is actually wired to the controller. Nothing here is saved — you click and
you find out — which is why they are on this page rather than in Settings.
Use them when adding an expander or a Modbus device, and when something that
used to work stops answering.
## Disk [#disk]
**Diagnostics → System → Disk** shows what fills the controller's storage, and
removes what is safe to remove. Look here when an update says there is not
enough space.
* **System storage** — how full the main filesystem is. The system, Docker and
your configuration all live there.
* **Docker images** — every image on the controller, with its size and whether
a container uses it. Every Node-RED update leaves the previous image behind;
a minimal one takes about 350 MB.
* **Other** — the package cache (apt), the system journal and the Node-RED
backups.
Two buttons clean up:
* **Remove unused images** deletes every image no container uses. Images a
container uses — running or stopped — are kept, so Node-RED and the HTTPS
proxy are not touched. Going back to an older Node-RED version afterwards
means downloading its image again.
* **Clear package cache** deletes packages apt downloaded earlier. A later
system update downloads again only what it needs.
Both run as soon as you click, without a confirmation, and say how much they
freed. The journal is capped by the system and has nothing to clean; Node-RED
backups are managed in **Settings → Services on this controller → Node-RED**.
## Logging levels [#logging-levels]
The capture window is temporary. To change what the controller records from now
on, use **Settings → Advanced → Logger**, which writes to `config.yaml`.
# Modbus (/en/docs/black/current/basic/modbus)
## Check what is on the Modbus bus [#check-what-is-on-the-modbus-bus]
The **Modbus** view shows every Modbus device you added, each in its own
panel: its readings under **Sensors**, the values you can change under
**Controls**, each with the time it was last read. Readings with a unit are drawn as small
charts, so you can see how a value moved over time.
## A device that stops answering [#a-device-that-stops-answering]
When a device does not answer — or refuses a read — the panel shows it: a red
triangle in the device's header, a red dot in the picker, and the text
**Device not responding or refusing reads** under its name. When it answers
again, the marks go away on their own.
## Finding a device [#finding-a-device]
With many meters and inverters the page gets long, so above the list there is
a device picker:
* **‹ ›** step to the previous or next device; past the last one they wrap
around to the first.
* The picker itself lists **All devices**, **Failing only** and then every
device, each with a status dot: **green** — reading fine, **red** — failing,
**grey** — polling is switched off. The picked device shows its area — or
the fault — under its name.
* **Failing only** shows just the devices that do not answer right now — the
first place to look when something in Home Assistant stopped updating.
* The search field (**Search: name or id…**) matches a device's name and an
entity's label, name or id.
The device you picked is remembered for your next visit; **Failing only** is
not, so a healthy system does not open on an empty page.
{/* SCREENSHOT: en_modbus_picker.webp — Modbus view with the device picker open: All devices, Failing only, a list with green and red dots */}
## Group by area [#group-by-area]
Once you have [areas](/en/docs/black/current/install/configure-areas), the
**Group by area** button sorts the devices into one heading per area, as on
Outputs and Inputs. The picker and its arrows then follow the same order, area
by area.
## Pausing a device [#pausing-a-device]
The switch in a device's header stops reading that device — **Polling
disabled — values are frozen**. It is handy while you work on the wiring.
Only an administrator can flip it, and it does not survive a restart: after
the next start every device is read again.
## On a phone [#on-a-phone]
On a phone the picker opens as a sheet from the bottom of the screen. In the
list view the small charts are hidden and the controls sit under each entity's
name, full width, so long names wrap instead of being cut off. Hold an entity (on a computer, right-click it) to open its card with a
larger chart; an administrator finds **Go to Settings** under **⋮** there.
{/* SCREENSHOT: en_modbus_phone.webp — Modbus view on a phone, picker sheet open from the bottom */}
# Node-RED (/en/docs/black/current/basic/node-red)
## Updating Node-RED [#updating-node-red]
Node-RED runs on the controller as its own container, and is updated
separately from boneIO, in **Settings → Services on this controller →
Node-RED**.
1. Click **Check for Updates**. Only versions that have an image for this
controller, and that keep the same flavour as the one you run, are offered.
2. Click **Update Now** and confirm.
What happens and what it costs:
* **A backup of your flows is made first**, automatically.
* **Node-RED is unavailable while it updates.** boneIO, its outputs and its
own automations keep running.
* **It checks for space before downloading.** A new image needs about four
times its download size free, and never less than 500 MB. If there is not
enough, the update stops before anything changes and says how much it needs
and how much is free.
* **The download can take several minutes** on the controller. Let it run.
* **If the new version cannot be downloaded or does not start**, the
previous one is put back.
When it finishes the panel says **Node-RED updated** and suggests removing the
previous image, which still takes up space — about 350 MB for a minimal one.
**Open Disk** takes you to [Diagnostics → System → Disk](/en/docs/black/current/basic/logs#disk),
where **Remove unused images** frees it.
# Outputs (/en/docs/black/current/basic/outputs)
## See and switch your outputs [#see-and-switch-your-outputs]
The **Outputs** view shows every output of the controller, what it is (light,
switch, valve, cover, group, virtual switch) and whether it is on. Tap a tile
to switch it — from a computer, phone or tablet, without Home Assistant.
Outputs are sorted into **Lights**, **Switches**, **Virtual switches**,
**Valves**, **Covers** and **Groups**; outputs on other controllers are under
**Remote Outputs**. Above the list you can:
* switch between tiles and a list,
* sort with **Sort by Name** or **Sort by Recent Event**,
* group the view by area (below).
## Group by area [#group-by-area]
Once you have [areas](/en/docs/black/current/install/configure-areas) set up,
a **Group by area** button appears next to sorting (on a phone, just the pin
icon). Turn it on and the view shows one panel per area — the living room's
lights, switches and covers together — in the order the areas are configured.
Anything without an area is in **No area**, at the end.
The choice is remembered in this browser, separately for Outputs, Inputs and
Modbus.
## Long press: details and settings [#long-press-details-and-settings]
Hold a tile for half a second (on a computer, right-click it) to open its card:
* the output's controls,
* **Recent events** — what happened to it since the panel was opened,
* under **⋮**: **MQTT Reference** (the topics to control it) and, for an
administrator, **Go to Settings**, which opens this output's settings
directly.
A virtual switch opens in **Settings → Virtual switches**, where it is
configured, not in Outputs.
A read-only account gets the card without **Go to Settings**.
# Security (/en/docs/black/current/basic/security)
**Settings → Access → Security** lists what is still unlocked on this
controller and where to fix each thing. The same information reaches Home
Assistant as a diagnostic entity, so a controller nobody visits can still say
something.
{/* SCREENSHOT: en_security_page.webp — Settings → Security with outstanding findings and the advice block */}
## Two lists, and the difference matters [#two-lists-and-the-difference-matters]
**Outstanding** is a problem with *this* controller — the shipped broker
password still in place, the panel reachable without signing in. Each entry
has a **Fix** button that takes you to the control that changes it, or, where
there is no control, the exact change to make by hand.
**Worth considering** is advice that applies to nearly every controller and
depends on how you use the device. A self-signed certificate is the designed
default, not a fault.
Only the first list drives the count beside **Security** in the sidebar and the
Home Assistant sensor. A badge that is red on every device ever shipped is a
badge nobody reads.
## What is checked [#what-is-checked]
| Check | Why |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Administrator account | Without one, whoever reaches the first-run wizard takes the device |
| Unauthenticated access | Anyone on the network could read the configuration, switch outputs and reboot |
| MQTT broker password | The one every boneIO ships with is published and identical on every device |
| Old credentials in `config.yaml` | The pre-1.6 `web.auth` block kept a password in clear text |
| HTTPS certificate | Self-signed means a browser warning on every visit |
| Embedding in other sites | Whether another site may put the panel in a frame |
| SSH login password | The `boneio` account can become root; the factory password `Black` (or none) means anyone who reaches SSH can too. With the factory password, **Fix** opens the [SSH login password](/en/docs/black/current/basic/accounts#ssh-login-password) card in Accounts; with none at all, log in over SSH and run `passwd` |
| Operating system updates | Installed updates waiting for a restart, or a kernel that is not ready for the next boot (then: do not restart, contact support). Automatic security updates switched off is listed under **Worth considering** |
| Panel served in the clear | The panel's own port answers without encryption on the network — **Move behind the proxy** closes it |
| Development mode | `BONEIO_DEV` mounts development routes — correct on a development board, never on a shipped one |
Checks that pass are listed too, folded away. Seeing how many things were
examined is what makes "two outstanding" mean something.
## After an update [#after-an-update]
The first time you open the panel after an update, a prompt points at this
section — but only if something is outstanding. It appears once per version
and closing it is enough; nothing here is forced.
## Who can see it [#who-can-see-it]
Administrators only, including through the API. A list of what is still
unlocked is a shopping list for anyone who should not have it, so a read-only
account gets nothing — not even the overview.
## Embedding the panel in other sites [#embedding-the-panel-in-other-sites]
The **Embedding this panel in other sites** card controls which sites may show
the panel inside a frame. Since 1.6 the default is this device only.
That is also what the **boneIO Black add-on for Home Assistant** needs: the
add-on proxies each controller, so the framed page is served on Home
Assistant's own address and counts as the same site.
The setup that needs more is a dashboard pointing an iframe card or
`panel_iframe` straight at `https://:8443`. Add that Home
Assistant address in the field on the card — the server address only, no path.
Turning the restriction off lets any site on the internet display your panel
in a frame. That is what clickjacking needs.
Changes here take effect after the application restarts.
## The Home Assistant sensor [#the-home-assistant-sensor]
The controller publishes `binary_sensor._security` — a diagnostic
entity with `device_class: problem`, ON while something is outstanding.
The details ride on the entity's attributes:
| Attribute | Meaning |
| ----------------------------- | ------------------------------------------------------------- |
| `actionable` | How many outstanding items — this is what turns the sensor on |
| `summary` | Readable description of those items, for a notification |
| `advice` | The "worth considering" items, kept separate on purpose |
| `critical`, `warning`, `info` | Counts by severity |
| `recommendations` | The same list in a form you can template against |
Template against `summary` for a notification and it describes exactly what
turned the sensor on — not the advice, which would make the automation say
something the sensor does not.
## Security events in Home Assistant [#security-events-in-home-assistant]
The sensor above says how the controller is set up. A second diagnostic
entity, **Security events**, says what is happening to it: it fires when
somebody keeps typing wrong passwords, so an automation can send you a
notification — the same way it would react to a button press.
| Event | When |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `password_guessing` | The wrong-password limit just filled — at the login form, the **Confirm your password** prompt, the change-your-own-password form or the SSH login password card. Once per burst, not once per refused try |
| `session_signed_out` | A signed-in session was [signed out after five wrong passwords](/en/docs/black/current/basic/accounts#too-many-wrong-passwords) |
Each event carries the account name (for a login, whatever was typed), the
form (`where`: `login`, `confirm`, `password_change` or `ssh_password`), a
readable `message` for the notification, and the address it came from
(`client`, left out when it is the controller itself).
Events are not stored: one that happens while Home Assistant or the broker is
down is not replayed later. A controller without MQTT still signs people in
normally — it just has nobody to tell.
{/* SCREENSHOT: en_ha_security_events.webp — Home Assistant device page, Diagnostic section with Security events showing a password_guessing event */}
# Sensors (/en/docs/black/current/basic/sensors)
The **Sensors** view shows the controller's sensors, sorted into groups, each
with its value, a small chart and the time of the last reading. Point at a
chart (or touch it) to see the value and time of that moment. Modbus readings
are not here — they have their own [Modbus](./modbus) view.
On a phone, **Sensors** is in the bottom bar — or under **More** when you have
templates or open the panel through the boneIO Dashboard add-on. See
[Interface navigation](/en/docs/black/current/install/interface-navigation#on-a-phone-or-tablet).
### ADC Sensors [#adc-sensors]
Analog inputs, if you configured any.
### Board Sensors [#board-sensors]
The temperature inside the controller and the on-board power monitor. 1-Wire
temperature sensors you connect show up here too.
### System Monitoring [#system-monitoring]
How the controller itself is doing:
* **CPU Usage** — how busy the processor is,
* **Memory Usage** — how much memory is taken, in percent,
* **System Disk Usage** — how full the storage is.
### Other Sensors [#other-sensors]
Everything else you defined, such as virtual sensors.
Hold a sensor (on a computer, right-click it) to open it in a card with a
larger chart.
# Settings (/en/docs/black/current/basic/settings)
Settings is where the controller is configured — every parameter, without
editing YAML by hand.
## Seven groups [#seven-groups]
From 1.6 everything is in one place. There is no separate System page any
more, and the sidebar is grouped by the question you are asking rather than by
where the setting happens to be stored:
| Group | What is in it |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Device** | boneIO (name, controller version), areas, [location](/en/docs/black/current/configuration/location), hostname, time zone, OLED display, board sensors |
| **Control** | Local inputs, local outputs, output groups, covers, Onewire sensors, ADC sensors, virtual energy sensors, templates, binding matrix, [virtual switches](/en/docs/black/current/configuration/virtual_switch), [schedules](/en/docs/black/current/configuration/schedule) |
| **Connections** | Modbus devices, remote devices, remote inputs, remote outputs, Home Assistant dashboard, MQTT, Loxone (UDP), Modbus, CAN Bus |
| **Services on this controller** | The local MQTT broker, Node-RED |
| **Access** | Security, user accounts, Web Server |
| **Maintenance** | Software update, backups, system migrations, restart and shutdown, device tools, hardware errors, factory reset |
| **Advanced** | Logger, YAML editor, MCP23017 |
**Remote Inputs** appears once you have a remote device to take inputs from,
and **CAN Bus** only on controllers that have one. **MQTT** and **Loxone (UDP)**
are two separate entries, each saved on its own — a mistake in one does not
stop you saving the other.
If you had the controller before 1.6: the **System** tab is gone. Everything
that was on it is under **Maintenance**, except the broker passwords, which
are under **Services on this controller**. Old links to `/system` still work —
they take you to Software update.
### Why the local broker is not under Connections [#why-the-local-broker-is-not-under-connections]
Two things that sound alike are deliberately apart:
* **Connections → MQTT** is where boneIO *connects to*. If
your broker is the one in Home Assistant, the username and password here are
Home Assistant's.
* **Services on this controller → MQTT broker (local)** is the broker
*running on the controller*, with its own accounts.
Changing a password in the second place does nothing to the first. The panel
marks the account boneIO actually signs in with, and if boneIO is pointed
somewhere else it says so instead of marking anything.
## Finding a setting [#finding-a-setting]
There are about forty sections, so three things help:
* **The filter** at the top of the sidebar. Type part of a name — "host",
"hasło", "modbus" — and matching sections are listed regardless of group.
* **Groups fold.** On a computer only the group you are in stays open; click
a heading to open another. On a phone you get the groups as tiles, then the
sections inside the one you tap.
* **On a phone or tablet** the section you are in is named in a bar at the
bottom of the screen. Tap it to open the list of sections; swipe the list
down by its header to close it. The page under it scrolls normally.
* **Settings remember where you were.** Opening Settings from the top menu
returns you to the section you last had open, not to the beginning.
Settings also open when you use the panel inside Home Assistant, through the
add-on.
## The restart badge [#the-restart-badge]
Some sections carry a **RESTART** badge. Those settings are written to
`config.yaml` and only take effect after the application restarts; everything
else applies immediately. Hovering the badge says so.
Saving a section that needs a restart shows a banner with a restart button —
you can make several changes and restart once.
## Tables [#tables]
All tables in Settings have sortable columns. Clicking a column header changes
the sort direction. This applies to outputs, inputs, output groups, covers,
Modbus sensors, sensors, virtual energy sensors, remote devices, areas and
templates.
The filter above the outputs, covers, remote outputs, templates and inputs
tables matches the name, the ID and the area — type "kitchen" to see
everything in the kitchen.
The buttons on each row — **Edit Item**, **Duplicate item**, **Home Assistant
dashboard**, **Delete Item** — say what they do when you hover over them, in
the panel's language. On a phone the same buttons are on each item's card.
## Every item needs its own ID [#every-item-needs-its-own-id]
Two outputs, output groups, covers or remote devices cannot share an ID. Saving
one under an ID that another item in the same section already has is refused:
*Another item already has the ID … Change the ID so it is unique.*
Two items with one ID would share their MQTT topics and their Home Assistant
entity, and the second would silently replace the first. Watch out with
covers: a cover without its own ID takes one from its relays, so a duplicated
cover collides with the original until you give it a different ID or
different relays.
## The map on the Location page [#the-map-on-the-location-page]
The [Location](/en/docs/black/current/configuration/location) page can show an
OpenStreetMap map to pick your coordinates from. It is off by default. To turn
it on, go to **Access → Web Server**, switch on **Show a map on the Location page**,
save, and restart the application.
What it costs: the map tiles are loaded by your browser from OpenStreetMap, so
OpenStreetMap sees which area you are looking at, and the panel's security
policy has to allow images from those servers.
## Editing YAML directly [#editing-yaml-directly]
The **YAML editor** is under Advanced. It edits `config.yaml` with no
validation beyond a syntax check, so a mistake there can stop the controller
from starting. Everything it can do, the forms can do too.
# Maintenance (/en/docs/black/current/basic/system)
This was the **System** tab. Since 1.6 it is **Settings → Maintenance**, with
the broker passwords moved to **Services on this controller**. Links to
`/system` still work.
Everything here acts on the device immediately. Where something only takes
effect after a restart, the page says so.
## Software update [#software-update]
The update centre. When a new version is available its details are shown
before you install anything.
Always read what a release changes before installing it.
The update does not back up your configuration — take a backup first (below).
An earlier version can be installed from **Available versions**. Step by step:
[Update controller](/en/docs/black/current/install/update-controller).
### Operating system [#operating-system]
Updating boneIO does not touch the Debian system underneath it. The
**Operating system** card on the same page updates that — the Debian packages
and the kernel.
1. Click **Check for system updates**. The card shows how many packages are
waiting and how long installing them should take — roughly ten seconds per
package, so a controller that has not been updated for a long time can
take up to an hour. If a new kernel is among them, the card says
so: the controller will need a restart at the end.
2. Click **Update system** and confirm. The panel asks whether you have
downloaded a configuration backup, and may ask for your password again.
3. Leave the page open, or come back later. The card shows a live log while
the update runs.
**Do not cut the power while it runs.** A power cut halfway through a package
install leaves the system half-updated. If the controller has no backup power
yet, see
[Backup power (UPS)](/en/docs/black/products/black_32x10a/hardware-installation#backup-power-ups--recommended).
What it costs: the controller keeps working, and outputs and automations keep
running. But as each service is updated, **MQTT (Home Assistant), Node-RED,
the HTTPS panel and SSH may drop for a moment**. Plan it for a time when a
short break does no harm.
**It does not restart by itself.** When it finishes the card shows a green
**System update finished** notice with the number of updated packages. If the
kernel or another component needs a restart, a **Restart required** notice
with **Restart now** appears — do it when the controller can be down for a few
minutes.
**Short of space?** The card checks first how much room this particular update
needs. If packages that apt downloaded earlier are what is in the way, it says
it will clear them first and goes ahead — apt downloads again only what it
needs. If there is still not enough room, the card says how much is free and
how much is needed; see [Disk](/en/docs/black/current/basic/logs#disk) for what
else can go.
**Interrupted.** If the controller restarted or lost power mid-update, the
card says **The system update was interrupted**, with the step it stopped
at. Do not restart the controller — click **Update system** again: it first
finishes the interrupted package install, then the rest.
**Do not restart the controller.** If this notice appears after an update, the
kernel the next boot would load is not ready. Leave the controller running and
contact boneIO support.
**Automatic security updates** — the switch on the same card, on by default.
Once a day it installs Debian security fixes only, never restarting the
controller. The kernel and everything else stay manual.
## Backups [#backups]
Full backup of the configuration and restoration from an archive. Worth taking
before any larger change — and it is what turns a failed controller into a
replacement that is running in minutes.
## System migrations [#system-migrations]
Some releases need changes outside the application — a systemd unit, a sudoers
rule, a file in `/etc`. Those are applied by migrations, which run on the first
start after an upgrade.
This section shows what has been applied and what is pending. On a controller
with nothing to do it says so.
The first time, the migration helper needs to be installed, which asks once for
your system password.
## Restart and shutdown [#restart-and-shutdown]
Proper, safe restart and shutdown of the controller.
After shutting down, disconnect the power. The OLED shows "System stopped. Safe
to unplug." once it is genuinely safe.
## Device tools [#device-tools]
**Hardware test** exercises every input and output so you can confirm the
wiring — it switches each output in turn and waits for input events.
**All outputs off** turns everything off and clears the saved relay states.
## Hardware errors [#hardware-errors]
Faults detected on the I2C bus, on expanders and on sensors. A controller with
no faults says so, rather than showing an empty page.
## Factory reset [#factory-reset]
Puts the factory configuration back. The dialog starts from what this
controller is — its type and its hardware version — so in most cases you only
click **Reset to Factory Defaults**. Each hardware version gets its own
configuration (a 1.1 controller keeps its buzzer, for example); change the
selection only if the controller really is something else.
What happens:
* your current configuration files are backed up first, and can be restored
from **Configuration Backups** on the same page,
* `secrets.yaml` is kept, and so is boneIO's MQTT password; the other MQTT
settings go back to factory values (the controller's own broker), so set the
broker again if you use another one,
* saved output states are cleared; your panel accounts stay,
* the panel may ask for your password again,
* the new configuration takes effect after a restart.
# Templates (/en/docs/black/current/basic/templates)
The **Templates** page is where you use your thermostats, alarm panels, gates and irrigation controllers from the controller's own panel — change the temperature, arm the alarm, open the gate, start watering. It works without Home Assistant.
Open it from **Templates** in the top menu. On a phone or tablet it is under **More** in the bottom bar.
The page only shows what you have configured, grouped by kind: **Thermostats**, **Alarm Panels**, **Gate Covers** and **Irrigation**. Groups with few tiles share a row; irrigation always takes a full row. The tiles refresh by themselves every few seconds.
If nothing is configured yet, the page says so. Templates are created in **Settings** → **Control** → **Templates** — see [Templates](/en/docs/black/current/configuration/template).
## The tiles [#the-tiles]
Every tile shows the name, an icon and the state in words.
| Tile | Shows | Controls |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Thermostat** | **Heating**, **Idle** or **Off**; the current temperature (**now**) and the **target** | Arrows to change the target by 0.5 °C, a button to turn the thermostat off or back on |
| **Alarm panel** | **Disarmed**, **Arming...**, **Armed Home**, **Armed Away**, **Armed Night**, **Pending...** or **TRIGGERED!** | **Home**, **Away**, **Night**, **Disarm** — asks for a PIN (**Enter PIN code**) when one is needed |
| **Gate** | **Open**, **Closed**, **Opening** or **Closing** | **Open**, **Stop**, **Close** (in Open only mode, without Close). The button that undoes the current state is highlighted |
| **Irrigation** | **Idle**, **Running** or **Paused**, the countdown, the next run and the zones | **Start cycle**, **Pause** / **Resume**, **Skip to next zone**, **Stop**, per-zone start; **Schedules and settings** opens the schedules and cycle settings |
The alarm's buttons appear only when **Allow Frontend Control** is on in its settings. By default it is off and the tile says **Frontend control disabled in config.** — the alarm can then be armed and disarmed from Home Assistant only. Turn it on only if the panel is protected by a login.
What each template does, and what its settings mean, is on its own page: [Thermostat](/en/docs/black/current/configuration/thermostat), [Alarm Panel](/en/docs/black/current/configuration/alarm), [Gate Cover](/en/docs/black/current/configuration/gate), [Irrigation](/en/docs/black/current/configuration/irrigation).
## Going to a template's settings [#going-to-a-templates-settings]
Press and hold a tile. A window asks whether to go to the settings; **Go to Settings** opens that template's form in **Settings** → **Control** → **Templates**.
This only works for an account with the **Administrator** role. For a **Read-only** account a long press does nothing, because it could not open the settings anyway.
# YAML Editor (/en/docs/black/current/basic/yaml)
Since 1.6 the YAML editor is in **Settings** → **Advanced** → **YAML editor** (administrators only). It is no longer a tab in the top menu; `/config` still redirects there.
## YAML Editor [#yaml-editor]
Although the recommended configuration method for boneIO Black controllers in the application from version 1.x.x is the graphical configurator available in the settings section, we also have a solution for users who prefer YAML code. To simplify the process and not require users to log in to the controller via SSH, we have provided a text editor with configuration validation in the web UI — this means that after making changes to the file, you can verify the correctness of your changes, save them, and save and restart the controller with the changes loaded.
In the side menu of the configurator, you have access to all YAML component files necessary to change all controller parameters.
* adc — full configuration of ADC converters.
* mqtt — MQTT parameters.
* config — main configuration file.
* event — event entity configuration file.
* binary\_sensor — binary sensor configuration file.
* output/cover — depending on the controller type — configuration file for the "output" part of the controller.
# ADC Sensors (/en/docs/black/current/configuration/adc)
The controller has 7 analog inputs (ADC). They measure a voltage, so you can connect sensors that report a value rather than just on/off.
Each input you set up here becomes a sensor in the panel and, if you want, in Home Assistant.
The highest voltage an analog input accepts is **1.8 V**. For a sensor with a higher output, use an external voltage divider.
See the hardware installation page for your model, for example [boneIO Black 32x10A](/en/docs/black/products/black_32x10a/hardware-installation).
## Adding an ADC sensor [#adding-an-adc-sensor]
1. Open **Settings** → **Control** → **ADC Sensors** and add a new entry.
2. Choose the **Pin**. The list shows each pin with its analog channel, for example `P9_39 (AIN0)`. Pins already used by another sensor are marked **in use**.
3. Optionally fill in **Name** (shown in Home Assistant) and **ID** (used in the MQTT topic). If you leave them empty, the pin's analog channel name is used.
4. Optionally choose an **Area / Room**.
5. Leave **Show in Home Assistant** on if the sensor should appear there.
6. Set **Update Interval**, how often the value is read. Default 60 s.
7. Adjust the **Filters** if needed (see below) and click **Save**.
Changes apply without a restart.
### Filters [#filters]
The input itself gives a number from 0 to 1. The filters turn that into something useful and are applied in the order they are listed.
The default, **multiply** by 1.8 and then **round** to 2 decimals, gives the voltage at the pin in volts.
On controllers from version 1.0 (the ones with a SERVICE port) every input has an input stage that divides the terminal voltage by about 7.7. Set **multiply** to **13.8** instead of 1.8 to read the voltage on the terminal (0–13.8 V). See [Analog inputs](/en/docs/black/products/black_32x10a/hardware-installation#analog-inputs-adc).
Available filters: `offset`, `round`, `multiply`, `filter_out`, `filter_out_greater`, `filter_out_lower`.
Add one with **Add Filter**. What each filter does is described in [Filters](./filters).
```yaml title="Sample configuration"
adc:
- pin: P9_39
name: Tank level
id: tank_level
area: garage
update_interval: 30s
show_in_ha: true
filters:
- multiply: 1.8
- round: 2
```
| Option | Required | Type | Default | Description |
| -------------------- | -------- | ----------- | --------------------------- | ----------------------------------------------------------------------------------- |
| **pin** | **yes** | string | none | Analog pin. Allowed: `P9_33`, `P9_35`, `P9_36`, `P9_37`, `P9_38`, `P9_39`, `P9_40`. |
| **name** | no | string | none | Name shown in Home Assistant. |
| **id** | no | string | name or pin | ID used in the MQTT topic. |
| **area** | no | string | none | ID of an area from [Areas/Rooms](./areas). |
| **update\_interval** | no | time period | `60s` | How often the value is read. |
| **show\_in\_ha** | no | boolean | `true` | Announce the sensor to Home Assistant. |
| **filters** | no | list | `multiply: 1.8`, `round: 2` | Filters, applied in order. |
Pins and analog channels: `P9_39` = AIN0, `P9_40` = AIN1, `P9_37` = AIN2, `P9_38` = AIN3, `P9_33` = AIN4, `P9_36` = AIN5, `P9_35` = AIN6.
**Which pin is which terminal**
The terminals printed **ADC 1**–**ADC 7** reach different pins depending on the controller version:
| Terminal | Controllers from 1.0 | Controllers before 1.0 |
| -------- | -------------------- | ---------------------- |
| ADC 1 | `P9_39` | `P9_39` |
| ADC 2 | `P9_40` | `P9_40` |
| ADC 3 | `P9_38` | `P9_37` |
| ADC 4 | `P9_37` | `P9_38` |
| ADC 5 | `P9_36` | `P9_35` |
| ADC 6 | `P9_35` | `P9_36` |
| ADC 7 | `P9_33` | `P9_33` |
The pin is what counts. Factory configurations from before this table named the sensors `adc1`–`adc7` in a different
order, so a sensor called `adc1` may be reading another terminal; check its **pin** against the table.
# Alarm Panel (/en/docs/black/current/configuration/alarm)
The **Alarm Panel** template turns the controller's inputs into a burglar alarm. Door and window contacts and motion sensors are grouped into **zones**; you arm the alarm in one of three modes, and when a sensor in an active zone trips, the controller switches on the siren (and anything else you give it).
It runs on the controller itself: an armed alarm keeps watching and sounds the siren without Home Assistant or the network.
This is a home-automation alarm, not a certified intrusion alarm system. It has no tamper lines, no battery backup of its own and no monitoring-station link. Use it where that is acceptable.
## How it works [#how-it-works]
**Zones.** A zone is a group of inputs — *Doors*, *Ground floor windows*, *Motion upstairs*. For each zone you decide in which arm modes it is watched and whether it gets an entry delay.
**Arm modes.** There are three:
| Mode | Typical use |
| --------------- | ------------------------------------------------------------------ |
| **Armed Away** | Nobody at home — every zone you assigned to it is watched. |
| **Armed Home** | You are at home — e.g. only doors and windows, motion sensors off. |
| **Armed Night** | At night — e.g. the ground floor only. |
Which zones are watched in which mode is entirely up to you: a zone is watched only in the modes ticked for it.
**The sequence.**
1. You arm the alarm. It first checks that every input in the zones for that mode is closed. If anything is open — a window left ajar — it **refuses to arm** and stays Disarmed.
2. It counts down the **Arming Time** (default 30 s) so you can leave. During the countdown nothing triggers it.
3. It is armed. When an input in a watched zone trips:
* in a zone **with Entry Delay** the alarm goes to Pending and counts down the **Entry Delay Time** (default 30 s) — time to walk in and disarm,
* in a zone **without** it the alarm triggers at once.
4. Triggered: all **Alarm Outputs** switch on for the **Trigger Duration** (default 5 min). After that the outputs switch off and the alarm **disarms itself** — it does not re-arm.
Disarming at any point stops the countdown, switches the outputs off and returns to Disarmed.
The armed mode survives a restart: an alarm that was Armed Away before a power cut comes back Armed Away. A countdown in progress (Arming, Pending) or a triggered state is not kept.
## Setting one up [#setting-one-up]
Configure the inputs first — door and window contacts and motion sensors must exist as binary sensors under **Settings** → **Control** → **Local Inputs** (or come from a remote device).
1. Open **Settings** → **Control** → **Templates**, click **Add New** and choose **Alarm Panel**
2. Under **Basic Settings**:
* **Display Name**, **ID**, **Area / Room**,
* **Alarm Outputs** — the siren, a strobe light, anything that should switch on when the alarm triggers. Under **Output Type Assignment** you can label each as **Siren**, **Light** or **Custom**; all of them switch on the same way,
* **PIN Codes** — **Add PIN Code** for each person, with a **User Name** and a **PIN Code**. The name appears in the log, so you can see who disarmed,
* **Alarm Zones** — **Add Zone** for each group of sensors (see below)
3. Under **Advanced Settings** set **Arming Time**, **Entry Delay Time**, **Trigger Duration**, **Code Required to Arm** and **Allow Frontend Control**
4. Save
### Zones [#zones]
For each zone:
| Field | What it does |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Zone Name** | E.g. *Perimeter*. Shown in the log and in Home Assistant when this zone triggers the alarm. |
| **Active in Arm Modes** | **Armed Away**, **Armed Home**, **Armed Night** — tick the modes in which the zone is watched. A new zone starts with Armed Away. |
| **Entry Delay** | Tripping this zone starts the entry countdown instead of triggering at once. Use it for the zone with the front door. |
| **Monitored Inputs** | The inputs in this zone. **Add input...** picks a local input, **Add remote input...** an input from a [remote device](/en/docs/black/current/configuration/remote-devices). |
Each input in a zone has a button that says how it is wired — click it to switch:
* **NC** (Normally Closed) — door and window contacts: closed means safe, **open** trips the alarm. This is the default.
* **NO** (Normally Open) — most PIR motion sensors: open means safe, **closed** trips the alarm.
A remote input has a second button, **Ignore** / **Trigger**, for when its remote device cannot be reached. In 1.6 this is only checked when arming: with **Trigger** the alarm refuses to arm while the controller does not know that input.
Test every input after setting it up: arm, open the door or walk past the sensor, and check that the alarm reacts. If an input is set to NC but wired NO (or the other way round), the alarm either refuses to arm or never triggers from it.
### Timers and codes [#timers-and-codes]
| Field | Default | What it does |
| -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Arming Time** | 30s | Countdown after arming, to leave the house. |
| **Entry Delay Time** | 30s | Countdown after a zone with Entry Delay trips, to disarm. |
| **Trigger Duration** | 5min | How long the outputs stay on before the alarm disarms itself. |
| **Code Required to Arm** | off | With PIN codes set, a PIN is always needed to **disarm**. This makes it needed to **arm** as well. |
| **Allow Frontend Control** | off | Lets the alarm be armed and disarmed from the controller's **Templates** page. Off by default — the tile then only shows the state. Turn it on only if the panel is protected by a login. |
Without any PIN codes the alarm is armed and disarmed without one.
PIN codes are not kept in the configuration in plain text. On the next start the controller replaces each PIN in `config.yaml` with a hash of it; the form then shows the PIN as `••••••`. A forgotten PIN cannot be read back — type a new one.
## Using it [#using-it]
On the **Templates** page the alarm's tile shows its state — **Disarmed**, **Arming...**, **Armed Home**, **Armed Away**, **Armed Night**, **Pending...** or **TRIGGERED!** — and, when **Allow Frontend Control** is on, the buttons **Home**, **Away**, **Night** and **Disarm**. If a PIN is needed, the tile asks for it (**Enter PIN code**). See [Templates page](/en/docs/black/current/basic/templates).
In Home Assistant the alarm is an **alarm\_control\_panel** entity with arm home, arm away, arm night and trigger. When PIN codes are set, Home Assistant asks for the code and the controller checks it. When arming is refused because something is open, the list of open inputs is published as the entity's `blocking_inputs` attribute, so an automation can tell you which window it was.
```yaml title="Alarm with two zones"
template:
- id: home_alarm
name: Home Alarm
platform: alarm_control_panel
area: house
arming_time: 45s
delay_time: 30s
trigger_time: 3min
code_arm_required: false
codes:
- name: John
code: "1234"
- name: Anna
code: "5678"
zones:
- name: Entrance
inputs:
- id: front_door
type: normally_closed
arm_modes: [armed_away, armed_home, armed_night]
entry_delay: true
- name: Motion
inputs:
- id: pir_hall
type: normally_open
- id: pir_living_room
type: normally_open
arm_modes: [armed_away]
outputs:
- id: siren
type: siren
- id: strobe
type: light
```
* **platform** (**Required**) — `alarm_control_panel`.
* **id**, **name**, **area** — as for every template, see [Templates](/en/docs/black/current/configuration/template).
* **arming\_time** (*Optional*, time period) — arming countdown. The controller uses `30s` when it is not set.
* **delay\_time** (*Optional*, time period) — entry delay. `30s` when not set.
* **trigger\_time** (*Optional*, time period) — how long the outputs stay on. `5min` when not set.
* **code\_arm\_required** (*Optional*, boolean, default `false`) — require a PIN to arm as well.
* **codes** (*Optional*, list) — PIN codes:
* **name** (**Required**, string) — user name, shown in the log.
* **code** (**Required**, string) — the PIN. Put it in quotes. Replaced by a hash on the next start.
* **outputs** (*Optional*, list) — outputs switched on when the alarm triggers:
* **id** (**Required**, string) — output ID.
* **type** (*Optional*, one of `siren`, `notification`, `light`, `custom`, default `siren`) — a label; every type is switched on the same way.
* **zones** (*Optional*, list) — alarm zones:
* **name** (*Optional*, string) — zone name.
* **inputs** (*Optional*, list) — the zone's inputs. Each item is either an input ID, or an `id` with `type: normally_closed` (default) or `type: normally_open`. The panel writes the second form.
* **arm\_modes** (*Optional*, list) — any of `armed_away`, `armed_home`, `armed_night`. The controller uses `[armed_away]` when it is not set.
* **entry\_delay** (*Optional*, boolean, default `false`) — use the entry delay for this zone.
The panel's **Allow Frontend Control** switch is saved as `allow_frontend_control: true`, and remote inputs are saved with `source: remote` and `on_disconnect`. Leave those to the panel.
# Areas/Rooms (/en/docs/black/current/configuration/areas)
An area is a room or a part of the house: Kitchen, Garage, First floor. Give an output, an input or a sensor an area, and the panel can list it under that room, and Home Assistant shows it as part of a device for that room instead of one long list on the controller.
Open **Settings** → **Device** → **Areas/Rooms**. The list shows each area with its **ID** and **Name**. Changes apply without a restart.
## Adding an area [#adding-an-area]
1. Click **Add New**.
2. Fill in **Area ID** and **Area Name**.
3. Click **Add Item**, then **Save** at the bottom of the section.
| Field | What it does |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Area ID** | The technical name other items refer to, for example `living_room`. Required. The panel turns what you type into lower-case letters, digits and underscores as you type: spaces become `_` and Polish letters lose their accents. |
| **Area Name** | The name shown in the panel and in Home Assistant, for example `Living Room`. Required. If you rename the area in Home Assistant, change the name here too. |
Keep every **Area ID** different. The panel does not stop you from entering the same ID twice, and two areas with one ID behave as one.
To edit an area, click the edit icon next to it, change it and click **Save Changes**, then **Save**.
## Putting items in an area [#putting-items-in-an-area]
The area itself does nothing until something is in it. Outputs, output groups, covers, inputs, 1-Wire and ADC sensors, Modbus devices and most other items have an **Area / Room** field in their own form. Pick the area there; **No area (main device)** leaves the item on the controller itself.
## What an area does [#what-an-area-does]
**In the panel.** The **Outputs**, **Inputs** and **Modbus** pages have a **Group by area** button. With it on, items are listed under their area, and items with no area come last under **No area**.
**In Home Assistant.** Every area that has items becomes its own device, named after the controller followed by the area, for example **boneIO Black - Kitchen**, and linked to the main controller device. Home Assistant suggests the room of the same name for it. Items with no area stay on the main device.
Home Assistant picks up a new or renamed area the next time the controller announces its devices: after the boneIO app restarts, or when Home Assistant itself restarts.
The experimental **HA Child Devices** option in [boneIO](./boneio) makes every output, output group, input, cover and ADC sensor its own device instead. The area is then given to each of those devices as its suggested room.
## Order [#order]
Areas appear in **Group by area** in the order they are in the list. A new area goes to the end. Clicking the **ID** or **Name** column header only sorts the view; it does not change the saved order. To reorder areas, move them in the YAML editor (see [below](#yaml)).
## Removing an area [#removing-an-area]
Click the bin next to the area.
* If items use it, the panel shows **Warning: Area is in use** with the list of those items. **Delete anyway** removes the area and saves at once.
* Otherwise it is removed from the list. Click **Save**.
The warning checks outputs, output groups, covers, inputs, 1-Wire sensors, Modbus devices and virtual energy sensors. An area used only by other items, such as an ADC sensor, a thermostat or an irrigation zone, is removed without a warning.
The items are not changed: each still refers to the removed area's ID. Once the controller announces its devices again (after a restart of the boneIO app or of Home Assistant), Home Assistant shows them on the main controller device, as if they had no area. On the **Group by area** view they still form a group, named by the old ID. Add an area with the same ID again and they are back where they were; otherwise give each of them a new area in its own form.
Do not change the **Area ID** of an area that is in use. Items refer to the ID, so changing it has the same effect as removing the area. To rename a room, change only **Area Name**.
```yaml title="Sample configuration"
areas:
- id: living_room
name: Living Room
- id: kitchen
name: Kitchen
output:
- id: ceiling_light
boneio_output: out_01
output_type: light
area: kitchen
```
| Option | Required | Type | Default | Description |
| -------- | -------- | ------ | ------- | ----------------------------------------------------------------------------------------- |
| **id** | **yes** | string | none | ID other items refer to with `area:`. Lower-case letters, digits and `_`. Must be unique. |
| **name** | **yes** | string | none | Name shown in the panel and in Home Assistant. |
Items refer to an area with `area: `. The order of the list is the order of the groups in the panel.
# Binary Sensors (/en/docs/black/current/configuration/binary)
A **binary sensor** is an input with two states: a motion sensor, a door or window reed switch, a flood sensor.
It runs one set of actions when the input becomes active (**Pressed**) and another when it becomes inactive (**Released**).
Home Assistant shows it as a binary sensor, and every change is published to MQTT.
For a push button that should tell single, double and long presses apart, use an [event](/en/docs/black/current/configuration/event) instead. Both are edited in the same place, see [Local Inputs](/en/docs/black/current/configuration/inputs_local).
## Adding a binary sensor [#adding-a-binary-sensor]
1. Open **Settings** → **Control** → **Local Inputs**
2. Click **Add New** (or the edit icon next to an existing input)
3. At the top of the form set **Type** to **Binary Sensors**
4. Fill in the tabs described below and save
### Basic Settings [#basic-settings]
| Field | What it does |
| ---------------- | --------------------------------------------------------------------------------------------------------------- |
| **Display Name** | Name shown in the panel, MQTT and Home Assistant. Optional. |
| **boneIO Input** | The physical input, e.g. `IN_05`. Inputs already taken by another input are listed under the field as **Used**. |
| **Area / Room** | Puts the sensor into an area, which becomes a sub-device in Home Assistant. |
| **Bounce Time** | Ignores contact bounce (default 120ms). Usually no change is needed. |
| **Device Class** | How Home Assistant shows the sensor — icon and wording, e.g. `motion`, `door`, `window`, `moisture`. |
Under **Options**:
| Option | Default | What it does |
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Show in Home Assistant** | on | Switch off to keep the sensor out of Home Assistant. |
| **Inverted** | off | Swaps the two states — for a reed switch that reports open when the door is closed. |
| **Send initial state** | off | Sends the current state to MQTT when the controller starts. The controller now sends it every time it connects to MQTT anyway (see below), so you rarely need this. |
### Pressed Actions / Released Actions [#pressed-actions--released-actions]
**Pressed** runs when the input becomes active (motion detected, door opened); **Released** when it becomes inactive.
On either tab click **Add Action** and choose what should happen — the full list is in [Actions](/en/docs/black/current/configuration/event#actions) on the Events page.
Binary sensor actions can also be delayed — for example, switch the light off 2 minutes after the motion stops, and cancel that if motion comes back. See [Delay](/en/docs/black/current/configuration/event#delay).
**Quick action setup** in the form fills in the actions for common cases — motion sensor, door sensor, doorbell — in one click.
## State in Home Assistant [#state-in-home-assistant]
The state of a binary sensor is kept on the MQTT broker, and every time the controller connects to MQTT it reads each input again and sends what is true now.
So after Home Assistant or the controller restarts, a door or float switch shows its real state straight away, not `unknown` until it next changes.
Sending the state this way never runs the sensor's actions.
Leftover to know about: if you delete a binary sensor, or change it to an event, its last state stays on the broker.
Home Assistant's event entity ignores it.
```yaml title="Sample configuration — hallway motion sensor"
binary_sensor:
- boneio_input: in_05
name: Hallway motion
area: hallway
device_class: motion
actions:
pressed:
- action: output
boneio_output: out_03
action_output: "ON"
released:
- action: output
boneio_output: out_03
action_output: "OFF"
delay: 2min
delay_cancel_on:
- pressed
```
**Options**
* **boneio\_input** (*Optional*, string) — the input, `in_01` … `in_52`.
* **pin** (*Optional*, string) — a raw GPIO pin, e.g. `P9_33`. Not needed with `boneio_input`.
* **id** (*Optional*, string) — identifier used in MQTT and Home Assistant. Defaults to the input.
* **name** (*Optional*, string) — display name.
* **area** (*Optional*, string) — ID of an area from the `areas` section.
* **bounce\_time** (*Optional*, time, default `120ms`)
* **device\_class** (*Optional*) — one of `battery`, `battery_charging`, `carbon_monoxide`, `cold`, `connectivity`, `door`, `garage_door`, `gas`, `heat`, `light`, `lock`, `moisture`, `motion`, `moving`, `occupancy`, `opening`, `plug`, `power`, `presence`, `problem`, `running`, `safety`, `smoke`, `sound`, `tamper`, `vibration`, `window`.
* **show\_in\_ha** (*Optional*, boolean, default `true`) — publish the sensor to Home Assistant.
* **inverted** (*Optional*, boolean, default `false`) — swap the two states.
* **initial\_send** (*Optional*, boolean, default `false`) — send the state to MQTT at startup.
* **actions** (*Optional*) — lists of actions under `pressed` and `released`. See [Actions](/en/docs/black/current/configuration/event#actions).
`kind` is not a binary sensor option, and `clear_message` was removed in 1.6. On its first start 1.6 deletes `clear_message` (and the old `gpio_mode`) from `binary_sensor` and `event` by itself.
# boneIO (/en/docs/black/current/configuration/boneio)
This section tells the application what controller it runs on: its name, the hardware version of the controller and the device type.
Open **Settings** → **Device** → **boneIO**.
This section carries the **restart** badge. After **Save**, the panel shows **App restart required**. Click **Restart Now**, or nothing changes.
| Field | What it does |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name** | The controller's name, shown in the panel, in Home Assistant and on other boneIO controllers. Required once a hardware version or device type is chosen. |
| **Hardware Version** | The version of the controller, printed on the label on the side of the housing. It decides which pins and chips the application expects. |
| **Device Type** | Which model this is: 32x10A, Cover or Cover Mix. The older 32x5A, 24x16A and 48x4A models are listed as DISCONTINUED. |
| **Serial Number Override** | Leave empty. Used only when a replacement controller has to take over the identity of an old one (see below). |
| **\[EXPERIMENTAL] HA Child Devices** | Registers every output, input, cover and sensor as a separate device in Home Assistant (see below). Off by default. |
## Hardware version [#hardware-version]
The wrong version means inputs, outputs or sensors of the controller do not work. Pick the one on the label:
| Version | What the controller has |
| --------- | ----------------------------------------------------------------- |
| 0.2, 0.3 | MCP9808 temperature sensor, no power monitor. Modbus on `uart1`. |
| 0.4 – 0.7 | LM75 temperature sensor, INA219 power monitor. Modbus on `uart4`. |
| 0.8 | Like 0.7, but the output expanders are at different addresses. |
| 1.0 | INA226 power monitor instead of INA219, built-in 1-Wire bridge. |
| 1.1 | Like 1.0, plus a buzzer. |
The buzzer exists only on 1.1. It is used like any other output, with `boneio_output: buzzer`. A 1.0 configuration that asks for it is rejected when it loads.
## Changing the device type [#changing-the-device-type]
Changing the **Device Type** can leave your configuration pointing at outputs or inputs the new model does not have. The panel checks this at once.
If there is a conflict, the **Device Type Change Warning** window lists the **Incompatible outputs** and **Incompatible inputs**.
Under **Load Example Configuration** you can tick which files to replace with the example configuration for the new model
(`output.yaml`, `event.yaml`, `binary_sensor.yaml`, `cover.yaml`) and click **Load & Apply**. Your current files are backed up first.
Then restart the application.
To start from a default working configuration for a device type, use **Settings** → **Maintenance** → **Factory reset**.
## Serial number override [#serial-number-override]
The serial number is made from the controller's MAC address, for example `blk8c7df0`. It is part of every MQTT topic and every Home Assistant entity ID.
A replacement controller (for example after a warranty exchange) has a different one, so Home Assistant would see it as a new device.
If you type the old controller's serial number into **Serial Number Override**, the new controller uses it, and your Home Assistant entities, dashboards and automations keep working.
The format is `blk` followed by six characters `0-9` / `a-f`.
When you restore a backup made on a controller with a different serial number, the panel asks the same question itself (**Keep Old Serial**).
Two controllers with the same serial number on one MQTT broker get in each other's way. Use the override only on the controller that replaces the old one.
## HA child devices [#ha-child-devices]
Experimental: this may change or disappear in a future version.
Normally Home Assistant sees the controller as one device with many entities. With **\[EXPERIMENTAL] HA Child Devices** on,
every output, input, cover and sensor becomes its own device, linked to the controller. Home Assistant can then build dashboards per area on its own.
**Child Device Naming Style** appears when the switch is on:
* **Default (entity name only, e.g. OUT 17)**: may give duplicate names if you have several boneIO controllers with the same output names,
* **Device name + entity (e.g. boneIO Black - OUT 17)**,
* **Device name + area + entity (e.g. boneIO Black - Gabinet - OUT 17)**: falls back to the device name if no area is assigned.
Before switching it on or off, click **Remove all HA devices** in [MQTT](./communication), so the old entries do not stay behind in Home Assistant.
The devices come back in the new form after the restart.
```yaml title="Sample configuration"
boneio:
name: boneIO Black 32x10A
version: "1.1"
device_type: 32x10A
```
| Option | Required | Type | Default | Description |
| ------------------------------ | -------- | ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **name** | **yes** | string | none | Name of the controller. |
| **version** | no | string or number | none | Hardware version. Allowed: `0.2`, `0.3`, `0.4`, `0.5`, `0.6`, `0.7`, `0.8`, `1.0`, `1.1`. |
| **device\_type** | no | string | none | Device type, not case-sensitive. Allowed: `32x10A`, `cover`, `cover mix`, and for older models `32x5A`, `24x16A`, `48x4A`. The short forms `32x10`, `32`, `32x5`, `24x16`, `24`, `48x4`, `48` and `cm` (Cover Mix) are also accepted. |
| **serial\_override** | no | string | none | Serial number to use instead of the one from the MAC address. Format: `blk` + 6 hex characters. |
| **ha\_child\_devices** | no | boolean | `false` | Experimental: one Home Assistant device per entity. |
| **ha\_child\_devices\_naming** | no | string | `default` | `default`, `device_name` or `device_name_area`. Used only with `ha_child_devices`. |
| **config\_version** | no | integer | `0` | Managed by the application during configuration upgrades. Do not change it. |
# CAN Bus (/en/docs/black/current/configuration/canbus)
The controller has a CAN bus port (terminals `H` and `L`). boneIO uses it to talk to other devices over the CANopen protocol, for example
another boneIO Black, or an ESPHome device running esphome-canopen. The bus is **off by default**.
For wiring, see the hardware installation page for your model, for example [boneIO Black 32x10A](/en/docs/black/products/black_32x10a/hardware-installation).
## Switching the bus on [#switching-the-bus-on]
1. Open **Settings** → **Connections** → **CAN Bus**
2. Switch on **Enable CAN Bus**. The rest of the fields appear once it is on.
3. In **CAN Interface**, pick the interface the panel found on the controller. If the list says **No CAN interfaces detected**,
the operating system does not see a CAN port, and no setting on this page will fix that.
4. Set **Bitrate**. It must be the same on **every** device on the bus. The default, 125 kbps, matches esphome-canopen.
5. Leave **Node ID** at `auto` unless you have a reason to change it (see below).
6. Choose the **Mode** (see below).
7. Click **Save** and then **Restart Now**. The section carries the **restart** badge: nothing changes until the application restarts.
{/* SCREENSHOT: en_settings_can.webp — Settings → Connections → CAN Bus with Enable CAN Bus switched on */}
| Field | What it does |
| ---------------------------- | --------------------------------------------------------------------------------------------- |
| **Enable CAN Bus** | Turns CAN communication on or off. |
| **CAN Interface** | The CAN port to use, chosen from those detected on this controller. |
| **Bitrate** | Bus speed: 10, 20, 50, 100, 125 (default), 250, 500 kbps or 1 Mbps. |
| **Node ID** | This device's address on the bus: `auto` or a number from 1 to 127. |
| **Mode** | **Master (has LAN/MQTT)** or **Slave (CAN only)**. |
| **Auto-setup interface** | Sets up the CAN port with the chosen bitrate each time the application starts. On by default. |
| **Restart on bus-off error** | Restarts the CAN port when the bus stops because of too many errors. On by default. |
### Node ID [#node-id]
Every device on one bus needs its own ID. With `auto`, the controller works out an ID from its MAC address and keeps it, so it stays the same across restarts.
Type a number from 1 to 127 only if two devices ended up with the same ID, or if another device on the bus expects this one at a fixed address.
### Master or slave [#master-or-slave]
* **Master (has LAN/MQTT)**: the controller is on the network. It passes the data of slave devices on to Home Assistant and sends them commands.
* **Slave (CAN only)**: the device has no network connection and sends its data only over the CAN bus, to a master.
A typical setup has one master connected to the network and one or more slaves.
**Auto-setup interface** and **Restart on bus-off error** need system permissions on the controller.
If the CAN port does not come up after a restart, open **Settings** → **Maintenance** → **System migrations** and apply any pending migrations.
## After the bus is on [#after-the-bus-is-on]
With the bus on, the **Scan CAN** button appears in **Settings** → **Connections** → **Remote Devices**, next to **Scan ESPHome** and **Scan WLED**.
It lists the devices that answered on the bus. See [Remote Devices](./remote-devices).
```yaml title="Sample configuration"
can:
enabled: true
channel: can0
bitrate: 125000
node_id: auto
mode: master
auto_setup: true
restart_on_error: true
```
| Option | Type | Default | Description |
| ---------------------- | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| **enabled** | boolean | `false` | Turn CAN communication on. |
| **channel** | string | `can0` | CAN interface name. |
| **bitrate** | integer | `125000` | Bus speed in bit/s. Allowed: `10000`, `20000`, `50000`, `100000`, `125000`, `250000`, `500000`, `1000000`. |
| **node\_id** | integer or string | `auto` | CANopen node ID, `1`–`127`, or `auto`. |
| **mode** | string | `master` | `master` or `slave`. |
| **auto\_setup** | boolean | `true` | Set up the interface on startup. |
| **restart\_on\_error** | boolean | `true` | Restart the interface after a bus-off error. |
All options are optional. Changes need an application restart.
# MQTT and Loxone (/en/docs/black/current/configuration/communication)
This is where you decide how the controller talks to the rest of your system: over **MQTT** (Home Assistant, other boneIO controllers)
and, if you use Loxone, over **Lox UDP**. Each has its own entry under **Settings** → **Connections**: **MQTT** and **Loxone (UDP)**.
They save separately, so a mistake on one never stops you saving the other.
Both entries carry the **restart** badge. After **Save**, the panel shows **App restart required**. Click **Restart Now**, or nothing changes.
While the application restarts, Home Assistant sees the controller as unavailable for a moment.
One exception: on the **MQTT** page, a change to only **Host**, **Port**, **Username** or **Password** needs no restart.
boneIO reconnects to the broker as soon as you click **Save**.
## MQTT [#mqtt]
Open **Settings** → **Connections** → **MQTT**.
A controller fresh from the factory connects to the MQTT broker running on itself (`localhost`). Home Assistant then connects to that broker too.
If you already have a broker, for example the Mosquitto add-on in Home Assistant, enter its address here instead.
| Field | What it does |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enable MQTT** | Turns the MQTT connection on or off. Without it there is no Home Assistant integration and no communication with other boneIO controllers over MQTT. |
| **Host** | Address or hostname of the MQTT broker. `localhost` means the broker on this controller. |
| **Port** | Broker port, 1883 by default, 8883 for TLS. |
| **Username** | The account boneIO signs in to the broker with. |
| **Password** | The password for that account. The panel never shows the stored password; leave the field as it is to keep it. |
### Where the password is kept [#where-the-password-is-kept]
The MQTT password is not written into the configuration itself. It lives in a separate file, `secrets.yaml`, and the configuration only refers to it
(`password: !secret mqtt_password`). That way the configuration files you look at, edit or paste when asking for help do not contain the password.
* A controller set up with 1.6 gets a random MQTT password of its own at first start, different on every device.
* A controller updated from an older version has its password moved to `secrets.yaml` on its own, the first time 1.6 starts.
* A new password typed on this page and saved also goes to `secrets.yaml`.
* A **factory reset** keeps the device's MQTT password.
`secrets.yaml` is deliberately not shown in the panel's YAML editor. To read it you need SSH.
A downloaded configuration backup does include `secrets.yaml`, so keep backup files as private as the password itself.
If the broker is the one on this controller, change the `boneio` account's password in **Settings** → **Services on this controller** → **MQTT broker (local)**
and leave **Also update boneIO's own configuration** switched on. The controller then stores the new password itself and reconnects;
there is nothing to type here. See [Home Assistant Connection](/en/docs/black/current/install/home-assistant-connection).
### Encryption (TLS) [#encryption-tls]
Plain MQTT sends the username and password in the clear. On your own home network that is often acceptable; on a shared network,
across a VPN or to a broker on the internet it is not. Under **Encryption (TLS)** boneIO connects to the broker encrypted.
1. Switch on **Encrypt the connection (TLS)**. If the port was the default 1883, it changes to 8883 by itself. A port you set yourself stays.
2. Under **Check the broker's certificate against**, choose:
* **Trusted public authorities**, for a broker with a certificate from a public authority such as Let's Encrypt.
* **My own CA**, for a broker whose certificate you made yourself, a company CA, or another boneIO controller's broker.
Upload that CA's certificate (`ca.crt`) and click **Upload**. Never upload the CA's key.
* **Don't check (testing only)** encrypts but does not check who answers.
3. If the broker asks for a client certificate, switch on **The broker asks for a client certificate**, choose the certificate and its private key,
and click **Upload the certificate and key**. Most brokers need only the username and password.
4. Click **Save**, then **Restart Now** when the panel asks.
Uploaded files are stored at once; the settings take effect when you save the page.
Under the switch the page tells you how the current connection is going: **Connected to the broker over TLS.**, **Connected, but still without TLS. Save this page to switch.**,
or, when something is wrong, **TLS is on but cannot be used** with the reason.
**If TLS is on and cannot be set up, boneIO does not connect at all.** It never falls back to plain text, because the password would travel in the clear.
A wrong port, a missing CA or a key that does not match the certificate means the controller stops reporting to Home Assistant until you fix it.
**Don't check (testing only)** really is for testing: anyone able to intercept the connection can pose as the broker and read the password.
The certificates are not part of a configuration backup. After restoring a backup on another controller, upload them again.
Do you not have certificates yet? **How to make certificates with openssl** on the same page shows the commands to copy and run on your own computer.
To encrypt the connections *to* the broker on this controller (Home Assistant connecting to boneIO), see
[Encrypting Home Assistant's connection](/en/docs/black/current/install/home-assistant-connection#encrypting-home-assistants-connection-tls).
### Home Assistant Discovery [#home-assistant-discovery]
| Field | What it does |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Enable HA Discovery** | The controller registers its outputs, inputs, covers and sensors in Home Assistant automatically. On by default. |
| **HA Discovery Topic Prefix** | The topic Home Assistant listens on for new devices, `homeassistant` by default. Change it only if you changed it in Home Assistant. |
Under **Remove devices from Home Assistant** there are two buttons. They act immediately, without **Save**, and only when HA Discovery is on:
* **Remove & re-send HA Discovery**: removes all entries this controller created in Home Assistant and sends them again straight away.
Use it when Home Assistant shows old names or entities you have already deleted.
* **Remove all HA devices**: removes all devices and entities this controller registered in Home Assistant.
They come back at the next application restart.
Both ask for confirmation first.
### boneIO Autodiscovery [#boneio-autodiscovery]
| Field | What it does |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Send boneIO Autodiscovery** | Publishes this controller's outputs, covers, inputs and sensors so that other boneIO controllers can find and control it. On by default. |
| **Receive boneIO Autodiscovery** | Finds other boneIO controllers on the same broker. They then appear in [Remote Devices](./remote-devices). On by default. |
### Update Settings [#update-settings]
**Update Channel** decides which versions Home Assistant's update entity for boneIO offers: **Stable (recommended)**
or **Development (pre-release)**, which also includes pre-release versions.
### MQTT topics [#mqtt-topics]
The controller publishes under `boneio/`, for example `boneio/blk8c7df0`. The serial number is shown next to **S/N** in the panel.
The topic cannot be changed. The only way to give the controller a different serial number is **Serial Number Override** in [boneIO](./boneio).
## Loxone (UDP) [#loxone-udp]
Lox UDP sends the state of outputs and inputs to a Loxone Miniserver and receives commands from it, as UDP messages. It is off by default.
Lox UDP support is **experimental**. It is compatible with Loxone devices, but test it on your installation before you rely on it.
1. Open **Settings** → **Connections** → **Loxone (UDP)** and switch on **Enable Lox UDP**.
2. Enter the Miniserver's address in **Host** (an IP address such as `192.168.1.100` or a hostname such as `miniserver.local`). This field is required.
3. Leave **Send Port** (4444) and **Listen Port** (4445) as they are, unless your Loxone project uses other ports.
4. Click **Save** and **Restart Now**.
Under **Lox Config Integration**:
* **Download Lox Config Template** downloads an XML file to import into Loxone Config. It contains Virtual Outputs (to control boneIO) and Virtual Inputs (to receive its states).
* **View UDP Commands** lists all available UDP commands.
```yaml title="Sample configuration"
mqtt:
enabled: true
host: localhost
port: 1883
username: boneio
password: !secret mqtt_password
ha_discovery:
enabled: true
topic_prefix: homeassistant
send_boneio_autodiscovery: true
receive_boneio_autodiscovery: true
update_channel: stable
lox_udp:
enabled: true
host: 192.168.1.100
send_port: 4444
listen_port: 4445
```
```yaml title="secrets.yaml (next to config.yaml)"
mqtt_password: "your_password"
```
A controller connecting to another broker over TLS, checking it against your own CA:
```yaml title="Sample configuration with TLS"
mqtt:
host: broker.example.lan
port: 8883
username: boneio
password: !secret mqtt_password
tls:
enabled: true
ca_certs: certs/mqtt-ca.pem # leave out to use the public authorities
# certfile: certs/mqtt-client.pem # only for a broker that asks for a client certificate
# keyfile: certs/mqtt-client.key
```
**`mqtt`**
| Option | Required | Type | Default | Description |
| ------------------------------------- | -------- | ------- | --------------- | --------------------------------------------------------------------------------- |
| **enabled** | no | boolean | `true` | Turn the MQTT connection on. |
| **host** | **yes** | string | none | Broker hostname or IP address. |
| **port** | **yes** | integer | `1883` | Broker port. |
| **username** | no | string | none | Username for the broker. |
| **password** | no | string | none | Password for the broker. Usually `!secret mqtt_password`, kept in `secrets.yaml`. |
| **ha\_discovery** → **enabled** | no | boolean | `true` | Register entities in Home Assistant. |
| **ha\_discovery** → **topic\_prefix** | no | string | `homeassistant` | Home Assistant discovery prefix. |
| **send\_boneio\_autodiscovery** | no | boolean | `true` | Publish this controller for other boneIO controllers. |
| **receive\_boneio\_autodiscovery** | no | boolean | `true` | Discover other boneIO controllers. |
| **update\_channel** | no | string | `stable` | `stable` or `dev`. |
| **tls** | no | dict | none | Encrypt the connection to the broker, see below. |
`topic_prefix` directly under `mqtt` is no longer used. If an older configuration still has it, it is ignored.
**`mqtt` → `tls`**
| Option | Required | Type | Default | Description |
| ------------- | -------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **enabled** | no | boolean | `false` | Connect over TLS, usually on port 8883. |
| **ca\_certs** | no | string | none | CA certificate (PEM) that signed the broker's certificate. Without it, the system's trusted public authorities are used. |
| **certfile** | no | string | none | Client certificate (PEM), for brokers that ask for one. Needs **keyfile**. |
| **keyfile** | no | string | none | Private key of the client certificate (PEM, unencrypted). Needs **certfile**. |
| **insecure** | no | boolean | `false` | Skip checking the broker's certificate. Anyone able to intercept the connection can pose as the broker and read the password. Only for testing. |
Relative paths start from the directory holding `config.yaml`. Files uploaded in the panel go to `certs/` there.
**`lox_udp`**
| Option | Required | Type | Default | Description |
| ---------------- | -------- | ------- | ------- | ------------------------------------------- |
| **enabled** | no | boolean | `false` | Turn Lox UDP on. |
| **host** | **yes** | string | none | IPv4 address or hostname of the Miniserver. |
| **send\_port** | no | integer | `4444` | Port boneIO sends to. |
| **listen\_port** | no | integer | `4445` | Port boneIO listens on. |
# Covers (/en/docs/black/current/configuration/cover)
A cover is a roller blind, a shutter or a venetian blind driven by two relays: one moves it up, the other down.
The controller knows where the cover is by counting how long each relay has been on, so it needs to know how long a full opening and a full closing take.
Covers work on the Cover and Cover Mix models and on an ordinary relay board.
Open **Settings** → **Control** → **Covers**. The list shows each cover with its type, times and area. Changes apply without a restart.
## Adding a cover [#adding-a-cover]
### Basic Settings [#basic-settings]
| Field | What it does |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Display Name** | Name shown in the panel and in Home Assistant. Optional: without it, the ID is used. |
| **ID** | Technical ID for MQTT topics and actions: lower-case letters, digits and underscores only. Optional: without it, the panel shows what it will be, for example `cover_out_31_out_32`. |
| **Area / Room** | The area the cover belongs to. |
| **Platform** | **TIME\_BASED**: an ordinary roller blind that goes up and down. **VENETIAN**: a venetian blind whose slats also tilt. Required. |
| **Open Relay** | The output that moves the cover up. Required. |
| **Close Relay** | The output that moves the cover down. Required. |
| **Open Time** | How long a full opening takes. At least 1 s. Required. |
| **Close Time** | How long a full closing takes. At least 1 s. Required. |
| **Actuator Activation Duration** | How long the motor takes to start after its relay switches on. This time is added to every movement. Leave `0ms` (the default) if the motor starts at once; some drives that ignore short pulses (e.g. Somfy J4 WT) need about `200ms`, otherwise a small tilt step does nothing. Up to 5 s. |
Only outputs whose type is `cover` or `none` are offered as relays. The output type is set in [Local Outputs](./outputs_local).
Measure the times with a stopwatch, from fully closed to fully open and back. If they are too short, the cover stops before it reaches the end; if too long, the position shown drifts.
For **VENETIAN** there are two more fields:
| Field | What it does |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Tilt Duration** | How long the slats take to turn from fully closed to fully open. Required for VENETIAN, at least 10 ms. |
| **Restore Tilt After Movement** | After the blind moves to a position in between, the slats return to the angle they had before. Not when the blind ends fully open or fully closed. Off by default. |
### Advanced Settings [#advanced-settings]
| Field | What it does |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Endstop Overrun** | On a move to fully open or fully closed, the relay stays on longer by this percent of the open/close time, so the cover runs into its endstop. Default `10` % — about 3 s on a 30 s cover. `0` turns it off. |
| **Direction Change Wait** | Pause between switching one direction off and the other on, so the motor stops before it reverses. Default `500ms`, up to 10 s. `0` turns it off. |
| **Device Class** | What Home Assistant shows the cover as (blind, shutter, garage and so on). |
| **Restore State** | After a restart, the cover starts from the position it had before, instead of assuming it is fully open. Off by default. |
| **Show in Home Assistant** | Announce the cover to Home Assistant. On by default. |
## How a cover moves [#how-a-cover-moves]
* **Full open and full close run into the endstop.** The controller keeps the relay on a little longer (**Endstop Overrun**) so the cover really reaches the end.
That corrects the small drift a time-based position collects, every time the cover goes all the way. A cover already fully closed is not driven again.
* **Reversing waits for the motor to stop.** Going straight from up to down waits **Direction Change Wait** first. Carrying on in the same direction does not wait.
* **Stop is exact.** A cover stopped mid-way keeps the position it actually reached.
* **A venetian blind at 0% with its slats open still responds to Close** — it shuts the slats. The panel's **Close** button stays active until they are shut.
Home Assistant's own cover card greys out Close at 0%, because it looks only at the position; use **Close tilt** there.
Endstop Overrun and Direction Change Wait apply to **every cover, including ones set up before 1.6** — after updating, a full open or close
runs about 10% longer and a reversal pauses for half a second. If your motor has no endstops, set **Endstop Overrun** to `0`.
**Roller blind (time\_based)**
```yaml title="Sample configuration"
cover:
- id: living_room_left
name: Living room left
area: living_room
platform: time_based
open_relay: cover_08_up
close_relay: cover_08_down
open_time: 30s
close_time: 28s
device_class: shutter
restore_state: true
show_in_ha: true
endstop_overrun: 10
direction_change_wait_time: 500ms
```
**Venetian blind (venetian)**
```yaml title="Sample configuration"
cover:
- id: office_blind
name: Office blind
platform: venetian
open_relay: cover_07_up
close_relay: cover_07_down
open_time: 14s
close_time: 14s
tilt_duration: 1200ms
tilt_restore_after_close: true
restore_state: true
```
| Option | Required | Type | Default | Description |
| ---------------------------------- | -------------- | ----------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **open\_relay** | **yes** | string | none | ID of the output that opens the cover. |
| **close\_relay** | **yes** | string | none | ID of the output that closes the cover. |
| **open\_time** | **yes** | time period | none | Full opening time. At least 1 s. |
| **close\_time** | **yes** | time period | none | Full closing time. At least 1 s. |
| **platform** | no | string | `time_based` | `time_based` or `venetian`. |
| **id** | no | string | `cover__` | Lower-case letters, digits and `_` only. |
| **name** | no | string | the ID | Name shown in the panel and Home Assistant. |
| **area** | no | string | none | ID of an area from [Areas/Rooms](./areas). |
| **tilt\_duration** | for `venetian` | time period | none | Full tilt time of the slats. At least 10 ms. |
| **tilt\_restore\_after\_close** | no | boolean | `false` | `venetian` only: restore the slat angle after moving to a position in between. |
| **device\_class** | no | string | none | `awning`, `blind`, `curtain`, `damper`, `door`, `garage`, `gate`, `shade`, `shutter` or `window`. |
| **restore\_state** | no | boolean | `false` | Start from the saved position after a restart. |
| **show\_in\_ha** | no | boolean | `true` | Announce the cover to Home Assistant. |
| **actuator\_activation\_duration** | no | time period | `0ms` | Time from switching the relay on until the motor moves, added to every movement. |
| **endstop\_overrun** | no | integer | `10` | Extra relay time on a move to fully open or closed, as a percent (0–100) of `open_time`/`close_time`. `0` turns it off. |
| **direction\_change\_wait\_time** | no | time period | `500ms` | Pause before driving the cover the other way. `0ms` turns it off. |
Neither `id` nor `name` is required. Without an `id`, one is built from the two relay IDs. Set your own if you want a readable ID in MQTT topics and actions.
# DS2482 (removed) (/en/docs/black/current/configuration/ds2482)
The `ds2482:` section is no longer used. 1-Wire buses, including the DS2484 bridge on 1.0 controllers, are handled by the operating system,
so there is nothing to configure. An old `ds2482:` section is ignored with a warning in the log — you can delete it.
To add a temperature sensor, see [Onewire sensors](/en/docs/black/current/configuration/onewire-sensors).
# Events (/en/docs/black/current/configuration/event)
An **event** input is for a push button. The controller tells the click types apart — single, double, triple, long, and three sequences such as *double, then hold* — and each can run its own actions.
Actions run on the controller itself, so a button keeps switching its light when the network or Home Assistant is down.
Every click is also published to MQTT, and Home Assistant shows the input as an **Event** entity (Home Assistant 2023.8 or newer).
For a sensor with two states — motion, reed switch, flood — use a [binary sensor](/en/docs/black/current/configuration/binary) instead. Both are edited in the same place, see [Local Inputs](/en/docs/black/current/configuration/inputs_local).
## Adding an event [#adding-an-event]
1. Open **Settings** → **Control** → **Local Inputs**
2. Click **Add New** (or the edit icon next to an existing input)
3. At the top of the form set **Type** to **Events**
4. Fill in the tabs described below and save
### Basic Settings [#basic-settings]
| Field | What it does |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Display Name** | Name shown in the panel, MQTT and Home Assistant. Optional. |
| **boneIO Input** | The physical input, e.g. `IN_04`. Inputs already taken by another event or binary sensor are listed under the field as **Used**. |
| **Area / Room** | Puts the input into an area, which becomes a sub-device in Home Assistant. |
### Single / Double / Triple / Long [#single--double--triple--long]
One tab per click type. On each tab click **Add Action** and choose what should happen — see [Actions](#actions) below.
The **Triple** tab only works after **Enable Triple Click** is switched on in **Advanced Settings**; the tab warns you if it is off.
### Sequences [#sequences]
A sequence is a combination of clicks:
| Sequence | Meaning |
| ------------------- | --------------------------------- |
| **Double + Long** | double click, then hold |
| **Single + Long** | single click, then hold |
| **Double + Single** | double click, then one more click |
Each sequence can have its own actions. The **MQTT** tick box next to a sequence decides whether that sequence is also published to MQTT (and Home Assistant) — it is off by default.
### Advanced Settings [#advanced-settings]
| Field | Default | What it does |
| --------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Bounce Time** | 30ms | Ignores contact bounce. Raise it only if one press is seen as two. |
| **Double Click Duration** | 220ms | How long the controller waits for a second click. |
| **Long Press Duration** | 400ms | How long the button must be held to count as a long press. |
| **Sequence Window** | 500ms | How long the controller waits for the next part of a sequence. |
| **Sequence Mode** | Exclusive | **Exclusive**: single, double and long are held back for the sequence window; if a sequence is recognised, only the sequence fires. **Immediate**: single, double and long fire at once, and a sequence fires in addition. |
| **Enable Triple Click** | off | Turns on triple-click detection. |
| **Long Press MQTT Mode** | Single | **Single**: only the first long-press message is sent to MQTT. **Periodic**: a message every 200ms while the button is held, with the growing duration. |
| **Max Long Press Duration** | 30s | Safety stop: a long press is ended after this time even if the release was missed. It cannot be more than 30s. |
**Restore Defaults** puts all timings back to the values above.
**Double Click Duration** must be shorter than **Long Press Duration** — the form warns you otherwise.
With **Sequence Mode: Exclusive** (the default) every single click waits for the sequence window before it acts. If a button feels slow and you use no sequences, switch to **Immediate**.
## Actions [#actions]
This is the list of everything an input can do. The same actions are used by [binary sensors](/en/docs/black/current/configuration/binary), [remote inputs](/en/docs/black/current/configuration/inputs_remote) and [schedules](/en/docs/black/current/configuration/schedule).
In the panel each action has an **Action Type** and the fields for that type. The ▶ button (**Test Action**) runs the action right away, so you can check it without pressing the button.
### Action types [#action-types]
| In the panel | In YAML (`action:`) | What it does | Fields |
| ------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| **Output** | `output` | Switches an output or an output group of this controller. | `boneio_output`, `action_output` |
| **Cover** | `cover` | Moves a cover of this controller. | `boneio_cover`, `action_cover` |
| **Virtual Switch** | `virtual_switch` | Sets a [virtual switch](/en/docs/black/current/configuration/virtual_switch) (ON, OFF or TOGGLE). | `boneio_virtual_switch`, `action_output` |
| **MQTT** | `mqtt` | Sends any message to any MQTT topic. | `topic`, `action_mqtt_msg` |
| **Output over MQTT** | `output_over_mqtt` | Switches an output of another boneIO through the broker. | `boneio_id`, `boneio_output`, `action_output` |
| **Cover over MQTT** | `cover_over_mqtt` | Moves a cover of another boneIO through the broker. | `boneio_id`, `boneio_cover`, `action_cover` |
| **Control Remote Output** | `remote_output` | Switches an output of a [remote device](/en/docs/black/current/configuration/remote-devices) (ESPHome, WLED, another boneIO). | `remote_device`, `output_id`, `action_output` |
| **Control Remote Cover** | `remote_cover` | Moves a cover of a remote device. | `remote_device`, `cover_id`, `action_cover` |
**Output**, **Cover** and **Virtual Switch** need no network. The other types need the MQTT broker or the remote device to be reachable.
`boneio_id` is the ID of the other boneIO — the prefix of its MQTT topics.
### Output actions (`action_output`) [#output-actions-action_output]
* `TOGGLE` (default), `ON`, `OFF` — for every output, output group and virtual switch.
A dimmable light on a remote device (an ESPHome light with brightness, or WLED) offers more. The panel only lists them when the chosen light supports them:
| Value | What it does |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `BRIGHTNESS_UP` / `BRIGHTNESS_DOWN` | Brighter / dimmer by one step. Up from off switches the light on at the first step; down from the first step switches it off. |
| `BRIGHTNESS_UP_CYCLE` / `BRIGHTNESS_DOWN_CYCLE` | As above, but wraps round from 100% to the lowest step (and back). |
| `SET_BRIGHTNESS` | Sets the brightness given in `brightness`. |
| `CYCLE_COLOR` | Each press moves to the next colour in `colors`. |
| `CYCLE_PRESET` | Each press moves to the next effect in `presets`. |
Extra fields for these lights:
* **brightness** (0–255) — for `SET_BRIGHTNESS`, or the brightness `ON` and `TOGGLE` switch on with.
* **brightness\_step** (1–50, percent, default 10) — the step of the four `BRIGHTNESS_*` actions.
* **colors** — a list of `[R, G, B]` colours, e.g. `[[255, 0, 0], [0, 0, 255]]`.
* **presets** — a list of effect names (ESPHome) or effect numbers (WLED).
* **rgb** — a colour `[R, G, B]`; **color\_temp** — colour temperature in mireds (153 cool … 500 warm), for lights that support it.
* **transition** — how long the change takes, e.g. `500ms`.
### Cover actions (`action_cover`) [#cover-actions-action_cover]
| Value | What it does |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `TOGGLE` (default) | Open or close, depending on the last movement. |
| `OPEN` / `CLOSE` / `STOP` | As named. |
| `TOGGLE_OPEN` | Alternates open and stop. |
| `TOGGLE_CLOSE` | Alternates close and stop. |
| `SMART_TOGGLE` | Like `TOGGLE`, but a cover at or below **Always open till (%)** (`data.always_open_till`, 0–100) always opens. |
| `TILT` | Sets the slats to **Tilt Position (%)** (`data.tilt_position`: 0 closed, 100 open). |
| `TILT_OPEN` / `TILT_CLOSE` | Opens / closes the slats. |
The three tilt actions are for venetian blinds only; the panel shows them only when a venetian blind is chosen.
**Restore tilt after movement** (`restore_tilt`) remembers the slat angle before the move and puts it back afterwards — also venetian blinds only.
### Conditions [#conditions]
Any action can be limited to certain circumstances. In the panel open **Conditions** under the action and click **Add Condition**.
| Condition Type | YAML `type:` | True when |
| ---------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Time Range** | `time` | the time is between `after` and `before` (`HH:MM`); a range such as 22:00–06:00 over midnight works. |
| **Date Range** | `date` | the date is between `after` and `before` (`MM-DD`); a range over New Year works. |
| **Entity State** | `state` | an entity (`entity` + `entity_id`) is in `state`: `is_on`, `is_off`, `is_open` or `is_closed`. |
| **Sun** | `sun` | the Sun is between two events (e.g. `sunset` and `sunrise`, each with an optional offset), in a phase of the day, or at an elevation. Needs a [location](/en/docs/black/current/configuration/location). |
For **Entity State** the entity can be a binary sensor, cover, output, light, virtual switch, remote input, remote output or remote cover (`binary_sensor`, `cover`, `output`, `light`, `virtual_switch`, `remote_input`, `remote_output`, `remote_cover`).
With more than one condition choose the **Condition Mode**: **AND** (all must pass, the default) or **OR** (any must pass).
### Delay [#delay]
**Delay execution** (`delay`) waits before running the action, for example to switch a light off 2 minutes after the motion sensor goes quiet.
**Cancel delay on events** (`delay_cancel_on`) lists the events on the same input that cancel the waiting action: `pressed`, `released`, `single`, `double`, `long`.
A typical pair: on **Released** switch the light off with a 2-minute delay, cancelled on `pressed` — new motion keeps the light on.
In the panel the delay is offered on binary sensor actions (Pressed / Released).
### Repeat on Hold [#repeat-on-hold]
On the **Long** tab an action can **Repeat on Hold** (`repeat`): it runs again and again while the button is held, at most every **Repeat Interval** (`repeat_interval`, default 800ms, not less than 200ms). Useful with `BRIGHTNESS_UP` / `BRIGHTNESS_DOWN`.
### Chance of running [#chance-of-running]
`probability` (0–1, YAML only) runs the action only some of the time: `0.7` is seven times out of ten. It is drawn after the conditions have passed. Meant for [presence simulation](/en/docs/black/current/configuration/presence_simulation).
```yaml title="Sample configuration"
event:
- boneio_input: in_04
name: Living room button
area: living_room
actions:
single:
- action: output
boneio_output: out_01
action_output: TOGGLE
double:
- action: cover
boneio_cover: living_room_blind
action_cover: SMART_TOGGLE
data:
always_open_till: 20
long:
- action: output
boneio_output: out_01
action_output: "OFF"
condition:
type: time
after: "22:00"
before: "06:00"
double_then_long:
- action: virtual_switch
boneio_virtual_switch: away
action_output: TOGGLE
mqtt_sequences:
double_then_long: true
```
Write `"ON"` and `"OFF"` in quotes — YAML would otherwise read them as true and false.
Older configurations may use `pin:` in an action to name the output or cover. Use `boneio_output` / `boneio_cover`; the panel replaces `pin` when you edit such an action.
**Input options**
* **boneio\_input** (*Optional*, string) — the input, `in_01` … `in_52`.
* **pin** (*Optional*, string) — a raw GPIO pin, e.g. `P9_33`. Not needed with `boneio_input`.
* **id** (*Optional*, string) — identifier used in MQTT topics and actions. Defaults to `boneio_input` (or `pin`).
* **name** (*Optional*, string) — display name.
* **area** (*Optional*, string) — ID of an area from the `areas` section.
* **device\_class** (*Optional*, default `button`) — `button`, `doorbell` or `motion`, as shown in Home Assistant.
* **show\_in\_ha** (*Optional*, boolean, default `true`) — publish the input to Home Assistant.
* **inverted** (*Optional*, boolean, default `false`) — invert the input.
* **bounce\_time** (*Optional*, time, default `30ms`)
* **double\_click\_duration** (*Optional*, time, default `220ms`)
* **long\_press\_duration** (*Optional*, time, default `400ms`)
* **sequence\_window\_duration** (*Optional*, time, default `500ms`)
* **sequence\_mode** (*Optional*, default `exclusive`) — `exclusive` or `immediate`.
* **enable\_triple\_click** (*Optional*, boolean, default `false`)
* **long\_press\_mqtt\_mode** (*Optional*, default `single`) — `single` or `periodic`.
* **max\_long\_press\_duration** (*Optional*, time, default `30s`, at most `30s`)
* **mqtt\_sequences** (*Optional*) — `double_then_long`, `single_then_long`, `double_then_single`: `true` to publish that sequence to MQTT. All default to `false`.
* **actions** (*Optional*) — lists of actions under `single`, `double`, `triple`, `long`, `double_then_long`, `single_then_long`, `double_then_single`. See [Actions](#actions).
# Sensor filters (/en/docs/black/current/configuration/filters)
A filter changes a sensor's reading before boneIO Black publishes it: it corrects a sensor that reads half a degree too high, rounds the value, converts it, or throws away a reading that cannot be right.
## Where you set filters [#where-you-set-filters]
Filters are part of a sensor's own form. The **Add Filter** button is in:
| Sensor | Where |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ADC | **Settings** → **Control** → **ADC Sensors**, in the sensor's form, section **Filters** (open by default). See [ADC Sensors](./adc). |
| 1-Wire (DS18B20 and others) | **Settings** → **Control** → **Onewire Sensors**, in the sensor's form, section **Filters** (click it to open). See [1-Wire Sensors](./onewire-sensors). |
| Modbus CWT sensor | **Settings** → **Connections** → **Modbus Devices**, a device with the CWT model, tab **Sensor Filters**: **Temperature Filters** and **Humidity Filters**. See [Modbus Devices](./modbus-devices). |
LM75, MCP9808 and INA219 accept filters too, but only in YAML: their form in **Settings** → **Device** → **Board Sensors** has no filter editor (see [below](#yaml)).
## Adding a filter [#adding-a-filter]
1. Open the sensor in its section and find **Filters**. The badge next to it says how many filters the sensor has.
2. Click **Add Filter**. A new row appears at the end, set to `round` with the value `2`.
3. Pick the filter in the drop-down and type its number in **Value**.
4. Save the sensor (**Add Item** or **Save Changes**), then **Save** at the bottom of the section. No restart is needed.
The bin at the end of a row removes that filter.
## The filters [#the-filters]
The drop-down lists the filters by name:
| Filter | What it does | Example |
| ------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **offset** | Adds the value to the reading. Use a negative value to subtract. | A sensor that shows 0.5 °C too much: `offset` `-0.5`. |
| **round** | Rounds to that many digits after the decimal point. Use a whole number. | `round` `1` turns 21.437 into 21.4. |
| **multiply** | Multiplies the reading by the value. | On an ADC input of a controller from version 1.0, `multiply` `13.8` gives the voltage on the terminal. |
| **filter\_out** | Throws away a reading exactly equal to the value. | A DS18B20 that sometimes reports `85` after a power glitch: `filter_out` `85`. |
| **filter\_out\_greater** | Throws away a reading greater than the value. A reading equal to it is kept. | A temperature that can never exceed 100 °C: `filter_out_greater` `100`. |
| **filter\_out\_lower** | Throws away a reading lower than the value. A reading equal to it is kept. | `filter_out_lower` `-40`. |
When an ADC, 1-Wire, LM75 or MCP9808 reading is thrown away, nothing is published for it: the panel and Home Assistant keep showing the previous value until the next good reading.
## Order matters [#order-matters]
Filters run from the top row down, each on the result of the one before. A thrown-away reading stops there.
* To show Fahrenheit, put `multiply` `1.8` first and `offset` `32` after it. The other way round gives a wrong value.
* `filter_out` compares exactly, so put it after `round` when the reading has decimals.
There is no button to move a row. To change the order, remove the rows and add them again in the order you want.
## When a sensor has no filters [#when-a-sensor-has-no-filters]
Each sensor has a default set: `round` `2` for 1-Wire, LM75, MCP9808 and INA219, and `multiply` `1.8` then `round` `2` for ADC (which turns the input's 0–1 into volts, see [ADC Sensors](./adc)).
A sensor gets the default only when it has no filters at all. Once you add your own, they replace the default, so add `round` yourself if you still want it.
If you remove every filter, the sensor goes back to its default after the next restart of the boneIO app. Until then it reports the unfiltered value; for ADC that is a number from 0 to 1, not volts.
`filters` is a list. Each entry has one key, the filter's name, with its value. They run in the order of the list.
**1-Wire sensor**
```yaml title="Sample configuration"
sensor:
- id: boiler
address: 28-0000098c7df0
filters:
- offset: -0.5
- round: 1
- filter_out: 85
```
**ADC input**
```yaml title="Sample configuration"
adc:
- id: tank_level
pin: P9_33
filters:
- multiply: 1.8
- round: 2
```
**LM75 (YAML only)**
```yaml title="Sample configuration"
lm75:
- id: controller_temp
address: 0x48
filters:
- offset: -1.5
- round: 1
```
**Modbus CWT sensor**
```yaml title="Sample configuration"
modbus_devices:
- id: soil
model: cwt
address: 1
update_interval: 30s
sensors_filters:
temperature:
- offset: -0.3
humidity:
- round: 0
```
| Filter | Value | Description |
| ------------------------ | ------------ | --------------------------------------- |
| **offset** | number | Adds the value to the reading. |
| **round** | whole number | Rounds to that many decimal places. |
| **multiply** | number | Multiplies the reading by the value. |
| **filter\_out** | number | Drops a reading equal to the value. |
| **filter\_out\_greater** | number | Drops a reading greater than the value. |
| **filter\_out\_lower** | number | Drops a reading lower than the value. |
Where `filters` can be used: `sensor` (1-Wire), `adc`, `lm75`, `mcp9808`, each sensor of `ina219`, and `sensors_filters.temperature` / `sensors_filters.humidity` of a `cwt` Modbus device.
Default when `filters` is missing: `- round: 2`; for `adc`: `- multiply: 1.8` and `- round: 2`.
# Gate Cover (/en/docs/black/current/configuration/gate)
The **Gate Cover** template controls a gate that has its own drive controller — a sliding or swing driveway gate, a garage door, a barrier, an electric strike on a wicket. boneIO does not power the motor; it gives the drive's control input a short **pulse** from a relay, the same way a push-button or a remote would. Contact sensors (limit switches, reed contacts) tell it where the gate really is.
In Home Assistant the gate is a **cover** entity with Open, Close and Stop; on the controller it has a tile on the **Templates** page.
## Choosing the control mode [#choosing-the-control-mode]
Look at how your gate drive is wired — its manual will say which inputs it has.
| Control Mode | For drives with | What boneIO does |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cyclic (single button)** | One "step" input: each press does open → stop → close → stop. The most common for driveway and garage gates. | Pulses one relay. It keeps track of what the next pulse will do: pressing Close while the gate is opening first stops it, and the next pulse closes. |
| **Separate buttons** | Separate open, close and (optionally) stop inputs. | Pulses the open, close or stop relay. |
| **Open only (electric lock)** | An electric strike or a gate that closes by itself. | Each Open pulses the relay. **Close** and **Stop** are ignored. |
## Setting one up [#setting-one-up]
1. Wire the relay output(s) to the drive's control input(s), and the contact sensors to controller inputs configured as binary sensors
2. Open **Settings** → **Control** → **Templates**, click **Add New** and choose **Gate Cover**
3. Fill in **Name**, **Entity ID** (optional — made from the name) and **Area / Room**
4. Choose the **Device Class in Home Assistant**: **Gate**, **Garage Door**, **Barrier** or **Door / Wicket**. It only changes the icon and wording in Home Assistant
5. Choose the **Control Mode**
6. Under **Outputs** pick the relays:
* **Pulse Output** for Cyclic and Open only,
* **Open Output**, **Close Output** and optionally **Stop Output** for Separate buttons
7. Set the **Pulse Duration** — how long the relay stays on per press. 500ms by default; use what your drive's manual asks for
8. Under **Contact Sensors** pick the **Closed Sensor** and, if you have one, the **Open Sensor** (or **None**)
9. Save
Use a relay output that is not driven by anything else — no button action, no schedule, no group. The template turns it on for the pulse and off again; anything else switching the same relay moves the gate.
### Open only without a pulse duration [#open-only-without-a-pulse-duration]
In **Open only** mode the **Pulse Duration** can be left empty. The relay then stays on until the **Open Sensor** reports that the door opened, and switches off at that moment — useful for a strike that must be held until the door is pushed.
Leave the pulse duration empty only when an **Open Sensor** is set. Without one nothing switches the relay off.
## What the controller knows about the position [#what-the-controller-knows-about-the-position]
The state shown on the tile and in Home Assistant depends on the sensors you gave it:
| Sensors | States | How |
| ------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------- |
| **Closed Sensor** and **Open Sensor** | Closed, Opening, Open, Closing | Closed sensor active → Closed. It releases → Opening. Open sensor active → Open. It releases → Closing. |
| **Closed Sensor** only | Closed, Open | Closed sensor active → Closed, released → Open. It cannot tell a moving gate from one standing half-open. |
| None | Closed, Open | Guessed from the last command. After a restart the gate is assumed Closed. |
A sensor counts as **active** when its contact is closed — the closed sensor when the gate is fully closed, the open sensor when it is fully open. A sensor always overrides what the controller guessed from a command.
With sensors, a restart reads their current state without sending anything — a controller restart never pulses the gate.
Without any sensor, the state is only a guess. If someone opens the gate with its own remote, the tile and Home Assistant still say Closed. Fit at least a closed sensor if automations depend on the gate's state.
## Using it [#using-it]
On the **Templates** page the gate's tile shows **Open**, **Closed**, **Opening** or **Closing** and has the buttons **Open**, **Stop** and **Close** (in Open only mode: **Open** and **Stop**). The button that undoes the current state is highlighted. See [Templates page](/en/docs/black/current/basic/templates).
```yaml title="Cyclic gate with two limit switches"
template:
- id: driveway_gate
name: Driveway Gate
platform: gate_cover
area: garden
device_class: gate
control_mode: cycle
pulse_output: gate_relay
pulse_duration: 500ms
closed_sensor: gate_closed
open_sensor: gate_open
```
```yaml title="Garage door with separate buttons"
template:
- id: garage_door
name: Garage Door
platform: gate_cover
device_class: garage_door
control_mode: separate
open_output: garage_open
close_output: garage_close
stop_output: garage_stop
pulse_duration: 1s
closed_sensor: garage_closed
```
```yaml title="Wicket with an electric strike held until the door opens"
template:
- id: wicket
name: Wicket
platform: gate_cover
device_class: door
control_mode: open_only
pulse_output: wicket_strike
open_sensor: wicket_open
```
* **platform** (**Required**) — `gate_cover`.
* **id**, **name**, **area** — as for every template, see [Templates](/en/docs/black/current/configuration/template).
* **control\_mode** (*Optional*, one of `cycle`, `separate`, `open_only`, default `cycle`).
* **device\_class** (*Optional*, one of `gate`, `garage_door`, `barrier`, `door`, default `gate`) — how Home Assistant shows the cover.
* **pulse\_output** (string) — relay output for `cycle` and `open_only`. Required in those modes.
* **open\_output** (string) — relay output for opening, `separate` mode.
* **close\_output** (string) — relay output for closing, `separate` mode. At least one of `open_output` and `close_output` is required.
* **stop\_output** (*Optional*, string) — relay output for stop, `separate` mode.
* **pulse\_duration** (*Optional*, time period) — how long each pulse lasts, e.g. `500ms`, `1s`. `500ms` when not set, except in `open_only`, where not setting it holds the relay until `open_sensor` becomes active.
* **closed\_sensor** (*Optional*, string) — ID of the binary sensor that is active when the gate is fully closed.
* **open\_sensor** (*Optional*, string) — ID of the binary sensor that is active when the gate is fully open.
A gate whose required output is missing, or points at an output that does not exist, is skipped when the configuration loads; the reason is in the log.
# INA219 / INA226 power monitor (/en/docs/black/current/configuration/ina219)
The power monitor inside the controller measures the controller's own supply: voltage (V), current (A) and power (W). Each of the three appears as a separate sensor in the panel and in Home Assistant.
Which chip your controller has depends on its version:
| Controller version | Power monitor |
| ------------------ | ----------------------------- |
| 0.2, 0.3 | none |
| 0.4 – 0.8 | INA219, at I2C address `0x40` |
| 1.0, 1.1 | INA226, at I2C address `0x40` |
The version is printed on the label on the side of the housing; see [boneIO](./boneio) for what each version contains. Both chips are set up the same way; this page covers both.
A controller set up from the factory configuration already has the right one. You only need this page to rename the measurements, change how often they are read, or add the monitor back after removing it.
## Where it is in the panel [#where-it-is-in-the-panel]
Open **Settings** → **Device** → **Board Sensors**. The list holds all sensors built into the controller: the power monitor and the temperature sensor ([LM75](./lm75) or [MCP9808](./mcp9808)).
The section has the **restart** badge: a change takes effect only after the application restarts.
## Adding or editing the power monitor [#adding-or-editing-the-power-monitor]
1. Open **Settings** → **Device** → **Board Sensors** and click **Add New** (or the edit icon next to the existing entry).
2. Set **Sensor Type** to **INA219** or **INA226**, the one your controller version has (see the table above).
3. Choose the **I2C Address**. `0x40` is the address used in boneIO Black. The magnifier button next to it (**Scan I2C bus**) looks for sensors on the bus and marks the addresses it finds as **detected**.
4. Under **INA Sensors**, rename the three measurements if you like.
5. Set the **Update Interval** if 60 s does not suit you.
6. Click **Add Item** (**Save Changes** when editing), then **Save**.
7. The panel shows **App restart required**. Click **Restart Now**.
| Field | What it does |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sensor Type** | **INA219** or **INA226**. It cannot be changed on an existing entry: to change the type, delete the entry and add a new one. |
| **Name / ID** | Optional. Put in front of each measurement's ID in MQTT: `Main` gives `MainBoardCurrent`, `MainBoardPower` and `MainBoardVoltage`. The names shown in Home Assistant do not change. |
| **I2C Address** | `0x40` (default), `0x41`, `0x44` or `0x45`. An address can be used by only one sensor in this list, of any type; the panel marks taken addresses **in use**. |
| **Update Interval** | How often the values are read: from 15 s to 5 min. On a new entry the field shows 0; left like that, the default 60 s is used. |
| **INA Sensors** | The three measurements: current, power and voltage, named `Board Current`, `Board Power` and `Board Voltage` by default. You can rename them, but not remove or add any. |
The values are rounded to 2 decimals. Other filters can be set only in YAML (see below).
The **Power (INA)** screen of the [OLED display](./oled) shows the same values, and has nothing to show until the power monitor is set up here.
Changing **Name / ID** or a name under **INA Sensors** changes the measurement's ID, so Home Assistant sees a new entity: dashboards, automations and history that use the old one have to be pointed at the new one.
Both chips sit at the same address, so a scan cannot tell them apart: pick the type from your controller version. If the chip does not answer at the chosen address, the controller does not create it and the panel lists it in **Settings** → **Maintenance** → **Hardware errors**.
Controllers 0.4 – 0.8 use the `ina219:` section, controllers 1.0 and 1.1 the `ina226:` section. Both take the same options.
**Minimal configuration (as in the factory configuration)**
```yaml title="Sample configuration"
ina226:
- address: 0x40
```
**With your own names and filters**
```yaml title="Sample configuration"
ina219:
- address: 0x40
update_interval: 30s
sensors:
- id: Board Current
device_class: current
filters:
- round: 3
- id: Board Power
device_class: power
filters:
- round: 1
- id: Board Voltage
device_class: voltage
filters:
- round: 2
```
| Option | Required | Type | Default | Description |
| ---------------------------- | ------------------- | ----------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **address** | **yes** | integer or string | `0x40` | I2C address of the chip. |
| **id** | no | string | the address as a decimal number | Put in front of each measurement's ID in MQTT (spaces removed). Without it the address is used, so `0x40` gives `64BoardCurrent`. |
| **update\_interval** | no | time period | `60s` | How often the values are read. The panel offers 15 s to 5 min; YAML takes any period. |
| **sensors** | no | list | `Board Current`, `Board Power`, `Board Voltage` | Which measurements to publish. Leaving one out means it is not published. If you list `sensors`, give each entry both `id` and `device_class`. |
| **sensors\[].id** | **yes** in practice | string | none | Name of the measurement in the panel and Home Assistant. |
| **sensors\[].device\_class** | **yes** in practice | string | none | `current` (A), `power` (W) or `voltage` (V). Each at most once. |
| **sensors\[].filters** | no | list | `- round: 2` | Filters for this measurement: `offset`, `round`, `multiply`, `filter_out`, `filter_out_greater`, `filter_out_lower`. See [Filters](./filters). |
# Configuration (/en/docs/black/current/configuration)
You configure boneIO Black in its web panel, at `https://:8443`. Everything is under **Settings**,
arranged in groups: **Device**, **Control**, **Connections**, **Services on this controller**, **Access**, **Maintenance** and **Advanced**.
The pages below follow the same order.
Most changes apply as soon as you click **Save**. Sections marked **restart** (boneIO, Board Sensors, MQTT, Loxone (UDP), Modbus, CAN Bus, Web Server, MCP23017)
only take effect after the application restarts: the panel then shows **App restart required** with a **Restart Now** button.
Each page ends with the matching YAML, for anyone editing the configuration by hand in **Settings** → **Advanced** → **YAML editor**.
## Device [#device]
Rooms and areas that organise your devices in Home Assistant
Where the controller stands, for sun-based features
Which screens the display shows, and when it goes dark
Name, hardware version, device type and serial number
Temperature inside the controller, from version 0.4
Temperature inside 0.2 and 0.3 controllers
Voltage, current and power of the controller itself
## Control [#control]
Wall switches, buttons and sensors wired to the inputs
Single, double and long press
Simple on/off inputs such as door or motion sensors
Relays for lights, sockets and other loads
Several outputs switched as one
Roller blinds and venetian blinds
DS18B20 temperature sensors
Analog sensors on the analog inputs
Energy and water use worked out from output run time
Thermostats, alarm panels and other combined entities
Watering zones and their schedule
Modes such as Away or Evening
Actions at a set time or with the sun
Make an empty house look lived in
## Connections [#connections]
Energy meters, sensors and other RS485 devices
Other boneIO controllers, ESPHome devices and WLED
Inputs of remote devices, used in actions
Switches and lights of remote devices
MQTT, Home Assistant and Lox UDP
Port, speed and timing of the Modbus bus
Speed, node ID and master/slave mode of the CAN bus
## Access [#access]
How the panel is reached on the network
## Maintenance [#maintenance]
Updates, backups, restart and factory reset: where the former System tab went
## Advanced [#advanced]
How much the controller writes to its log
I2C addresses of the output expanders
# Local Inputs (/en/docs/black/current/configuration/inputs_local)
**Local Inputs** are the physical inputs of this controller. Each input you use is set up as one of two types:
| Type | For | Actions on |
| ----------------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **[Events](/en/docs/black/current/configuration/event)** | push buttons | single, double, triple and long press, and three click sequences |
| **[Binary Sensors](/en/docs/black/current/configuration/binary)** | motion sensors, reed switches, flood sensors — anything with two states | pressed (active) and released (inactive) |
Both types can run the same [actions](/en/docs/black/current/configuration/event#actions) — switch an output, move a cover, set a virtual switch, send MQTT, control another device.
Inputs of other devices (an ESPHome board, another boneIO) are set up separately, under [Remote Inputs](/en/docs/black/current/configuration/inputs_remote).
## Where [#where]
Open **Settings** → **Control** → **Local Inputs**. The list shows events and binary sensors together. Click **Add New** to add an input, or the edit icon to change one.
At the top of the form, **Type** chooses **Events** or **Binary Sensors**; the rest of the form follows that choice.
## Changing the type [#changing-the-type]
You can switch an existing input from one type to the other. The panel converts what it can and asks before it goes ahead:
* **Events → Binary Sensors**: single-click actions become **Pressed** actions. Double, triple, long and sequence actions are removed.
* **Binary Sensors → Events**: **Pressed** actions become single-click actions. **Released** actions are removed.
The confirmation window (**Switch Input Type**) lists the actions that will be removed. Settings that only one type has — for example **Device Class** of a binary sensor, or the click timings of an event — are dropped too.
Changing the type changes the entity in Home Assistant: an event entity becomes a binary sensor or the other way round. Automations in Home Assistant that used the old entity have to be updated.
In the configuration file the two types are two sections, `event:` and `binary_sensor:`. Use each input in only one of them.
```yaml title="One button and one reed switch"
event:
- boneio_input: in_04
name: Living room button
actions:
single:
- action: output
boneio_output: out_01
action_output: TOGGLE
binary_sensor:
- boneio_input: in_06
name: Front door
device_class: door
initial_send: true
```
All options are on the [Events](/en/docs/black/current/configuration/event#yaml) and [Binary Sensors](/en/docs/black/current/configuration/binary#yaml) pages.
# Remote Inputs (/en/docs/black/current/configuration/inputs_remote)
A **remote input** follows an input of another device and treats it like one of this controller's own inputs: it runs [actions](/en/docs/black/current/configuration/event#actions), can appear in Home Assistant, and can be used in a condition.
Typical uses:
* a button on another boneIO switches a relay on this one, with only the MQTT broker in between,
* a door sensor on an ESPHome board closes a cover on this controller.
The other device must first be added under [Remote Devices](/en/docs/black/current/configuration/remote-devices).
## Adding a remote input [#adding-a-remote-input]
1. Open **Settings** → **Connections** → **Remote Inputs**
2. Click **Add New**
3. At the top set **Type**: **Binary Sensors** (pressed / released) or **Events** (single, double, long … clicks)
4. Fill in the form and save
{/* SCREENSHOT: en_remote_input_form.webp — Settings → Connections → Remote Inputs, form with Device and Input/Sensor ID filled in */}
### Basic Settings [#basic-settings]
| Field | What it does |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Display Name** | Name shown in the panel and Home Assistant. Optional. |
| **Custom Input ID** | Optional. If left empty, the ID is made from the device and the input, e.g. `garage_esp_door`. |
| **Device** | The remote device. The panel sets the protocol from it. |
| **Input/Sensor ID** | The input on that device. For ESPHome it is picked from the sensors the device reported; for MQTT it is typed in, e.g. `in_04`. |
| **MQTT topic** | MQTT devices only. Leave it empty for another boneIO — the default is the topic it publishes its own inputs on. Fill it in for anything else. |
| **Area / Room** | Area in Home Assistant. |
| **Device Class** | How Home Assistant shows it, e.g. `door`, `motion`, `window`. |
Under **Options**:
| Option | Default | What it does |
| ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| **Forward to Home Assistant** | off | Publishes the input to Home Assistant. Leave it off if the other device already shows up in Home Assistant by itself. |
| **Inverted** | off | Swaps the two states. |
If the device you want is not in the **Device** list, add the input in the YAML editor (see below).
### Actions [#actions]
With **Binary Sensors** the form has **Pressed Actions** and **Released Actions**; with **Events** it has the click tabs **Single**, **Double**, **Triple**, **Long** and **Sequences**, as for a local [event](/en/docs/black/current/configuration/event).
The actions are the same as for local inputs, see [Actions](/en/docs/black/current/configuration/event#actions).
In **Advanced Settings** of an event-type remote input, these settings take effect: **Double Click Duration**, **Long Press Duration**, **Sequence Mode**, **Enable Triple Click** and **Long Press MQTT Mode**.
## Mirroring another boneIO [#mirroring-another-boneio]
Add the other boneIO under Remote Devices with the MQTT protocol, then add a remote input with its input ID. No topic is needed: by default the input listens where a boneIO publishes its own inputs, `/input/` — the device ID is the other controller's topic prefix (its serial).
With **Events** the click the other boneIO has already recognised (single, double, long …) is passed through as it is.
## Other MQTT devices [#other-mqtt-devices]
For anything that is not a boneIO, fill in the **MQTT topic**. These messages are understood (upper or lower case):
| On | Off |
| --------------------------------------------------------- | ---------------------------------------------------------------- |
| `on`, `true`, `1`, `pressed`, `open`, `opening`, `active` | `off`, `false`, `0`, `released`, `closed`, `closing`, `inactive` |
Any other message is written to the log and ignored — the state stays as it was.
A remote input only **follows** a state that exists on another device; nothing can set it from this controller or from Home Assistant.
For a mode that the controller itself should keep — *Evening*, *Away* — use a [virtual switch](/en/docs/black/current/configuration/virtual_switch).
```yaml title="A button on another boneIO toggles a local relay"
remote_devices:
- id: blk8c7df0 # the other boneIO's topic prefix (its serial)
name: Garage boneIO
protocol: mqtt
remote_inputs:
- id: garage_button
name: Garage button
remote_source: mqtt
device_id: blk8c7df0
input_id: in_04
mode: event
actions:
single:
- action: output
boneio_output: out_02
action_output: TOGGLE
```
```yaml title="A door sensor published on a topic"
remote_inputs:
- id: front_door
remote_source: mqtt
device_id: esp_hall
input_id: door
topic: esphome/hall/binary_sensor/door/state
device_class: door
show_in_ha: true
```
**Options**
* **remote\_source** (**Required**) — how the state arrives:
* `esphome_api` — an ESPHome device over its native API,
* `mqtt` — a topic on the MQTT broker,
* `can` — not implemented yet: the controller still starts, but the input is refused with an error in the log.
* **device\_id** (**Required**, string) — ID of the device in the `remote_devices` section.
* **input\_id** (**Required**, string) — the input or sensor on that device, e.g. `in_02`.
* **id** (*Optional*, string) — own ID. Default: `device_id` and `input_id` joined, e.g. `blk8c7df0_in_04`.
* **name** (*Optional*, string) — display name.
* **topic** (*Optional*, string, `mqtt` only) — default `/input/`.
* **mode** (*Optional*, default `binary_sensor`) — `binary_sensor` (pressed / released) or `event` (clicks).
* **device\_class** (*Optional*, string) — e.g. `door`, `motion`, `window`, `opening`.
* **area** (*Optional*, string) — area in Home Assistant.
* **show\_in\_ha** (*Optional*, boolean, default `false`) — publish to Home Assistant.
* **inverted** (*Optional*, boolean, default `false`)
* **double\_click\_duration** (*Optional*, milliseconds, default 220) — `event` mode.
* **long\_press\_duration** (*Optional*, milliseconds, default 400) — `event` mode.
* **sequence\_mode** (*Optional*, default `exclusive`) — `exclusive` or `immediate`, `event` mode.
* **long\_press\_mqtt\_mode** (*Optional*, default `single`) — `single` or `periodic`, `event` mode.
* **enable\_triple\_click** (*Optional*, boolean, default `false`) — `event` mode.
* **actions** (*Optional*) — `pressed` / `released` in `binary_sensor` mode; click types (`single`, `double`, `long` …) in `event` mode. See [Actions](/en/docs/black/current/configuration/event#actions).
# Irrigation (/en/docs/black/current/configuration/irrigation)
The **Irrigation** template waters a garden zone by zone. Each zone is one valve on one controller output; the controller opens them one after another for the time you set, switches on the water supply — a main valve, a pump — while they run, and starts the whole cycle on its own at the times you schedule.
It runs on the controller itself, so the garden is watered on time without Home Assistant or the network.
## The parts [#the-parts]
* **Controller** — one irrigation template: its zones, its water sources and its schedules. Most gardens need one.
* **Zones** — each zone opens one valve for its **Run Duration**. Zones run in the order of the list, never two at once (except for the short **Valve Overlap**, if you set one).
* **Water sources** — what has to be on for water to flow: a main valve, a pump, or both. A source can switch several outputs one after another. If you have more than one — mains water and a rainwater tank — you choose which one is used on the Irrigation tile or in Home Assistant; only one is used at a time.
* **Schedules** — a time and days (daily, weekdays, weekend or one day of the week). At that time the controller starts a full cycle. The time is the controller's local time.
A zone can also run only every *N*th cycle (**Run Every**), so the drip line under the hedge gets water every third time while the lawn gets it every time.
## Setting one up [#setting-one-up]
First make the valve outputs: in **Settings** → **Control** → **Local Outputs** set the type of each zone valve's output to **Valve**. Only outputs of that type can be picked as a zone valve. Pumps and main valves can be any type except light or cover.
1. Open **Settings** → **Control** → **Templates**, click **Add New** and choose **Irrigation**
2. Fill in **Name**, **Entity ID** (optional — made from the name) and **Area / Room**
3. Under **Water Sources**, click **Add Water Source** for each supply and pick its **Outputs (valves/pumps)**. Skip this if the zone valves alone are enough
4. Under **Zones**, click **Add Zone** for each valve: **Zone Name**, **Valve Output**, **Run Duration**, **Run Every**. The arrows (**Move up** / **Move down**) set the order
5. Under **Schedules**, click **Add Schedule** and set the time and the days
6. Save
### Zones [#zones]
| Field | What it does |
| ---------------- | -------------------------------------------------------------------------------- |
| **Zone Name** | Shown on the tile and in Home Assistant. |
| **Entity ID** | Made from the name if left empty. |
| **Valve Output** | The output that opens this zone's valve. Required. |
| **Run Duration** | How long the zone runs in one cycle, e.g. `10min`. At least one minute. |
| **Run Every** | Run the zone every *N*th cycle: 1 = every time, 2 = every other time, and so on. |
| **Zone enabled** | A disabled zone is skipped. |
### Water sources [#water-sources]
| Field | What it does |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Source Name** | E.g. *City Water*, *Rainwater tank*. |
| **Outputs (valves/pumps)** | The outputs switched on when this source is used. At least one. |
| **Sequential Output Delay** → **Delay between ON** / **Delay between OFF** | With several outputs, they switch on one by one with this pause between them, and off in reverse order. Useful to open the main valve before the pump starts. |
| **Pump Delays** | The order of source and zone valve at the start and end — see below. |
| **Turn off pump during valve delay** | Switches the source off during the **Valve Open Delay** between two zones. |
**Pump Delays** — set at most one of each pair:
| Field | Start / end of a zone |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pump Start (pump delay)** | The zone valve opens first, the source switches on after this delay. |
| **Pump Start (valve delay)** | The source switches on first, the zone valve opens after this delay. |
| **Pump Stop (pump delay)** | The zone valve closes first, the source switches off after this delay. Protects a pump from running against a closed valve for long. |
| **Pump Stop (valve delay)** | Meant for the opposite order. In 1.6 the zone valve is always closed before the source is switched off, so this only adds a wait after the source is off. |
### Advanced Pump/Valve Timing [#advanced-pumpvalve-timing]
| Field | What it does |
| -------------------- | ----------------------------------------------------------------------------------------------------- |
| **Valve Open Delay** | A pause between one zone's valve closing and the next one opening. Prevents pressure drops. |
| **Valve Overlap** | The next valve opens this long before the current one closes. Prevents water hammer. Do not set both. |
| **Pause Timeout** | A paused cycle is stopped after this long. Default 30min; `0` keeps it paused indefinitely. |
If an output of the water source or a zone valve cannot be switched on because an [interlock](/en/docs/black/current/configuration/outputs_local) blocks it, the controller stops the cycle, switches off what it had turned on, and reports it (an event in Home Assistant).
## Using it [#using-it]
The controller has a tile on the **Templates** page (see [Templates page](/en/docs/black/current/basic/templates)). It shows the state — **Idle**, **Running** or **Paused** — the time left in the current zone, the **Next Run**, and each zone with its duration and how often it runs.
* **Start cycle** runs the whole list; **Pause**, **Resume**, **Skip to next zone** and **Stop** control a running cycle.
* **Start this zone only** runs one zone and stops.
* Clicking a zone's duration or frequency changes it; the zone's switch enables or disables it.
* **Schedules and settings** opens a window with the schedules (each can **Skip** its next run), **Skip next scheduled run**, and the settings below.
Settings on the tile (also in Home Assistant):
| Setting | What it does |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Duration multiplier** | Scales every zone's time: 1.0 = as set, 0.5 = half, 2.0 = double. Handy in a heat wave. |
| **Repeat Cycle** | 0 = run the list once, 1 = twice, and so on. |
| **Auto-advance zones** | On: after one zone the next starts. Off: the cycle stops after the first zone. |
| **Reverse zone order** | Runs the list from the bottom up. |
| **Standby** | Nothing starts — neither the schedule nor **Start cycle** or **Start this zone only** — until it is turned off again. The tile says so. |
| **Water Source** | With more than one source, which one is used. |
What you change on the tile or in Home Assistant is remembered and **wins over the configuration**: a zone's duration, frequency and on/off state, the multiplier, repeat, auto-advance, reverse, standby and the chosen water source. Changing the same value in the form later has no effect on a controller that has already had it set on the tile — change it on the tile.
A few things to know:
* **Start cycle** counts as a cycle for **Run Every**, just like a scheduled run. **Start this zone only** does not.
* With **Skip next scheduled run** on, the next full cycle is skipped — also one started with **Start cycle**.
* The schedule starts a cycle even if one is already running: the running cycle is stopped first.
## In Home Assistant [#in-home-assistant]
Each controller is one device with these entities:
| Entity | What it is |
| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| switch (controller name) | Starts and stops a full cycle. |
| switches **Skip Next Run**, **Standby** | As on the tile. |
| switches **Auto Advance**, **Reverse** | Only with more than one zone. |
| numbers **Multiplier** (0.1–5.0), **Repeat** (0–10) | As on the tile. |
| buttons **Pause**, **Resume**, **Next Valve** | **Next Valve** only with more than one zone. |
| sensors **Zone End Time**, **Next Run** | When the running zone ends and when the next scheduled run starts. |
| select (water source) | Only with more than one water source. |
| event | Reports a finished cycle, a start blocked by standby, and an interlock fault. |
| per zone: a **valve**, a switch **… Enabled**, a number **… Duration** (minutes) | Open or close one zone, enable it, change its time. |
| per schedule: a switch **Schedule N Skip** | Skip that schedule's next run. |
From the list in **Settings** → **Control** → **Templates**, the irrigation row has a button that copies a ready Home Assistant dashboard for this controller (Sections layout) to the clipboard.
```yaml title="Two zones from mains water, daily at 6:00"
template:
- id: garden
name: Garden
platform: irrigation
area: garden
water_sources:
- id: mains
name: Mains water
outputs: [main_valve]
zones:
- id: lawn
name: Lawn
valve_id: valve_lawn
run_duration: 15min
- id: flower_bed
name: Flower bed
valve_id: valve_flowers
run_duration: 5min
schedule:
- time: "06:00"
days: daily
```
```yaml title="Pump and main valve, two sources, drip every third cycle"
template:
- id: garden_pro
name: Garden
platform: irrigation
valve_open_delay: 3s
pause_timeout: 45min
water_sources:
- id: well
name: Well pump
outputs: [well_main_valve, well_pump]
output_start_delay: 2s
output_stop_delay: 2s
pump_start_valve_delay: 3s
pump_stop_pump_delay: 5s
pump_switch_off_during_valve_open_delay: true
- id: rain
name: Rainwater tank
outputs: [tank_pump]
zones:
- id: front_lawn
name: Front lawn
valve_id: valve_front
run_duration: 15min
- id: back_lawn
name: Back lawn
valve_id: valve_back
run_duration: 10min
- id: drip
name: Hedge drip line
valve_id: valve_drip
run_duration: 30min
run_every_n: 3
schedule:
- time: "05:30"
days: weekdays
- time: "07:00"
days: weekend
```
* **platform** (**Required**) — `irrigation`.
* **id**, **name**, **area** — as for every template, see [Templates](/en/docs/black/current/configuration/template).
* **zones** (list) — at least one zone with a valve; a controller without one is skipped.
* **id** (string) — zone identifier. The controller skips a zone without one; the panel makes it from the name.
* **name** (*Optional*, string) — zone name.
* **valve\_id** (string) — ID of the valve output. Required in practice: a zone without it is skipped.
* **run\_duration** (*Optional*, time period) — e.g. `10min`, `300s`. `1min` when not set; shorter values are raised to one minute.
* **enabled** (*Optional*, boolean, default `true`).
* **run\_every\_n** (*Optional*, integer ≥ 1, default `1`) — run the zone every Nth cycle.
* **water\_sources** (*Optional*, list):
* **id** (string) — source identifier; a source without one is skipped.
* **name** (*Optional*, string).
* **outputs** (**Required**, list of output IDs) — switched on in order, off in reverse.
* **output\_start\_delay** (*Optional*, time period) — pause between switching each output on.
* **output\_stop\_delay** (*Optional*, time period) — pause between switching each output off.
* **pump\_start\_pump\_delay** (*Optional*, time period) — valve first, source after this delay.
* **pump\_start\_valve\_delay** (*Optional*, time period) — source first, valve after this delay.
* **pump\_stop\_pump\_delay** (*Optional*, time period) — valve closes, source off after this delay.
* **pump\_stop\_valve\_delay** (*Optional*, time period) — see the note under **Pump Delays** above.
* **pump\_switch\_off\_during\_valve\_open\_delay** (*Optional*, boolean, default `false`) — source off during `valve_open_delay`.
* **schedule** (*Optional*, list):
* **time** (**Required**, string) — `"HH:MM"`, local time. Put it in quotes.
* **days** (*Optional*, one of `daily`, `weekdays`, `weekend`, `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`, default `daily`).
* **valve\_open\_delay** (*Optional*, time period) — pause between zones. Not together with `valve_overlap`.
* **valve\_overlap** (*Optional*, time period) — both valves open for this long at a zone change.
* **pause\_timeout** (*Optional*, time period) — stop a paused cycle after this long. `30min` when not set; `0` to never stop.
* **multiplier** (*Optional*, float, default `1.0`), **repeat** (*Optional*, integer, default `0`), **auto\_advance** (*Optional*, boolean, default `true`), **reverse** (*Optional*, boolean, default `false`), **standby** (*Optional*, boolean, default `false`) — starting values of the tile settings. Once changed on the tile or in Home Assistant, the remembered value is used instead.
Configurations from before irrigation became a template may have a separate top-level `irrigation:` section. Version 1.6 still loads it and shows the controller on the Templates page, but the panel's form edits only irrigation under `template:`. Moving it there — the same fields plus `platform: irrigation` — makes it editable in the panel.
# LM75 temperature sensor (/en/docs/black/current/configuration/lm75)
The LM75 is the temperature sensor inside the controller. It reports the temperature of the controller itself, not of the room, so it is useful for spotting a cabinet that runs hot.
Every boneIO Black controller from version 0.4 has one, at I2C address `0x48`. Versions 0.2 and 0.3 have an [MCP9808](./mcp9808) instead.
Which version you have is printed on the label on the side of the housing; see [boneIO](./boneio) for what each version contains.
A controller set up from the factory configuration already has this sensor, named `Board temperature`. You only need this page to rename it, change how often it is read, or add it back after removing it.
## Where it is in the panel [#where-it-is-in-the-panel]
Open **Settings** → **Device** → **Board Sensors**. The list holds all sensors built into the controller: temperature (LM75, MCP9808) and the power monitor ([INA219 / INA226](./ina219)).
The section has the **restart** badge: a change takes effect only after the application restarts.
## Adding or editing the sensor [#adding-or-editing-the-sensor]
1. Open **Settings** → **Device** → **Board Sensors** and click **Add New** (or the edit icon next to the existing sensor).
2. Set **Sensor Type** to **LM75 / PCT2075**.
3. Fill in **Name / ID**, for example `Board temperature`.
4. Choose the **I2C Address**. `0x48` is the address used in boneIO Black. The magnifier button next to it (**Scan I2C bus**) looks for sensors on the bus and marks the addresses it finds as **detected**.
5. Set the **Update Interval** if 60 s does not suit you.
6. Click **Add Item** (**Save Changes** when editing), then **Save**.
7. The panel shows **App restart required**. Click **Restart Now**.
| Field | What it does |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sensor Type** | **LM75 / PCT2075** for this sensor. It cannot be changed on an existing entry: to change the type, delete the entry and add a new one. |
| **Name / ID** | Name of the sensor in the panel and Home Assistant. Required. Spaces are removed for the MQTT ID, so `Board temperature` becomes `Boardtemperature`. |
| **I2C Address** | `0x48` (default) to `0x4F`. An address can be used by only one sensor in this list, of any type; the panel marks taken addresses **in use**. |
| **Update Interval** | How often the temperature is read: from 15 s to 5 min. On a new entry the field shows 0; left like that, the default 60 s is used. |
The reading is rounded to 2 decimals. Other filters, such as an offset, and the unit can be set only in YAML (see below).
The temperature also appears on the **Uptime** screen of the [OLED display](./oled).
Renaming the sensor changes its ID, so Home Assistant sees a new entity: dashboards, automations and history that use the old one have to be pointed at the new one.
If the sensor does not answer at the chosen address, the controller does not create it and the panel lists it in **Settings** → **Maintenance** → **Hardware errors**. Use **Scan I2C bus** to see which address it really has.
**Sample configuration**
```yaml title="Sample configuration"
lm75:
- id: Board temperature
address: 0x48
update_interval: 60s
filters:
- round: 2
```
| Option | Required | Type | Default | Description |
| ------------------------- | ------------------- | ----------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id** | **yes** in practice | string | none | Name of the sensor in the panel and Home Assistant; spaces are removed for the MQTT ID. An entry without `id` is skipped and no sensor is created. |
| **address** | **yes** | integer | `0x48` | I2C address of the sensor. |
| **update\_interval** | no | time period | `60s` | How often the sensor is read. The panel offers 15 s to 5 min; YAML takes any period. |
| **filters** | no | list | `- round: 2` | Filters applied to the reading, in order: `offset`, `round`, `multiply`, `filter_out`, `filter_out_greater`, `filter_out_lower`. See [Filters](./filters). |
| **unit\_of\_measurement** | no | string | `°C` | `°C` or `°F`. Only the label changes: the value is not converted. To show Fahrenheit, convert it yourself with `multiply` and `offset` filters. |
# Location (/en/docs/black/current/configuration/location)
Since version 1.6 the controller can act on the sun — close the covers at sunset, turn on a light at dusk.
For that it has to know **where it is**. You set that once, in **Settings → Device → Location**.
Nothing sun-related works without a location: sun options in schedules and conditions are greyed out with the note **needs a location**.
## Setting the location [#setting-the-location]
1. Open **Settings** → **Device** → **Location**
2. Fill in **Latitude** and **Longitude** — either
* click **Fill from timezone** to use your timezone's capital city (usually within a quarter of an hour of sunrise; for less common zones the fields stay empty), or
* type the coordinates of your house (for example copied from a map app on your phone), or
* pick the point on the map, if the map is switched on (see below)
3. Optionally fill in **Elevation (m)** above sea level
4. Click **Save location**
The change applies immediately, without a restart. Below the form the page shows **Sun times for today** and the current position
of the sun — a quick way to check that you did not swap latitude and longitude.
Four decimal places (about 11 m) are more than enough. The coordinates are stored in the configuration and in configuration backups.
## Picking the location on a map [#picking-the-location-on-a-map]
The page can show an OpenStreetMap map — you drag it until the marker is over your house; the coordinates follow the marker (or click **Use map centre**).
The map is **off by default**, because it lets the panel load map images from the internet. To switch it on, open **Settings → Access → Web Server**, turn on **Show a map on the Location page**,
save and **restart boneIO** (in YAML it is `web.security.map_tiles: true`) — until the restart the map shows but its images do not load. Then pick the point and click **Save location**.
The map images are downloaded by **your browser**, not by the controller, so this works even when the controller itself has no internet.
OpenStreetMap sees which area you are looking at.
## The clock must be right [#the-clock-must-be-right]
The controller has no battery-backed clock. After a power cut it does not know the time until it reaches a time server (NTP) on the internet.
Until then the page says **The device clock has not been set yet** and sun-based schedules wait.
If your controller has no internet access, point it at a time server in your own network: **Settings → Device → Time zone** → **NTP servers** → **Custom servers**, type for example your router's address (`192.168.1.1`) and click **Save NTP servers**.
## In Home Assistant [#in-home-assistant]
With a location set, the controller publishes a few sun entities: sun elevation and azimuth, the phase of the day
(day, twilight, night), whether the sun is above the horizon, and the next sunrise and sunset.
```yaml title="Sample configuration"
location:
latitude: 52.2297 # -90 … 90
longitude: 21.0122 # -180 … 180
elevation: 110 # metres above sea level, optional
```
The time zone is not set here — it comes from **Settings → Device → Time zone**.
# Logger (/en/docs/black/current/configuration/logger)
The Logger decides how much boneIO Black writes to its log, which you read in [Diagnostics](/en/docs/black/current/basic/logs). The default level is `INFO`: normal operation, warnings and errors. Change it when you are chasing a problem that the log does not explain, or when one part of the controller writes more than you want to read.
Open **Settings** → **Advanced** → **Logger**. Changes apply without a restart.
## The fields [#the-fields]
| Field | What it does |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Default Log Level** | The level for the whole application: `DEBUG`, `INFO`, `WARNING`, `ERROR` or `CRITICAL`. Each level writes its own messages and everything more serious. `INFO` if not set. |
| **Quick Add Common Modules** | A list of modules with a suggested level. **Add** puts one into the list below; a module already there shows **Added**. |
| **Module-specific Log Levels** | Modules that get their own level, different from the default. Type the module name in the field, for example `boneio.modbus`, and click **Add**. A new module starts at `INFO`; pick its level in the drop-down. The bin (**Remove module**) takes it off the list. |
Click **Save** at the bottom of the section.
A module name covers everything below it: `boneio.modbus` also sets `boneio.modbus.client`. Take the names from the module filter in [Diagnostics](/en/docs/black/current/basic/logs), which lists the modules that actually write to the log.
`DEBUG` writes a great deal: an idle controller logs around twenty MQTT messages a second. Left on, it fills the journal and pushes out the history you will want later. Set it for one module rather than as the default, and set it back when you are done.
Removing a module from the list takes full effect after the next restart of the boneIO app. Until then, that module keeps the level it had.
Adding any `pymodbus` module also shows pymodbus's own messages about Modbus devices that do not answer. boneIO normally hides them, because it reports those devices itself with their address.
## Logger and the capture window [#logger-and-the-capture-window]
For a one-off look, you usually do not need the Logger at all. **Support** → **Open a capture window** in [Diagnostics](/en/docs/black/current/basic/logs#the-capture-window) raises the default level to `DEBUG` for the minutes you choose and then puts it back by itself. The Logger is for what the controller records from now on.
The two work together like this:
* The capture window raises only the default level. A module you gave its own level in **Module-specific Log Levels** keeps it: set to `WARNING`, it stays quiet during the capture too.
* Saving the Logger while a capture window is open puts the default level back to what the Logger says, which ends the extra detail early. Change the Logger before or after a capture, not during it.
```yaml title="Sample configuration"
logger:
default: info
logs:
boneio.modbus: debug
pymodbus.client: warning
```
| Option | Required | Type | Default | Description |
| ----------- | -------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| **default** | no | string | `info` | Level for the whole application: `debug`, `info`, `warning`, `error` or `critical`. Upper case is accepted too. |
| **logs** | no | dictionary | none | Module name as the key, its level as the value. Same levels as `default`. |
**Running boneIO by hand**
When boneIO is started from the command line instead of as the service, `-d` turns on `DEBUG` for boneIO itself and `-dd` also for the MQTT and Modbus libraries:
```bash
boneio run -c config.yaml -d
boneio run -c config.yaml -dd
```
The service does not use these flags.
# MCP23017 expander (/en/docs/black/current/configuration/mcp23017)
The relays of a boneIO Black controller are driven by MCP23017 chips (expanders) on the I2C bus. Each chip has an address, and the controller has to know it, or the outputs on that chip do nothing.
Most owners never open this section: the addresses and the relay logic come from the controller type and version set in [boneIO](./boneio). Change them only if your controller uses different addresses, for example an older controller after an update or a replaced relay board.
## Where it is [#where-it-is]
Open **Settings** → **Advanced** → **MCP23017 (Advanced)**. The entry carries the **restart** badge.
## Changing the addresses [#changing-the-addresses]
1. Check which addresses actually respond: **Diagnostics** → **Buses** → **I2C** scans the bus. Nothing is saved there.
2. Open **Settings** → **Advanced** → **MCP23017 (Advanced)**. There is one card for **mcp\_left** and one for **mcp\_right**.
3. Pick the **I2C Address** of each expander and set **Inverted logic (active-LOW)** if needed.
4. Click **Save**. The panel shows **App restart required**. Click **Restart Now**, or nothing changes.
| Field | What it does |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **I2C Address** | The address of this expander, `0x20` to `0x27`. **mcp\_left** drives OUT\_01–OUT\_16 on 32x10 (OUT\_01–OUT\_12 on 24x16), **mcp\_right** OUT\_17–OUT\_32 on 32x10 (OUT\_13–OUT\_24 on 24x16). |
| **Inverted logic (active-LOW)** | The relays switch on with a LOW signal. On for controllers from version 1.0, off for older ones. If it is not set at all, the controller detects it at startup and remembers it; the card then says what it detected. The **Active-LOW** badge appears while inverted logic is in use. |
Defaults, for comparison: controllers from version 0.8 use `0x23` for **mcp\_left** and `0x24` for **mcp\_right** (48x4: `0x23`, `0x24`, `0x25`). Older controllers mostly use them the other way round from what you might expect: `0x21` for **mcp\_left** and `0x20` for **mcp\_right**. Picking them in the wrong order swaps OUT\_01–OUT\_16 with OUT\_17–OUT\_32, so check against the I2C scan and switch an output to see which relay clicks.
A wrong address means the outputs on that expander stop working. The controller lists the failure in **Settings** → **Maintenance** → **Hardware errors**.
Wrong **Inverted logic** turns the relays the other way round: off shows as on, and every relay may switch on at once.
**48x4 controllers: do not save this section in the panel.** They have a third expander, `mcp_middle`, which the form does not show.
Saving keeps only **mcp\_left** and **mcp\_right**, so the outputs on `mcp_middle` stop working. Edit the addresses in **Settings** → **Advanced** → **YAML editor** instead ([YAML](#yaml) below).
The same applies to any extra MCP23017 you added in YAML yourself.
Once saved, the addresses stay in the configuration as you set them: changing the controller type or version in [boneIO](./boneio) no longer changes them.
To go back to the defaults, delete the whole `mcp23017:` section in **Settings** → **Advanced** → **YAML editor** and restart.
Without an `mcp23017:` section, the addresses come from the controller type and version in `boneio:`. Add the section only to override them; it then replaces the defaults entirely, so list every expander the controller has.
```yaml title="Sample configuration (32x10, version 1.0)"
mcp23017:
- id: mcp_left
address: 0x23
inverted: true
- id: mcp_right
address: 0x24
inverted: true
```
```yaml title="Sample configuration (48x4, version 1.0)"
mcp23017:
- id: mcp_left
address: 0x23
inverted: true
- id: mcp_middle
address: 0x24
inverted: true
- id: mcp_right
address: 0x25
inverted: true
```
| Option | Required | Type | Default | Description |
| --------------- | ---------------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **id** | yes, in practice | string | none | Outputs refer to the expander by this ID (`mcp_id`). With `boneio:`, use `mcp_left`, `mcp_right` and, on 48x4, `mcp_middle`. |
| **address** | **yes** | integer | none | I2C address, as hex (`0x23`) or decimal (`35`). |
| **inverted** | no | boolean | detected | Active-LOW relay board. If left out, detected at startup and remembered. |
| **init\_sleep** | no | time period | `0s` | How long to wait after setting up the expander, for chips that start slowly. |
The panel saves the address as a decimal number, so after a save the YAML editor shows `35` for `0x23`. Saving in the panel also drops `init_sleep`; if you need it, set it in the YAML editor and do not save this section in the panel afterwards.
Changes take effect after an application restart (**Save and Restart** in the YAML editor).
# MCP9808 temperature sensor (/en/docs/black/current/configuration/mcp9808)
The MCP9808 is the temperature sensor inside the earliest boneIO Black controllers, versions 0.2 and 0.3, at I2C address `0x18`. It reports the temperature of the controller itself, not of the room.
Controllers from version 0.4 have an [LM75](./lm75) instead, so if yours is newer, this page is not for you.
Which version you have is printed on the label on the side of the housing; see [boneIO](./boneio) for what each version contains.
When the factory configuration is applied to a 0.2 or 0.3 controller, it already contains this sensor, named `Board temperature`.
## Where it is in the panel [#where-it-is-in-the-panel]
Open **Settings** → **Device** → **Board Sensors**. The list holds all sensors built into the controller.
The section has the **restart** badge: a change takes effect only after the application restarts.
## Adding or editing the sensor [#adding-or-editing-the-sensor]
1. Open **Settings** → **Device** → **Board Sensors** and click **Add New** (or the edit icon next to the existing sensor).
2. Set **Sensor Type** to **MCP9808**.
3. Fill in **Name / ID**, for example `Board temperature`.
4. Choose the **I2C Address**. `0x18` is the address used in boneIO Black. The magnifier button next to it (**Scan I2C bus**) looks for sensors on the bus and marks the addresses it finds as **detected**.
5. Set the **Update Interval** if 60 s does not suit you.
6. Click **Add Item** (**Save Changes** when editing), then **Save**.
7. The panel shows **App restart required**. Click **Restart Now**.
| Field | What it does |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sensor Type** | **MCP9808** for this sensor. It cannot be changed on an existing entry: to change the type, delete the entry and add a new one. |
| **Name / ID** | Name of the sensor in the panel and Home Assistant. Required. Spaces are removed for the MQTT ID, so `Board temperature` becomes `Boardtemperature`. |
| **I2C Address** | `0x18` (default) to `0x1F`. An address can be used by only one sensor in this list, of any type; the panel marks taken addresses **in use**. |
| **Update Interval** | How often the temperature is read: from 15 s to 5 min. On a new entry the field shows 0; left like that, the default 60 s is used. |
The reading is rounded to 2 decimals. Other filters, such as an offset, and the unit can be set only in YAML (see below).
The temperature also appears on the **Uptime** screen of the [OLED display](./oled).
Renaming the sensor changes its ID, so Home Assistant sees a new entity: dashboards, automations and history that use the old one have to be pointed at the new one.
If the sensor does not answer at the chosen address, the controller does not create it and the panel lists it in **Settings** → **Maintenance** → **Hardware errors**. Use **Scan I2C bus** to see which address it really has.
**Sample configuration**
```yaml title="Sample configuration"
mcp9808:
- id: Board temperature
address: 0x18
update_interval: 60s
filters:
- round: 2
- offset: -1.5
```
| Option | Required | Type | Default | Description |
| ------------------------- | ------------------- | ----------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id** | **yes** in practice | string | none | Name of the sensor in the panel and Home Assistant; spaces are removed for the MQTT ID. An entry without `id` is skipped and no sensor is created. |
| **address** | **yes** | integer or string | `0x18` | I2C address of the sensor. |
| **update\_interval** | no | time period | `60s` | How often the sensor is read. The panel offers 15 s to 5 min; YAML takes any period. |
| **filters** | no | list | `- round: 2` | Filters applied to the reading, in order: `offset`, `round`, `multiply`, `filter_out`, `filter_out_greater`, `filter_out_lower`. See [Filters](./filters). |
| **unit\_of\_measurement** | no | string | `°C` | `°C` or `°F`. Only the label changes: the value is not converted. To show Fahrenheit, convert it yourself with `multiply` and `offset` filters. |
# Modbus Devices (/en/docs/black/current/configuration/modbus-devices)
The boneIO Black controller supports the Modbus RTU protocol, which allows you to connect external measurement devices, energy meters, sensors, and other devices.
**Modbus is configured by default** - you don't need to change UART settings. Just add the devices you want to monitor.
## Modbus Devices List [#modbus-devices-list]
Go to **Settings** → **Connections** → **Modbus Devices** to see the list of configured Modbus devices.
## Supported Devices [#supported-devices]
boneIO Black supports the following Modbus device models:
### Energy Meters [#energy-meters]
| Model | Description |
| ----------------------------- | -------------------------------------------------------------- |
| **SDM120** | Eastron SDM120 single-phase energy meter |
| **SDM630** | Eastron SDM630 3-phase energy meter |
| **OR-WE-517** | ORNO OR-WE-517 3-phase energy meter |
| **DTS1964** | DTS1964 3-phase power and energy meter |
| **LE-03MW** | F\&F LE-03MW 3-phase energy meter |
| **LE-03MW CT** | F\&F LE-03MW CT 3-phase energy meter with current transformers |
| **Socomec Countis E03 / E23** | Socomec Countis energy meters |
### Sensors [#sensors]
| Model | Description |
| ----------------------- | ----------------------------------------------------------- |
| **CWT** | CWT soil moisture, temperature and EC sensor (with filters) |
| **SHT20 / SHT30** | Sensirion temperature and humidity sensors |
| **PT100** | PT100 temperature transmitter |
| **boneIO Edge Temp** | boneIO temperature sensor extension board |
| **DYP-A12** | DYP-A12 ultrasonic distance / level sensor |
| **Liquid Level Sensor** | Generic liquid level sensor (with tank dimensions) |
| **QDW90A** | Liquid pressure sensor |
| **GDFS / GDFX** | GD series flow sensors |
### Ventilation, heat recovery and air conditioning [#ventilation-heat-recovery-and-air-conditioning]
| Model | Description |
| ---------------------- | -------------------------------------------- |
| **Defro AIR DRX** | Defro heat recovery ventilation unit |
| **EHT Topventil Plus** | EHT ventilation system |
| **Thessla Green** | Thessla Green heat recovery ventilation unit |
| **Wanas 415** | Wanas heat recovery ventilation unit |
| **Ventclear** | Ventclear ventilation system |
| **Fujitsu AC** | Fujitsu air conditioning interface |
### Other Devices [#other-devices]
| Model | Description |
| ------------------------- | ----------------------------------- |
| **R4DCB08** | 8-channel 1-Wire thermometer module |
| **N4DSC08** | N4DSC08 8-channel relay board |
| **ESP32 Relay x4 Modbus** | boneIO ESP32 4-channel relay board |
| **Sofar** | Sofar photovoltaic inverter |
## Adding a Modbus Device [#adding-a-modbus-device]
1. Go to **Settings** → **Connections** → **Modbus Devices**
2. Click **Add** (+ button)
3. Fill in the form:
### Basic Settings [#basic-settings]
| Field | Description | Required |
| ------------------- | ------------------------------------ | -------- |
| **Display Name** | Name displayed in Home Assistant | No |
| **Area** | Area/room | No |
| **Address** | Modbus address of the device (1-247) | ✅ Yes |
| **Model** | Device model from the supported list | ✅ Yes |
| **ID** | Custom identifier (optional) | No |
| **Update Interval** | Data reading interval (default 30s) | No |
**Modbus Address** must be unique for each device on the bus. Check the device documentation to find or set its address.
### Example SDM120 Meter Configuration [#example-sdm120-meter-configuration]
1. **Display Name**: `Kitchen power meter`
2. **Area**: `Kitchen`
3. **Address**: `1` (default SDM120 address)
4. **Model**: `SDM120`
5. **Update Interval**: `10s` (read every 10 seconds)
## Additional Options for Selected Models [#additional-options-for-selected-models]
### CWT - Sensor Filters [#cwt---sensor-filters]
The CWT model allows adding filters for temperature and humidity readings:
| Filter | Description |
| ------------------------ | ---------------------------------- |
| **round** | Round to N decimal places |
| **offset** | Add a constant value (calibration) |
| **multiply** | Multiply by value |
| **filter\_out** | Filter out a specific value |
| **filter\_out\_greater** | Filter out values greater than N |
| **filter\_out\_lower** | Filter out values less than N |
### LIQUID-SENSOR - Tank Dimensions [#liquid-sensor---tank-dimensions]
The LIQUID-SENSOR model requires tank dimensions:
| Field | Description |
| ---------- | ----------------------- |
| **Width** | Tank width (in meters) |
| **Length** | Tank length (in meters) |
## Modbus Settings (Advanced) [#modbus-settings-advanced]
If your device requires custom communication parameters, you can change them in **Settings** → **Connections** → **Modbus**:
| Parameter | Default | Description |
| ------------- | -------- | ------------------------------------------------- |
| **UART** | uart4 | Serial port (uart4 for new boneIO, uart1 for old) |
| **Baudrate** | 9600 | Transmission speed |
| **Data bits** | 8 | Number of data bits |
| **Parity** | N (None) | Parity: N (none), E (even), O (odd) |
| **Stop bits** | 1 | Number of stop bits |
**Changing UART parameters** is only needed when the Modbus device requires different settings than default. Most devices work with default parameters (9600 8N1).
## Verification in Home Assistant [#verification-in-home-assistant]
After adding a Modbus device:
1. The device will automatically appear in Home Assistant via MQTT Discovery
2. Go to **Settings** → **Devices & Services** → **MQTT**
3. Find the boneIO Black device - Modbus sensors will be visible as entities
Data from Modbus devices is automatically published to MQTT and available in Home Assistant for creating automations, charts, and dashboards.
# Modbus (/en/docs/black/current/configuration/modbus)
These settings apply to the whole RS485 Modbus bus, and so to **every** Modbus device connected to it.
The devices themselves (energy meters, sensors) are added in [Modbus Devices](./modbus-devices).
Open **Settings** → **Connections** → **Modbus**.
This section carries the **restart** badge. After **Save**, the panel shows **App restart required**. Click **Restart Now**, or nothing changes.
| Field | What it does |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **UART** | The serial port the bus is on. **UART4 (current BoneIO)** on every controller from version 0.4, including 1.0 and 1.1. **UART1 (old BoneIO)** only on 0.2 and 0.3. Required. |
| **Baudrate** | Bus speed, from 1200 to 115200. Default 9600. |
| **Data Bits** | 7 or 8. Default 8. |
| **Parity** | None (N), Even (E) or Odd (O). Default None. |
| **Stop Bits** | 1 or 2. Default 1. |
| **Timeout** | How long to wait for a device to answer. Default 1500 ms; the panel accepts 100 ms to 10 s. Increase it for slow devices or long cables. |
| **Inter-device delay** | Pause between two Modbus transactions. Default 5 ms; the panel accepts 0 to 200 ms. |
All devices on the bus must use the **same** speed, data bits, parity and stop bits. A device set differently will not answer.
### Inter-device delay and wiring [#inter-device-delay-and-wiring]
If the devices are wired **one after another** (daisy-chain, the recommended RS485 layout), `0 ms` is enough.
If several cables run from the controller in a **star**, signal reflections need time to settle. Set 5–50 ms.
```yaml title="Sample configuration"
modbus:
uart: uart4
baudrate: 9600
bytesize: 8
parity: N
stopbits: 1
timeout: 1500ms
inter_device_delay: 5ms
```
| Option | Required | Type | Default | Description |
| ------------------------ | -------- | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **uart** | **yes** | string | none | Serial port. Allowed: `uart1`, `uart2`, `uart3`, `uart4`, `uart5`. `uart4` on controllers 0.4 and newer, `uart1` on 0.2 and 0.3. |
| **baudrate** | no | integer | `9600` | Bus speed in bps. |
| **bytesize** | no | integer | `8` | Data bits. |
| **parity** | no | string | `N` | `N`, `E` or `O`. |
| **stopbits** | no | integer | `1` | `1` or `2`. |
| **timeout** | no | time period | `1500ms` | Response timeout. |
| **inter\_device\_delay** | no | time period | `5ms` | Delay between transactions. |
# OLED Display (/en/docs/black/current/configuration/oled)
The small display on the front of the controller shows the controller's status: its IP address, the state of the outputs and inputs, a QR code that opens the panel, and more.
You choose which screens it shows, and in what order, in **Settings** → **Device** → **OLED Display**.
## Using the button [#using-the-button]
* **Press** the button next to the display to go to the next screen. After the last screen it starts again from the first.
* If the display has gone dark (screensaver), the first press only wakes it up.
* **Hold** the button for 2 seconds to shut the controller down: the display asks **Shutdown system?**.
Release, then hold again for 3 seconds to confirm. A single press, or 30 seconds without doing anything, cancels.
## Notices [#notices]
Twice the display puts a notice ahead of the screens you chose, because something needs your attention at the cabinet.
### Setup required [#setup-required]
A controller with no administrator account yet shows **Setup required**, **Onboarding needed.**, **Open in a browser:** and the panel's address.
Open that address and go through the [First-time setup](/en/docs/black/current/install/first-run-wizard).
* The display does **not** go dark while the notice is up.
* The button still steps through the configured screens. After a minute without a press the notice comes back.
* The address is checked every few seconds, so it appears once the router hands one out. Until then the last line reads `http://:8090` — a placeholder, not the address. A controller already registered with boneIO Cloud shows its cloud address.
* The notice goes away by itself within a few seconds of the account being created — by the wizard or by restoring a backup.
{/* SCREENSHOT: oled_setup_required.webp — photo of the OLED showing "Setup required" with the panel address */}
### Updating — do not power off [#updating--do-not-power-off]
After a boneIO update the controller may run system migrations before the panel starts. On a controller several releases behind this can take minutes.
Meanwhile the display shows **Updating**, **Do not power off.** and how far it has got (for example `40% 1.6.32: …`). The panel does not answer yet.
**Do not unplug the controller while this is shown.** The notice goes away by itself when the migrations are done, and the panel starts.
With **OLED Display Enabled** off, the display shows a single line instead: `Updating system 40%`.
{/* SCREENSHOT: oled_updating.webp — photo of the OLED showing "Updating / Do not power off." with a percentage */}
## Choosing the screens [#choosing-the-screens]
1. Open **Settings** → **Device** → **OLED Display**
2. Make sure **OLED Display Enabled** is on.
3. Under **Screens**:
* drag a screen up or down to change the order,
* remove a screen with the bin icon,
* add a screen from the buttons under **Add screen:**. Only screens not already on the list are offered.
4. Click **Save**. The change applies straight away, no restart needed.
### What each screen shows [#what-each-screen-shows]
| Screen in the panel | YAML | What it shows |
| ------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Uptime** | `uptime` | boneIO logo, the hostname, the software version and how long the controller has been running. If the controller has a temperature sensor, also its temperature and whether MQTT is connected (`CONN` / `DOWN`). |
| **Network** | `network` | The controller's **IP address**, network mask and MAC address. |
| **Power (INA)** | `ina` | Voltage, current and power from the power monitor in the controller (INA219 or INA226). It has nothing to show unless the power monitor is set up in **Settings** → **Device** → **Board Sensors**. |
| **CPU** | `cpu` | Processor load. |
| **Disk** | `disk` | Total, used and free storage. |
| **Memory** | `memory` | Total, used and free RAM. |
| **Swap** | `swap` | Total, used and free swap. |
| **Outputs** | `outputs` | The state of every output, one screen for each group of outputs. |
| **Inputs** | `inputs` | The state of the inputs, over as many screens as needed. |
| **Extra Sensors** | `extra_sensors` | Up to three sensors of your choice (see below). |
| **Web QR Code** | `web` | A QR code. Scan it with your phone to open the panel. |
A factory-fresh controller shows: Uptime, Network, CPU, Disk, Memory, Swap, Outputs, Inputs and Web QR Code, in that order.
## Extra sensors [#extra-sensors]
The **Extra Sensors** screen can show up to **three** readings from Modbus devices or 1-Wire temperature sensors.
1. Add the **Extra Sensors** screen to the list. The **Extra Screen Sensors** card appears below.
2. Click **Add Sensor**.
3. Choose the **Sensor Type**:
* `modbus`: pick the device in **Modbus ID** and then the reading in **Sensor ID**,
* `dallas`: pick the 1-Wire sensor in **Sensor ID**.
4. Click **Save**.
After the third sensor the panel shows **Maximum 3 extra sensors allowed.**
## Screensaver [#screensaver]
Under **Screensaver**, the **Screensaver Timeout** slider sets how long the display stays on after the last button press, from 10 seconds to 10 minutes.
Move it all the way to the left (**Off**) and the display never goes dark.
```yaml title="Sample configuration"
oled:
enabled: true
screensaver_timeout: 60s
screens:
- uptime
- network
- cpu
- disk
- memory
- swap
- outputs
- inputs
- extra_sensors
- web
extra_screen_sensors:
- sensor_type: modbus
modbus_id: energy_meter
sensor_id: voltage
- sensor_type: dallas
sensor_id: room_temp
```
| Option | Type | Default | Description |
| -------------------------- | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **enabled** | boolean | `false` | Turn the display on. |
| **screens** | list | see below | Screens to show, in this order. Allowed: `uptime`, `network`, `ina`, `ina219`, `cpu`, `disk`, `memory`, `swap`, `outputs`, `inputs`, `extra_sensors`, `web`. `ina219` is the old name of `ina` and still accepted. |
| **screensaver\_timeout** | time period | `60s` | Time without a button press before the display goes dark. `0` switches the screensaver off. |
| **extra\_screen\_sensors** | list | none | Sensors for the `extra_sensors` screen. Only the first three are shown. |
If `screens` is left out altogether, the controller uses `uptime`, `network`, `ina`, `cpu`, `disk`, `memory`, `swap`, `outputs`.
Each entry of **extra\_screen\_sensors**:
| Option | Required | Description |
| ---------------- | ------------ | ------------------------------------------------------------------------------------------------ |
| **sensor\_type** | yes | `modbus` or `dallas`. |
| **modbus\_id** | for `modbus` | ID of the Modbus device. |
| **sensor\_id** | yes | For `modbus`: the name of the reading on that device. For `dallas`: the ID of the 1-Wire sensor. |
`modbus_id` and `sensor_id` are stored in lower case with spaces removed.
# 1-Wire Sensors (/en/docs/black/current/configuration/onewire-sensors)
The boneIO Black controller supports Dallas DS18B20 temperature sensors via the 1-Wire protocol. Sensors are automatically detected by the Linux kernel.
**1-Wire sensors are automatically detected** - after connecting a sensor, just refresh the list in the webUI to see available addresses.
## 1-Wire Sensors List [#1-wire-sensors-list]
Go to **Settings** → **Control** → **Onewire Sensors** to see the list of configured 1-Wire sensors.
## Connecting DS18B20 Sensor [#connecting-ds18b20-sensor]
The DS18B20 sensor has 3 pins:
* **VCC** (red) - power supply 3.3V or 5V
* **GND** (black) - ground
* **DATA** (yellow/white) - 1-Wire data line
### Connection diagram: [#connection-diagram]
1. Connect the sensor to the boneIO Black controller
2. Connect a 4.7kΩ pull-up resistor between DATA and VCC
3. The sensor will be automatically detected by the Linux kernel
**Pull-up resistor is required!** Without a 4.7kΩ resistor between DATA and VCC, the sensor may not work properly.
## Adding a 1-Wire Sensor [#adding-a-1-wire-sensor]
1. Go to **Settings** → **Control** → **Onewire Sensors**
2. Click **Add** (+ button)
3. Fill in the form:
### Basic Settings [#basic-settings]
| Field | Description | Required |
| ----------------------- | --------------------------------------------- | -------- |
| **Display Name** | Name displayed in Home Assistant | No |
| **Area** | Area/room | No |
| **Address** | 1-Wire sensor address (e.g., 28-0000098c7df0) | ✅ Yes |
| **ID** | Custom identifier (optional) | No |
| **Update Interval** | Temperature reading interval (default 60s) | No |
| **Unit of Measurement** | Unit: °C or °F (default °C) | No |
| **Show in HA** | Show in Home Assistant (default yes) | No |
**Sensor address** is automatically detected by the system. After connecting the sensor, click the refresh button next to the Address field to see available sensors.
### Example Configuration [#example-configuration]
1. **Display Name**: `Living room temperature`
2. **Area**: `Living room`
3. **Address**: `28-0000098c7df0` (select from detected list)
4. **Update Interval**: `30s` (read every 30 seconds)
5. **Unit of Measurement**: `°C`
## Filters for Sensors [#filters-for-sensors]
You can add filters to process temperature readings:
| Filter | Description |
| ------------------------ | ----------------------------------------- |
| **round** | Round to N decimal places (default 2) |
| **offset** | Add a constant value (sensor calibration) |
| **multiply** | Multiply by value |
| **filter\_out** | Filter out a specific value |
| **filter\_out\_greater** | Filter out values greater than N |
| **filter\_out\_lower** | Filter out values less than N |
### Example filter usage: [#example-filter-usage]
If the sensor shows temperature 0.5°C too low:
* Add **offset** filter with value `0.5`
## Sensor Not Detected? [#sensor-not-detected]
If you don't see the sensor in the available addresses list after connecting:
1. **Check connections** - make sure the sensor is properly connected
2. **Check pull-up resistor** - is there a 4.7kΩ resistor between DATA and VCC
3. **Reboot the device** - go to **Settings** → **Maintenance** → **Restart and shutdown**
**Never reboot the device by unplugging!** Always use **Settings → Maintenance → Restart and shutdown** in the webUI. Sudden power loss can damage the file system.
## R4DCB08 Module - Hub for Multiple Sensors [#r4dcb08-module---hub-for-multiple-sensors]
If you want to connect multiple 1-Wire sensors in a star topology, you can use the **R4DCB08** module via Modbus. See the [Modbus Devices](/en/docs/black/current/configuration/modbus-devices) section to learn more.
## Verification in Home Assistant [#verification-in-home-assistant]
After adding a 1-Wire sensor:
1. The sensor will automatically appear in Home Assistant via MQTT Discovery
2. Go to **Settings** → **Devices & Services** → **MQTT**
3. Find the boneIO Black device - temperature sensors will be visible as entities
Data from sensors is automatically published to MQTT and available in Home Assistant for creating automations, historical charts, and dashboards.
# Output Groups (/en/docs/black/current/configuration/output_group)
An **output group** switches several outputs at once: all the lights of a room, every socket on a circuit.
The group is one entity in Home Assistant, and a button action with type **Output** can target a group just like a single output.
## Adding a group [#adding-a-group]
1. Open **Settings** → **Control** → **Output Groups**
2. Click **Add New**
3. Fill in the form and save
### Basic Settings [#basic-settings]
| Field | What it does |
| ------------------ | ------------------------------------------------------------------------------------------------------ |
| **ID** | Required. Identifier used in MQTT topics and actions. Only lowercase letters, numbers and underscores. |
| **Name** | Name shown in Home Assistant. Optional — the ID is used if empty. |
| **Member Outputs** | The outputs in the group. At least one. |
| **Output Type** | **SWITCH** or **LIGHT** — how Home Assistant shows the group. |
| **Area / Room** | Puts the group into an area in Home Assistant. |
### Advanced Settings [#advanced-settings]
| Field | What it does |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **All On Behaviour** | Off (default): the group shows **on** when any of its outputs is on. On: the group shows **on** only when all of them are. |
Outputs of type **Cover** cannot be members — the controller skips them and writes a warning to the log.
```yaml title="All living room lights"
output_group:
- id: living_room_lights
name: Living room lights
output_type: light
all_on_behaviour: false
outputs:
- out_01
- out_02
- hall_light
```
Members are listed by their output ID — the `id` of the output, or its `boneio_output` if it has no own ID.
**Options**
* **id** (**Required**, string) — identifier of the group.
* **name** (*Optional*, string) — display name. Defaults to the ID.
* **outputs** (**Required**, list) — IDs of the member outputs.
* **output\_type** (**Required**, default `switch`) — `switch` or `light`.
* **all\_on\_behaviour** (**Required**, boolean, default `false`) — `true`: on only when all members are on; `false`: on when any member is on.
* **area** (*Optional*, string) — ID of an area from the `areas` section.
# Local Outputs (/en/docs/black/current/configuration/outputs_local)
**Local Outputs** are the relays and other outputs built into this controller. For each one you choose what it drives — a light, a switch, a valve, a cover motor — and that decides how it appears in Home Assistant.
Outputs of other devices (ESPHome, WLED, another boneIO) are set up separately, under [Remote Outputs](/en/docs/black/current/configuration/outputs_remote).
## Adding or editing an output [#adding-or-editing-an-output]
1. Open **Settings** → **Control** → **Local Outputs**
2. Click **Add New** (or the edit icon next to an output)
3. Fill in the two tabs and save
### Basic Settings [#basic-settings]
| Field | What it does |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **boneIO Output** | The physical output, e.g. `OUT_01`. Outputs already in use are listed under the field as **Used**. |
| **Output Type** | What the output drives — see the table below. |
| **Display Name** | Name shown in the panel, MQTT and Home Assistant. Optional. |
| **Custom ID** | Optional. Leave it empty to use the output (e.g. `out_01`) as the ID. Only lowercase letters, numbers and underscores. |
| **Area / Room** | Puts the output into an area, which becomes a sub-device in Home Assistant. |
| **Restore State** (under **Options**) | After a restart the relay comes back in the state it had. On by default. |
| Output Type | Use it for | In Home Assistant |
| ----------- | ---------------------------------------------------------------------------- | -------------------------------- |
| **Switch** | sockets, pumps, anything on/off | a switch |
| **Light** | lights | a light |
| **Valve** | water valves, irrigation | a valve |
| **Cover** | one motor direction of a [cover](/en/docs/black/current/configuration/cover) | not shown — the cover is |
| **None** | an output used only inside the controller | not shown, not published to MQTT |
An output used by a cover cannot be edited here — the form says which cover uses it. Remove it from the cover first.
An output of type **Cover** cannot be put into an [output group](/en/docs/black/current/configuration/output_group).
### Advanced Settings [#advanced-settings]
| Field | What it does |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Momentary Turn On** | After switching on, the output switches itself off after this time, e.g. `500ms`, `5s`, `20min`. For door strikes, gate pulses. |
| **Momentary Turn Off** | After switching off, the output switches itself on again after this time. |
| **Adjustable Duration** | Adds a slider in Home Assistant that sets how long the output stays on before it switches itself off. Set **Default Duration** (60s if empty), **Minimum Duration** (1s), **Maximum Duration** (1h) and the **HA Slider Unit** (seconds or minutes). Cannot be used together with **Momentary Turn On** — clear that first. |
| **Interlock Group** | Outputs in the same group cannot be on at the same time — for example heating and cooling. Choose an existing group or type a new name. |
Timers and interlock are not available for type **Cover** — the cover takes care of that.
## Buzzer [#buzzer]
On hardware revision **1.1** the buzzer is an output too: `boneio_output: buzzer`. Revision 1.0 has no buzzer fitted, and a configuration that names it is refused when it is loaded.
```yaml title="Two lights and a door strike"
output:
- boneio_output: out_01
name: Kitchen light
output_type: light
area: kitchen
- id: hall_light # own ID, used in actions and MQTT
boneio_output: out_02
name: Hall light
output_type: light
- boneio_output: out_03
name: Door strike
output_type: switch
momentary_turn_on: 2s
restore_state: false
```
```yaml title="Irrigation valve with a slider in Home Assistant"
output:
- boneio_output: out_05
name: Garden zone 1
output_type: valve
adjustable_duration: true
duration_default: 10min
duration_min: 1min
duration_max: 1h
duration_unit: min
```
```yaml title="Two outputs that must never be on together"
output:
- boneio_output: out_07
name: Heating
output_type: switch
interlock_group: heat_cool
- boneio_output: out_08
name: Cooling
output_type: switch
interlock_group: heat_cool
```
**Options**
* **boneio\_output** (*Optional*, string) — the output, e.g. `out_01`. Needs the `boneio:` section.
* **id** (*Optional*, string) — identifier used in MQTT topics, output groups and actions. Defaults to `boneio_output`; required when there is no `boneio_output`.
* **name** (*Optional*, string) — display name. Defaults to the ID.
* **output\_type** (**Required**) — `switch`, `light`, `cover`, `valve` or `none`.
* **area** (*Optional*, string) — ID of an area from the `areas` section.
* **restore\_state** (*Optional*, boolean, default `true`) — bring the output back to its last state after a restart. The state is kept in `state.json` next to `config.yaml`. Not used for `none` and `cover`.
* **momentary\_turn\_on** (*Optional*, time) — switch off automatically this long after switching on.
* **momentary\_turn\_off** (*Optional*, time) — switch on automatically this long after switching off.
* **adjustable\_duration** (*Optional*, boolean, default `false`) — add a duration slider in Home Assistant.
* **duration\_default** / **duration\_min** / **duration\_max** (*Optional*, time) — the slider's default, minimum and maximum.
* **duration\_unit** (*Optional*, default `s`) — `s` or `min`, the unit of the slider.
* **interlock\_group** (*Optional*, string or list) — one group name, or a list if the output belongs to several groups.
**Direct hardware (advanced)**
Normally `boneio_output` is enough. Without it, the output is described by its hardware:
* **kind** (*Optional*) — `gpio`, `mcp`, `pca`, `pcf` or `buzzer`.
* **pin** (*Optional*, integer) — pin number on the expander (for MCP 0–15).
* **mcp\_id** / **pca\_id** / **pcf\_id** (*Optional*, string) — which expander.
* **sysfs\_path** (*Optional*, string) — for `buzzer`: the system file that drives it.
* **percentage\_default\_brightness** (*Optional*, integer) — PCA only: the brightness used when the light is switched on without a brightness value.
```yaml title="Output on an MCP23017 expander"
output:
- id: kitchen_light
name: Kitchen light
kind: mcp
mcp_id: mcp2
pin: 15
output_type: light
```
# Remote Outputs (/en/docs/black/current/configuration/outputs_remote)
A **remote output** is a relay, light or cover of another device that this controller uses as if it were its own.
It shows up on the **Outputs** page, can be switched by buttons and schedules, and can be used in irrigation zones, [output groups](/en/docs/black/current/configuration/output_group) and templates.
The other device must first be added under [Remote Devices](/en/docs/black/current/configuration/remote-devices).
To switch a remote output from a single button you do not need a remote output at all — the **Control Remote Output** action does that directly, see [Actions](/en/docs/black/current/configuration/event#actions).
A remote output is worth adding when the device should behave like a local output: with a timer, an interlock, a place in a group or in irrigation.
## Adding a remote output [#adding-a-remote-output]
1. Open **Settings** → **Connections** → **Remote Outputs**
2. Click **Add New**
3. Fill in the two tabs and save
### Basic Settings [#basic-settings]
| Field | What it does |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Device** | The remote device. Only devices with outputs are listed. The panel sets the protocol from it. |
| **Output Entity** | The switch, light or cover on that device. For WLED: **Main (whole device)** or one segment. |
| **Display Name** | Name shown in the panel and Home Assistant. Optional. |
| **Custom Output ID** | Optional. If left empty, the ID is made from the device and the output, e.g. `garden_esp_relay_1`. |
| **Output Type** | **Switches**, **Lights**, **Valves** or **Covers**. A light that supports brightness can only be a light. |
| **On Disconnect** | What happens when the device drops off the network — see below. |
| **Area / Room** | Area in Home Assistant. |
| **Forward to Home Assistant** | Off by default. Leave it off if the device already shows up in Home Assistant by itself, or you get the same thing twice. |
**On Disconnect**:
* **Ignore (keep last state)** — the default. The output keeps showing its last known state.
* **Force OFF (safe for pumps)** — the output is shown as off at once, and when the device comes back the controller sends it an OFF command. Choose this for pumps and irrigation, where "stays on while nobody can see it" is the worst case.
### Advanced Settings [#advanced-settings]
| Field | What it does |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Momentary Turn On** | Switches off by itself this long after switching on. |
| **Momentary Turn Off** | Switches on by itself this long after switching off. |
| **Adjustable Duration** | A slider in Home Assistant that sets how long the output stays on — with **Default Duration**, **Minimum Duration**, **Maximum Duration** and **HA Slider Unit**, as for [local outputs](/en/docs/black/current/configuration/outputs_local#advanced-settings). |
| **Interlock Group** | Shared with local outputs: a remote output and a local output in the same group cannot be on at the same time. |
| **Enforce Interlock** | Off by default. |
The interlock only guards what goes **through boneIO**. If the output is switched on directly — in ESPHome, or through its own entity in Home Assistant — boneIO is not asked.
With **Enforce Interlock** on, boneIO notices such a change and, if it breaks the interlock, switches the output off again at once.
```yaml title="An irrigation pump on an ESPHome board"
remote_outputs:
- id: garden_pump
name: Garden pump
remote_source: esphome_api
device_id: garden_esp
output_id: relay_1
output_type: valve
on_disconnect: turn_off
adjustable_duration: true
duration_default: 15min
duration_max: 1h
duration_unit: min
```
```yaml title="A remote relay sharing an interlock with a local one"
remote_outputs:
- remote_source: esphome_api
device_id: boiler_esp
output_id: relay_heat
interlock_group: heat_cool
enforce_interlock: true
output:
- boneio_output: out_08
name: Cooling
output_type: switch
interlock_group: heat_cool
```
**Options**
* **remote\_source** (**Required**) — `esphome_api`, `mqtt`, `wled` or `can`. The panel fills it in from the device's protocol.
* **device\_id** (**Required**, string) — ID of the device in the `remote_devices` section.
* **output\_id** (**Required**, string) — the switch, light or cover on that device, e.g. `relay_1`.
* **id** (*Optional*, string) — own ID. Default: `device_id` and `output_id` joined, e.g. `garden_esp_relay_1`.
* **name** (*Optional*, string) — display name.
* **output\_type** (*Optional*, default `switch`) — `switch`, `light`, `valve` or `cover`.
* **area** (*Optional*, string) — area in Home Assistant.
* **show\_in\_ha** (*Optional*, boolean, default `false`) — publish to Home Assistant.
* **on\_disconnect** (*Optional*, default `ignore`) — `ignore` or `turn_off`.
* **momentary\_turn\_on** / **momentary\_turn\_off** (*Optional*, time)
* **adjustable\_duration** (*Optional*, boolean, default `false`)
* **duration\_default** / **duration\_min** / **duration\_max** (*Optional*, time)
* **duration\_unit** (*Optional*, default `s`) — `s` or `min`.
* **interlock\_group** (*Optional*, string or list) — shared with local outputs.
* **enforce\_interlock** (*Optional*, boolean, default `false`) — switch the output off again if it is turned on outside boneIO against the interlock.
# PCA9685 expander (/en/docs/black/current/configuration/pca9685)
The PCA9685 is a chip with 16 PWM outputs on the I2C bus. None of the controller types you choose in [boneIO](./boneio) uses it, so this section is only for a PCA9685 that is not set up for you, for example one you connect to the I2C bus yourself.
If you have not added one, you do not need this page.
There is no form for it in the panel. The section is edited only in **Settings** → **Advanced** → **YAML editor**.
## Adding a PCA9685 [#adding-a-pca9685]
1. Check the chip's address: **Diagnostics** → **Buses** → **I2C** scans the bus and lists what responds. Nothing is saved there.
2. Open **Settings** → **Advanced** → **YAML editor** and add a `pca9685:` section, as in the example below.
3. Click **Save and Restart**. The chip is set up only when the application starts, so **Save** alone is not enough.
4. If the address is wrong, the controller lists the failure in **Settings** → **Maintenance** → **Hardware errors**, and the outputs on that chip do nothing.
The address is set by the chip's address pins, usually from `0x40` up. Avoid `0x40`, which the controller's own INA219 sensor may use, and `0x70`, which every PCA9685 also answers to.
```yaml title="Sample configuration: two chips, 32 channels"
pca9685:
- id: pca1
address: 0x41
- id: pca2
address: 0x42
```
```yaml title="Sample configuration: three chips, 48 channels"
pca9685:
- id: pca1
address: 0x41
- id: pca2
address: 0x42
- id: pca3
address: 0x43
```
| Option | Required | Type | Default | Description |
| --------------- | ---------------- | ----------- | ------- | ------------------------------------------------------------------------ |
| **id** | yes, in practice | string | none | Outputs refer to the chip by this ID (`pca_id`). |
| **address** | **yes** | integer | none | I2C address, as hex (`0x41`) or decimal (`65`). |
| **init\_sleep** | no | time period | `0s` | How long to wait after setting up the chip, for chips that start slowly. |
An output on the chip is defined in the `output:` section with `kind: pca`, `pca_id` (the ID above), `pin` (channel `0`–`15`) and `percentage_default_brightness` (the brightness, in percent, it turns on with).
# PCF8575 expander (/en/docs/black/current/configuration/pcf8575)
The PCF8575 is a 16-pin GPIO expander, used for example to drive extra relays. None of the controller types you choose in [boneIO](./boneio) uses it, so this section is only for a PCF8575 that is not set up for you, for example one you connect to the I2C bus yourself.
If you have not added one, you do not need this page.
Support for the PCF8575 is marked unstable.
There is no form for it in the panel. The section is edited only in **Settings** → **Advanced** → **YAML editor**.
## Adding a PCF8575 [#adding-a-pcf8575]
1. Check the chip's address: **Diagnostics** → **Buses** → **I2C** scans the bus and lists what responds. Nothing is saved there.
The scan names every address from `0x20` to `0x27` "MCP23017 GPIO expander", a PCF8575 included.
2. Open **Settings** → **Advanced** → **YAML editor** and add a `pcf8575:` section, as in the example below.
3. Click **Save and Restart**. The chip is set up only when the application starts, so **Save** alone is not enough.
4. If the address is wrong, the controller lists the failure in **Settings** → **Maintenance** → **Hardware errors**, and the outputs on that chip do nothing.
The address is set by the chip's address pins, `0x20` to `0x27`. The controller's own MCP23017 expanders use addresses from the same range (see [MCP23017 expander](./mcp23017)), so pick one they do not.
```yaml title="Sample configuration"
pcf8575:
- id: pcf1
address: 0x26
- id: pcf2
address: 0x27
```
| Option | Required | Type | Default | Description |
| --------------- | ---------------- | ----------- | ------- | ------------------------------------------------------------------------ |
| **id** | yes, in practice | string | none | Outputs refer to the chip by this ID (`pcf_id`). |
| **address** | **yes** | integer | none | I2C address, as hex (`0x26`) or decimal (`38`). |
| **init\_sleep** | no | time period | `0s` | How long to wait after setting up the chip, for chips that start slowly. |
An output on the chip is defined in the `output:` section with `kind: pcf`, `pcf_id` (the ID above) and `pin` (`0`–`15`).
# Presence simulation (/en/docs/black/current/configuration/presence_simulation)
Going on holiday? The **presence simulation** switches lights in the evening as if someone were walking through the house:
as it gets dark a light comes on in the living room, later in the bedroom, then in the kitchen — and at bedtime everything goes off.
You turn the whole thing on and off with one switch, **Away**.
## Setting it up [#setting-it-up]
Open **Settings** → **Control** → **Schedules** and click **Presence simulation**. The wizard asks four things:
1. **Lights** — click the lights in the order they should come on through the evening. The number shows the order.
2. **Timing** — when the evening ends (**Everything goes off at**, e.g. 23:10). The start follows civil dusk on its own,
calculated each day from the controller's [location](./location).
3. **Randomness** — how much the evenings should differ from each other:
* **Calm** — the same steps every evening, each within a quarter of an hour of the day before,
* **Normal** — half an hour of drift, and a step is occasionally skipped,
* **Lively** — up to about forty minutes of drift, and roughly one step in three is skipped.
4. **Summary** — what it will do and what it will create. Click **Create**.
The location must be set first — the first light follows dusk. See [Location](./location).
## Using it [#using-it]
* **Leaving** — turn on the **Away** switch: in Home Assistant, on the **Outputs** page of the panel, or with a button you assign to it.
If it is already dark (and not yet bedtime) when you leave, the first light comes on straight away.
* **Coming back** — turn **Away** off. Every light the simulation uses is switched off, so nothing is left burning.
While **Away** is off, nothing happens — the simulation never runs while you are at home.
## What the wizard creates [#what-the-wizard-creates]
Nothing magical: one [virtual switch](./virtual_switch) (**Away**), one [schedule](./schedule) per light, and one more schedule that switches everything off.
Four lights and bedtime at 23:10 give roughly:
```
~21:10 Living room on ← at dusk, but no later than the evening start
~21:40 Bedroom on (living room off)
~22:10 Kitchen on (bedroom off)
~22:40 Study on (kitchen off)
23:10 everything off
```
One room at a time looks like someone walking through the house; the whole floor lit at once looks like a timer.
In summer, when dusk is very late, the first light comes on no later than two hours before bedtime, so the evening does not shrink to an hour.
Afterwards they are ordinary entries on the **Schedules** and **Virtual switches** pages — you can rename them, change the times,
delete one or add another. Everything the wizard creates has an identifier starting with `presence_`. Running the wizard again replaces all of those entries —
including ones you renamed or edited — and leaves everything else alone.
## Good to know [#good-to-know]
* The final **everything off** always runs — a step that sometimes does not happen is realistic, a light that stays on until morning is not.
* The simulation does not pick rooms at random: it can skip a step, but it will not light the kitchen instead of the bedroom.
* Weekends are not different. For a later Friday evening, add a second set of schedules by hand.
# Remote Devices (/en/docs/black/current/configuration/remote-devices)
The controller can control devices elsewhere on the network: other **boneIO Black** controllers (over MQTT), **ESPHome** devices (over the ESPHome API)
and **WLED** LED controllers. Once a device is added here, its outputs, lights and covers can be used in this controller's actions.
Open **Settings** → **Connections** → **Remote Devices**. Changes apply without a restart.
## Supported protocols [#supported-protocols]
| Protocol | For | What you get |
| ---------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| **MQTT** | Other boneIO Black controllers on the same MQTT broker | Their outputs and covers |
| **ESPHOME\_API** | ESPHome devices with the native API switched on | Switches, lights (brightness, colour temperature, RGB/RGBW), covers (position, tilt), binary sensors |
| **WLED** | WLED LED controllers | The whole strip and its segments, with effects and palettes |
## Finding devices [#finding-devices]
The **Discovered devices** card at the top lists devices found on the network that are not configured yet.
* **boneIO Black** controllers appear by themselves, if they use the same MQTT broker. The list refreshes every 30 seconds.
The other controller must have **Send boneIO Autodiscovery** on, and this one **Receive boneIO Autodiscovery**, both in [MQTT](./communication) settings.
* **Scan ESPHome** and **Scan WLED** search the local network (mDNS) for 3 seconds.
* **Scan CAN** appears only when the [CAN bus](./canbus) is on, and lists the devices that answered on the bus.
Click **Add** next to a device to add it. **Remove from list** next to a discovered boneIO clears the messages it left on the broker, so it disappears from the list.
## Adding a device by hand [#adding-a-device-by-hand]
If a device was not found, add it yourself. Every device has:
| Field | Description |
| --------------- | -------------------------------------------------------------------------------------------------------- |
| **Device ID** | Unique identifier, used in actions, for example `salon_boneio`. Required. |
| **Device Name** | Name shown in the panel. Required. |
| **Protocol** | **MQTT**, **ESPHOME\_API** or **WLED**. Required. |
| **Device Type** | Only for MQTT: boneIO Black, ESPHome, WLED or Generic. For ESPHome API and WLED it is set automatically. |
### boneIO Black (MQTT) [#boneio-black-mqtt]
For a boneIO Black, the **Device ID** must be that controller's serial number, for example `blk8c7df0`: it is used to build the MQTT topics.
Under **MQTT Settings** you can list its **Outputs** (**Add Output**) and **Covers** (**Add Cover**), so they are offered in action dropdowns.
A controller added from **Discovered devices** gets all of this filled in.
### ESPHome device [#esphome-device]
Under **ESPHome API Settings**:
| Field | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| **Host** | Address of the device. A hostname such as `device.local` is better than an IP address, which can change. Required. |
| **Port** | API port, 6053 by default. |
| **API Password** | Only if the device has one. |
| **Encryption Key** | Only if the device has one (Base64). |
Click **Discover Entities**. The controller connects to the device and lists its **Switches**, **Lights**, **Covers** and **Binary Sensors**.
Only the binary sensors you tick are monitored; use **Select all** / **Deselect all**. In the device list, the same **Discover Entities** button
refreshes the entities later and shows how many were found.
### WLED [#wled]
Under **WLED Settings**:
| Field | Description |
| -------- | ------------------------------------------------------------------------- |
| **Host** | Address of the WLED controller, for example `wled-salon.local`. Required. |
| **Port** | 80 by default. |
Click **Discover Segments** to read the device's **Segments** (name and number of LEDs).
After the device is saved, **Refresh effects & palettes cache** appears. The controller reads the list of effects and palettes from WLED by itself when it connects.
Use the button if you updated WLED or changed its effects: it reads them again without removing and re-adding the device.
The panel then shows how many effects and palettes it found.
{/* SCREENSHOT: en_settings_remote_wled.webp — editing a WLED remote device, with Segments and the Refresh effects & palettes cache button */}
The WLED strip and its segments are then set up as [remote outputs](./outputs_remote).
## Example: a second boneIO Black [#example-a-second-boneio-black]
1. Make sure both controllers use the same MQTT broker.
2. The second controller appears in **Discovered devices**.
3. Click **Add**. It is added with all its outputs and covers.
4. Its outputs can now be chosen in this controller's actions.
## Example: an ESPHome device [#example-an-esphome-device]
**On the ESPHome device:**
```yaml
api:
encryption:
key: "your_encryption_key"
switch:
- platform: gpio
pin: GPIO5
name: "Garage Light"
id: garage_light
```
**On boneIO Black:**
1. Click **Scan ESPHome**. The device should appear.
2. Click **Add** next to it.
3. Enter the **Encryption Key**.
4. Click **Discover Entities**.
5. "Garage Light" can now be chosen in actions.
## Managed by [#managed-by]
The **Managed by** card lists other boneIO controllers that have added **this** controller as a remote device and can control it.
Useful when you are working out which controller switches what in a larger installation.
## Using remote devices [#using-remote-devices]
Remote outputs and covers can be used in input actions, binary sensor actions and schedules. In the action dropdowns they carry the remote device's name.
The controller does the controlling. To control a remote device directly from Home Assistant, add it to Home Assistant on its own (MQTT or ESPHome integration).
## Troubleshooting [#troubleshooting]
### A boneIO Black does not appear [#a-boneio-black-does-not-appear]
1. Check that both controllers use the same MQTT broker.
2. Check **Send boneIO Autodiscovery** on the other controller and **Receive boneIO Autodiscovery** on this one.
3. Wait: the list refreshes every 30 seconds.
### An ESPHome or WLED device does not appear [#an-esphome-or-wled-device-does-not-appear]
1. Make sure it is on the same local network.
2. For ESPHome, check that `api:` is in its configuration.
3. mDNS scanning does not cross routers or VLANs. Add the device by hand, with its IP address.
### ESPHome API does not connect [#esphome-api-does-not-connect]
1. Check the API password and the encryption key.
2. Check that port 6053 is not blocked by a firewall.
3. Look at the ESPHome device's logs.
```yaml title="Sample configuration"
remote_devices:
- id: blk8c7df0
name: boneIO garage
protocol: mqtt
device_type: boneio_black
mqtt:
outputs:
- id: out_01
name: Garage light
covers:
- id: garage_door
- id: garage_esp
name: ESP Garage
protocol: esphome_api
device_type: esphome
esphome_api:
host: garage-esp.local
port: 6053
encryption_key: "your_encryption_key"
- id: wled_salon
name: WLED living room
protocol: wled
device_type: wled
wled:
host: wled-salon.local
port: 80
```
| Option | Required | Type | Default | Description |
| -------------------------------------- | ------------------------- | ------- | -------------- | ----------------------------------------------- |
| **id** | **yes** | string | none | Unique device ID, used in actions. |
| **name** | **yes** | string | none | Name shown in the panel. |
| **protocol** | **yes** | string | none | `mqtt`, `esphome_api` or `wled`. |
| **device\_type** | no | string | `boneio_black` | `boneio_black`, `esphome`, `wled` or `generic`. |
| **mqtt** → **outputs**, **covers** | no | list | none | Each with `id` (required) and `name`. |
| **esphome\_api** → **host** | **yes** for `esphome_api` | string | none | Device address. |
| **esphome\_api** → **port** | no | integer | `6053` | API port. |
| **esphome\_api** → **password** | no | string | none | API password. |
| **esphome\_api** → **encryption\_key** | no | string | none | Encryption key (Base64). |
| **wled** → **host** | **yes** for `wled` | string | none | WLED address. |
| **wled** → **port** | no | integer | `80` | WLED port. |
The lists of ESPHome entities are filled in by **Discover Entities**. WLED segments, effects and palettes are not stored in the configuration at all: the controller reads them from the device.
# Schedules (/en/docs/black/current/configuration/schedule)
A **schedule** runs actions by itself, with nobody pressing anything: *close the covers 15 minutes after sunset*,
*turn off the garden lights at 23:30 on weekdays*. It runs on the controller, so it works even when Home Assistant or the internet is down.
You find them in **Settings → Control → Schedules**.
## Adding a schedule [#adding-a-schedule]
The editor reads like one sentence: **When** … **Only if** … **Do** …
### Name [#name]
Give the schedule a readable name, e.g. *Covers at dusk*. The identifier is made from it automatically
(`covers_at_dusk`) — that is what the logs show.
### When [#when]
Pick the **Trigger**:
* **Clock time** — a fixed hour, e.g. `23:30`
* **Sun** — a moment the sun defines: **Sunrise**, **Sunset**, **Civil dusk**, **Civil dawn**, the golden or blue hour and a few more.
The hour moves with the seasons by itself. Requires the [Location](./location) to be set; until then the option is greyed out.
With a sun trigger you can also set an **Offset** in minutes — negative means *before*: `-15` with **Sunset** is fifteen minutes before sunset.
Under **Days** choose **Every day**, **Weekdays**, **Weekend** or one day of the week. For, say, Monday and Wednesday, make two schedules.
### Only if (optional) [#only-if-optional]
Conditions checked at the moment the schedule fires — for example *only when it is dark*, *only between October and April*,
or *only when the virtual switch "Away" is on*. Without conditions the schedule always fires.
### Do [#do]
The actions to run — exactly the same as for a button: switch an output, open or close a cover, set a [virtual switch](./virtual_switch)…
### More options [#more-options]
* **Random spread** — delays each firing by a random time up to this value, different every day. Used by the presence simulation,
so the lights do not come on at the exact same minute every evening.
* **Missed firing** — what happens if the controller was off at that moment: **Skip it** (default) or **Catch up (within 15 min)**.
A controller that was off all day will not close the covers at breakfast.
Save the section when you are done.
## Checking that it works [#checking-that-it-works]
A schedule is the one thing you cannot test by pressing a button, so the table tells you what it does:
* **Next** — when it will fire next. A dash means it is switched off, the clock has not been set yet, or the sun never reaches that point in the coming year.
* **Last run** — what happened last time: **ran**, **condition blocked it** or **failed**. Click the arrow at the start of the row to see the **Run history**
of the last 20 runs, including whether a run came **on schedule**, was **caught up** or started **by hand**.
* **Run now** (the ⚡ button) — fires the schedule immediately, conditions included, without affecting its next regular firing. Save your changes first.
* The switch in each row turns a schedule off and on without deleting it (also only after saving your changes).
## In Home Assistant [#in-home-assistant]
Each schedule appears in Home Assistant as a **switch** (turn the schedule off for a holiday, for example) plus three diagnostic sensors:
next firing, last firing and last outcome.
If you switch a schedule off in Home Assistant and later change `enabled:` in the configuration file by hand, the file wins.
## Good to know [#good-to-know]
* **After a power cut** the controller waits for the correct time from the network before it arms any schedule — it has no battery clock.
Without internet, set your own time server: see [Location → The clock must be right](./location#the-clock-must-be-right).
* **Daylight saving time**: a schedule set for a time that does not exist on the night the clocks go forward (e.g. 02:30) fires at 03:00;
on the night the clocks go back it fires once, not twice.
* **"On at dusk, off at dawn"** is two schedules — a schedule is a moment, not a time span.
```yaml title="Sample configuration"
schedule:
- name: Covers at dusk
trigger:
type: sun # sun | time
event: sunset
offset: "-15min" # negative is earlier
jitter: "10min" # random spread
latest: "21:30" # never later than this, whatever the season
days: daily # daily | weekdays | weekend | mon … sun
on_missed: skip # skip | run
condition:
type: date
after: "10-01"
before: "04-30"
actions:
- action: cover
boneio_cover: living_room
action_cover: CLOSE
- name: Garden lights off
trigger:
type: time
at: "23:30"
days: weekdays
actions:
- action: output
boneio_output: garden
action_output: "OFF"
```
`earliest:` and `latest:` keep a sun trigger inside a clock window — useful because in summer dusk can be very late.
They are set in YAML only.
# Maintenance (/en/docs/black/current/configuration/system)
Since version 1.6 there is no **System** tab. Everything it held is now in
**Settings**, mostly in the **Maintenance** group — see
[Maintenance](/en/docs/black/current/basic/system) for the full description.
| In 1.5 (System tab) | Since 1.6 |
| ------------------------------------- | ---------------------------------------------------------------- |
| System update, available versions | **Settings → Maintenance → Software update** |
| Configuration backup | **Settings → Maintenance → Backups** |
| Restart / shutdown device | **Settings → Maintenance → Restart and shutdown** |
| Hardware test, switch off all outputs | **Settings → Maintenance → Device tools** |
| Restore factory settings | **Settings → Maintenance → Factory reset** |
| MQTT passwords | **Settings → Services on this controller → MQTT broker (local)** |
| Hostname, time zone | **Settings → Device → Hostname / Time zone** |
# Templates (/en/docs/black/current/configuration/template)
A **template** turns things the controller already has — a temperature sensor and a relay, a few door contacts and a siren, a gate relay and a limit switch — into one device that behaves like the real thing. You do not wire anything new: you tell boneIO which inputs, outputs and sensors belong together, and it runs the logic itself, with or without Home Assistant.
Version 1.6 has four kinds:
Keeps a room at a set temperature by switching a heating relay.
Zones of door, window and motion sensors, arming modes, PIN codes and a siren.
A driveway gate, garage door, barrier or wicket driven by relay pulses, with contact sensors.
Watering zones one after another, with schedules, water sources and pump timing.
Every template appears in Home Assistant by itself (through MQTT discovery) and on the controller's own **Templates** page, where you use it day to day — see [Templates page](/en/docs/black/current/basic/templates).
## Adding a template [#adding-a-template]
1. Open **Settings** → **Control** → **Templates**
2. Click **Add New**. A window asks **What would you like to add?** — pick **Thermostat**, **Alarm Panel**, **Gate Cover** or **Irrigation**
3. Fill in the form. What it asks for depends on the kind — each page above goes through its form field by field
4. Save
Saving takes effect without restarting the controller.
Every form starts with the same three fields:
| Field | What it does |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Name** (**Display Name** on the thermostat and alarm forms) | The name shown in Home Assistant and on the Templates page. |
| **ID** (**Entity ID** on the gate and irrigation forms) | The identifier used in MQTT topics and Home Assistant. Leave it empty and the panel makes one from the name. |
| **Area / Room** | Puts the device in an area, so Home Assistant groups it with the rest of that room. |
An ID made from the name contains only the letters a–z, digits and underscores — accented letters are replaced with `_` (the Polish "Łazienka" becomes `azienka`). If you want a readable ID, type it yourself.
Changing the **ID** of a template that is already in use makes it a new device: Home Assistant shows the old entity as unavailable and dashboards and automations that pointed at it have to be updated. Choose the ID once.
## The list in Settings [#the-list-in-settings]
**Settings** → **Control** → **Templates** lists all templates with their icon, name, ID, kind and area. From the list you can:
* edit or delete a template,
* duplicate one with the copy button — the copy gets `_copy` added to its ID and opens for editing, which is the quickest way to make a second thermostat or gate,
* for irrigation, copy a ready Home Assistant dashboard for that controller to the clipboard (Sections layout).
Templates live in the `template:` section of the configuration, one list item per device. The kind is chosen with `platform`:
```yaml title="One of each"
template:
- id: living_room_heating
name: Living Room Heating
platform: thermostat
sensor_ids: [temp_living_room]
output_id: floor_heating
- id: home_alarm
name: Home Alarm
platform: alarm_control_panel
zones:
- name: Doors
inputs: [front_door]
arm_modes: [armed_away, armed_home]
outputs:
- id: siren
- id: driveway_gate
name: Driveway Gate
platform: gate_cover
pulse_output: gate_relay
closed_sensor: gate_closed
- id: garden
name: Garden
platform: irrigation
zones:
- id: lawn
name: Lawn
valve_id: valve_lawn
run_duration: 10min
```
Fields every template has:
* **platform** (**Required**, string, one of `thermostat`, `alarm_control_panel`, `gate_cover`, `irrigation`) — the kind of template.
* **id** (string) — identifier used in MQTT topics and Home Assistant. The schema lists it as optional, but the controller skips a template without one; the panel fills it in from the name.
* **name** (*Optional*, string) — display name. The ID is used when it is missing.
* **area** (*Optional*, string) — ID of an area from the `areas:` section.
The remaining fields depend on the platform and are described on each template's page.
# Thermostat (/en/docs/black/current/configuration/thermostat)
The **Thermostat** template keeps a room at the temperature you set. It reads one or more temperature sensors and switches a heating output — an underfloor heating actuator, an electric heater, a boiler contact — on when the room is too cold and off when it is warm enough.
It runs on the controller itself, so the heating keeps working when Home Assistant or the network is down.
It is a heating-only thermostat with two modes, **heat** and **off**. It does not drive cooling, and it does not modulate — the output is either on or off.
## How it decides [#how-it-decides]
The thermostat keeps the temperature in a band around the target, set by the **Hysteresis**:
* below *target − hysteresis* it turns the heating output **on**,
* above *target + hysteresis* it turns it **off**,
* in between it leaves the output as it is.
With a target of 21 °C and a hysteresis of 0.5 °C the heating comes on at 20.5 °C and goes off at 21.5 °C. A larger hysteresis means fewer relay clicks and a wider swing in temperature.
With more than one sensor the thermostat uses the **average** of the readings it has received.
## Setting one up [#setting-one-up]
1. Open **Settings** → **Control** → **Templates**, click **Add New** and choose **Thermostat**
2. Under **Basic Settings** fill in:
* **Display Name** — e.g. *Living Room Heating*,
* **ID** — leave empty to make it from the name,
* **Area / Room**,
* **Temperature Sensor** — pick one or more temperature sensors (board, 1-Wire, Modbus…),
* **Heating Output** — the output that switches the heating,
* **Target Temperature**
3. Under **Advanced Settings**, if the defaults do not suit you, change **Initial Mode**, **Hysteresis**, **Minimum Temperature** and **Maximum Temperature**
4. Save
| Field | What it does |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Temperature Sensor** | The sensors the thermostat reads. At least one is required. |
| **Heating Output** | The output switched on and off. Required. |
| **Target Temperature** | The temperature to hold, in °C. Default 21. |
| **Initial Mode** | **HEAT** or **OFF** — the mode the thermostat starts in after a restart. Default HEAT. |
| **Hysteresis** | Half the width of the band around the target, in °C. Default 0.5. |
| **Minimum Temperature** / **Maximum Temperature** | The range the target can be set in, from the panel or Home Assistant. Defaults 5 and 35. The target must lie inside it. |
The thermostat does not remember changes across a restart. After the controller restarts — a power cut, an update, a configuration change that needs one — it comes back in the **Initial Mode** with the **Target Temperature** from the configuration, whatever was set on the Templates page or in Home Assistant before.
## Using it [#using-it]
On the **Templates** page each thermostat has a tile with the current temperature (**now**), the target (**target**), and the state: **Heating**, **Idle** or **Off**. The arrows change the target in 0.5 °C steps, and the button turns the thermostat off or back on. See [Templates page](/en/docs/black/current/basic/templates).
In Home Assistant the thermostat is a **climate** entity with the modes *heat* and *off*, the current temperature, and a target settable in 0.5 °C steps between the minimum and maximum.
```yaml title="Thermostat with one sensor"
template:
- id: living_room_heating
name: Living Room Heating
platform: thermostat
sensor_ids:
- temp_living_room
output_id: floor_heating_living
target_temperature: 21.0
area: living_room
```
```yaml title="Two sensors, wider band"
template:
- id: bedroom_heating
name: Bedroom Heating
platform: thermostat
sensor_ids:
- temp_bedroom_window
- temp_bedroom_door
output_id: heater_bedroom
mode: heat
target_temperature: 20.0
hysteresis: 1.0
min_temperature: 15.0
max_temperature: 25.0
```
* **platform** (**Required**) — `thermostat`.
* **id**, **name**, **area** — as for every template, see [Templates](/en/docs/black/current/configuration/template).
* **sensor\_ids** (list of strings) — IDs of the temperature sensors to read. The average of the readings is used. This is what the panel writes.
* **sensor\_id** (string) — a single sensor ID. Used only when `sensor_ids` is missing. One of the two is required.
* **output\_id** (**Required**, string) — ID of the output (or output group) to switch.
* **mode** (*Optional*, `heat` or `off`, default `heat`) — mode after a restart.
* **target\_temperature** (*Optional*, float, default `21.0`) — target after a restart, in °C.
* **hysteresis** (*Optional*, float, default `0.5`) — in °C.
* **min\_temperature** (*Optional*, float, default `5.0`) — lowest target that can be set.
* **max\_temperature** (*Optional*, float, default `35.0`) — highest target that can be set.
A thermostat missing its ID, its sensors or its output, or pointing at an output that does not exist, is skipped when the configuration loads; the reason is in the log.
# Time based cover (/en/docs/black/current/configuration/time-based-cover)
`time_based` is the platform for an ordinary roller blind or shutter that only goes up and down.
The controller works out the position from how long each relay has been on. It works on the Cover and Cover Mix models and on an ordinary relay board.
Set it up in **Settings** → **Control** → **Covers** with **Platform** set to **TIME\_BASED**. Every field and option is described on [Covers](./cover).
```yaml title="Sample configuration"
cover:
- id: living_room_left
name: Living room left
platform: time_based
open_relay: cover_08_up
close_relay: cover_08_down
open_time: 30s
close_time: 30s
restore_state: true
```
Only `open_relay`, `close_relay`, `open_time` and `close_time` are required. Since 1.6 a full open or close runs a little longer into the endstop
(`endstop_overrun`, default 10%) and a reversal waits for the motor to stop (`direction_change_wait_time`, default `500ms`) —
see [How a cover moves](./cover#how-a-cover-moves).
# Venetian blind (/en/docs/black/current/configuration/venetian-blind)
`venetian` is the platform for a venetian blind: it goes up and down, and its slats also tilt.
It works on the Cover and Cover Mix models and on an ordinary relay board.
Set it up in **Settings** → **Control** → **Covers** with **Platform** set to **VENETIAN**. Every field and option is described on [Covers](./cover).
```yaml title="Sample configuration"
cover:
- id: office_blind
name: Office blind
platform: venetian
open_relay: cover_07_up
close_relay: cover_07_down
open_time: 14s
close_time: 14s
tilt_duration: 1200ms
tilt_restore_after_close: true
restore_state: true
```
On top of the four required options, a venetian blind needs `tilt_duration`: how long the slats take to turn from fully closed to fully open.
* A blind at 0% with its slats still open responds to **Close** by shutting the slats. In Home Assistant use **Close tilt** for that — its card greys out Close at 0%.
* If the drive ignores short pulses and small tilt steps do nothing, set `actuator_activation_duration` (for example `200ms`).
See [How a cover moves](./cover#how-a-cover-moves) for the endstop overrun and the pause before reversing.
# Virtual energy sensor (/en/docs/black/current/configuration/virtual_energy_sensor)
Virtual meters are a very interesting aspect of the controller. In the case of connecting a source with constant consumption to a given output, they allow for the creation of a meter based on the active time of that output and a user-defined flow/energy consumption.
## Configuration in the web application [#configuration-in-the-web-application]
Recommended configuration method. Open **Settings** → **Control** → **Virtual Energy Sensors**.
### Sample webui configuration [#sample-webui-configuration]
Currently, there are two types of sensors - an electricity meter and a flow meter.
### Adding a new one [#adding-a-new-one]
| Option Name | Description |
| ----------- | --------------------------------------------------------- |
| Name | Virtual sensor name - Visible in the webui, MQTT, and HA. |
| Custom ID | Allows entering a user-defined device ID. |
| Output | Selection of the output the sensor is associated with. |
| Sensor Type | Allows selection between energy and flow measurement. |
##### Energy: [#energy]
| Option Name | Description |
| ----------- | ----------------------------------------------------- |
| Power usage | Power consumption of the sensor - expressed in Watts. |
| Area | Selection of the appropriate area. |
##### Flow: [#flow]
| Option Name | Description |
| ----------- | --------------------------------------------------------- |
| Flow | Water flow for the sensor - expressed in liters per hour. |
| Area | Selection of the appropriate area. |
## How the total is counted and kept [#how-the-total-is-counted-and-kept]
* While the output is on, the counter adds up energy (Wh) or water (L) and sends the total every 30 seconds.
* **Switching the output off counts the last stretch too**, so a light that was on for 10 seconds is counted.
* **The total survives a restart.** It is kept on the MQTT broker. At start the counter first fetches it from the broker and sends nothing
until it has — even when the broker connection is slow — and the time the output was on in the meantime is added, not lost.
Because the total lives on the MQTT broker, it is only as safe as the broker's stored messages: a broker that is reinstalled, or one that does not save them to disk, starts every counter from 0.
If the broker has no stored total within about 15 seconds of connecting, the counter starts counting from 0 too.
## YAML Editor [#yaml-editor]
### Sample configuration [#sample-configuration]
```yaml title="Sample configuration from config.yaml"
virtual_energy_sensor:
- name: Lighting - test
output_id: OUT_01
sensor_type: power
power_usage: 30
area: test
```
# Virtual switches (/en/docs/black/current/configuration/virtual_switch)
A **virtual switch** is a switch that does not switch anything by itself. It just remembers **on** or **off**.
You use it to describe a *mode* of the house — *Away*, *Evening*, *Guests* — and let other things depend on it:
* a button turns on the hall light **only when "Evening" is on**,
* a schedule runs the presence simulation **only when "Away" is on**,
* turning "Away" on can switch everything off at once.
You flip it in Home Assistant, on the controller's **Outputs** page, from a button or from a schedule.
The controller keeps the state itself — it does not forget it when Home Assistant or the network is down, or after a restart.
## Creating one [#creating-one]
1. Open **Settings** → **Control** → **Virtual switches** and add a new one
2. Type a **Name**, e.g. *Away* — the identifier is made from it (`away`)
3. Optionally add actions:
* **On turn on** — what to do when the switch goes on (e.g. turn off all lights),
* **On turn off** — what to do when it goes off (e.g. put back what "on" changed)
4. Save
Under **More options** you will find:
* **Remember across restarts** (on by default) — after a power cut the switch comes back in the state it had,
* **Start on** — available when *Remember across restarts* is off: the switch then comes up in this state after every restart,
* **Show in Home Assistant** (on by default), the icon and the area.
The actions of a virtual switch run **only when someone changes it** — not when the controller starts up and restores the state,
and not when the network reconnects. Coming back from a power cut never "replays" a mode.
## Using it [#using-it]
**In a condition.** In any action (of a button or a schedule) add a condition *state of virtual switch "Away" is on*.
The action then runs only in that mode.
**From a button.** A button action can set a virtual switch — **ON**, **OFF** or **TOGGLE** — for example a long press on the button by the door arms "Away".
**Day-to-day.** On the **Outputs** page virtual switches have their own group with a toggle, so you do not need to go to Settings.
## In Home Assistant [#in-home-assistant]
Each virtual switch is a regular **switch** in Home Assistant — you can put it on a dashboard or use it in automations.
## Renaming [#renaming]
Because the identifier is made from the name, **renaming a switch changes its identifier**: the old Home Assistant entity becomes unavailable,
the switch starts off, and conditions pointing at the old name stop matching. If you expect to rename it, give it a fixed `id:` in YAML (see below).
A condition that names a virtual switch that does not exist stops the configuration from loading — with the name quoted,
so a typo is caught right away instead of the action quietly running when it should not.
```yaml title="Sample configuration"
virtual_switch:
- name: Away
id: away # optional: keeps the identifier fixed if you rename it
restore_state: true
actions:
on_turn_on:
- action: output
boneio_output: living_room
action_output: "OFF"
event:
- boneio_input: in_12
actions:
long:
- action: virtual_switch
boneio_virtual_switch: away
action_output: TOGGLE
```
The keys are `on_turn_on` / `on_turn_off`, not `on` / `off` — YAML would read bare `on` and `off` as true and false.
# Web Server (/en/docs/black/current/configuration/web)
The panel is served over HTTPS at `https://:8443` by a proxy that runs on the controller.
The settings are in **Settings** → **Access** → **Web Server**. The defaults suit almost every installation.
| Option | Description |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Port** | The port the panel itself runs on behind the proxy (default `8090`). Leave it unless you know why to change it. |
| **Only reachable through the proxy** | Off: the panel also answers on its own port on the network, without encryption. On: only over HTTPS (`:8443`), an SSH tunnel or the USB cable. Saving is refused if HTTPS is not working yet, so you cannot lock yourself out. Takes effect after a restart. New controllers ship with it on. |
| **Cloud Registration (PWA)** | Registers the controller with boneIO Cloud: it gets its own address with a trusted certificate and can be installed as an app. See [HTTPS certificate](/en/docs/black/current/advanced/certificate#option-1-boneio-cloud--the-easiest). |
| **Not interested in cloud registration** | Stops the panel from recommending cloud registration. |
| **PWA App Name** | The name under the app icon on your phone (max 12 characters). |
Panel sign-in is no longer configured here. Since 1.6 accounts are managed in
**Settings** → **Access** → **User accounts** — see [Accounts and access](/en/docs/black/current/basic/accounts).
Embedding the panel in other sites is set in **Settings** → **Access** → **Security**.
```yaml title="Sample configuration"
web:
port: 8090
expose: proxy # all | proxy
cloud:
enabled: false
declined: false
security:
map_tiles: false # allow the map on the Location page
```
`web.auth.allow_anonymous: true` switches accounts off entirely. It is an emergency option only — see
[Accounts and access](/en/docs/black/current/basic/accounts#running-without-accounts).
# Testing dev version (/en/docs/black/current/contribute/dev-version)
The easiest way to try a development version is in the panel: **Settings** → **Maintenance** → **Software update** shows
**Development Version Available** with **Install Dev Version** when one exists. To have Home Assistant offer development versions too,
set **Update channel** to dev in the MQTT settings (Settings → Connections → MQTT). The steps below are for testing in a separate environment over SSH.
## Prepare VENV [#prepare-venv]
You can check current test version here [https://pypi.org/project/boneio/#history](https://pypi.org/project/boneio/#history)
Assume test version is boneio==1.7.0.dev1
```bash
mkdir ~/boneio_test
python3 -m venv ~/boneio_test/venv
source ~/boneio_test/venv/bin/activate
pip3 install boneio==1.7.0.dev1
```
Now prepare your config according to release notes.
# Developer guide (/en/docs/black/current/contribute/developer)
## Prepare VENV [#prepare-venv]
Create fork on [https://github.com/boneIO-eu/app\_black.git](https://github.com/boneIO-eu/app_black.git) and clone it on beagleboard using command below.
replace last line with your forked repo.
```bash
mkdir ~/boneio_development
python3 -m venv ~/boneio_development/venv
source ~/boneio_development/venv/bin/activate
cd ~/boneio_development
git clone git@github.com//app_black.git
```
Below instruction assume you are still in activated venv.
```
source ~/boneio_development/venv/bin/activate
```
## Install Dependencies [#install-dependencies]
```bash
cd app_black
pip3 install -r requirements.txt
pip3 install -e .
```
Now you're ready to add new features to app, prepare config.yaml, test it and create Pull Request later!
## Updating your repo [#updating-your-repo]
If your repo is not up to date with current version you have to `git rebase` it.
To do so, do in your repository:
```bash
git remote add upstream https://github.com/boneIO-eu/app_black.git
```
```bash
git fetch upstream dev
git rebase upstream/dev
```
You might need to rebase your branch.
Read more at Home Assistant developer guide: [https://developers.home-assistant.io/docs/development\_catching\_up/](https://developers.home-assistant.io/docs/development_catching_up/)
# Contribute to boneIO! (/en/docs/black/current/contribute)
## Help us develop your smart home! [#help-us-develop-your-smart-home]
boneIO and the boneIO Black series are constantly evolving. We want the controller to become better and better thanks to software changes. However, our work alone is not enough; we need help testing our new features.
### Test with us! [#test-with-us]
Test developer versions of the controller – you'll get the latest features and help find bugs!
### Add your Modbus device! [#add-your-modbus-device]
Do you own a Modbus device and created an integration for it? Add it, so every user will be able to add it to their system!
# Adding Modbus Device (/en/docs/black/current/contribute/modbus)
This guide explains how to add support for a new Modbus device (sensor, energy meter, etc.) to boneIO Black. The device definition is stored as a JSON file that describes how to read and interpret Modbus registers.
## Web Application - Device Creator [#web-application---device-creator]
The easiest way to create a new Modbus device definition is using the built-in **Modbus Device Creator** in the web interface.
### Accessing the Creator [#accessing-the-creator]
1. Open the boneIO web interface
2. Navigate to **Modbus Helper** section
3. Select the **Creator** tab
### Device Information [#device-information]
| Option | Description |
| ------------------- | --------------------------------------------------------------------------------------------- |
| Model Name | Device model name displayed in Home Assistant (e.g., "SHT30 Temperature and Humidity Sensor") |
| File Name | Name for the JSON file (e.g., "sht30"). If empty, it will be generated from model name |
| Category | Device category: `sensors`, `energy_meters`, `hvac`, `inverters`, or `other` |
| Test Device Address | Modbus address of a connected device for testing registers |
### Adding Registers [#adding-registers]
Click **Add Register** to define each data point you want to read from the device.
| Option | Description |
| ------------- | ------------------------------------------------------------------ |
| Name | Sensor name displayed in Home Assistant |
| Address | Modbus register address (check device documentation) |
| Register Type | `holding` or `input` register |
| Unit | Unit of measurement (e.g., °C, %, V, A, kWh) |
| Value Type | Data type - see table below |
| Device Class | Home Assistant device class (temperature, humidity, voltage, etc.) |
| State Class | `measurement`, `total`, or `total_increasing` |
#### Value Types [#value-types]
| Type | Description | Size |
| ----------- | --------------------------------------- | ----------- |
| U\_WORD | Unsigned 16-bit integer | 1 register |
| S\_WORD | Signed 16-bit integer | 1 register |
| U\_DWORD | Unsigned 32-bit integer (Big Endian) | 2 registers |
| S\_DWORD | Signed 32-bit integer (Big Endian) | 2 registers |
| U\_DWORD\_R | Unsigned 32-bit integer (Little Endian) | 2 registers |
| S\_DWORD\_R | Signed 32-bit integer (Little Endian) | 2 registers |
| FP32 | 32-bit float (Big Endian) | 2 registers |
| FP32\_R | 32-bit float (Little Endian) | 2 registers |
| U\_QWORD | Unsigned 64-bit integer | 4 registers |
| S\_QWORD | Signed 64-bit integer | 4 registers |
### Filters [#filters]
Filters allow you to transform raw register values. Click the **+** button next to "Filters" to add:
* **Multiply** - Multiply the value (e.g., `0.1` to convert 245 → 24.5°C)
* **Offset** - Add/subtract a value
### Testing Registers [#testing-registers]
Before saving, you can test each register by clicking the **▶** button. This reads the actual value from a connected device to verify the configuration is correct.
### Set Base Configuration (Optional) [#set-base-configuration-optional]
Enable these options if the device supports changing its Modbus address or baud rate:
| Option | Description |
| ------------------- | ------------------------------------------------------------- |
| Enable Set Address | Device supports changing Modbus address |
| Address Register | Register address for writing new Modbus address |
| Enable Set Baudrate | Device supports changing baud rate |
| Baudrate Register | Register address for writing baud rate |
| Baudrate Mappings | Map baud rates to register values (e.g., 9600 → 0, 19200 → 1) |
### Exporting [#exporting]
* **Show JSON Preview** - Preview the generated configuration
* **Copy JSON** - Copy to clipboard
* **Download JSON** - Download as a file
## JSON File Structure [#json-file-structure]
Device definitions are stored in `boneio/modbus/devices//` directory.
### Sample Configuration [#sample-configuration]
```json title="sht30.json"
{
"model": "SHT30 Temperature and Humidity Sensor",
"set_base": {
"set_address_address": 256
},
"registers_base": [
{
"base": 1,
"length": 2,
"register_type": "holding",
"registers": [
{
"name": "Temperature",
"address": 1,
"unit_of_measurement": "°C",
"state_class": "measurement",
"device_class": "temperature",
"value_type": "S_WORD",
"filters": [
{ "multiply": 0.1 }
]
},
{
"name": "Humidity",
"address": 2,
"unit_of_measurement": "%",
"state_class": "measurement",
"device_class": "humidity",
"value_type": "S_WORD",
"filters": [
{ "multiply": 0.1 }
]
}
]
}
]
}
```
### Configuration Variables [#configuration-variables]
#### Root Level [#root-level]
| Variable | Required | Description |
| --------------- | -------- | -------------------------------------------------- |
| model | Yes | Model name displayed in Home Assistant |
| set\_base | No | Configuration for changing device address/baudrate |
| registers\_base | Yes | Array of register blocks |
#### set\_base [#set_base]
| Variable | Description |
| --------------------------------- | ----------------------------------------------- |
| set\_address\_address | Register address for writing new Modbus address |
| set\_baudrate.address | Register address for writing baud rate |
| set\_baudrate.possible\_baudrates | Map of baud rate to register value |
#### registers\_base (Block) [#registers_base-block]
| Variable | Description |
| -------------- | ------------------------------------------ |
| base | Starting register address for this block |
| length | Number of registers to read in one request |
| register\_type | `holding` or `input` |
| registers | Array of register definitions |
#### registers (Individual Register) [#registers-individual-register]
| Variable | Required | Description |
| --------------------- | -------- | --------------------------------------------- |
| name | Yes | Sensor name in Home Assistant |
| address | Yes | Register address |
| unit\_of\_measurement | Yes | Unit (°C, %, V, A, etc.) |
| state\_class | Yes | `measurement`, `total`, or `total_increasing` |
| device\_class | No | HA device class |
| value\_type | Yes | Data type (see Value Types table) |
| filters | No | Array of filters to apply |
## Contributing Your Device [#contributing-your-device]
After creating and testing your device definition:
1. Fork the [boneIO repository](https://github.com/boneIO-eu/app_black)
2. Add your JSON file to the appropriate folder:
* `boneio/modbus/devices/sensors/` - sensors (temperature, humidity, distance)
* `boneio/modbus/devices/energy_meters/` - energy meters
* `boneio/modbus/devices/hvac/` - HVAC devices
* `boneio/modbus/devices/inverters/` - inverters
* `boneio/modbus/devices/other/` - other devices
3. Create a Pull Request
Your contribution will help other users with the same device!
# Actions (/en/docs/black/current/install/actions)
## What it's all about? [#what-its-all-about]
Actions are best way to made some simple core automations inside of your controller. With them its possible to made some cricital automations
inside of your boneIO Black.
To make it easy i will give you some example and will describe it:
```yaml
- id: IN_01_living_room1
boneio_input: IN_01
actions:
single:
- action: output
pin: OUT_01_living_room_light_1
double:
- action: output
pin: OUT_02_living_room_light_2
long:
- action: output
pin: OUT_03_living_room_light_3
- id: IN_02_living_room2
boneio_input: IN_02
actions:
single:
- action: output
pin: OUT_04_living_room_light_4
long:
- action: output
pin: OUT_01_living_room_light_1
action_output: off
- action: output
pin: OUT_02_living_room_light_2
action_output: off
- action: output
pin: OUT_03_living_room_light_3
action_output: off
- action: output
pin: OUT_04_living_room_light_4
action_output: off
```
What have we achived? By using just 2 buttons we can independly turn on 4 lights, an by single long click of one of them you can turn all of them off.
In the case of `IN_01_living_room1` its really simple, we define each action fo each action type, in our case for `single` click Living room light 1
for `double` Living room light 2 and for `long` click Living room light 3. The default action for `- action: output` type its `toogle`
So by simple click of the button you will change the state of light from on to off etc.
In the case of button 2 - `IN_02_living_room2` with single click you will change state of Living room light 4. But intresting thing will happen if
you `long` click that button. That will turn off all 4 defined lights in living room. There are many possibilities with actions!
If you want to know more - please check documentation.
# Configure areas (/en/docs/black/current/install/configure-areas)
Areas are rooms or zones that group devices in Home Assistant. The area configuration in boneIO must match the configuration in Home Assistant.
With properly configured areas, you can automatically create a simple dashboard in Home Assistant divided by these areas - all devices from a given area will be automatically grouped together.
## Important information [#important-information]
**Every area name change in Home Assistant requires a name change in the boneIO application!**
Area names must be identical 1:1 with the names in Home Assistant. It's worth configuring areas carefully from the very beginning to avoid problems later.
## How to configure areas? [#how-to-configure-areas]
1. Go to the **Settings** tab
2. Find the **Areas** section
3. Click the **Add area** button or edit an existing one
4. Enter the area name **exactly the same** as in Home Assistant
5. Click **Save**
6. Wait for the application to reload
## Synchronization with Home Assistant [#synchronization-with-home-assistant]
### Before configuring in boneIO [#before-configuring-in-boneio]
1. Open Home Assistant
2. Go to **Settings** → **Areas & zones**
3. Note down the exact names of all areas (case sensitive!)
4. Use the same names in boneIO configuration
### After changing the name in Home Assistant [#after-changing-the-name-in-home-assistant]
If you change an area name in Home Assistant:
1. Open the boneIO interface
2. Go to **Settings** → **Device** → **Areas/Rooms**
3. Edit the corresponding area
4. Change the name to the new one (same as in HA)
5. Save and wait for reload
## Export and Import areas [#export-and-import-areas]
You can transfer area configuration between devices:
1. On the first device: click **Export** in the Areas section
2. Save the YAML file
3. On the second device: click **Import** in the Areas section
4. Load the saved YAML file
5. Save and wait for reload
## Best practices [#best-practices]
* **Plan ahead** - think through area names before starting configuration
* **Use simple names** - avoid special characters and diacritics
* **Be consistent** - use the same naming convention across all devices
* **Document changes** - save an export after each major change as a backup
# Configure binary sensors (/en/docs/black/current/install/configure-binary-sensors)
Binary sensors are ideal for devices with two states: motion sensors, reed switches, flood sensors, etc.
## How to add or edit a binary sensor? [#how-to-add-or-edit-a-binary-sensor]
1. Go to **Settings** → **Control** → **Local Inputs**
2. Click **Add New** or the edit icon next to an existing sensor
3. Fill in the configuration form
## Basic settings [#basic-settings]
### Display Name [#display-name]
Friendly name for the sensor, e.g.:
* `Living Room Motion Sensor`
* `Front Door`
* `Bedroom Window`
This name will be visible in the interface and Home Assistant.
### BoneIO Input [#boneio-input]
Select the physical input from the dropdown:
* `IN_01`, `IN_02`, `IN_03`, ... `IN_56` (depending on model)
**Avoid inputs with limitations** (IN\_01, IN\_02, IN\_09, IN\_10, IN\_19, IN\_20, IN\_21, IN\_29–IN\_34) for reed switches and motion sensors that may be active at controller startup.
### Area / Room [#area--room]
Select an area from the dropdown - the sensor will be automatically assigned to this area in Home Assistant.
### Bounce Time [#bounce-time]
Contact debounce time (default: 120ms). For motion sensors and reed switches, usually no change is needed.
### Device Class [#device-class]
Device class in Home Assistant - affects icon and behavior:
| Device Class | Icon | Use Case |
| ------------- | --------- | ----------------------- |
| **motion** | Motion | Motion sensors |
| **door** | Door | Door reed switches |
| **window** | Window | Window reed switches |
| **opening** | Opening | General opening sensors |
| **moisture** | Water | Flood sensors |
| **smoke** | Smoke | Smoke detectors |
| **gas** | Gas | Gas detectors |
| **occupancy** | Occupancy | Occupancy sensors |
| **vibration** | Vibration | Vibration sensors |
| **tamper** | Tamper | Tamper sensors |
## Options [#options]
### Show in HA [#show-in-ha]
Enable to make the sensor visible in Home Assistant (enabled by default).
### Inverted [#inverted]
Invert sensor logic:
* Normal: active input = sensor ON
* Inverted: active input = sensor OFF
Useful when a reed switch is mounted in reverse.
### Initial Send [#initial-send]
Send sensor state at controller startup.
## Actions - Pressed and Released [#actions---pressed-and-released]
Binary sensors have two action tabs:
### Pressed [#pressed]
Actions executed when the sensor changes to active state (e.g., motion detected, door opened).
### Released [#released]
Actions executed when the sensor changes to inactive state (e.g., no motion, door closed).
## How to add an action? [#how-to-add-an-action]
1. Go to the **Pressed** or **Released** tab
2. Click **Add Action**
3. Select the action type and configure parameters
### Action types [#action-types]
| Action Type | Description |
| ---------------------- | -------------------------------------- |
| **output** | Control an output (light, switch) |
| **cover** | Control a cover |
| **virtual\_switch** | Set a virtual switch (ON, OFF, TOGGLE) |
| **mqtt** | Send an MQTT message |
| **output\_over\_mqtt** | Control an output via MQTT |
| **cover\_over\_mqtt** | Control a cover via MQTT |
| **remote\_output** | Control an output on a remote device |
| **remote\_cover** | Control a cover on a remote device |
Every action can also have conditions (time, date, state, sun) and, on binary sensors, a delay. The full list of types, values and options is in [Actions](/en/docs/black/current/configuration/event#actions).
## Configuration examples [#configuration-examples]
### Example 1: Hallway motion sensor [#example-1-hallway-motion-sensor]
1. **Display Name**: `Hallway Motion Sensor`
2. **BoneIO Input**: `IN_05` (avoid inputs with limitations)
3. **Area / Room**: `Hallway`
4. **Device Class**: `motion`
**Actions:**
* **Pressed**: ON `Hallway Light`
* **Released**: OFF `Hallway Light`
### Example 2: Front door reed switch [#example-2-front-door-reed-switch]
1. **Display Name**: `Front Door`
2. **BoneIO Input**: `IN_06`
3. **Area / Room**: `Entrance`
4. **Device Class**: `door`
5. **Inverted**: ✅ (if reed switch shows reversed)
No actions - just state monitoring in Home Assistant.
### Example 3: Flood sensor [#example-3-flood-sensor]
1. **Display Name**: `Bathroom Flood Sensor`
2. **BoneIO Input**: `IN_07`
3. **Area / Room**: `Bathroom`
4. **Device Class**: `moisture`
**Actions:**
* **Pressed**: OFF `Main Water Valve` (automatic valve closure when water detected)
After saving, the sensor will appear in the table and be available in Home Assistant with the appropriate icon and device class.
# Configure events (/en/docs/black/current/install/configure-events)
Events allow you to assign different actions to a single button depending on the click type.
## How to add or edit an event? [#how-to-add-or-edit-an-event]
1. Go to **Settings** → **Control** → **Local Inputs**
2. Click **Add New** or the edit icon next to an existing event
3. Fill in the configuration form
## Basic settings [#basic-settings]
### Display Name [#display-name]
Friendly name for the event, e.g.:
* `Living Room Button`
* `Bedroom Switch`
* `Doorbell`
This name will be visible in the interface and Home Assistant.
### BoneIO Input [#boneio-input]
Select the physical input from the dropdown:
* `IN_01`, `IN_02`, `IN_03`, ... `IN_56` (depending on model)
Inputs already used by other events or binary sensors are automatically hidden from the list.
### Area / Room [#area--room]
Select an area from the dropdown - the event will be automatically assigned to this area in Home Assistant.
## Actions - click tabs [#actions---click-tabs]
The form has separate tabs for each click type:
### Single (Single click) [#single-single-click]
Actions executed after a single button click.
### Double (Double click) [#double-double-click]
Actions executed after a quick double click.
### Triple (Triple click) [#triple-triple-click]
Actions executed after a triple click.
Triple click must be enabled in advanced settings (disabled by default).
### Long (Long press) [#long-long-press]
Actions executed after holding the button for a specified time.
## How to add an action? [#how-to-add-an-action]
1. Go to the appropriate tab (Single, Double, Triple, Long)
2. Click **Add Action**
3. Select the action type and configure parameters
### Action types [#action-types]
| Action Type | Description |
| ---------------------- | -------------------------------------- |
| **output** | Control an output (light, switch) |
| **cover** | Control a cover |
| **virtual\_switch** | Set a virtual switch (ON, OFF, TOGGLE) |
| **mqtt** | Send an MQTT message |
| **output\_over\_mqtt** | Control an output via MQTT |
| **cover\_over\_mqtt** | Control a cover via MQTT |
| **remote\_output** | Control an output on a remote device |
| **remote\_cover** | Control a cover on a remote device |
Every action can also have conditions (time, date, state, sun). The full list of types, values and options is in [Actions](/en/docs/black/current/configuration/event#actions).
### Output action [#output-action]
The most commonly used action - control an output:
| Parameter | Description |
| ---------- | --------------------------------------------- |
| **Output** | Select output from the list |
| **Action** | TOGGLE (toggle), ON (turn on), OFF (turn off) |
### Cover action [#cover-action]
Control a cover:
| Parameter | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Cover** | Select cover from the list |
| **Action** | TOGGLE, OPEN, CLOSE, STOP, TOGGLE\_OPEN, TOGGLE\_CLOSE, SMART\_TOGGLE; for venetian blinds also TILT, TILT\_OPEN, TILT\_CLOSE |
## Sequences [#sequences]
Sequences are advanced click combinations:
| Sequence | Description |
| ------------------- | ------------------------- |
| **Double → Long** | Double click, then hold |
| **Single → Long** | Single click, then hold |
| **Double → Single** | Double click, then single |
Each sequence can have its own actions and optionally send an MQTT event.
## Advanced settings [#advanced-settings]
Click the **Advanced Settings** tab to access additional options:
### Bounce Time [#bounce-time]
Contact debounce time (default: 30ms). Increase if the button generates false clicks.
### Double Click Duration [#double-click-duration]
Maximum time between clicks for a double click (default: 220ms).
This parameter affects single click delay - the controller waits this time to check if a second click will follow.
### Long Press Duration [#long-press-duration]
Hold time for a long click (default: 400ms).
### Sequence Window Duration [#sequence-window-duration]
Time window for sequences (default: 500ms).
### Sequence Mode [#sequence-mode]
| Mode | Description |
| ------------- | ---------------------------------------------- |
| **Immediate** | Actions executed immediately upon detection |
| **Exclusive** | Waits for sequence completion before executing |
### Enable Triple Click [#enable-triple-click]
Enable triple click support (disabled by default).
## Configuration example [#configuration-example]
**Scenario**: A button in the living room controlling lighting.
1. **Display Name**: `Living Room Button`
2. **BoneIO Input**: `IN_04`
3. **Area / Room**: `Living Room`
**Actions:**
* **Single**: Toggle `Living Room Main Light`
* **Double**: Toggle `Living Room Lamp`
* **Long**: OFF `Living Room Main Light`, OFF `Living Room Lamp` (turn off everything)
After saving, the event will appear in the table and be available in Home Assistant.
# Edit configuration (/en/docs/black/current/install/edit-configuration)
The **Settings** tab contains forms for configuring all controller functions. Here you can configure outputs, inputs, areas, events, and many other options.
## Important configuration rules [#important-configuration-rules]
### Saving changes [#saving-changes]
**Each edit in a given section requires saving and waiting for reload or restart of the application before you start working on the next section.**
After saving changes:
1. Click the **Save** button in the given section
2. Wait for save confirmation
3. Wait for the application to reload or restart
4. Only then proceed to edit the next section
### Export and Import [#export-and-import]
Each configuration section has **Export** and **Import** buttons:
* **Export** - saves the configuration of the given section to a YAML file
* **Import** - loads the configuration from a YAML file
This allows you to:
* Manually copy configuration sections
* Transfer created configurations between devices
* Create backups of individual sections
## Configuration sections [#configuration-sections]
In the Settings tab you will find the following sections:
* **Areas** - defining areas compatible with Home Assistant
* **Outputs** - relay output configuration
* **Covers** - cover and blind configuration
* **Inputs** - digital input configuration
* **Events** - event and automation definitions
* **Binary Sensors** - binary sensor configuration
* **Actions** - action definitions
* And more...
# Events and Binary Sensors (/en/docs/black/current/install/events-and-binary-sensors)
In boneIO Black you have two types of inputs to choose from: **Events** and **Binary Sensors**. The choice depends on what device you're connecting.
## Events - for buttons [#events---for-buttons]
Events are the best choice for **wall switches**. They allow detection of different click types:
| Click Type | Description |
| ------------- | ---------------------------------- |
| **Single** | Single click |
| **Double** | Double click |
| **Triple** | Triple click |
| **Long** | Long press |
| **Sequences** | Combinations (e.g., double → long) |
**Example**: One button can turn on the main light (single), bedside lamp (double), and turn off all lights (long).
**Events have a minimal delay** for single clicks. The controller waits a short time (\~220ms) to check if another click will follow (double/triple). If you need immediate response, use a binary sensor.
## Binary Sensors - for sensors [#binary-sensors---for-sensors]
Binary sensors are the best choice for devices with two states:
| Device | States |
| ------------------ | --------------------------- |
| **Motion sensor** | Motion detected / No motion |
| **Reed switch** | Open / Closed |
| **Flood sensor** | Dry / Wet |
| **Smoke detector** | OK / Alarm |
**Advantages of binary sensors:**
* ✅ Immediate response (no delay)
* ✅ Actions on press (pressed) and release (released)
* ✅ Different device classes (motion, door, window, smoke, etc.)
## Which to choose? [#which-to-choose]
| Device | Input Type |
| ------------------------- | ------------------------------ |
| Wall switch | **Event** |
| Doorbell | **Event** or **Binary Sensor** |
| Motion sensor | **Binary Sensor** |
| Reed switch (door/window) | **Binary Sensor** |
| Flood sensor | **Binary Sensor** |
| Smoke detector | **Binary Sensor** |
## Input limitations [#input-limitations]
Some inputs on boneIO Black **cannot be active at controller startup**. We do not recommend connecting reed switches or motion sensors to them, as they may be active during startup.
| Inputs with limitations |
| ---------------------------------------------- |
| IN\_01, IN\_02 |
| IN\_09, IN\_10 |
| IN\_19, IN\_20, IN\_21 |
| IN\_29, IN\_30, IN\_31, IN\_32, IN\_33, IN\_34 |
For reed switches and motion sensors, use the remaining inputs (IN\_03 to IN\_08, IN\_11 to IN\_18, IN\_22 to IN\_28, and IN\_35 onwards).
# Events vs Binary Sensors (/en/docs/black/current/install/events-vs-binary-sensors)
In boneIO Black you have two types of inputs to choose from: **Events** and **Binary Sensors**. The choice depends on what device you're connecting.
## Events - for buttons [#events---for-buttons]
Events are the best choice for **wall switches**. They allow detection of different click types:
| Click Type | Description |
| ------------- | ---------------------------------- |
| **Single** | Single click |
| **Double** | Double click |
| **Triple** | Triple click |
| **Long** | Long press |
| **Sequences** | Combinations (e.g., double → long) |
**Example**: One button can turn on the main light (single), bedside lamp (double), and turn off all lights (long).
**Events have a minimal delay** for single clicks. The controller waits a short time (\~220ms) to check if another click will follow (double/triple). If you need immediate response, use a binary sensor.
## Binary Sensors - for sensors [#binary-sensors---for-sensors]
Binary sensors are the best choice for devices with two states:
| Device | States |
| ------------------ | --------------------------- |
| **Motion sensor** | Motion detected / No motion |
| **Reed switch** | Open / Closed |
| **Flood sensor** | Dry / Wet |
| **Smoke detector** | OK / Alarm |
**Advantages of binary sensors:**
* ✅ Immediate response (no delay)
* ✅ Actions on press (pressed) and release (released)
* ✅ Different device classes (motion, door, window, smoke, etc.)
## Which to choose? [#which-to-choose]
| Device | Input Type |
| ------------------------- | ------------------------------ |
| Wall switch | **Event** |
| Doorbell | **Event** or **Binary Sensor** |
| Motion sensor | **Binary Sensor** |
| Reed switch (door/window) | **Binary Sensor** |
| Flood sensor | **Binary Sensor** |
| Smoke detector | **Binary Sensor** |
## Input limitations [#input-limitations]
Some inputs on boneIO Black **cannot be active at controller startup**. We do not recommend connecting reed switches or motion sensors to them, as they may be active during startup.
| Inputs with limitations |
| ---------------------------------------------- |
| IN\_01, IN\_02 |
| IN\_09, IN\_10 |
| IN\_19, IN\_20, IN\_21 |
| IN\_29, IN\_30, IN\_31, IN\_32, IN\_33, IN\_34 |
For reed switches and motion sensors, use the remaining inputs (IN\_03 to IN\_08, IN\_11 to IN\_18, IN\_22 to IN\_28, and IN\_35 onwards).
# First-time setup (/en/docs/black/current/install/first-run-wizard)
The first time you open the panel of a new controller, you do not see the panel yet but the **First-time setup** wizard.
It creates the administrator account — the username and password you will sign in with from now on — and helps you get going.
The whole wizard takes a few minutes.
There is no way to skip the wizard. Until it is completed, the controller answers nothing except the wizard itself, so nobody can
change its configuration without a password.
The bar at the top shows how far you are (**Step 2 of 6**, for example). Not every controller sees every step:
| Step | When you see it |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| Start | Always. |
| Account | Always. |
| Which controller is this? | Only if the controller does not yet know which model it is. |
| Import | Only on a controller that still has its factory configuration. |
| Devices | Only on a controller that still has its factory configuration, and only if you did not import a backup. |
| Cloud | Only if boneIO Cloud registration is not already on, and only if you did not import a backup. |
| Done | Always. |
## Start [#start]
The wizard explains that the device has no administrator account yet, and under **What's ahead** lists the steps this controller will go through.
Click **Get started**.
## Account [#account]
Choose the **Username** and **Password** for the panel and type the password again under **Confirm password**.
* the password must be **at least 8 characters** long,
* it must **not contain the username** — the username is visible on the sign-in screen, so a password built from it is easy to guess.
Click **Create account**. From here on there is no way back to this step — the account exists.
The same account also opens the **Node-RED** editor: Node-RED has no accounts of its own, and only panel administrators get in.
**This password is also your SSH password.** On a new controller the wizard sets the same password for the `boneio` user.
Over SSH you always log in as `boneio` (for example `ssh boneio@192.168.1.100`) — the username you typed here is for the panel only.
This happens only once: changing the panel password later does not change the SSH password. For that, use the
[SSH login password](/en/docs/black/current/basic/accounts#ssh-login-password) card in **Settings → Access → User accounts**, or run `passwd` over SSH.
Write the password down somewhere safe.
## Which controller is this? [#which-controller-is-this]
You only see this step if the controller was not told at the factory which model it is. Until you answer, it has no outputs configured.
Pick your model — **32x10A**, **24x16A**, **Cover** or **Cover Mix** — and click **Apply**.
The controller restarts with that model's configuration, which takes up to a minute; the wizard waits and then carries on by itself.
The wizard does not come back to this step, so check the label on the controller first.
{/* SCREENSHOT: en_wizard_board.webp — "Which controller is this?" step with the four models */}
## Import (optional) [#import-optional]
If you are replacing an older boneIO and have a configuration backup from it (a `.tar.gz` file downloaded from
**Settings → Maintenance → Backups** on the old device), drop the file on **Choose a file or drag it here**, or click it to pick the file,
then click **Import configuration**. The controller will take over that configuration after a restart.
Setting up from scratch? Click **Skip**.
If you imported a backup, the Devices and Cloud steps are skipped — the imported configuration already decides them.
## Devices [#devices]
The outputs are already set up for your model. Here you decide what the inputs should do with them:
* **Inputs control outputs** — each input switches one output (a push button turns on a light),
* **Inputs control covers** — pairs of inputs open and close covers,
* **Inputs control covers and outputs** — a mix, on models that have both,
* **Wire nothing — I will do it myself** — leave the inputs empty and configure them later.
Leave **Restore relay and cover state after a restart** on (it is by default) if lights and covers should come back to where they were after a power cut.
Click **Apply**, or **Skip** to leave everything as it is. You can change all of it later in **Settings → Control → Local Inputs**.
## Cloud (optional) [#cloud-optional]
You can register the controller with **boneIO Cloud**. It then gets its own address with a trusted certificate — the browser stops
warning about the connection, and you can install the panel as an app on your phone.
* Registration sends the controller's serial number to boneIO Cloud.
* The controller is still reachable **only on your own network** — nothing is exposed to the internet.
* Your router must not block so-called *DNS rebinding*; if the new address does not open, that is usually the reason.
Click **Enable registration**, or **Skip**. You can turn it on later in **Settings → Access → Web Server**.
After **Enable registration** the controller restarts its HTTPS server with the new certificate. The wizard shows
**Switching the HTTPS server** and holds **Next** while it waits — usually about half a minute, at most three minutes. There is nothing to do, the controller keeps running.
When it is ready, the notice gives you the new address as a link.
If the controller does not know its own network address yet, the wizard says **Registration is saved** instead:
registration starts on the next boot.
## Done [#done]
The wizard confirms **The controller has an owner**, names the account it created, and reminds you that Node-RED takes the same login.
It also says what happened to the SSH password. If it says **The SSH password could not be set**,
SSH login with a password stays closed — contact us on Discord.
How you leave depends on the Cloud step:
* **Without cloud registration**, click **Go to the panel**.
* **With cloud registration**, click **Go to blk….black.boneio.app:8443**. The panel opens at its new address in a new tab.
Sign in there once more with the same password — the browser keeps sign-ins separately for each address.
**Stay at this address** keeps you where you are.
* **If the new address did not answer** (usually DNS rebinding protection on the router), the wizard says so and offers
**Open blk….black.boneio.app:8443 anyway**. The panel keeps working at the current address.
If you imported a configuration or clicked **Apply** in Devices, restart the controller once:
**Settings → Maintenance → Restart and shutdown**. Until then the controller still runs the old configuration.
## Updating from version 1.5? [#updating-from-version-15]
A controller that was already configured before sees a **shorter wizard: Start → Account → Cloud → Done**.
The Cloud step is left out too if cloud registration was already on.
If the 1.5 panel already had a password (`web.auth` in `config.yaml`), there is no wizard at all — sign in with that password.
The wizard only creates the account — your outputs, inputs and actions stay exactly as they were.
If the SSH password of the `boneio` user was still the factory `Black`, the wizard replaces it with your new password too;
if you had already changed it, it is left alone and the wizard says so.
See [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6) for the rest of the checklist.
## Forgot the password? [#forgot-the-password]
Log in over SSH and reset it — see [Accounts and access](/en/docs/black/current/basic/accounts#forgotten-password).
## What's next? [#whats-next]
* [Home Assistant connection](./home-assistant-connection) - connect the controller to Home Assistant
* [Interface navigation](./interface-navigation) - learn about the menu and tabs
* [Accounts and access](/en/docs/black/current/basic/accounts) - add a read-only account for the rest of the household
# Home Assistant Connection (/en/docs/black/current/install/home-assistant-connection)
The boneIO Black controller communicates with Home Assistant via the MQTT protocol. There are two configuration methods: using a local broker or a remote one (located on HA itself).
Additionally, to make managing the controller from Home Assistant easier, we have prepared a special Add-on for you, which gives you instant access to your boneIO.
## Option 1: MQTT Broker on boneIO Black (default) [#option-1-mqtt-broker-on-boneio-black-default]
**This is the easiest way** - the controller has a built-in Mosquitto MQTT broker that is already configured and running.
### Default configuration [#default-configuration]
By default, the controller is connected to the local MQTT broker:
* **Host**: `localhost`
* **Port**: `1883`
* **Username**: `boneio`
* **Topics**: `boneio/` — set automatically
The broker has three accounts: `boneio` (the one the controller itself uses), `homeassistant` and `mqtt` (for your integrations).
On a controller installed with version 1.6 or later **each account has its own random password**, different on every device — there is no shared default password any more.
That means before you connect Home Assistant you **set a password you know** for the `homeassistant` account.
**Set the MQTT password first.** Go to **Settings** → **Services on this controller** → **MQTT broker (local)**,
in the `homeassistant` card type the new password twice (at least 8 characters) and click **Change Password**.
This is the password you will type into Home Assistant below.
If you change the password of the `boneio` user, leave **Also update boneIO's own configuration** switched on —
the controller then saves the new password in its own configuration and reconnects on its own.
Without it, the controller keeps using the old password and goes offline.
### Connecting Home Assistant to the broker on boneIO [#connecting-home-assistant-to-the-broker-on-boneio]
1. **No Mosquitto add-on needed** — with this option the broker already runs on the controller,
so in Home Assistant you only add the MQTT integration.
2. **Add MQTT integration in Home Assistant**:
* Go to **Settings** → **Devices & Services**
* Click **Add Integration** → search for **MQTT**
* Enter the details:
* **Broker**: boneIO controller IP (e.g., `192.168.1.100`)
* **Port**: `1883`
* **Username**: `homeassistant`
* **Password**: the password you just set for `homeassistant`
* Click **Submit**
Every step with Home Assistant screenshots is in [Connecting boneIO Black](/en/docs/home-assistant/boneio-black) in the Home Assistant guide.
3. **Automatic discovery**:
* The boneIO controller will automatically register all devices with Home Assistant
* Devices will appear in **Settings** → **Devices & Services** → **MQTT**
### Encrypting Home Assistant's connection (TLS) [#encrypting-home-assistants-connection-tls]
Optional. By default Home Assistant talks to the broker on boneIO in plain text on port 1883, password included.
On your own home network that is often fine. If the network is shared, or the traffic crosses a VPN, have the broker accept encrypted connections on port **8883**.
Go to **Settings** → **Services on this controller** → **MQTT broker (local)** and scroll to the **Broker encryption (TLS)** card, below the accounts.
1. **Get a certificate.** Click **Make a certificate on this controller**. It is valid for ten years and covers the controller's names, listed under **Valid for**.
Then click **Download the CA (ca.crt) for clients** — Home Assistant needs that file.
If you would rather use your own certificate, open **Upload my own certificate** (the page shows the openssl commands under **How to make certificates with openssl**).
2. **Pick a mode** under **Mode**:
* **Off** — plain MQTT on port 1883 only, as before.
* **TLS beside plain** — TLS on 8883, and 1883 keeps working. Start here.
* **TLS only on the network** — from the network only TLS on 8883. Plain 1883 stays only for programs on the controller itself, boneIO included.
3. **Move Home Assistant to TLS.** In the MQTT integration, choose **Reconfigure**, set port **8883**, open the advanced options,
enable certificate validation with a custom broker certificate and upload `ca.crt`.
As the broker address use the controller's name exactly as it appears under **Valid for**, for example `boneio-1234.local`.
An IP address works only if it is on that list, and an address from DHCP can change.
4. Once Home Assistant and everything else connects on 8883, switch to **TLS only on the network** if you want plain MQTT closed to the network.
**What it costs:**
* **Every mode change restarts the broker**, which briefly disconnects everyone, Home Assistant included. If the broker does not come back with the new settings, the panel puts the previous ones back and says so.
* **TLS only on the network** cuts off anything still on port 1883 from another machine until you move it to 8883. The panel refuses this mode while boneIO itself connects to this broker in plain text by the controller's network address: first set boneIO's MQTT host to `localhost`, or turn on TLS for its own connection.
* **Node-RED on the controller** reaches the broker from Docker's network, not from `localhost`. Before **TLS only on the network**, move its broker node to port 8883 with TLS and `ca.crt`.
* **A new certificate means a new CA.** Every client that trusts the current `ca.crt` must be given the new one, or it refuses the broker.
If the card says this controller's system helper does not manage the broker's TLS yet, go to **Settings** → **System migrations**,
click **Apply pending migrations** and come back.
## Option 2: MQTT Broker on Home Assistant [#option-2-mqtt-broker-on-home-assistant]
You can connect the controller to an MQTT broker located on Home Assistant or another device.
### Configuring the broker in Home Assistant [#configuring-the-broker-in-home-assistant]
1. **Install Mosquitto Broker** (if you don't have it yet):
* Go to **Settings** → **Apps** → **Install app**
* Search for **Mosquitto broker**
* Click **Install** and **Start**
2. **Create an MQTT user**:
* Go to **Settings** → **People** → **Users**
* Click **Add User**
* Fill in the details:
* **Name**: `boneio`
* **Username**: `boneio`
* **Password**: choose a secure password
* Click **Create**
3. **Add MQTT integration** (if you don't have it yet):
* Go to **Settings** → **Devices & Services**
* MQTT should be automatically detected
* If not, click **Add Integration** → **MQTT**
### Configuring MQTT in boneIO controller [#configuring-mqtt-in-boneio-controller]
1. Go to **Settings** → **Connections** → **MQTT**
2. Enter the broker details:
* **Host**: Home Assistant IP (e.g., `192.168.1.50`)
* **Port**: `1883`
* **Username**: `boneio`
* **Password**: password of the created user
3. Click **Save**. A change of only these four fields needs no restart: boneIO reconnects to the new broker straight away
4. Devices will automatically appear in Home Assistant
If that broker accepts TLS, switch on **Encrypt the connection (TLS)** on the same page.
See [Encryption (TLS)](/en/docs/black/current/configuration/communication#encryption-tls).
### Installation of the boneIO Home Assistant Add-on [#installation-of-the-boneio-home-assistant-add-on]
1. Go to **Settings** → **Apps** → **Install app**
2. Click the three dots in the top right corner
3. Select Repositories
4. Add this URL: [https://github.com/boneio-eu/home-assistant-addons](https://github.com/boneio-eu/home-assistant-addons)
5. Click Add
6. Find the desired add-on and click Install
## Communication between boneIO controllers [#communication-between-boneio-controllers]
If you have multiple boneIO Black controllers and want them to execute commands on each other (e.g., a button on one controller turns on a light on another), **all controllers must be connected to the same MQTT broker**.
### Example configuration for multiple controllers: [#example-configuration-for-multiple-controllers]
1. Choose one MQTT broker (e.g., on Home Assistant or on one of the controllers)
2. Connect all controllers to the same broker
3. Each controller publishes under its own serial number (`boneio/blk…`), so there is nothing to set to keep them apart
4. In actions, you can use **Control Remote Output** and **Control Remote Cover** to control devices on other controllers
## Connection verification [#connection-verification]
After proper configuration:
1. In Home Assistant, go to **Settings** → **Devices & Services** → **MQTT**
2. You should see the **boneIO Black** device with all configured outputs, covers, inputs, and sensors
3. All entities will be automatically available in Home Assistant
The controller uses **MQTT Discovery** - all devices are automatically detected by Home Assistant without the need for manual configuration.
## How the controller shows up in Home Assistant [#how-the-controller-shows-up-in-home-assistant]
The controller appears in Home Assistant as one device, under the name set for it in boneIO.
Everything you put in an [area](/en/docs/black/current/configuration/areas) — an output, a cover, an input, a sensor — goes to a separate device
named after the controller and the room, for example **boneIO Black 24x16A - Living room**, and Home Assistant puts that device in the room when it first creates it.
* **Entities stay in their room.** They keep their room device after the controller restarts and after Home Assistant restarts.
* **Moving an entity to another area moves it, nothing more.** It is the same entity under the other room's device, not a new one, so no duplicates appear — not after an update either.
* **Covers keep their Device Class.** A cover set to `shutter` or `blind` is shown as one, not as a plain window.
* **Show in Home Assistant switched off means off.** That entity is not announced to Home Assistant at all, and stays hidden after restarts.
* **Saving a section only touches that section.** Saving inputs, outputs or covers in **Settings** does not remove or freeze entities that belong to other sections.
* **Binary sensors keep their state.** After Home Assistant restarts, a door or motion sensor shows its real state straight away instead of `unknown` — see [Binary Sensors](/en/docs/black/current/configuration/binary).
{/* SCREENSHOT: en_ha_room_devices.webp — Home Assistant, MQTT integration device list with "boneIO Black 24x16A" and "boneIO Black 24x16A - Living room" */}
# Connect to your controller (/en/docs/black/current/install/how-to-connect)
After connecting your controller to the local network, you can access the boneIO web interface through a web browser. This is the most convenient way to configure and monitor your controller.
## Prerequisites [#prerequisites]
* boneIO controller connected to local network via Ethernet cable
* Network with DHCP service enabled (enabled by default on most routers)
* Computer or mobile device on the same local network
* Web browser (Chrome, Firefox, Safari, Edge)
## Step 1: Connect the controller to the network [#step-1-connect-the-controller-to-the-network]
1. Connect an Ethernet cable to the network port of your boneIO controller
2. Connect the other end of the cable to your router or switch
3. Make sure the controller is powered on
The controller will automatically receive an IP address from the DHCP server on your network.
## Step 2: Find the controller's IP address [#step-2-find-the-controllers-ip-address]
There are two ways to find the controller's IP address:
### Option A: Display on the controller [#option-a-display-on-the-controller]
Press the button next to the display on the controller to scroll through the screens:
* the **network** screen shows the controller's **IP address** (plus the network mask and MAC address),
* the **last screen** shows a **QR code** — scan it with your phone and the panel opens straight away, at the right `https://…:8443` address
(or at the controller's own boneIO Cloud address, if you registered it; on a controller upgraded from 1.5 it is `http://…:8090` until you move the panel behind the proxy).
{/* SCREENSHOT: oled_network.webp — photo of the OLED network screen with the IP address */}
{/* SCREENSHOT: oled_qr.webp — photo of the OLED QR code screen */}
Which screens are shown is set in **Settings** → **Device** → **OLED Display**. Both are on in the factory configuration.
### Option B: Router admin panel [#option-b-router-admin-panel]
Log in to your router's admin panel and find the list of connected devices. The boneIO controller will be visible under a name corresponding to its serial number, starting with `blk`, e.g., `blk8c7df0`.
## Step 3: Open the web interface [#step-3-open-the-web-interface]
1. Open a web browser
2. In the address bar, type the controller's IP address with port 8443, e.g., `https://192.168.1.100:8443`
3. Press Enter
Always type `https://` at the start — without it the page will not open.
### The browser warns about the connection — this is expected [#the-browser-warns-about-the-connection--this-is-expected]
The first time you open the panel, the browser shows a warning such as **"Your connection is not private"**.
The connection **is** encrypted; the browser only warns because the certificate was issued by the controller itself,
not by a company the browser knows.
* **Chrome / Edge**: click **Advanced**, then **Proceed to 192.168.1.100 (unsafe)**
* **Firefox**: click **Advanced…**, then **Accept the Risk and Continue**
* **Safari**: click **Show Details**, then **visit this website**
The controller's certificate is valid for six months, so the browser does not ask again every day.
To get rid of the warning for good, see [HTTPS certificate](/en/docs/black/current/advanced/certificate).
## Step 4: Create your administrator account [#step-4-create-your-administrator-account]
A new controller has no owner yet. Instead of the panel you will see the **First-time setup** wizard.
Until the account exists, the controller's display says so: it shows **Setup required**, **Onboarding needed.**,
**Open in a browser:** and the panel's address. The display does not go dark while that notice is up, and the address
appears as soon as the controller gets one from the router (until then the line reads `http://:8090`, which is only a placeholder). The button still steps through the other screens;
after a minute the notice comes back. Once the account is created, the notice goes away by itself within a few seconds.
{/* SCREENSHOT: oled_setup_required.webp — photo of the OLED showing "Setup required" with the panel address */}
For a moment right at power-on, before that notice, the display may show `SETUP REQUIRED - open :8090` —
ignore the port there and use the address from the notice, or `https://…:8443`.
In the wizard you choose a username and password for the panel. It takes about a minute — see
[First-time setup](./first-run-wizard) for every step.
Do this right away. Until an account exists, **whoever on your network completes the wizard first becomes the owner** of the controller.
After the wizard you land in the main panel showing the controller status.
## Troubleshooting [#troubleshooting]
### I can't find the IP address [#i-cant-find-the-ip-address]
* Make sure the Ethernet cable is properly connected
* Check if the network LED on the controller is lit or blinking
* Restart the controller and wait about 30 seconds to obtain an IP address
### The page won't load [#the-page-wont-load]
* Check if your computer is on the same network as the controller
* Make sure you type `https://` before the IP address and `:8443` after it
* Try clearing your browser cache or use incognito mode
* A warning about the certificate is not an error — see Step 3
### The controller doesn't receive an IP address [#the-controller-doesnt-receive-an-ip-address]
If your network doesn't have a DHCP server, you can connect to the controller via USB cable:
1. Connect a USB cable to the USB port of the controller and to your computer
2. Your computer will receive an IP address from the `192.168.7.x` range
3. The controller will be available at `192.168.7.2` — the panel opens at `http://192.168.7.2:8090`
(if it does not open, restart the controller with the cable plugged in)
4. Connect via SSH and configure a static IP address for the `eth0` interface
This guide does not cover the exact network configuration commands.
## What's next? [#whats-next]
After connecting to the controller, you can proceed to:
* [First-time setup](./first-run-wizard) - every step of the wizard explained
* [Home Assistant connection](./home-assistant-connection) - connect the controller to Home Assistant
* [Interface navigation](./interface-navigation) - learn about the menu and tabs in the web interface
* [Update controller](./update-controller) - check if you have the latest software version
* [Configure controller](./edit-configuration) - configure the controller according to your needs
# Software Setup Introduction (/en/docs/black/current/install)
# Software Setup [#software-setup]
This section guides you through the software configuration of your **boneIO Black** device. Proper setup is crucial for integrating the controller with your home automation system - Home Assistant.
Our custom software, built to run on the powerful BeagleBone Black, offers a web interface for initial setup and monitoring.
The following guide is divided into several steps. In the first two, you will learn how to connect to the **boneIO** controller and how to connect the controller to the Home Assistant system. In the following steps, you will learn how to configure and adapt your boneIO to your needs.
# Interface navigation (/en/docs/black/current/install/interface-navigation)
After connecting to the controller, you will see the web interface with a top navigation bar. Below you'll find a description of all available tabs.
On a phone or tablet the same tabs move to a bar at the bottom of the screen — see [On a phone or tablet](#on-a-phone-or-tablet).
## Main menu [#main-menu]
| Tab | Description |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Outputs** | Control relay outputs, covers, and view relay states. |
| **Inputs** | View the state of digital inputs. |
| **Sensors** | Readings from onboard sensors: temperature, current consumption, memory usage, CPU, disk, and Dallas sensors (if connected). |
| **Modbus** | List of connected and configured Modbus devices. |
| **Templates** | Ready-made building blocks such as irrigation. |
| **Diagnostics** | The log, the support bundle and the bus tools (Modbus, I2C, CAN). See [Diagnostics](/en/docs/black/current/basic/logs). |
| **Settings** | Everything you configure, in seven groups — from outputs and schedules to software update, backups and restart. See [Settings](/en/docs/black/current/basic/settings). |
| **Node-RED** | The pre-installed visual automation tool. Shown only when Node-RED is running. |
| **Help** | Link to Discord community and documentation. |
**Where did System, Logs and the YAML editor go?** Since version 1.6 they are all inside the two tabs above:
the old **System** tab is now **Settings → Maintenance**, **Logs** and **Tools** are **Diagnostics**,
and the **YAML editor** is **Settings → Advanced → YAML editor**. Old bookmarks still work — they redirect.
A **read-only** account sees only the first five tabs. Diagnostics, Settings and Node-RED are for administrators — see [Accounts and access](/en/docs/black/current/basic/accounts).
## On a phone or tablet [#on-a-phone-or-tablet]
On a phone, a tablet or a narrow browser window the top bar shows only the
controller's name, and the tabs move to a bar at the bottom, under your thumb:
| Slot | What it opens |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Outputs** | The outputs view |
| **Inputs** | The inputs view |
| **Sensors** or **Templates** | Sensors — or Templates, once you have any; Sensors then moves under **More** |
| **Modbus** | The Modbus view |
| **More** | Everything else: Diagnostics, Settings, Node-RED, Help, and below them the version, serial number and the account you are signed in with |
### Inside the boneIO Dashboard add-on [#inside-the-boneio-dashboard-add-on]
When you open the panel through the **boneIO Dashboard** add-on in Home
Assistant, the bottom bar gets one more slot on the left: **Devices**. It opens
the add-on's device list. To make room, **Sensors** moves under **More**. Opened
through plain Home Assistant ingress, the bar stays as above.
{/* SCREENSHOT: en_bottom_nav_dashboard.webp — the panel inside the boneIO Dashboard add-on on a phone, Devices slot on the left of the bottom bar */}
## Language change [#language-change]
In the top right corner, you'll find flags to change the interface language. Available languages are Polish (PL) and English (EN).
# Naming Inputs (/en/docs/black/current/install/naming-inputs)
# Why should you name them? [#why-should-you-name-them]
Naming your inputs will make working with the controller much easier. It's a lot easier to remember "Bedroom Button1" than "IN\_04", right?
## Events – event entities [#events--event-entities]
Let's start with event entities. Below is the default configuration from the file:
```
~/boneio/event.yaml
```
```yaml
- id: IN_04
boneio_input: IN_04
actions:
single:
- action: output
pin: OUT_04
- id: IN_05
boneio_input: IN_05
actions:
single:
- action: output
pin: OUT_05
- id: IN_06
boneio_input: IN_06
actions:
single:
- action: output
pin: OUT_06
```
How do you name your input? It's very simple!
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | This part of the configuration is the input name, and you can change it freely. There are many naming approaches. For example, you can change the name to `BedroomButton1` or `IN_04_BedroomButton_1`. |
| `boneio_input` | This is the input number that your name refers to. For now, ignore `actions:` – we'll discuss them later. |
Our example looks like this:
```yaml
- id: IN_04_BedroomButton_1
boneio_input: IN_04
actions:
single:
- action: output
pin: OUT_04
```
## Binary (Binary sensor) [#binary-binary-sensor]
Below is the default configuration from the file:
```
~/boneio/binary_sensor.yaml
```
```yaml
- id: IN_01
boneio_input: IN_01
actions:
pressed:
- action: output
pin: OUT_01
- id: IN_02
boneio_input: IN_02
actions:
pressed:
- action: output
pin: OUT_02
```
| Parameter | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | This part of the configuration is the input name, and you can change it freely. There are many naming approaches. For example, you can change the name to `MotionBedroom` or `IN_01_MotionBedroom`. |
| `boneio_input` | This is the input number that your name refers to. For now, ignore `actions:` – we'll discuss them later. |
Our example looks like this:
```yaml
- id: IN_01_MotionBedroom
boneio_input: IN_01
actions:
pressed:
- action: output
pin: OUT_01
```
# Update boneIO (/en/docs/black/current/install/update-controller)
The controller checks for a new version by itself every few hours. You install it with one click —
from Home Assistant or from the controller's own panel.
## Requirements [#requirements]
* The controller must have an internet connection
* You must be signed in to the panel as an **administrator**
* To update from Home Assistant, the controller must be connected to Home Assistant over MQTT
## How to update? [#how-to-update]
### From Home Assistant [#from-home-assistant]
1. In Home Assistant, open **Settings** — available updates are listed at the top,
2. Click the **boneIO Black Firmware** update,
3. Press **Update**,
4. That's all!
### From the web interface [#from-the-web-interface]
1. Open the controller's web interface in your browser
2. Go to **Settings** → **Maintenance** → **Software update**
3. Click **Check for Updates**
4. If a new version is available, read what it changes (**View Release Notes**), then click **Update to \** (for example **Update to 1.6.0**)
The update starts on its own. When it finishes, the application on the controller restarts and the panel reloads.
While the controller is installing and restarting, the panel shows **Update in progress** with the time since it started,
and comes back by itself once the new version is running. If the controller comes back on the old version, the panel says
**The update failed** — the details are in [Diagnostics](/en/docs/black/current/basic/logs).
If your browser shows the old panel after the update, it reloads the new one on its own (**Loading the new version of the panel**);
if it cannot, it asks you to press **Ctrl+Shift+R** (**Cmd+Shift+R** on a Mac).
{/* SCREENSHOT: en_panel_update_in_progress.webp — the "Update in progress" screen with "The controller is installing version …" and the elapsed time */}
**The update does not back up your configuration.** Download a backup first in **Settings → Maintenance → Backups**.
If something is wrong after the update, open **Available Versions** on the same page and install the previous version (the button is **Install**).
## After the update: system migrations [#after-the-update-system-migrations]
Some versions also change settings of the operating system underneath the app — for example firewall rules or SSH hardening.
These changes are called **system migrations**. They run by themselves on the first start after the update; you do not need to do anything.
You can see them in **Settings** → **Maintenance** → **System migrations**.
If a red banner says that **a system update was refused**, the page shows the reason — send it to us
(see [Diagnostics](/en/docs/black/current/basic/logs) for the support bundle).
## Updating from version 1.5? [#updating-from-version-15]
**Update to 1.5.6 first**, then to 1.6. Only 1.5.6 hands the browser over to the new panel cleanly; from older 1.5
versions the old panel may keep coming back after the update until you press **Ctrl+Shift+R**.
Version 1.6 adds accounts, so after the update the panel asks you to create an administrator account first
(unless the 1.5 panel already had a password — then you simply sign in with it).
Follow [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6).
## Important information [#important-information]
* **Do not turn off the controller's power during the update.** A backup power supply is worth having for exactly this — see
[Backup power (UPS)](/en/docs/black/products/black_32x10a/hardware-installation#backup-power-ups--recommended).
* A small update takes a few minutes. Jumping several versions can take over ten minutes, and coming from 1.5 up to an hour,
because the system migrations run on the first start.
* While migrations run, the display shows **Updating** and **Do not power off.** with how far it has got
(**Updating system** with a percentage, if the display is not set up in the configuration). The panel does
not answer until they finish.
* After the update, the application on the controller restarts by itself.
{/* SCREENSHOT: oled_updating.webp — photo of the OLED showing "Updating", "Do not power off." and the percentage */}
## Updating the operating system [#updating-the-operating-system]
Updating boneIO does not update the Debian system and the kernel underneath it. That is a separate card on the same page,
**Operating system** — see [Maintenance → Operating system](/en/docs/black/current/basic/system#operating-system).
Unlike a boneIO update, it does not restart the controller by itself.
## Update via SSH [#update-via-ssh]
If you need to update the controller manually via SSH (e.g., when the web interface update doesn't work), see the [SSH update guide](/en/docs/black/advanced/update-via-ssh).
# Upgrading from 1.5 to 1.6 (/en/docs/black/current/install/upgrade-1-5-to-1-6)
Version 1.6 is the biggest change to the panel so far: it gets accounts and passwords, the settings are reorganised and
several security settings are switched on. Your configuration — outputs, inputs, covers, actions — **stays as it is**.
Going through this list takes about ten minutes, plus the update itself — which can take up to an hour.
Not sure what is new? See [What's new in 1.6](/en/docs/black/whats-new-1-6) first.
## 1. Before the update [#1-before-the-update]
1. **Update to 1.5.6 first.** Only 1.5.6 hands the browser over to the new panel cleanly. From an older 1.5 the old panel
may keep coming back after the update until you press **Ctrl+Shift+R**.
2. **Take a backup.** In the 1.5 panel open the **System** tab, find the **Backup** section and download a backup to your computer.
The update itself does not make one. If you can, also copy the `/home/boneio/boneio` folder over SSH.
3. **Plan up to an hour, and keep the power on.** On a controller coming from 1.5 the update runs system migrations at
start-up. The display and the panel say what is happening. Do not cut the power while it runs — a
[UPS](/en/docs/black/products/black_32x10a/hardware-installation#backup-power-ups--recommended) is the safe way.
4. **Be able to reach the controller physically** — an SD card reader or a serial console. 1.6 changes how boneIO gets
administrator rights on the system. It has been run on our own controllers, but a mistake at this step is the kind
that needs hands on the device to repair.
## 2. Install the update [#2-install-the-update]
In the 1.5 panel: **System** → **Check for Updates** → **Update to 1.6.0**, or install the boneIO update in Home Assistant.
Wait for the controller to restart and finish its migrations — the display shows *Do not power off* and the progress
while they run. See [Update controller](./update-controller).
## 3. Open the panel again — now over HTTPS [#3-open-the-panel-again--now-over-https]
Open `https://:8443` and use this address from now on. An old `http://…:8090` bookmark may still open the panel,
but without encryption — step 5 switches that off.
If the browser warns about the certificate, that is expected — see
[Connect to your boneIO](./how-to-connect#the-browser-warns-about-the-connection--this-is-expected).
## 4. Create the administrator account [#4-create-the-administrator-account]
What you see depends on whether the 1.5 panel had a password:
* **You had a password in `config.yaml` (`web.auth`)** — there is **no wizard**. That account is moved over automatically:
sign in with your old username and password. The SSH password is not changed in this case; step 5 tells you if it is still `Black`.
* **You had no password** — the panel starts with a **short wizard: Start → Account → Done**. Choose a username and password for the panel
(see [First-time setup](./first-run-wizard#account) for the rules). If the SSH password of the `boneio` user was still the factory `Black`,
it becomes your new password as well.
Either way your configuration is not touched.
{/* SCREENSHOT: en_wizard_upgraded.webp — the short wizard on an upgraded controller ("This device already has its configuration…") */}
## 5. Review the security list [#5-review-the-security-list]
Right after signing in the panel shows **Security recommendations** with the number of things to look at.
Click **Review security** (or later: **Settings** → **Access** → **Security**). Each item has a short explanation and,
where the panel can fix it, a button that does it. On a controller upgraded from 1.5 you will usually see:
| Item | What to do |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Old credentials in config.yaml** | Click **Remove it** and confirm — the old password block is removed (a copy of `config.yaml` is kept first). You keep signing in as before. |
| **MQTT broker password** | The controller still connects to its broker with the factory password. Click **Fix**, set a new password for the `boneio` user and leave **Also update boneIO's own configuration** on — the controller reconnects by itself. |
| **SSH login password** | If it is still the factory one, change it in **Settings** → **Access** → **User accounts** → **SSH login password**, with the factory password as the current one. Or log in over SSH as `boneio` and run `passwd`. |
| **Panel served in the clear** | Click **Move behind the proxy** and confirm. After the next restart the panel answers only at `https://…:8443` (and still at `http://192.168.7.2:8090` over a USB cable). The change is refused if HTTPS is not working yet, so you cannot lock yourself out. |
| **HTTPS certificate** | Optional — see [HTTPS certificate](/en/docs/black/current/advanced/certificate) to get rid of the browser warning. |
{/* SCREENSHOT: en_security_after_upgrade.webp — Settings → Access → Security on a controller just upgraded from 1.5, with several outstanding items */}
Not ready now? **Remind me tomorrow** puts the prompt off by a day. Details: [Security](/en/docs/black/current/basic/security).
## 6. Check Home Assistant [#6-check-home-assistant]
* **Entities keep working** — the controller talks to Home Assistant over MQTT, and the update does not change that.
* **Changing the `boneio` broker password (step 5) does not affect Home Assistant** — Home Assistant signs in with its own account, usually `homeassistant`.
* **Worth doing:** the `homeassistant` and `mqtt` accounts on a controller from before 1.6 still have the factory password too.
Change them in **Settings** → **Services on this controller** → **MQTT broker (local)**, and then type the new password in Home Assistant:
**Settings** → **Devices & Services** → **MQTT** → **Configure**. Until you do, Home Assistant shows the boneIO entities as unavailable.
* **The boneIO Black add-on** works without any change.
* **Showing the panel in a dashboard card (iframe)?** Add your Home Assistant address in **Settings** → **Access** → **Security** →
**Embedding this panel in other sites** → **One more address you trust**. Without it the card stays empty.
## 7. Node-RED asks for a password now [#7-node-red-asks-for-a-password-now]
If you use Node-RED, it now asks you to sign in with your **boneIO administrator account**. Your flows are unchanged.
This starts once Node-RED restarts — after the next controller restart, or restart it in **Settings → Services on this controller → Node-RED**.
## 8. Things that moved [#8-things-that-moved]
The **System** tab is gone. Update, backups, restart and factory reset are in **Settings → Maintenance**;
logs and bus tools are in **Diagnostics**; the YAML editor is in **Settings → Advanced**.
See [Interface navigation](./interface-navigation) for the full map.
## 9. Optional: readable names in YAML [#9-optional-readable-names-in-yaml]
In 1.6 entries in the configuration can have a `name:` instead of an `id:` — the identifier is made from the name.
Old files with `id:` keep working, so you do not need to change anything. If you edit YAML by hand and want to switch,
see [What's new in 1.6](/en/docs/black/whats-new-1-6#readable-names-instead-of-identifiers).
## Something went wrong? [#something-went-wrong]
* **Cannot sign in / forgot the password** — reset it over SSH: [Accounts and access](/en/docs/black/current/basic/accounts#forgotten-password).
* **The controller does not start after the update** — the panel opens in recovery mode; see [Troubleshooting](/en/docs/black/current/troubleshooting#recovery-mode).
* **You want to go back** — **Settings** → **Maintenance** → **Software update** → **Available Versions** lets you install an older version.
Talk to us on Discord first: the system changes 1.6 made (for example SSH hardening) stay in place.
# Hardware Installation (/en/docs/black/products/black_24x16a/hardware-installation)
**boneIO Black 24x16A is discontinued.** This guide stays for controllers already installed. The boneIO app supports it as before, including the 1.6 updates. For a new installation see the [current controllers](/en/docs/black#choose-your-controller).
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
***
## DIN Rail Mounting [#din-rail-mounting]
The boneIO ESP controller is designed for mounting on a standard DIN rail (TS35).
1. Hook the upper clips of the enclosure onto the top edge of the DIN rail.
2. Press the lower part of the enclosure firmly until the latches lock onto the rail with a distinct click.
3. Ensure the module is securely mounted.
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 24V DC power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+24V` output of the power supply to the `+` screw terminal on the boneIO.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO.
4. Double-check the connections and polarity before turning on the power supply.
## Backup power (UPS) — recommended [#backup-power-ups--recommended]
**Power boneIO Black from a 24 V DC supply with battery backup** — a UPS or a buffered (DC-UPS) power supply. boneIO Black should see uninterrupted 24 V, even when the mains drops for a moment.
boneIO Black is a small Linux computer. It writes its configuration, logs and — during an update — system packages to its memory card or eMMC, and it has no battery-backed clock. Most of its unexpected restarts are caused by short brownouts on the mains. A few minutes on a battery covers them.
What a UPS gives you:
* **No restart on a mains blip.** Outputs, inputs and automations keep working through short cuts and voltage dips.
* **The right time.** After a power cut the controller does not know the time until its network is up and a time server answers. Until then schedules, sun events and time windows in conditions wait.
* **Safe updates.** A system update can take up to an hour on a controller that has not been updated for a long time. The display and the panel say *Do not power off* — a power cut in the middle of it is the one case that may need hands on the device to repair.
The choice of the unit is yours or your installer's. Two common setups:
* a **DIN-rail 24 V DC-UPS module** (or a power supply with a buffer and battery) in the cabinet, between the power supply and boneIO Black,
* a **230 V UPS** feeding the 24 V power supply.
Either way the wiring to boneIO Black is the one in the picture above: `+24V` to `+` and `GND` to `GND` on the POWER terminal, coming from the UPS side.
Size it for everything on the same 24 V line, not just boneIO Black — relay coils, sensors and other devices powered from it count too.
boneIO Black copes better with a power cut since 1.6: it checks and repairs its file system at start, a damaged boot partition no longer stops it, and an interrupted package install is finished on the next boot. A UPS is still the recommendation — the controller does not shut itself down when the battery runs out, so the UPS is what keeps it running.
## Connect Ethernet [#connect-ethernet]
The device communicates with the network using a built-in Ethernet port, which guarantees a stable and reliable connection. To establish connectivity, connect the module to your network switch using a standard Ethernet (RJ45) cable.
1. Connect ethernet cable to LAN port on your controller.
2. Connect other side of ethernet cable to your network switch.
## Connecting Digital Inputs [#connecting-digital-inputs]
Digital inputs are used to connect buttons and sensors. To change the potential used to control the inputs, use the switch on the casing marked `INPUTS`. By default, the inputs are controlled by ground (GND).
> **IMPORTANT: If you want to change the position of the switch - make sure you do it while the device is turned off!**
1. Connect one of the wires from a momentary switch to the common `GND` (ground) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will short the input to ground, which will be interpreted as an "on" signal.
### Logical diagram of connecting digital input [#logical-diagram-of-connecting-digital-input]
### Example: [#example]
### Example 2: [#example-2]
### Example 3: [#example-3]
## Connecting Relay Outputs (16A) [#connecting-relay-outputs-16a]
The key feature of the 24x16A model is that **each of the 24 relays has its own, galvanically isolated `COM` terminal**. This provides tremendous flexibility and allows for controlling circuits powered from different phases or protected by different residual-current devices (RCDs).
### Protection and Correct Wiring Order [#protection-and-correct-wiring-order]
**It is critical that all overcurrent protection (Miniature Circuit Breakers, MCBs) and residual-current devices (RCDs) are installed in the circuit *before* the boneIO controller.**
The current rating (in Amps) of the overcurrent protection must be sized appropriately for the planned load of the circuit (e.g., the wattage of the loads), but at the same time, it **must not exceed the maximum rated current of the relay, which is 16A**.
The correct current flow for the phase (L) wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> OUT terminal in boneIO
-> Load`
### Example 1: Controlling a standard circuit [#example-1-controlling-a-standard-circuit]
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 16A), to the `COM` terminal of the selected output (e.g., `COM 1`).
2. Connect the wire leading to the **load** (e.g., an outlet) to the `NO` (Normally Open) terminal of the same output (e.g., `OUT 1`).
3. Run the **neutral wire (N)** directly to the load.
### Logical Diagram [#logical-diagram]
### Example 2: Controlling circuits from different phases / RCDs [#example-2-controlling-circuits-from-different-phases--rcds]
Thanks to the separation of the `COM` terminals, you can safely connect circuits from different sources.
### Logical Diagram [#logical-diagram-1]
### Safe Connecting of COM and OUT Terminals [#safe-connecting-of-com-and-out-terminals]
In the boneIO controller, version Cover **every two outputs (e.g., Cover 01 UP and DOWN) share a single common power terminal `COM`**. This means that the phase wire (L) from a single circuit breaker supplies a pair of relays - with hardware interlock.
1. **REMEMBER**, ensure that the relevant circuit breakers in the electrical cabinet **are turned off**.
2. Connect the **phase wire (L)**, coming from the overcurrent protection, to the appropriate COM terminal - tighten it with adequate force.
3. Connect the wire leading to your load (e.g., socket) to **its corresponding output terminal** - tighten it with adequate force.
4. Run the neutral (N) wire directly from the neutral bar to the load.
### Example 2: [#example-2-1]
## Connecting Communication Buses [#connecting-communication-buses]
### I2C Bus [#i2c-bus]
For connecting additional sensors and expanders over short distances.
* Connect the `SDA` line to the `SDA` terminal.
* Connect the `SCL` line to the `SCL` terminal.
* Also, connect the `VCC` and `GND` power for the sensor.
### Analog Inputs ADC [#analog-inputs-adc]
Analog inputs read sensors that give a voltage instead of on/off — level, humidity or pressure transmitters and the like.
boneIO Black has 7 of them, **ADC 1**–**ADC 7**. How they are wired depends on the controller version: controllers from **1.0** have a
**SERVICE** port next to **POWER**, older ones do not.
#### Controllers from version 1.0 (with a SERVICE port) [#controllers-from-version-10-with-a-service-port]
* Every input has its own protected, buffered input stage, so it takes **0–13.8 V** on the terminal — a 0–10 V transmitter
connects without an external divider.
* The terminal marked **X** next to **ADC 1** is **AGND**, the analog ground. Connect the sensor's ground there.
* These controllers have no **ADC PWR** terminal.
* The default filter (**multiply** by 1.8) shows the voltage after the input stage, about 0.13 of the voltage on the terminal.
To read the voltage on the terminal itself, set **multiply** to **13.8**. See [ADC](/en/docs/black/current/configuration/adc).
**Examples:**
* **0–10 V transmitter** (humidity, pressure, level…): **+24V** from the **POWER** terminal to the transmitter's supply,
its output to an ADC terminal, its ground to **X (AGND)**. With **multiply** set to **13.8** the panel shows 0–10 V.
* **NTC 10 kΩ thermometer:** from **+3.3V** (the I²C terminal) through the NTC to an ADC terminal, and a 10 kΩ resistor
from that terminal to **X (AGND)**. The terminal never sees more than 3.3 V. The panel shows a voltage, not a temperature —
the app has no thermistor curve, so convert it in Home Assistant. With **multiply** at **13.8**, the NTC's resistance is
`R = 9.2 kΩ × (3.3 − U) / U`, where `U` is the reading in volts and 9.2 kΩ is the 10 kΩ resistor in parallel with the
input's own 115 kΩ. The temperature follows from the NTC's B value in its datasheet.
* **The same thermometer from +5V:** the NTC takes **+5V** from the **1-WIRE** block instead, the 10 kΩ resistor stays.
A higher supply gives a larger swing per degree, so a finer reading. The terminal never sees more than 5 V, and the
resistance is `R = 9.2 kΩ × (5 − U) / U`. That +5V also powers the 1-Wire sensors; the NTC draws about 0.3 mA.
Ground the sensor on **X (AGND)** rather than on any GND terminal: it is the same ground, but on its own path, so the
current of the relays and the processor does not flow through the wire the voltage is measured against.
#### Controllers before version 1.0 (no SERVICE port) [#controllers-before-version-10-no-service-port]
On these controllers the terminals go straight to the BeagleBone Black processor. **Never apply more than 1.8 V** — a higher voltage
damages it. A sensor with a higher output needs an external voltage divider.
* The sensor takes its power from the **ADC PWR** terminal: **+** is the 1.8 V ADC reference, **GNDA** the analog ground.
The terminal marked **X** is not connected.
* The default filter (**multiply** by 1.8) shows the voltage on the terminal.
The diagram below is for controllers before 1.0.
### 1-Wire Bus [#1-wire-bus]
Popular for connecting temperature sensors (e.g., DS18B20).
* Connect the `DATA` line to the `1-Wire` terminal.
* Also, connect `VCC` and `GND` power.
The maximum length of the bus cable is 20m.
### CAN [#can]
Used for communication with industrial HVAC devices and sensors.
* Connect the `L` line of the bus to the `L` terminal on the boneIO.
* Connect the `H` line of the bus to the `H` terminal on the boneIO.
### Modbus RS485 [#modbus-rs485]
Used for communication with industrial and HVAC devices.
* Connect the `A` line of the bus to the `A` terminal on the boneIO.
* Connect the `B` line of the bus to the `B` terminal on the boneIO.
# Overview and Specification (/en/docs/black/products/black_24x16a/overview)
# boneIO Black 24x16A [#boneio-black-24x16a]
**boneIO Black 24x16A is discontinued.** This guide stays for controllers already installed. The boneIO app supports it as before, including the 1.6 updates. For a new installation see the [current controllers](/en/docs/black#choose-your-controller).
Based on the powerful **BeagleBone Black** and running our **custom software**, the boneIO Black controller offers robust and reliable performance for your smart home.
With 49 digital inputs and 24 relay outputs, a single unit has enough capacity to manage all the automation in an entire house or apartment. This includes lighting and heating systems, as well as controlling entrance and garage gates by providing a pulse to the drive.
The **boneIO Black 24x16A** is a specialized control unit designed to manage high-load electrical circuits. Equipped with **24 powerful 16A relays**, each featuring its **own, galvanically isolated COM terminal**, it provides maximum flexibility and safety for controlling outlets, electric heating, pumps, or other high-power devices.
## Key Features [#key-features]
* **49 digital inputs** for connecting switches, motion sensors, contact sensors and others.
* **24 independent 16A relay outputs** with **full galvanic isolation** (each relay has its own `COM` terminal). for controlling sockets and high-power appliances.
* **7 analog inputs** for integration with analog sensors (e.g., light or wind sensors).
* **Reliable network connection** via an **Ethernet port**.
* **Wide expansion capabilities** thanks to **Modbus, I2C, CAN and 1-Wire** interfaces.
* Built-in **OLED screen** for a quick overview of the device's status.
* Standard **DIN rail mounting (15 modules)**.
## Use Cases [#use-cases]
Thanks to the high load capacity and separation of the relays, the 24x16A model is ideal for:
* Directly controlling electrical outlet circuits throughout a house.
* Managing electric underfloor heating or convector heaters.
* Controlling high-consumption devices such as pumps, fans, motors, or solenoid valves.
* Integration with three-phase power systems.
## Technical Specification [#technical-specification]
| Feature | Value |
| ----------------------- | ------------------------------------------------------------------------ |
| **Module** | BeagleBone Black |
| **Power Supply** | 24V DC |
| **Power Consumption** | 5W - 18W |
| **Digital Inputs** | 49 |
| **Inputs Voltage** | 24V DC |
| **Relay Outputs** | 24 (each with a separate COM) |
| **Max Output Voltage** | 230V AC / 30V DC |
| **Max Output Current** | 16A |
| **Analog Inputs** | 7 (Max 1.8V) |
| **External Interfaces** | Modbus RS485, I2C bus, 1-Wire, CAN (for future use) |
| **Communication** | Ethernet 10/100Mbit, Mini-USB |
| **Dimensions (WxHxD)** | 270mm x 106mm x 57mm (without plugs) / 270mm x 123mm x 57mm (with plugs) |
| **Mounting Width** | 15 DIN modules |
| **Weight** | 900g |
## Connectors and Components Description [#connectors-and-components-description]
1. **Power Supply Connector (+/GND):** Main power supply for the device (24V DC).
2. **OUT Screw Terminals (1-24):** Relay outputs.
3. **Inputs control switch** - inputs can be controlled either by + or GND.
4. **IN Screw Terminals (1-49):** Digital inputs.
5. **I²C bus connector:** I²C bus connector for connecting I²C devices.
6. **CAN bus connector:** CAN bus connector for connecting CAN devices. **For future use**.
7. **Modbus RS485 connector:** Modbus RS485 connector for connecting Modbus devices.
8. **1-Wire bus connector:** 1-Wire bus connector for connecting 1-Wire devices.
9. **ADC Power connector:** Connector for powering up ADC devices.
10. **ADC connector:** ADC connector for connecting analog sensors to get analog reading of voltage.
11. **OLED Screen:** Displays key information about the device's status, such as IP address, connection status, or CPU load.
12. **Control Button:** Located next to the screen, it is used to switch between different views on the OLED display.
13. **USB-mini connector:** USB-mini connector.
14. **Ethernet Port (RJ45):** For connecting to the LAN.
## Quick Start Guide [#quick-start-guide]
1. **Device Installation:** A qualified person must mount the device on a DIN rail.
2. **Offline Verification:** Connect a switch to input **IN01** and a light bulb to output **OUT01**. Press the switch – the bulb should change its state.
3. **Network Connection:** Plug a LAN cable into the RJ45 port.
4. **Accessing the Web Panel:** Find the device's IP address (displayed on the OLED screen or in your router) and enter it into a browser to access the web interface.
## Certificates [#certificates]
* [EU Declaration of Conformity (CE)](https://cdn.boneio.eu/certificates/boneio_black_en.pdf)
## What's Next? [#whats-next]
You can find detailed instructions on the dedicated pages. Go ahead and read it!
# Hardware Installation (/en/docs/black/products/black_32x10a/hardware-installation)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
***
## DIN Rail Mounting [#din-rail-mounting]
The boneIO ESP controller is designed for mounting on a standard DIN rail (TS35).
1. Hook the upper clips of the enclosure onto the top edge of the DIN rail.
2. Press the lower part of the enclosure firmly until the latches lock onto the rail with a distinct click.
3. Ensure the module is securely mounted.
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 24V DC power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+24V` output of the power supply to the `+` screw terminal on the boneIO.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO.
4. Double-check the connections and polarity before turning on the power supply.
## Backup power (UPS) — recommended [#backup-power-ups--recommended]
**Power boneIO Black from a 24 V DC supply with battery backup** — a UPS or a buffered (DC-UPS) power supply. boneIO Black should see uninterrupted 24 V, even when the mains drops for a moment.
boneIO Black is a small Linux computer. It writes its configuration, logs and — during an update — system packages to its memory card or eMMC, and it has no battery-backed clock. Most of its unexpected restarts are caused by short brownouts on the mains. A few minutes on a battery covers them.
What a UPS gives you:
* **No restart on a mains blip.** Outputs, inputs and automations keep working through short cuts and voltage dips.
* **The right time.** After a power cut the controller does not know the time until its network is up and a time server answers. Until then schedules, sun events and time windows in conditions wait.
* **Safe updates.** A system update can take up to an hour on a controller that has not been updated for a long time. The display and the panel say *Do not power off* — a power cut in the middle of it is the one case that may need hands on the device to repair.
The choice of the unit is yours or your installer's. Two common setups:
* a **DIN-rail 24 V DC-UPS module** (or a power supply with a buffer and battery) in the cabinet, between the power supply and boneIO Black,
* a **230 V UPS** feeding the 24 V power supply.
Either way the wiring to boneIO Black is the one in the picture above: `+24V` to `+` and `GND` to `GND` on the POWER terminal, coming from the UPS side.
Size it for everything on the same 24 V line, not just boneIO Black — relay coils, sensors and other devices powered from it count too.
boneIO Black copes better with a power cut since 1.6: it checks and repairs its file system at start, a damaged boot partition no longer stops it, and an interrupted package install is finished on the next boot. A UPS is still the recommendation — the controller does not shut itself down when the battery runs out, so the UPS is what keeps it running.
## SERVICE port [#service-port]
From version 1.0, boneIO Black controllers have a **SERVICE** terminal with three pins: **TX**, **RX** and **GND**. It is the controller's serial console (UART) — a terminal into its Linux system, used for diagnostics and repair when the network or the panel does not answer.
**Do not connect anything to it permanently.** It is for servicing only. There is no **+3.3V** pin: the port does not power the adapter you connect.
## Connect Ethernet [#connect-ethernet]
The device communicates with the network using a built-in Ethernet port, which guarantees a stable and reliable connection. To establish connectivity, connect the module to your network switch using a standard Ethernet (RJ45) cable.
1. Connect ethernet cable to LAN port on your controller.
2. Connect other side of ethernet cable to your network switch.
## Connecting Digital Inputs [#connecting-digital-inputs]
Digital inputs are used to connect buttons and sensors. To change the potential used to control the inputs, use the switch on the casing marked `INPUTS`. By default, the inputs are controlled by ground (GND).
> **IMPORTANT: If you want to change the position of the switch - make sure you do it while the device is turned off!**
1. Connect one of the wires from a momentary switch to the common `GND` (ground) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will short the input to ground, which will be interpreted as an "on" signal.
### Logical diagram of connecting digital input [#logical-diagram-of-connecting-digital-input]
### Example: [#example]
### Example 2: [#example-2]
### Example 3: [#example-3]
## Connecting Relay Outputs (10A) [#connecting-relay-outputs-10a]
The key feature of the 32x10A model is its high output density, integrating 32 relays of 10A each into a remarkably compact form factor. This provides tremendous possibilities for controlling a large number of independent circuits from a single device, saving both space and complexity.
### Protection and Correct Wiring Order [#protection-and-correct-wiring-order]
**It is critical that all overcurrent protection (Miniature Circuit Breakers, MCBs) and residual-current devices (RCDs) are installed in the circuit *before* the boneIO controller.**
The current rating (in Amps) of the overcurrent protection must be sized appropriately for the planned load of the circuit (e.g., the wattage of the lights), but at the same time, it **must not exceed the maximum rated current of the relay, which is 10A**.
The correct current flow for the phase (L) wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> OUT terminal in boneIO
-> Load`
### Example 1: Controlling a standard circuit [#example-1-controlling-a-standard-circuit]
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 10A), to the `COM` terminal of the selected output (e.g., `COM 1` or `COM 2`).
2. Connect the wire leading to the **load** (e.g., an outlet) to the `NO` (Normally Open) terminal of the same output (e.g., `OUT 1`).
3. Run the **neutral wire (N)** directly to the load.
### Logical Diagram [#logical-diagram]
### Safe Connecting of COM and OUT Terminals [#safe-connecting-of-com-and-out-terminals]
In the boneIO controller, version 32x10A **every two outputs (e.g., OUT1 and OUT2) share a single common power terminal `COM`**. This means that the phase wire (L) from a single circuit breaker supplies a pair of relays.
1. **REMEMBER**, ensure that the relevant circuit breakers in the electrical cabinet **are turned off**.
2. Connect the **phase wire (L)**, coming from the overcurrent protection, to the appropriate COM terminal - tighten it with adequate force.
3. Connect the wire leading to your load (e.g., a light bulb) to **its corresponding output terminal** - tighten it with adequate force.
4. Run the neutral (N) wire directly from the neutral bar to the load.
## Connecting Communication Buses [#connecting-communication-buses]
### I2C Bus [#i2c-bus]
For connecting additional sensors and expanders over short distances.
* Connect the `SDA` line to the `SDA` terminal.
* Connect the `SCL` line to the `SCL` terminal.
* Also, connect the `VCC` and `GND` power for the sensor.
### Analog Inputs ADC [#analog-inputs-adc]
Analog inputs read sensors that give a voltage instead of on/off — level, humidity or pressure transmitters and the like.
boneIO Black has 7 of them, **ADC 1**–**ADC 7**. How they are wired depends on the controller version: controllers from **1.0** have a
**SERVICE** port next to **POWER**, older ones do not.
#### Controllers from version 1.0 (with a SERVICE port) [#controllers-from-version-10-with-a-service-port]
* Every input has its own protected, buffered input stage, so it takes **0–13.8 V** on the terminal — a 0–10 V transmitter
connects without an external divider.
* The terminal marked **X** next to **ADC 1** is **AGND**, the analog ground. Connect the sensor's ground there.
* These controllers have no **ADC PWR** terminal.
* The default filter (**multiply** by 1.8) shows the voltage after the input stage, about 0.13 of the voltage on the terminal.
To read the voltage on the terminal itself, set **multiply** to **13.8**. See [ADC](/en/docs/black/current/configuration/adc).
**Examples:**
* **0–10 V transmitter** (humidity, pressure, level…): **+24V** from the **POWER** terminal to the transmitter's supply,
its output to an ADC terminal, its ground to **X (AGND)**. With **multiply** set to **13.8** the panel shows 0–10 V.
* **NTC 10 kΩ thermometer:** from **+3.3V** (the I²C terminal) through the NTC to an ADC terminal, and a 10 kΩ resistor
from that terminal to **X (AGND)**. The terminal never sees more than 3.3 V. The panel shows a voltage, not a temperature —
the app has no thermistor curve, so convert it in Home Assistant. With **multiply** at **13.8**, the NTC's resistance is
`R = 9.2 kΩ × (3.3 − U) / U`, where `U` is the reading in volts and 9.2 kΩ is the 10 kΩ resistor in parallel with the
input's own 115 kΩ. The temperature follows from the NTC's B value in its datasheet.
* **The same thermometer from +5V:** the NTC takes **+5V** from the **1-WIRE** block instead, the 10 kΩ resistor stays.
A higher supply gives a larger swing per degree, so a finer reading. The terminal never sees more than 5 V, and the
resistance is `R = 9.2 kΩ × (5 − U) / U`. That +5V also powers the 1-Wire sensors; the NTC draws about 0.3 mA.
Ground the sensor on **X (AGND)** rather than on any GND terminal: it is the same ground, but on its own path, so the
current of the relays and the processor does not flow through the wire the voltage is measured against.
*A 0–10 V transmitter powered from +24V.*
*An NTC 10 kΩ thermometer powered from +3.3V.*
*The same thermometer powered from +5V.*
#### Controllers before version 1.0 (no SERVICE port) [#controllers-before-version-10-no-service-port]
On these controllers the terminals go straight to the BeagleBone Black processor. **Never apply more than 1.8 V** — a higher voltage
damages it. A sensor with a higher output needs an external voltage divider.
* The sensor takes its power from the **ADC PWR** terminal: **+** is the 1.8 V ADC reference, **GNDA** the analog ground.
The terminal marked **X** is not connected.
* The default filter (**multiply** by 1.8) shows the voltage on the terminal.
The diagram below is for controllers before 1.0.
### 1-Wire Bus [#1-wire-bus]
Popular for connecting temperature sensors (e.g., DS18B20).
* Connect the `DATA` line to the `1-Wire` terminal.
* Also, connect `VCC` and `GND` power.
The maximum length of the bus cable is 20m.
### CAN [#can]
Used for communication with industrial HVAC devices and sensors.
* Connect the `L` line of the bus to the `L` terminal on the boneIO.
* Connect the `H` line of the bus to the `H` terminal on the boneIO.
### Modbus RS485 [#modbus-rs485]
Used for communication with industrial and HVAC devices.
* Connect the `A` line of the bus to the `A` terminal on the boneIO.
* Connect the `B` line of the bus to the `B` terminal on the boneIO.
# Overview and Specification (/en/docs/black/products/black_32x10a/overview)
# boneIO Black 32x10A [#boneio-black-32x10a]
You can buy the controller -> [HERE](https://store.boneio.eu/product/inp-boneio-black-32x10a/?v=288404204e3d)
Based on the powerful **BeagleBone Black** and running our **custom software**, the boneIO Black controller offers robust and reliable performance for your smart home. With 49 digital inputs and 32 relay outputs, a single unit has enough capacity to manage all the automation in an entire house or apartment. This includes lighting and heating systems, as well as controlling entrance and garage gates by providing a pulse to the drive. It's also possible to control blinds (though we offer dedicated controllers for this purpose).
The **boneIO Black 32x10A** is designed to manage lights and some other not electrical demanding devices throughout your home.
## Key Features [#key-features]
* **49 digital inputs** for connecting switches, motion sensors, contact sensors and others.
* **32 relay outputs (10A)** for controlling lights, outlets, valves.
* **7 analog inputs** for integration with analog sensors (e.g., light or wind sensors).
* **Reliable network connection** via an **Ethernet port**.
* **Wide expansion capabilities** thanks to **Modbus, I2C, CAN and 1-Wire** interfaces.
* Built-in **OLED screen** for a quick overview of the device's status.
* Standard **DIN rail mounting (15 modules)**.
## Use Cases [#use-cases]
The boneIO controller is the perfect choice for:
* Comprehensive automation of single-family homes and large apartments.
* Controlling multiple lighting circuits from a single location.
* Integration with an alarm system by collecting signals from sensors.
* Integration with various sensors for advanced automation scenarios.
* Automating HVAC systems (heating, ventilation, air conditioning) thanks to Modbus support.
## Technical Specification [#technical-specification]
| Feature | Value |
| ----------------------- | ------------------------------------------------------------------------ |
| **Module** | BeagleBone Black |
| **Power Supply** | 24V DC |
| **Power Consumption** | 5W - 18W |
| **Digital Inputs** | 49 |
| **Inputs Voltage** | 24V DC |
| **Relay Outputs** | 32 |
| **Max Output Voltage** | 230V AC / 30V DC |
| **Max Output Current** | 10A |
| **Analog Inputs** | 7 (0–13.8 V from version 1.0, 1.8 V at most before) |
| **External Interfaces** | Modbus RS485, I2C bus, 1-Wire, CAN |
| **Communication** | Ethernet 10/100Mbit, Mini-USB |
| **Dimensions (WxHxD)** | 270mm x 106mm x 57mm (without plugs) / 270mm x 123mm x 57mm (with plugs) |
| **Mounting Width** | 15 DIN modules |
| **Weight** | 900g |
## Connectors and Components Description [#connectors-and-components-description]
Controllers from version 1.0 have a **SERVICE** port (TX/RX/GND) between the I²C and POWER connectors, and an **X** printed before the ADC terminals. The panel shows the version too: **Settings** → **Device** → **boneIO**, the **Hardware Version** field. The tab you pick is remembered on the other controllers' pages.
1. **Power Supply Connector (+/GND):** Main power supply for the device (24V DC).
2. **OUT Screw Terminals (1-32):** Relay outputs.
3. **Inputs control switch** - inputs can be controlled either by + or GND.
4. **IN Screw Terminals (1-49):** Digital inputs.
5. **I²C bus connector:** I²C bus connector for connecting I²C devices.
6. **CAN bus connector:** connects boneIO Black controllers to each other and to ESPHome devices running esphome-canopen, see [CAN bus](/en/docs/black/current/configuration/canbus).
7. **Modbus RS485 connector:** Modbus RS485 connector for connecting Modbus devices.
8. **1-Wire bus connector:** 1-Wire bus connector for connecting 1-Wire devices.
9. **SERVICE port (TX/RX/GND):** a UART serial console for servicing. Do not connect anything here permanently, see [SERVICE port](hardware-installation#service-port).
10. **ADC connector (X, ADC 1–7):** 7 analog inputs, 0–13.8 V. The **X** terminal is AGND, the ground of the analog sensors, see [Analog inputs](hardware-installation#analog-inputs-adc).
11. **OLED Screen:** Displays key information about the device's status, such as IP address, connection status, or CPU load.
12. **Control Button:** Located next to the screen, it is used to switch between different views on the OLED display.
13. **USB-mini connector:** USB-mini connector.
14. **Ethernet Port (RJ45):** For connecting to the LAN.
1. **Power Supply Connector (+/GND):** Main power supply for the device (24V DC).
2. **OUT Screw Terminals (1-32):** Relay outputs.
3. **Inputs control switch** - inputs can be controlled either by + or GND.
4. **IN Screw Terminals (1-49):** Digital inputs.
5. **I²C bus connector:** I²C bus connector for connecting I²C devices.
6. **CAN bus connector:** connects boneIO Black controllers to each other and to ESPHome devices running esphome-canopen, see [CAN bus](/en/docs/black/current/configuration/canbus).
7. **Modbus RS485 connector:** Modbus RS485 connector for connecting Modbus devices.
8. **1-Wire bus connector:** 1-Wire bus connector for connecting 1-Wire devices.
9. **ADC PWR connector (+/GND):** power for the analog sensors: VDD\_ADC 1.8 V and GND\_ADC.
10. **ADC connector (ADC 1–7):** 7 analog inputs, 1.8 V at most. The **X** terminal is not connected.
11. **OLED Screen:** Displays key information about the device's status, such as IP address, connection status, or CPU load.
12. **Control Button:** Located next to the screen, it is used to switch between different views on the OLED display.
13. **USB-mini connector:** USB-mini connector.
14. **Ethernet Port (RJ45):** For connecting to the LAN.
## Quick Start Guide [#quick-start-guide]
1. **Device Installation:** A qualified person must mount the device on a DIN rail.
2. **Offline Verification:** Connect a switch to input **IN01** and a light bulb to output **OUT01**. Press the switch – the bulb should change its state.
3. **Network Connection:** Plug a LAN cable into the RJ45 port.
4. **Accessing the Web Panel:** Find the device's IP address (displayed on the OLED screen or in your router) and enter it into a browser to access the web interface.
## Certificates [#certificates]
* [EU Declaration of Conformity (CE)](https://cdn.boneio.eu/certificates/boneio_black_en.pdf)
## What's Next? [#whats-next]
You can find detailed instructions on the dedicated pages. Go ahead and read it!
# Hardware Installation (/en/docs/black/products/black_cover/hardware-installation)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
***
## DIN Rail Mounting [#din-rail-mounting]
The boneIO ESP controller is designed for mounting on a standard DIN rail (TS35).
1. Hook the upper clips of the enclosure onto the top edge of the DIN rail.
2. Press the lower part of the enclosure firmly until the latches lock onto the rail with a distinct click.
3. Ensure the module is securely mounted.
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 24V DC power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+24V` output of the power supply to the `+` screw terminal on the boneIO.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO.
4. Double-check the connections and polarity before turning on the power supply.
## Backup power (UPS) — recommended [#backup-power-ups--recommended]
**Power boneIO Black from a 24 V DC supply with battery backup** — a UPS or a buffered (DC-UPS) power supply. boneIO Black should see uninterrupted 24 V, even when the mains drops for a moment.
boneIO Black is a small Linux computer. It writes its configuration, logs and — during an update — system packages to its memory card or eMMC, and it has no battery-backed clock. Most of its unexpected restarts are caused by short brownouts on the mains. A few minutes on a battery covers them.
What a UPS gives you:
* **No restart on a mains blip.** Outputs, inputs and automations keep working through short cuts and voltage dips.
* **The right time.** After a power cut the controller does not know the time until its network is up and a time server answers. Until then schedules, sun events and time windows in conditions wait.
* **Safe updates.** A system update can take up to an hour on a controller that has not been updated for a long time. The display and the panel say *Do not power off* — a power cut in the middle of it is the one case that may need hands on the device to repair.
The choice of the unit is yours or your installer's. Two common setups:
* a **DIN-rail 24 V DC-UPS module** (or a power supply with a buffer and battery) in the cabinet, between the power supply and boneIO Black,
* a **230 V UPS** feeding the 24 V power supply.
Either way the wiring to boneIO Black is the one in the picture above: `+24V` to `+` and `GND` to `GND` on the POWER terminal, coming from the UPS side.
Size it for everything on the same 24 V line, not just boneIO Black — relay coils, sensors and other devices powered from it count too.
boneIO Black copes better with a power cut since 1.6: it checks and repairs its file system at start, a damaged boot partition no longer stops it, and an interrupted package install is finished on the next boot. A UPS is still the recommendation — the controller does not shut itself down when the battery runs out, so the UPS is what keeps it running.
## SERVICE port [#service-port]
From version 1.0, boneIO Black controllers have a **SERVICE** terminal with three pins: **TX**, **RX** and **GND**. It is the controller's serial console (UART) — a terminal into its Linux system, used for diagnostics and repair when the network or the panel does not answer.
**Do not connect anything to it permanently.** It is for servicing only. There is no **+3.3V** pin: the port does not power the adapter you connect.
## Connect Ethernet [#connect-ethernet]
The device communicates with the network using a built-in Ethernet port, which guarantees a stable and reliable connection. To establish connectivity, connect the module to your network switch using a standard Ethernet (RJ45) cable.
1. Connect ethernet cable to LAN port on your controller.
2. Connect other side of ethernet cable to your network switch.
## Connecting Digital Inputs [#connecting-digital-inputs]
Digital inputs are used to connect buttons and sensors. To change the potential used to control the inputs, use the switch on the casing marked `INPUTS`. By default, the inputs are controlled by ground (GND).
> **IMPORTANT: If you want to change the position of the switch - make sure you do it while the device is turned off!**
1. Connect one of the wires from a momentary switch to the common `GND` (ground) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will short the input to ground, which will be interpreted as an "on" signal.
### Logical diagram of connecting digital input [#logical-diagram-of-connecting-digital-input]
### Example: [#example]
### Example 2: [#example-2]
### Example 3: [#example-3]
## Connecting Relay Outputs (Cover Motors) [#connecting-relay-outputs-cover-motors]
The key feature of the Cover version is that it has 32 relays, which are paired to control up to 16 roller shutter motors. Each pair of relays (e.g., Cover 01`UP`/`DOWN`, Cover 02 `UP`/`DOWN`) is protected by a hardware interlock to prevent simultaneous 'up' and 'down' signals, which protects the motor from damage.
### Protection and Correct Wiring Order [#protection-and-correct-wiring-order]
**It is critical that all overcurrent protection (Miniature Circuit Breakers, MCBs) and residual-current devices (RCDs) are installed in the circuit *before* the boneIO controller.**
The current rating (in Amps) of the overcurrent protection must be sized appropriately for the planned load of the circuit (in this case - cover motors), but at the same time, it **must not exceed the maximum rated current of the relay, which is 10A**.
The correct current flow for the phase (L) wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> UP/DOWN terminal in boneIO
-> COVER`
### Example 1: Controlling a standard cover circuit [#example-1-controlling-a-standard-cover-circuit]
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 10A), to the `COM` terminal of the selected Cover output (e.g., `Cover 01 COM`).
2. Connect the wire leading to the **Cover motor UP** to the `UP` terminal of the same output (e.g., `Cover 01 UP`).
3. Connect the wire leading to the **Cover motor DOWN** to the `DOWN` terminal of the same output (e.g., `Cover 01 DOWN`).
4. Run the **neutral wire (N)** directly to the load (cover engine).
### Logical Diagram [#logical-diagram]
### Safe Connecting of COM and OUT Terminals [#safe-connecting-of-com-and-out-terminals]
In the boneIO controller, version Cover **every two outputs (e.g., Cover 01 UP and DOWN) share a single common power terminal `COM`**. This means that the phase wire (L) from a single circuit breaker supplies a pair of relays - with hardware interlock.
1. **REMEMBER**, ensure that the relevant circuit breakers in the electrical cabinet **are turned off**.
2. Connect the **phase wire (L)**, coming from the overcurrent protection, to the appropriate COM terminal - tighten it with adequate force.
3. Connect the wire leading to your load (e.g., a cover motor) to **its corresponding output terminal** - tighten it with adequate force.
4. Run the neutral (N) wire directly from the neutral bar to the load.
## Connecting Communication Buses [#connecting-communication-buses]
### I2C Bus [#i2c-bus]
For connecting additional sensors and expanders over short distances.
* Connect the `SDA` line to the `SDA` terminal.
* Connect the `SCL` line to the `SCL` terminal.
* Also, connect the `VCC` and `GND` power for the sensor.
### Analog Inputs ADC [#analog-inputs-adc]
Analog inputs read sensors that give a voltage instead of on/off — level, humidity or pressure transmitters and the like.
boneIO Black has 7 of them, **ADC 1**–**ADC 7**. How they are wired depends on the controller version: controllers from **1.0** have a
**SERVICE** port next to **POWER**, older ones do not.
#### Controllers from version 1.0 (with a SERVICE port) [#controllers-from-version-10-with-a-service-port]
* Every input has its own protected, buffered input stage, so it takes **0–13.8 V** on the terminal — a 0–10 V transmitter
connects without an external divider.
* The terminal marked **X** next to **ADC 1** is **AGND**, the analog ground. Connect the sensor's ground there.
* These controllers have no **ADC PWR** terminal.
* The default filter (**multiply** by 1.8) shows the voltage after the input stage, about 0.13 of the voltage on the terminal.
To read the voltage on the terminal itself, set **multiply** to **13.8**. See [ADC](/en/docs/black/current/configuration/adc).
**Examples:**
* **0–10 V transmitter** (humidity, pressure, level…): **+24V** from the **POWER** terminal to the transmitter's supply,
its output to an ADC terminal, its ground to **X (AGND)**. With **multiply** set to **13.8** the panel shows 0–10 V.
* **NTC 10 kΩ thermometer:** from **+3.3V** (the I²C terminal) through the NTC to an ADC terminal, and a 10 kΩ resistor
from that terminal to **X (AGND)**. The terminal never sees more than 3.3 V. The panel shows a voltage, not a temperature —
the app has no thermistor curve, so convert it in Home Assistant. With **multiply** at **13.8**, the NTC's resistance is
`R = 9.2 kΩ × (3.3 − U) / U`, where `U` is the reading in volts and 9.2 kΩ is the 10 kΩ resistor in parallel with the
input's own 115 kΩ. The temperature follows from the NTC's B value in its datasheet.
* **The same thermometer from +5V:** the NTC takes **+5V** from the **1-WIRE** block instead, the 10 kΩ resistor stays.
A higher supply gives a larger swing per degree, so a finer reading. The terminal never sees more than 5 V, and the
resistance is `R = 9.2 kΩ × (5 − U) / U`. That +5V also powers the 1-Wire sensors; the NTC draws about 0.3 mA.
Ground the sensor on **X (AGND)** rather than on any GND terminal: it is the same ground, but on its own path, so the
current of the relays and the processor does not flow through the wire the voltage is measured against.
*A 0–10 V transmitter powered from +24V.*
*An NTC 10 kΩ thermometer powered from +3.3V.*
*The same thermometer powered from +5V.*
#### Controllers before version 1.0 (no SERVICE port) [#controllers-before-version-10-no-service-port]
On these controllers the terminals go straight to the BeagleBone Black processor. **Never apply more than 1.8 V** — a higher voltage
damages it. A sensor with a higher output needs an external voltage divider.
* The sensor takes its power from the **ADC PWR** terminal: **+** is the 1.8 V ADC reference, **GNDA** the analog ground.
The terminal marked **X** is not connected.
* The default filter (**multiply** by 1.8) shows the voltage on the terminal.
The diagram below is for controllers before 1.0.
### 1-Wire Bus [#1-wire-bus]
Popular for connecting temperature sensors (e.g., DS18B20).
* Connect the `DATA` line to the `1-Wire` terminal.
* Also, connect `VCC` and `GND` power.
The maximum length of the bus cable is 20m.
### CAN [#can]
Used for communication with industrial HVAC devices and sensors.
* Connect the `L` line of the bus to the `L` terminal on the boneIO.
* Connect the `H` line of the bus to the `H` terminal on the boneIO.
### Modbus RS485 [#modbus-rs485]
Used for communication with industrial and HVAC devices.
* Connect the `A` line of the bus to the `A` terminal on the boneIO.
* Connect the `B` line of the bus to the `B` terminal on the boneIO.
# Overview and Specification (/en/docs/black/products/black_cover/overview)
# boneIO Black Cover [#boneio-black-cover]
You can buy the controller -> [HERE](https://store.boneio.eu/product/boneio-black-cover/?v=288404204e3d)
Based on the powerful **BeagleBone Black** and running our **custom software**, the boneIO Black controller offers robust and reliable performance for your smart home.
With 49 digital inputs and 16 cover outputs, a single unit has enough capacity to manage all the automation in an entire house or apartment.
**The boneIO Black Cover** is a specialized controller designed for automating roller shutters, blinds, or gates. It features 32 relays paired with a hardware interlock, allowing for the safe control of up to 16 bidirectional motors. The hardware interlock prevents simultaneous activation of the 'up' and 'down' relays for a single motor, protecting it from damage.
For controlling lights and demanding electrical circuits, we offer other dedicated controllers.
## Key Features [#key-features]
* **49 digital inputs** for connecting switches, motion sensors, contact sensors and others.
* **32 relay outputs** paired for controlling **16 roller shutters**.
* **Hardware interlock** for motor protection.
* **7 analog inputs** for integration with analog sensors (e.g., light or wind sensors).
* **Reliable network connection** via an **Ethernet port**.
* **Wide expansion capabilities** thanks to **Modbus, I2C, CAN and 1-Wire** interfaces.
* Built-in **OLED screen** for a quick overview of the device's status.
* Standard **DIN rail mounting (15 modules)**.
## Use Cases [#use-cases]
The boneIO Cover model is the perfect choice for:
* Complete automation of roller shutters in single-family homes and large apartments.
* Centralized control of all blinds from a single point or via an app.
* Creating schedules for automatic opening and closing of shutters based on time or sunlight.
* Integration with an alarm system to automatically close all shutters when the alarm is armed.
## Technical Specification [#technical-specification]
| Feature | Value |
| ----------------------- | ------------------------------------------------------------------------ |
| **Module** | BeagleBone Black |
| **Power Supply** | 24V DC |
| **Power Consumption** | 5W - 18W |
| **Digital Inputs** | 49 |
| **Inputs Voltage** | 24V DC |
| **Relay Outputs** | 16 for blinds |
| **Max Output Voltage** | 230V AC / 30V DC |
| **Max Output Current** | 10A |
| **Analog Inputs** | 7 (0–13.8 V from version 1.0, 1.8 V at most before) |
| **External Interfaces** | Modbus RS485, I2C bus, 1-Wire, CAN |
| **Communication** | Ethernet 10/100Mbit, Mini-USB |
| **Dimensions (WxHxD)** | 270mm x 106mm x 57mm (without plugs) / 270mm x 123mm x 57mm (with plugs) |
| **Mounting Width** | 15 DIN modules |
| **Weight** | 900g |
## Connectors and Components Description [#connectors-and-components-description]
Controllers from version 1.0 have a **SERVICE** port (TX/RX/GND) between the I²C and POWER connectors, and an **X** printed before the ADC terminals. The panel shows the version too: **Settings** → **Device** → **boneIO**, the **Hardware Version** field. The tab you pick is remembered on the other controllers' pages.
1. **Power Supply Connector (+/GND):** Main power supply for the device (24V DC).
2. **Cover Up/Down Screw Terminals (1-16):** Cover outputs, grouped in pairs for cover control.
3. **Inputs control switch** - inputs can be controlled either by + or GND.
4. **IN Screw Terminals (1-49):** Digital inputs.
5. **I²C bus connector:** I²C bus connector for connecting I²C devices.
6. **CAN bus connector:** connects boneIO Black controllers to each other and to ESPHome devices running esphome-canopen, see [CAN bus](/en/docs/black/current/configuration/canbus).
7. **Modbus RS485 connector:** Modbus RS485 connector for connecting Modbus devices.
8. **1-Wire bus connector:** 1-Wire bus connector for connecting 1-Wire devices.
9. **SERVICE port (TX/RX/GND):** a UART serial console for servicing. Do not connect anything here permanently, see [SERVICE port](hardware-installation#service-port).
10. **ADC connector (X, ADC 1–7):** 7 analog inputs, 0–13.8 V. The **X** terminal is AGND, the ground of the analog sensors, see [Analog inputs](hardware-installation#analog-inputs-adc).
11. **OLED Screen:** Displays key information about the device's status, such as IP address, connection status, or CPU load.
12. **Control Button:** Located next to the screen, it is used to switch between different views on the OLED display.
13. **USB-mini connector:** USB-mini connector.
14. **Ethernet Port (RJ45):** For connecting to the LAN.
1. **Power Supply Connector (+/GND):** Main power supply for the device (24V DC).
2. **Cover Up/Down Screw Terminals (1-16):** Cover outputs, grouped in pairs for cover control.
3. **Inputs control switch** - inputs can be controlled either by + or GND.
4. **IN Screw Terminals (1-49):** Digital inputs.
5. **I²C bus connector:** I²C bus connector for connecting I²C devices.
6. **CAN bus connector:** connects boneIO Black controllers to each other and to ESPHome devices running esphome-canopen, see [CAN bus](/en/docs/black/current/configuration/canbus).
7. **Modbus RS485 connector:** Modbus RS485 connector for connecting Modbus devices.
8. **1-Wire bus connector:** 1-Wire bus connector for connecting 1-Wire devices.
9. **ADC PWR connector (+/GND):** power for the analog sensors: VDD\_ADC 1.8 V and GND\_ADC.
10. **ADC connector (ADC 1–7):** 7 analog inputs, 1.8 V at most. The **X** terminal is not connected.
11. **OLED Screen:** Displays key information about the device's status, such as IP address, connection status, or CPU load.
12. **Control Button:** Located next to the screen, it is used to switch between different views on the OLED display.
13. **USB-mini connector:** USB-mini connector.
14. **Ethernet Port (RJ45):** For connecting to the LAN.
## Quick Start Guide [#quick-start-guide]
1. **Device Installation:** A qualified person must mount the device on a DIN rail.
2. **Network Connection:** Plug a LAN cable into the RJ45 port.
3. **Accessing the Web Panel:** Find the device's IP address (displayed on the OLED screen or in your router) and enter it into a browser to access the web interface.
4. **Estimate Shutter Movement Time:** Measure the time it takes for the shutter to fully open or close.
5. **Connect the Shutter:** Turn off the shutter's circuit breaker. Connect the shutter motor to the `Cover01 Up/Down` outputs.
6. **Edit cover.yaml file:** Set the estimated movement time in the configuration file and save it.
7. **Test the Shutter:** Run the shutter from the web panel to verify the configuration.
## Certificates [#certificates]
* [EU Declaration of Conformity (CE)](https://cdn.boneio.eu/certificates/boneio_black_en.pdf)
## What's Next? [#whats-next]
You can find detailed instructions on the dedicated pages. Go ahead and read it!
# Hardware Installation (/en/docs/black/products/black_cover_mix/hardware-installation)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
***
## DIN Rail Mounting [#din-rail-mounting]
The boneIO ESP controller is designed for mounting on a standard DIN rail (TS35).
1. Hook the upper clips of the enclosure onto the top edge of the DIN rail.
2. Press the lower part of the enclosure firmly until the latches lock onto the rail with a distinct click.
3. Ensure the module is securely mounted.
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 24V DC power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+24V` output of the power supply to the `+` screw terminal on the boneIO.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO.
4. Double-check the connections and polarity before turning on the power supply.
## Backup power (UPS) — recommended [#backup-power-ups--recommended]
**Power boneIO Black from a 24 V DC supply with battery backup** — a UPS or a buffered (DC-UPS) power supply. boneIO Black should see uninterrupted 24 V, even when the mains drops for a moment.
boneIO Black is a small Linux computer. It writes its configuration, logs and — during an update — system packages to its memory card or eMMC, and it has no battery-backed clock. Most of its unexpected restarts are caused by short brownouts on the mains. A few minutes on a battery covers them.
What a UPS gives you:
* **No restart on a mains blip.** Outputs, inputs and automations keep working through short cuts and voltage dips.
* **The right time.** After a power cut the controller does not know the time until its network is up and a time server answers. Until then schedules, sun events and time windows in conditions wait.
* **Safe updates.** A system update can take up to an hour on a controller that has not been updated for a long time. The display and the panel say *Do not power off* — a power cut in the middle of it is the one case that may need hands on the device to repair.
The choice of the unit is yours or your installer's. Two common setups:
* a **DIN-rail 24 V DC-UPS module** (or a power supply with a buffer and battery) in the cabinet, between the power supply and boneIO Black,
* a **230 V UPS** feeding the 24 V power supply.
Either way the wiring to boneIO Black is the one in the picture above: `+24V` to `+` and `GND` to `GND` on the POWER terminal, coming from the UPS side.
Size it for everything on the same 24 V line, not just boneIO Black — relay coils, sensors and other devices powered from it count too.
boneIO Black copes better with a power cut since 1.6: it checks and repairs its file system at start, a damaged boot partition no longer stops it, and an interrupted package install is finished on the next boot. A UPS is still the recommendation — the controller does not shut itself down when the battery runs out, so the UPS is what keeps it running.
## SERVICE port [#service-port]
From version 1.0, boneIO Black controllers have a **SERVICE** terminal with three pins: **TX**, **RX** and **GND**. It is the controller's serial console (UART) — a terminal into its Linux system, used for diagnostics and repair when the network or the panel does not answer.
**Do not connect anything to it permanently.** It is for servicing only. There is no **+3.3V** pin: the port does not power the adapter you connect.
## Connect Ethernet [#connect-ethernet]
The device communicates with the network using a built-in Ethernet port, which guarantees a stable and reliable connection. To establish connectivity, connect the module to your network switch using a standard Ethernet (RJ45) cable.
1. Connect ethernet cable to LAN port on your controller.
2. Connect other side of ethernet cable to your network switch.
## Connecting Digital Inputs [#connecting-digital-inputs]
Digital inputs are used to connect buttons and sensors. To change the potential used to control the inputs, use the switch on the casing marked `INPUTS`. By default, the inputs are controlled by ground (GND).
> **IMPORTANT: If you want to change the position of the switch - make sure you do it while the device is turned off!**
1. Connect one of the wires from a momentary switch to the common `GND` (ground) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will short the input to ground, which will be interpreted as an "on" signal.
### Logical diagram of connecting digital input [#logical-diagram-of-connecting-digital-input]
### Example: [#example]
### Example 2: [#example-2]
### Example 3: [#example-3]
## Connecting Relay Outputs [#connecting-relay-outputs]
The key feature of the Covermix version is that it has 32 relays in total, but half of them (16) are are paired to control up to 8 roller shutter motors. Each pair of relays (e.g., Cover 01`UP`/`DOWN`, Cover 02 `UP`/`DOWN`) is protected by a hardware interlock to prevent simultaneous 'up' and 'down' signals, which protects the motor from damage. The rest of relays (16) are classic 10A relays which are usually used in lighting circuits. This provides tremendous possibilities for controlling a large number of independent circuits from a single device, saving both space and complexity.
### Protection and Correct Wiring Order [#protection-and-correct-wiring-order]
**It is critical that all overcurrent protection (Miniature Circuit Breakers, MCBs) and residual-current devices (RCDs) are installed in the circuit *before* the boneIO controller.**
The current rating (in Amps) of the overcurrent protection must be sized appropriately for the planned load of the circuit (e.g. cover motors, lighting), but at the same time, it **must not exceed the maximum rated current of the relay, which is 10A**.
The correct current flow for the phase (L) for covers - wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> UP/DOWN terminal in boneIO
-> COVER`
The correct current flow for the phase (L) for relays - wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> OUT terminal in boneIO
-> Load`
### Part 1: Connecting Cover Outputs (OUT1 - OUT16) Cover 1-8 [#part-1-connecting-cover-outputs-out1---out16-cover-1-8]
These outputs are designed to control bidirectional 230V AC motors for roller shutters or blinds. They are grouped in pairs (e.g., OUT1/OUT2, OUT3/OUT4) and feature a **hardware interlock** to prevent the motor from being damaged.
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 10A), to the `COM` terminal of the selected Cover output (e.g., `Cover 01 COM`).
2. Connect the wire leading to the **Cover motor UP** to the `UP` terminal of the same output (e.g., `Cover 01 UP`).
3. Connect the wire leading to the **Cover motor DOWN** to the `DOWN` terminal of the same output (e.g., `Cover 01 DOWN`).
4. Run the **neutral wire (N)** directly to the load (cover engine).
### Logical diagram: [#logical-diagram]
### Part 2: Connecting Relay Outputs (OUT17 - OUT32) [#part-2-connecting-relay-outputs-out17---out32]
These are standard relay outputs for general-purpose use, such as controlling lighting.
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 10A), to the `COM` terminal of the selected output (e.g., `COM9` for `OUT17` and `OUT18`).
2. Connect the wire leading to the **load** (e.g., a lamp) to the corresponding output terminal (e.g., `OUT17`).
3. Run the **neutral wire (N)** directly to the load.
### Logical Diagram [#logical-diagram-1]
### Safe Connecting of COM and OUT Terminals [#safe-connecting-of-com-and-out-terminals]
In the boneIO controller, version Covermix **every two outputs (e.g., Cover 01 UP, DOWN) and also outputs dedicated for lights (e. g. OUT17, OUT18) share a single common power terminal `COM`**. This means that the phase wire (L) from a single circuit breaker supplies a pair of relays - with hardware interlock.
1. **REMEMBER**, ensure that the relevant circuit breakers in the electrical cabinet **are turned off**.
2. Connect the **phase wire (L)**, coming from the overcurrent protection, to the appropriate COM terminal - tighten it with adequate force.
3. Connect the wire leading to your load (e.g., cover motor, a light bulb) to **its corresponding output terminal** - tighten it with adequate force.
4. Run the neutral (N) wire directly from the neutral bar to the load.
### Part 1: Connecting Cover Outputs Cover 1-8 (OUT1 - OUT16) [#part-1-connecting-cover-outputs-cover-1-8-out1---out16]
### Part 2: Connecting Relay Outputs (OUT17 - OUT32) [#part-2-connecting-relay-outputs-out17---out32-1]
## Connecting Communication Buses [#connecting-communication-buses]
### I2C Bus [#i2c-bus]
For connecting additional sensors and expanders over short distances.
* Connect the `SDA` line to the `SDA` terminal.
* Connect the `SCL` line to the `SCL` terminal.
* Also, connect the `VCC` and `GND` power for the sensor.
### Analog Inputs ADC [#analog-inputs-adc]
Analog inputs read sensors that give a voltage instead of on/off — level, humidity or pressure transmitters and the like.
boneIO Black has 7 of them, **ADC 1**–**ADC 7**. How they are wired depends on the controller version: controllers from **1.0** have a
**SERVICE** port next to **POWER**, older ones do not.
#### Controllers from version 1.0 (with a SERVICE port) [#controllers-from-version-10-with-a-service-port]
* Every input has its own protected, buffered input stage, so it takes **0–13.8 V** on the terminal — a 0–10 V transmitter
connects without an external divider.
* The terminal marked **X** next to **ADC 1** is **AGND**, the analog ground. Connect the sensor's ground there.
* These controllers have no **ADC PWR** terminal.
* The default filter (**multiply** by 1.8) shows the voltage after the input stage, about 0.13 of the voltage on the terminal.
To read the voltage on the terminal itself, set **multiply** to **13.8**. See [ADC](/en/docs/black/current/configuration/adc).
**Examples:**
* **0–10 V transmitter** (humidity, pressure, level…): **+24V** from the **POWER** terminal to the transmitter's supply,
its output to an ADC terminal, its ground to **X (AGND)**. With **multiply** set to **13.8** the panel shows 0–10 V.
* **NTC 10 kΩ thermometer:** from **+3.3V** (the I²C terminal) through the NTC to an ADC terminal, and a 10 kΩ resistor
from that terminal to **X (AGND)**. The terminal never sees more than 3.3 V. The panel shows a voltage, not a temperature —
the app has no thermistor curve, so convert it in Home Assistant. With **multiply** at **13.8**, the NTC's resistance is
`R = 9.2 kΩ × (3.3 − U) / U`, where `U` is the reading in volts and 9.2 kΩ is the 10 kΩ resistor in parallel with the
input's own 115 kΩ. The temperature follows from the NTC's B value in its datasheet.
* **The same thermometer from +5V:** the NTC takes **+5V** from the **1-WIRE** block instead, the 10 kΩ resistor stays.
A higher supply gives a larger swing per degree, so a finer reading. The terminal never sees more than 5 V, and the
resistance is `R = 9.2 kΩ × (5 − U) / U`. That +5V also powers the 1-Wire sensors; the NTC draws about 0.3 mA.
Ground the sensor on **X (AGND)** rather than on any GND terminal: it is the same ground, but on its own path, so the
current of the relays and the processor does not flow through the wire the voltage is measured against.
*A 0–10 V transmitter powered from +24V.*
*An NTC 10 kΩ thermometer powered from +3.3V.*
*The same thermometer powered from +5V.*
#### Controllers before version 1.0 (no SERVICE port) [#controllers-before-version-10-no-service-port]
On these controllers the terminals go straight to the BeagleBone Black processor. **Never apply more than 1.8 V** — a higher voltage
damages it. A sensor with a higher output needs an external voltage divider.
* The sensor takes its power from the **ADC PWR** terminal: **+** is the 1.8 V ADC reference, **GNDA** the analog ground.
The terminal marked **X** is not connected.
* The default filter (**multiply** by 1.8) shows the voltage on the terminal.
The diagram below is for controllers before 1.0.
### 1-Wire Bus [#1-wire-bus]
Popular for connecting temperature sensors (e.g., DS18B20).
* Connect the `DATA` line to the `1-Wire` terminal.
* Also, connect `VCC` and `GND` power.
The maximum length of the bus cable is 20m.
### CAN [#can]
Used for communication with industrial HVAC devices and sensors.
* Connect the `L` line of the bus to the `L` terminal on the boneIO.
* Connect the `H` line of the bus to the `H` terminal on the boneIO.
### Modbus RS485 [#modbus-rs485]
Used for communication with industrial and HVAC devices.
* Connect the `A` line of the bus to the `A` terminal on the boneIO.
* Connect the `B` line of the bus to the `B` terminal on the boneIO.
# Overview and Specification (/en/docs/black/products/black_cover_mix/overview)
# boneIO Black Cover Mix [#boneio-black-cover-mix]
You can buy the controller -> [HERE](https://store.boneio.eu/product/boneio-black-cover-mix/?v=288404204e3d)
Based on the powerful **BeagleBone Black** and running our **custom software**, the boneIO Black controller offers robust and reliable performance for your smart home.
With 49 digital inputs 8 blind outputs, and 16 relay outputs, a single unit has enough capacity to manage all the automation in an entire house or apartment. This includes lighting and heating systems, as well as controlling entrance and garage gates by providing a pulse to the drive. It's also possible to control blinds though its build in blind outputs.
The **boneIO Black Cover Mix** is a versatile controller that combines the features of a standard relay module with a specialized shutter controller. It features 32 relays, where 16 are paired with a hardware interlock for controlling up to 8 bidirectional motors (e.g., roller shutters), and the remaining 16 relays can be used for general purposes, such as controlling lighting circuits.
## Key Features [#key-features]
* **49 digital inputs** for connecting switches, motion sensors, contact sensors and others.
* **Hybrid Outputs:** 32 relays in total, including 8 pairs with a **hardware interlock (motor protection)** for controlling **8 roller shutters** and **16 individual relays (10A)** for general use.
* **7 analog inputs** for integration with analog sensors (e.g., light or wind sensors).
* **Reliable network connection** via an **Ethernet port**.
* **Wide expansion capabilities** thanks to **Modbus, I2C, CAN and 1-Wire** interfaces.
* Built-in **OLED screen** for a quick overview of the device's status.
* Standard **DIN rail mounting (15 modules)**.
## Use Cases [#use-cases]
The boneIO Cover Mix model is perfect choice for:
* Comprehensive automation of roller shutters and lighting in single-family homes and large apartments.
* Creating advanced scenes combining shutter control and lighting.
* Integration with an alarm system to automatically close all shutters when the alarm is armed.
* Integration with various sensors for advanced automation scenarios.
* Automating HVAC systems (heating, ventilation, air conditioning) thanks to Modbus support.
## Technical Specification [#technical-specification]
| Feature | Value |
| ----------------------- | ------------------------------------------------------------------------ |
| **Module** | BeagleBone Black |
| **Power Supply** | 24V DC |
| **Power Consumption** | 5W - 18W |
| **Digital Inputs** | 49 |
| **Inputs Voltage** | 24V DC |
| **Relay Outputs** | 8 for blinds, 16 for lighting |
| **Max Output Voltage** | 230V AC / 30V DC |
| **Max Output Current** | 10A |
| **Analog Inputs** | 7 (0–13.8 V from version 1.0, 1.8 V at most before) |
| **External Interfaces** | Modbus RS485, I2C bus, 1-Wire, CAN |
| **Communication** | Ethernet 10/100Mbit, Mini-USB |
| **Dimensions (WxHxD)** | 270mm x 106mm x 57mm (without plugs) / 270mm x 123mm x 57mm (with plugs) |
| **Mounting Width** | 15 DIN modules |
| **Weight** | 900g |
## Connectors and Components Description [#connectors-and-components-description]
Controllers from version 1.0 have a **SERVICE** port (TX/RX/GND) between the I²C and POWER connectors, and an **X** printed before the ADC terminals. The panel shows the version too: **Settings** → **Device** → **boneIO**, the **Hardware Version** field. The tab you pick is remembered on the other controllers' pages.
1. **Power Supply Connector (+/GND):** Main power supply for the device (24V DC).
2. **OUT Screw Terminals:** Top part **Cover Up/Down for cover 1-8** lower part **Relay outputs 17-32**.
3. **Inputs control switch** - inputs can be controlled either by + or GND.
4. **IN Screw Terminals (1-49):** Digital inputs.
5. **I²C bus connector:** I²C bus connector for connecting I²C devices.
6. **CAN bus connector:** connects boneIO Black controllers to each other and to ESPHome devices running esphome-canopen, see [CAN bus](/en/docs/black/current/configuration/canbus).
7. **Modbus RS485 connector:** Modbus RS485 connector for connecting Modbus devices.
8. **1-Wire bus connector:** 1-Wire bus connector for connecting 1-Wire devices.
9. **SERVICE port (TX/RX/GND):** a UART serial console for servicing. Do not connect anything here permanently, see [SERVICE port](hardware-installation#service-port).
10. **ADC connector (X, ADC 1–7):** 7 analog inputs, 0–13.8 V. The **X** terminal is AGND, the ground of the analog sensors, see [Analog inputs](hardware-installation#analog-inputs-adc).
11. **OLED Screen:** Displays key information about the device's status, such as IP address, connection status, or CPU load.
12. **Control Button:** Located next to the screen, it is used to switch between different views on the OLED display.
13. **USB-mini connector:** USB-mini connector.
14. **Ethernet Port (RJ45):** For connecting to the LAN.
1. **Power Supply Connector (+/GND):** Main power supply for the device (24V DC).
2. **OUT Screw Terminals:** Top part **Cover Up/Down for cover 1-8** lower part **Relay outputs 17-32**.
3. **Inputs control switch** - inputs can be controlled either by + or GND.
4. **IN Screw Terminals (1-49):** Digital inputs.
5. **I²C bus connector:** I²C bus connector for connecting I²C devices.
6. **CAN bus connector:** connects boneIO Black controllers to each other and to ESPHome devices running esphome-canopen, see [CAN bus](/en/docs/black/current/configuration/canbus).
7. **Modbus RS485 connector:** Modbus RS485 connector for connecting Modbus devices.
8. **1-Wire bus connector:** 1-Wire bus connector for connecting 1-Wire devices.
9. **ADC PWR connector (+/GND):** power for the analog sensors: VDD\_ADC 1.8 V and GND\_ADC.
10. **ADC connector (ADC 1–7):** 7 analog inputs, 1.8 V at most. The **X** terminal is not connected.
11. **OLED Screen:** Displays key information about the device's status, such as IP address, connection status, or CPU load.
12. **Control Button:** Located next to the screen, it is used to switch between different views on the OLED display.
13. **USB-mini connector:** USB-mini connector.
14. **Ethernet Port (RJ45):** For connecting to the LAN.
## Quick Start Guide [#quick-start-guide]
1. **Device Installation:** A qualified person must mount the device on a DIN rail.
2. **Network Connection:** Plug a LAN cable into the RJ45 port.
3. **Accessing the Web Panel:** Find the device's IP address (displayed on the OLED screen or in your router) and enter it into a browser to access the web interface.
4. **Estimate Shutter Movement Time:** Measure the time it takes for the shutter to fully open or close.
5. **Connect the Shutter:** Turn off the shutter's circuit breaker. Connect the shutter motor to the `Cover01 Up/Down` outputs.
6. **Edit cover.yaml file:** Set the estimated movement time in the configuration file and save it.
7. **Test the Shutter:** Run the shutter from the web panel to verify the configuration.
## Certificates [#certificates]
* [EU Declaration of Conformity (CE)](https://cdn.boneio.eu/certificates/boneio_black_en.pdf)
## What's Next? [#whats-next]
You can find detailed instructions on the dedicated pages. Go ahead and read it!
# Hardware Installation (/en/docs/edge/products/tempandhumidity/hardware-installation)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
## Device Installation [#device-installation]
boneIO Edge Temperature & Humidity is an extremely compact device. Thanks to its compact, longitudinal design, it allows for installation in almost every corner of the house. We recommend securing the device with hot glue (**NOTE**: this must be done carefully to avoid damaging the device) or mounting tape.
> **IMPORTANT: CONFIGURE BEFORE INSTALLATION!!!**
>
> Although this part of the documentation is dedicated to the hardware, we emphasize that before installing the device, you should configure it! Every sensor is delivered with the same address! This means it must be changed in each device one by one.
## Connection [#connection]
boneIO Edge Temperature & Humidity is a device that we connect to a serial Modbus RTU bus.
Our sensor is equipped with a single cable connector. Thanks to it, the installation process is extremely simple.
We recommend using secure and durable connections such as solder joints. You should also remember to properly insulate the wires, e.g., with "heat shrinks".
* Disconnect the plug from the device! - Extremely important to avoid damaging the device during the installation process!
* Disconnect the Modbus RTU bus from the controller! - No work should be performed on a connected bus!
* Disconnect the power from the bus - No work should be performed with the power connected!
* Connect the sensor wires to the Modbus bus.
* Connect the wires responsible for the power supply.
* Connect the plug to the sensor, connect the bus, and turn on the power.
Wiring is led out from the male plug and should be connected in the following way:
| Wire Color | Task |
| ------------- | -------------- |
| 🟥 **Red** | Supply voltage |
| ⬛ **Black** | Device ground |
| 🟩 **Green** | Modbus - A |
| 🟨 **Yellow** | Modbus - B |
## Final Check [#final-check]
1. Carefully check the wire connections.
2. Ensure there are no short circuits.
3. Turn on the power to the device.
# Overview and Specification (/en/docs/edge/products/tempandhumidity/overview)
## boneIO Edge Temp & Humidity [#boneio-edge-temp--humidity]
An extremely compact, precise, and reliable temperature and humidity sensor. Ideal for placement in junction boxes, frames, and anywhere an accurate measurement of temperature and humidity is required. Thanks to the use of reliable components, the device measures climatic conditions very faithfully. Due to its very well-thought-out design, it does not distort readings even in "tight" locations – it does not heat up the surroundings.
## Key Features [#key-features]
* A wide supply voltage range (5 to 24V DC) means there is no need to worry about voltage drops when powering the device via the "bus."
* Stable and reliable Modbus RTU communication protocol ensures solid data transmission.
* Extremely compact design allows the device to be mounted even in the "tightest" spots.
## Application Examples [#application-examples]
* Measurement of room **temperature and humidity**.
* Measurement of **temperature and humidity** in electrical distribution boards.
* Measurement of **humidity** in heat recovery (recuperation) units.
* Measurement of **humidity** in bathrooms.
## Technical Specification [#technical-specification]
| Feature | Value |
| ---------------------- | ---------------- |
| **Power supply** | 5-24V DC |
| **Power consumption** | \< 20mW |
| **Temperature range** | -40 to 125°C |
| **Accuracy** | 0.2°C |
| **Humidity range** | 0 to 100% |
| **Accuracy** | 1.8% |
| **Communication** | Modbus RTU |
| **Dimensions (WxHxD)** | 33mm x 8mm x 3mm |
| **Weight** | 2g |
## Description of Connectors and Components [#description-of-connectors-and-components]
1. Power and communication connector.
* Red wire **+** - power supply connection.
* Black wire **GND** - ground connection.
* Green wire **A** - Modbus communication.
* Yellow wire **B** - Modbus communication.
2. The device is programmed by the manufacturer. The user does not need to program it. If, however, you want to do it yourself, you have that option.
Programming pins. Looking from the narrower part of the sensor — from left to right: **3.3V**, **Udpi**, **GND**
3. LED
It is used to signal the status of the device. It can be completely turned off.
### Quick Start [#quick-start]
1. Change the address.
2. Device installation - a qualified person must connect the device.
3. Configure the sensor.
4. Done!
### Certificates [#certificates]
* [EU Declaration of Conformity (CE)](https://cdn.boneio.eu/certificates/boneio_edge_temp_humidity_en.pdf)
### What's Next? [#whats-next]
# Basic concepts (/en/docs/esp/products/dimmer/basic-concepts)
## Welcome to boneIO ESP Documentation! [#welcome-to-boneio-esp-documentation]
On this page, you'll find step-by-step guides and instructions for configuring your boneIO ESP controller. Whether you have one of our larger models like ESP 32x10, 24x16, Cover, or Cover Mix, or one of our smaller devices like the Dimmer or 8x10A, you'll find the documentation you need to get started.
Your device comes preinstalled with ESPHome and a default configuration. You'll need to adjust it to match your specific requirements. Below are the essential steps to help you configure your boneIO ESP controller:
# First steps (/en/docs/esp/products/dimmer/first-steps)
## Welcome to boneIO ESP Documentation! [#welcome-to-boneio-esp-documentation]
On this page, you'll find step-by-step guides and instructions for configuring your boneIO ESP controller. Whether you have one of our larger models like ESP 32x10, 24x16, Cover, or Cover Mix, or one of our smaller devices like the Dimmer or 8x10A, you'll find the documentation you need to get started.
Your device comes preinstalled with ESPHome and a default configuration. You'll need to adjust it to match your specific requirements. Below are the essential steps to help you configure your boneIO ESP controller:
# Philosophy (/en/docs/esp/products/dimmer/philosopy)
## Welcome to boneIO ESP Documentation! [#welcome-to-boneio-esp-documentation]
On this page, you'll find step-by-step guides and instructions for configuring your boneIO ESP controller. Whether you have one of our larger models like ESP 32x10, 24x16, Cover, or Cover Mix, or one of our smaller devices like the Dimmer or 8x10A, you'll find the documentation you need to get started.
Your device comes preinstalled with ESPHome and a default configuration. You'll need to adjust it to match your specific requirements. Below are the essential steps to help you configure your boneIO ESP controller:
# Requirements (/en/docs/esp/products/dimmer/requirements)
## Welcome to boneIO ESP Documentation! [#welcome-to-boneio-esp-documentation]
On this page, you'll find step-by-step guides and instructions for configuring your boneIO ESP controller. Whether you have one of our larger models like ESP 32x10, 24x16, Cover, or Cover Mix, or one of our smaller devices like the Dimmer or 8x10A, you'll find the documentation you need to get started.
Your device comes preinstalled with ESPHome and a default configuration. You'll need to adjust it to match your specific requirements. Below are the essential steps to help you configure your boneIO ESP controller:
# Hardware Installation (/en/docs/esp/products/esp_24_16/hardware-installation)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
***
## DIN Rail Mounting [#din-rail-mounting]
The boneIO ESP controller is designed for mounting on a standard DIN rail (TS35).
1. Hook the upper clips of the enclosure onto the top edge of the DIN rail.
2. Press the lower part of the enclosure firmly until the latches lock onto the rail with a distinct click.
3. Ensure the module is securely mounted.
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 24V DC power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+24V` output of the power supply to the `+` screw terminal on the boneIO.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO.
4. Double-check the connections and polarity before turning on the power supply.
## Connect Ethernet [#connect-ethernet]
The device communicates with the network using a built-in Ethernet port, which guarantees a stable and reliable connection. To establish connectivity, connect the module to your network switch using a standard Ethernet (RJ45) cable.
1. Connect ethernet cable to LAN port on your controller.
2. Connect other side of ethernet cable to your network switch.
## Connecting Digital Inputs [#connecting-digital-inputs]
Digital inputs are used to connect buttons and sensors. To change the potential used to control the inputs, use the switch on the casing marked `INPUTS`. By default, the inputs are controlled by ground (GND).
> **IMPORTANT: If you want to change the position of the switch - make sure you do it while the device is turned off!**
1. Connect one of the wires from a momentary switch to the common `GND` (ground) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will short the input to ground, which will be interpreted as an "on" signal.
### Logical diagram of connecting digital input [#logical-diagram-of-connecting-digital-input]
### Example: [#example]
### Example 2: [#example-2]
### Example 3: [#example-3]
## Connecting Relay Outputs (16A) [#connecting-relay-outputs-16a]
The key feature of the 24x16A model is that **each of the 24 relays has its own, galvanically isolated `COM` terminal**. This provides tremendous flexibility and allows for controlling circuits powered from different phases or protected by different residual-current devices (RCDs).
### Protection and Correct Wiring Order [#protection-and-correct-wiring-order]
**It is critical that all overcurrent protection (Miniature Circuit Breakers, MCBs) and residual-current devices (RCDs) are installed in the circuit *before* the boneIO controller.**
The current rating (in Amps) of the overcurrent protection must be sized appropriately for the planned load of the circuit (e.g., the wattage of the loads), but at the same time, it **must not exceed the maximum rated current of the relay, which is 16A**.
The correct current flow for the phase (L) wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> OUT terminal in boneIO
-> Load`
### Example 1: Controlling a standard circuit [#example-1-controlling-a-standard-circuit]
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 16A), to the `COM` terminal of the selected output (e.g., `COM 1`).
2. Connect the wire leading to the **load** (e.g., an outlet) to the `NO` (Normally Open) terminal of the same output (e.g., `OUT 1`).
3. Run the **neutral wire (N)** directly to the load.
### Logical Diagram [#logical-diagram]
### Example 2: Controlling circuits from different phases / RCDs [#example-2-controlling-circuits-from-different-phases--rcds]
Thanks to the separation of the `COM` terminals, you can safely connect circuits from different sources.
### Logical Diagram [#logical-diagram-1]
### Safe Connecting of COM and OUT Terminals [#safe-connecting-of-com-and-out-terminals]
In the boneIO controller, version Cover **every two outputs (e.g., Cover 01 UP and DOWN) share a single common power terminal `COM`**. This means that the phase wire (L) from a single circuit breaker supplies a pair of relays - with hardware interlock.
1. **REMEMBER**, ensure that the relevant circuit breakers in the electrical cabinet **are turned off**.
2. Connect the **phase wire (L)**, coming from the overcurrent protection, to the appropriate COM terminal - tighten it with adequate force.
3. Connect the wire leading to your load (e.g., socket) to **its corresponding output terminal** - tighten it with adequate force.
4. Run the neutral (N) wire directly from the neutral bar to the load.
### Example 2: [#example-2-1]
## Connecting Communication Buses [#connecting-communication-buses]
### I2C Bus [#i2c-bus]
For connecting additional sensors and expanders over short distances.
* Connect the `SDA` line to the `SDA` terminal.
* Connect the `SCL` line to the `SCL` terminal.
* Also, connect the `VCC` and `GND` power for the sensor.
### CAN [#can]
Used for communication with industrial HVAC devices and sensors.
* Connect the `L` line of the bus to the `L` terminal on the boneIO.
* Connect the `H` line of the bus to the `H` terminal on the boneIO.
### Modbus RS485 [#modbus-rs485]
Used for communication with industrial and HVAC devices.
* Connect the `A` line of the bus to the `A` terminal on the boneIO.
* Connect the `B` line of the bus to the `B` terminal on the boneIO.
> ESP series devices have undergone Modbus RTU bus testing with 5 connected devices. Using a larger number of Modbus devices connected to an ESP series controller may cause delays in the controller's response (both inputs and outputs). This is due to the specifics of the processor used. In the case of extensive Modbus buses, we recommend splitting them across several devices.
### 1-Wire Bus [#1-wire-bus]
Popular for connecting temperature sensors (e.g., DS18B20).
* Connect the `DATA` line to the `1-Wire` terminal.
* Also, connect `VCC` and `GND` power.
The maximum length of the bus cable is 20m.
## Connecting Analog Inputs [#connecting-analog-inputs]
Analog inputs allow you to read values from sensors that do not operate in a binary (on/off) manner.
### Analog Inputs ADC [#analog-inputs-adc]
The boneIO controller is equipped with three analog inputs, utilizing integrated voltage dividers to support a variety of voltage ranges for connecting different sensors.
| Input Name | ESP32 GPIO Number | Voltage |
| :--------: | :---------------: | :-----: |
| A\_1 | GPIO39 | 0 - 5V |
| A\_2 | GPIO36 | 0 - 10V |
| A\_3 | GPIO35 | 0 - 25V |
## Final Checks [#final-checks]
After completing the installation:
1. Double-check all connections.
2. Ensure there are no short circuits.
3. Turn on the main power (24V DC power supply).
4. The device's OLED screen should light up, indicating it has started successfully.
# Overview and Specification (/en/docs/esp/products/esp_24_16/overview)
# boneIO ESP 24x16A [#boneio-esp-24x16a]
You can buy the controller -> [HERE](https://store.boneio.eu/product/boneio-esp-24x16/?v=288404204e3d)
Leveraging the versatile **ESP32 microcontroller** and the simplicity of **ESPHome**, the boneIO ESP controller provides an incredibly flexible and easy-to-configure core for your smart home automations.
With 35 digital inputs and 24 relay outputs, a single boneIO ESP controller has enough capacity to manage all the automation in an entire house or apartment. This includes lighting and heating systems, as well as controlling entrance and garage gates by providing a pulse to the drive.
The **boneIO ESP 24x16A** is a specialized control unit designed to manage high-load electrical circuits. Equipped with **24 powerful 16A relays**, each featuring its **own, galvanically isolated COM terminal**, it provides maximum flexibility and safety for controlling outlets, electric heating, pumps, or other high-power devices.
## Key Features [#key-features]
* **35 digital inputs** for connecting switches, motion sensors, contact sensors and others.
* **24 independent 16A relay outputs** with **full galvanic isolation** (each relay has its own `COM` terminal). for controlling sockets and high-power appliances.
* **3 analog inputs** for integration with analog sensors (e.g., light or wind sensors).
* **Reliable network connection** via an **Ethernet port** and **USB-C**.
* **Wide expansion capabilities** thanks to **Modbus, I2C, CAN and 1-Wire** interfaces.
* Built-in **OLED screen** for a quick overview of the device's status.
* Standard **DIN rail mounting (12 modules)**.
## Use Cases [#use-cases]
Thanks to the high load capacity and separation of the relays, the 24x16A model is ideal for:
* Directly controlling electrical outlet circuits throughout a house.
* Managing electric underfloor heating or convector heaters.
* Controlling high-consumption devices such as pumps, fans, motors, or solenoid valves.
* Integration with three-phase power systems.
## Technical Specification [#technical-specification]
| Feature | Value |
| ----------------------- | ------------------------------------------------------------------------ |
| **Module** | ESP32 |
| **Power Supply** | 24V DC |
| **Power Consumption** | 3W - 15W |
| **Digital Inputs** | 35 |
| **Inputs Voltage** | 24V DC |
| **Relay Outputs** | 24 (each with a separate COM) |
| **Max Output Voltage** | 230V AC / 30V DC |
| **Max Output Current** | 16A |
| **Analog Inputs** | 3 (A\_1 - 0-5V, A\_2 - 0-10V, A\_3 0-25V) |
| **External Interfaces** | Modbus RS485, I2C bus, 1-Wire, CAN (for future use) |
| **Communication** | Ethernet 10/100Mbit, USB-C (for firmware installation) |
| **Dimensions (WxHxD)** | 216mm x 106mm x 57mm (without plugs) / 216mm x 123mm x 57mm (with plugs) |
| **Mounting Width** | 12 DIN modules |
| **Weight** | 800g |
## Connectors and Components Description [#connectors-and-components-description]
1. **Power Supply Connector (+/GND):** Main power supply for the device (24V DC).
2. **OUT Screw Terminals (1-24):** Relay outputs. Each output has a separate `COM` and `NO` terminal.
3. **Inputs control switch** - inputs can be controlled either by + or GND.
4. **IN Screw Terminals (1-35):** Digital inputs.
5. **I²C bus connector:** I²C bus connector for connecting I²C devices.
6. **CAN bus connector:** CAN bus connector for connecting CAN devices. **For future use**.
7. **Modbus RS485 connector:** Modbus RS485 connector for connecting Modbus devices.
8. **1-Wire bus connector:** 1-Wire bus connector for connecting 1-Wire devices.
9. **GPIO connector:** GPIO connector for connecting device which can transmit data to ESP32 GPIO. It's pulled down to GND.
10. **ADC connector:** ADC connector for connecting analog sensors to get analog reading of voltage.
11. **OLED Screen:** Displays key information about the device's status, such as IP address, connection status, or CPU load.
12. **Control Button:** Located next to the screen, it is used to switch between different views on the OLED display.
13. **USB-C connector:** USB-C connector for connecting to the computer to upload the firmware.
14. **Ethernet Port (RJ45):** For connecting to the LAN.
## Quick Start Guide [#quick-start-guide]
1. **Device Installation:** A qualified person must mount the device on a DIN rail.
2. **Offline Verification:** Connect a switch to input **IN01** and a light bulb to output **OUT01**. Press the switch – the bulb should change its state.
3. **Network Connection:** Plug a LAN cable into the RJ45 port.
4. **Accessing the Web Panel:** Find the device's IP address (displayed on the OLED screen or in your router) and enter it into a browser to access the web interface.
## Certificates [#certificates]
* [EU Declaration of Conformity (CE)](https://cdn.boneio.eu/certificates/boneio_esp_all_en.pdf)
## What's Next? [#whats-next]
You can find detailed instructions on the dedicated pages. Go ahead and read it!
# Hardware Installation (/en/docs/esp/products/esp_32_10/hardware-installation)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
***
## DIN Rail Mounting [#din-rail-mounting]
The boneIO ESP controller is designed for mounting on a standard DIN rail (TS35).
1. Hook the upper clips of the enclosure onto the top edge of the DIN rail.
2. Press the lower part of the enclosure firmly until the latches lock onto the rail with a distinct click.
3. Ensure the module is securely mounted.
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 24V DC power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+24V` output of the power supply to the `+` screw terminal on the boneIO.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO.
4. Double-check the connections and polarity before turning on the power supply.
## Connect Ethernet [#connect-ethernet]
The device communicates with the network using a built-in Ethernet port, which guarantees a stable and reliable connection. To establish connectivity, connect the module to your network switch using a standard Ethernet (RJ45) cable.
1. Connect ethernet cable to LAN port on your controller.
2. Connect other side of ethernet cable to your network switch.
## Connecting Digital Inputs [#connecting-digital-inputs]
Digital inputs are used to connect buttons and sensors. To change the potential used to control the inputs, use the switch on the casing marked `INPUTS`. By default, the inputs are controlled by ground (GND).
> **IMPORTANT: If you want to change the position of the switch - make sure you do it while the device is turned off!**
1. Connect one of the wires from a momentary switch to the common `GND` (ground) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will short the input to ground, which will be interpreted as an "on" signal.
### Logical diagram of connecting digital input [#logical-diagram-of-connecting-digital-input]
### Example: [#example]
### Example 2: [#example-2]
### Example 3: [#example-3]
## Connecting Relay Outputs (10A) [#connecting-relay-outputs-10a]
The key feature of the 32x10A model is its high output density, integrating 32 relays of 10A each into a remarkably compact form factor. This provides tremendous possibilities for controlling a large number of independent circuits from a single device, saving both space and complexity.
### Protection and Correct Wiring Order [#protection-and-correct-wiring-order]
**It is critical that all overcurrent protection (Miniature Circuit Breakers, MCBs) and residual-current devices (RCDs) are installed in the circuit *before* the boneIO controller.**
The current rating (in Amps) of the overcurrent protection must be sized appropriately for the planned load of the circuit (e.g., the wattage of the lights), but at the same time, it **must not exceed the maximum rated current of the relay, which is 10A**.
The correct current flow for the phase (L) wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> OUT terminal in boneIO
-> Load`
### Example 1: Controlling a standard circuit [#example-1-controlling-a-standard-circuit]
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 10A), to the `COM` terminal of the selected output (e.g., `COM 1` or `COM 2`).
2. Connect the wire leading to the **load** (e.g., an outlet) to the `NO` (Normally Open) terminal of the same output (e.g., `OUT 1`).
3. Run the **neutral wire (N)** directly to the load.
### Logical Diagram [#logical-diagram]
### Safe Connecting of COM and OUT Terminals [#safe-connecting-of-com-and-out-terminals]
In the boneIO controller, version 32x10A **every two outputs (e.g., OUT1 and OUT2) share a single common power terminal `COM`**. This means that the phase wire (L) from a single circuit breaker supplies a pair of relays.
1. **REMEMBER**, ensure that the relevant circuit breakers in the electrical cabinet **are turned off**.
2. Connect the **phase wire (L)**, coming from the overcurrent protection, to the appropriate COM terminal - tighten it with adequate force.
3. Connect the wire leading to your load (e.g., a light bulb) to **its corresponding output terminal** - tighten it with adequate force.
4. Run the neutral (N) wire directly from the neutral bar to the load.
## Connecting Communication Buses [#connecting-communication-buses]
### I2C Bus [#i2c-bus]
For connecting additional sensors and expanders over short distances.
* Connect the `SDA` line to the `SDA` terminal.
* Connect the `SCL` line to the `SCL` terminal.
* Also, connect the `VCC` and `GND` power for the sensor.
### CAN [#can]
Used for communication with industrial HVAC devices and sensors.
* Connect the `L` line of the bus to the `L` terminal on the boneIO.
* Connect the `H` line of the bus to the `H` terminal on the boneIO.
### Modbus RS485 [#modbus-rs485]
Used for communication with industrial and HVAC devices.
* Connect the `A` line of the bus to the `A` terminal on the boneIO.
* Connect the `B` line of the bus to the `B` terminal on the boneIO.
> ESP series devices have undergone Modbus RTU bus testing with 5 connected devices. Using a larger number of Modbus devices connected to an ESP series controller may cause delays in the controller's response (both inputs and outputs). This is due to the specifics of the processor used. In the case of extensive Modbus buses, we recommend splitting them across several devices.
### 1-Wire Bus [#1-wire-bus]
Popular for connecting temperature sensors (e.g., DS18B20).
* Connect the `DATA` line to the `1-Wire` terminal.
* Also, connect `VCC` and `GND` power.
The maximum length of the bus cable is 20m.
## Connecting Analog Inputs [#connecting-analog-inputs]
Analog inputs allow you to read values from sensors that do not operate in a binary (on/off) manner.
### Analog Inputs ADC [#analog-inputs-adc]
The boneIO controller is equipped with three analog inputs, utilizing integrated voltage dividers to support a variety of voltage ranges for connecting different sensors.
| Input Name | ESP32 GPIO Number | Voltage |
| :--------: | :---------------: | :-----: |
| A\_1 | GPIO39 | 0 - 5V |
| A\_2 | GPIO36 | 0 - 10V |
| A\_3 | GPIO35 | 0 - 25V |
## Final Checks [#final-checks]
After completing the installation:
1. Double-check all connections.
2. Ensure there are no short circuits.
3. Turn on the main power (24V DC power supply).
4. The device's OLED screen should light up, indicating it has started successfully.
# Overview and Specification (/en/docs/esp/products/esp_32_10/overview)
# boneIO ESP 32x10A [#boneio-esp-32x10a]
You can buy the controller -> [HERE](https://store.boneio.eu/product/boneio-esp-32x10a/?v=288404204e3d)
Leveraging the versatile **ESP32 microcontroller** and the simplicity of **ESPHome**, the boneIO ESP controller provides an incredibly flexible and easy-to-configure core for your smart home automations.
With 35 digital inputs and 32 relay outputs, a single boneIO ESP controller has enough capacity to manage all the automation in an entire house or apartment. This includes lighting and heating systems, as well as controlling entrance and garage gates by providing a pulse to the drive. It's also possible to control blinds (though we offer dedicated controllers for this purpose).
The **boneIO ESP 32x10A** is designed to manage lights and some other not electrical demanding devices throughout your home.
## Key Features [#key-features]
* **35 digital inputs** For connecting switches, motion sensors, contact sensors and others.
* **32 relay outputs (10A)** For controlling lights, outlets, valves.
* **3 analog inputs** for integration with analog sensors (e.g., light or wind sensors).
* **Reliable network connection** via an **Ethernet port** and **USB-C**.
* **Wide expansion capabilities** thanks to **Modbus, I2C, CAN and 1-Wire** interfaces.
* Built-in **OLED screen** for a quick overview of the device's status.
* Standard **DIN rail mounting (12 modules)**.
## Use Cases [#use-cases]
The boneIO controller is the perfect choice for:
* Comprehensive automation of single-family homes and large apartments.
* Controlling multiple lighting circuits from a single location.
* Integration with an alarm system by collecting signals from sensors.
* Integration with various sensors for advanced automation scenarios.
* Automating HVAC systems (heating, ventilation, air conditioning) thanks to Modbus support.
## Technical Specification [#technical-specification]
| Feature | Value |
| ----------------------- | ------------------------------------------------------------------------ |
| **Module** | ESP32 |
| **Power Supply** | 24V DC |
| **Power Consumption** | 3W - 15W |
| **Digital Inputs** | 35 |
| **Inputs Voltage** | 24V DC |
| **Relay Outputs** | 32 |
| **Max Output Voltage** | 230V AC / 30V DC |
| **Max Output Current** | 10A |
| **Analog Inputs** | 3 (A\_1 - 0-5V, A\_2 - 0-10V, A\_3 0-25V) |
| **External Interfaces** | Modbus RS485, I2C bus, 1-Wire, CAN (for future use) |
| **Communication** | Ethernet 10/100Mbit, USB-C (for firmware installation) |
| **Dimensions (WxHxD)** | 216mm x 106mm x 57mm (without plugs) / 216mm x 123mm x 57mm (with plugs) |
| **Mounting Width** | 12 DIN modules |
| **Weight** | 800g |
## Connectors and Components Description [#connectors-and-components-description]
1. **Power Supply Connector (+/GND):** Main power supply for the device (24V DC).
2. **OUT Screw Terminals (1-32):** Relay outputs.
3. **Inputs control switch** - inputs can be controlled either by + or GND.
4. **IN Screw Terminals (1-35):** Digital inputs.
5. **I²C bus connector:** I²C bus connector for connecting I²C devices.
6. **CAN bus connector:** CAN bus connector for connecting CAN devices. **For future use**.
7. **Modbus RS485 connector:** Modbus RS485 connector for connecting Modbus devices.
8. **1-Wire bus connector:** 1-Wire bus connector for connecting 1-Wire devices.
9. **GPIO connector:** GPIO connector for connecting device which can transmit data to ESP32 GPIO. It's pulled down to GND.
10. **ADC connector:** ADC connector for connecting analog sensors to get analog reading of voltage.
11. **OLED Screen:** Displays key information about the device's status, such as IP address, connection status, or CPU load.
12. **Control Button:** Located next to the screen, it is used to switch between different views on the OLED display.
13. **USB-C connector:** USB-C connector for connecting to the computer to upload the firmware.
14. **Ethernet Port (RJ45):** For connecting to the LAN.
## Quick Start Guide [#quick-start-guide]
1. **Device Installation:** A qualified person must mount the device on a DIN rail.
2. **Offline Verification:** Connect a switch to input **IN01** and a light bulb to output **OUT01**. Press the switch – the bulb should change its state.
3. **Network Connection:** Plug a LAN cable into the RJ45 port.
4. **Add to Home Assistant:** Home Assistant discovers the controller on your network — see [Connecting boneIO ESP](/en/docs/home-assistant/boneio-esp). Firmware from [boneio.eu/esp](https://boneio.eu/esp) has no web panel by default. If you want to open the controller in a browser at its IP address, choose the **+ web panel** variant in the installer ([what that means](/en/docs/esp/security)).
## Certificates [#certificates]
* [EU Declaration of Conformity (CE)](https://cdn.boneio.eu/certificates/boneio_esp_all_en.pdf)
## What's Next? [#whats-next]
You can find detailed instructions on the dedicated pages. Go ahead and read it!
# Hardware Installation (/en/docs/esp/products/esp_8_g2/hardware-installation)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
***
## DIN Rail Mounting [#din-rail-mounting]
The boneIO ESP controller is designed for mounting on a standard DIN rail (TS35).
1. Hook the upper clips of the enclosure onto the top edge of the DIN rail.
2. Press the lower part of the enclosure firmly until the latches lock onto the rail with a distinct click.
3. Ensure the module is securely mounted.
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 24V DC power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+24V` output of the power supply to the `+` screw terminal on the boneIO.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO.
4. Double-check the connections and polarity before turning on the power supply.
## Connect Ethernet [#connect-ethernet]
The device communicates with the network using a built-in Ethernet port, which guarantees a stable and reliable connection. To establish connectivity, connect the module to your network switch using a standard Ethernet (RJ45) cable.
1. Connect ethernet cable to LAN port on your controller.
2. Connect other side of ethernet cable to your network switch.
## Connecting Digital Inputs [#connecting-digital-inputs]
Digital inputs are used for connecting switches and sensors. By default, they are ground-controlled.
1. Connect one of the wires from a momentary switch to the common `GND` (ground) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will short the input to ground, which will be interpreted as an "on" signal.
### Logical diagram of connecting digital input [#logical-diagram-of-connecting-digital-input]
### GND or + [#gnd-or-]
Input behavior can be changed via the internal switch. Please see the switch location below.
* Down: GND control.
* Up: High-potential control.
### Example: [#example]
### Example 2: [#example-2]
### Example 3: [#example-3]
## Connecting Relay Outputs (10A) [#connecting-relay-outputs-10a]
The key feature of the 32x10A model is its high output density, integrating 32 relays of 10A each into a remarkably compact form factor. This provides tremendous possibilities for controlling a large number of independent circuits from a single device, saving both space and complexity.
### Protection and Correct Wiring Order [#protection-and-correct-wiring-order]
**It is critical that all overcurrent protection (Miniature Circuit Breakers, MCBs) and residual-current devices (RCDs) are installed in the circuit *before* the boneIO controller.**
The current rating (in Amps) of the overcurrent protection must be sized appropriately for the planned load of the circuit (e.g., the wattage of the lights), but at the same time, it **must not exceed the maximum rated current of the relay, which is 10A**.
The correct current flow for the phase (L) wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> OUT terminal in boneIO
-> Load`
### Example 1: Controlling a standard circuit [#example-1-controlling-a-standard-circuit]
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 10A), to the `COM` terminal of the selected output (e.g., `COM 1` or `COM 2`).
2. Connect the wire leading to the **load** (e.g., an outlet) to the `NO` (Normally Open) terminal of the same output (e.g., `OUT 1`).
3. Run the **neutral wire (N)** directly to the load.
### Logical Diagram [#logical-diagram]
### Safe Connecting of COM and OUT Terminals [#safe-connecting-of-com-and-out-terminals]
In the boneIO controller, version 32x10A **every two outputs (e.g., OUT1 and OUT2) share a single common power terminal `COM`**. This means that the phase wire (L) from a single circuit breaker supplies a pair of relays.
1. **REMEMBER**, ensure that the relevant circuit breakers in the electrical cabinet **are turned off**.
2. Connect the **phase wire (L)**, coming from the overcurrent protection, to the appropriate COM terminal - tighten it with adequate force.
3. Connect the wire leading to your load (e.g., a light bulb) to **its corresponding output terminal** - tighten it with adequate force.
4. Run the neutral (N) wire directly from the neutral bar to the load.
## Connecting Communication Buses [#connecting-communication-buses]
### CAN [#can]
Used for communication with industrial HVAC devices and sensors.
* Connect the `L` line of the bus to the `L` terminal on the boneIO.
* Connect the `H` line of the bus to the `H` terminal on the boneIO.
### Modbus RS485 [#modbus-rs485]
Used for communication with industrial and HVAC devices.
* Connect the `A` line of the bus to the `A` terminal on the boneIO.
* Connect the `B` line of the bus to the `B` terminal on the boneIO.
> ESP series devices have undergone Modbus RTU bus testing with 5 connected devices. Using a larger number of Modbus devices connected to an ESP series controller may cause delays in the controller's response (both inputs and outputs). This is due to the specifics of the processor used. In the case of extensive Modbus buses, we recommend splitting them across several devices.
## Final Checks [#final-checks]
After completing the installation:
1. Double-check all connections.
2. Ensure there are no short circuits.
3. Turn on the main power (24V DC power supply).
4. The device's OLED screen should light up, indicating it has started successfully.
# Overview and Specification (/en/docs/esp/products/esp_8_g2/overview)
# boneIO ESP 8x10A gen2 [#boneio-esp-8x10a-gen2]
You can buy the controller -> [HERE](https://store.boneio.eu/product/boneio-8x10a-gen2/?v=288404204e3d)
Utilizing the versatile **ESP32-S3 microcontroller** and the simplicity of **ESPHome** software, the boneIO ESP controller provides an extremely flexible and easy-to-configure core for your smart home automation.
Thanks to 8 digital inputs and 8 relay outputs, a single boneIO ESP controller has enough power to manage automation in several rooms. This includes lighting systems, heating, as well as controlling the entrance gate and garage door by sending an impulse to the drive. It is also possible to control blinds (for which we offer dedicated controllers).
The **boneIO ESP 8x10A gen2** is primarily designed to manage lights and other non-power-demanding circuits in your home.
## Key Features [#key-features]
* **8 digital inputs** For connecting switches, motion sensors, contact sensors and others.
* **8 relay outputs (10A)** For controlling lights, outlets, valves.
* **Reliable network connection** via an **Ethernet port** or \*\*WiFi (with external antenna), **USB-C** - for programming.
* **Wide expansion capabilities** thanks to **Modbus, CAN** interfaces.
* Standard **DIN rail mounting (7 modules)**.
## Use Cases [#use-cases]
The boneIO controller is the perfect choice for:
* Comprehensive automation of rooms and small apartments.
* Expansion of the number of inputs, outputs, and communication capabilities in a compact-sized device.
* Controlling multiple lighting circuits from a single location.
* Integration with an alarm system by collecting signals from sensors.
* Integration with various sensors for advanced automation scenarios.
* Automating HVAC systems (heating, ventilation, air conditioning) thanks to Modbus support.
## Technical Specification [#technical-specification]
| Feature | Value |
| ----------------------- | ----------------------------------------------------------------------------------- |
| **Module** | ESP32-S3 |
| **Power Supply** | 12-24V DC |
| **Power Consumption** | 3W - 5W |
| **Digital Inputs** | 8 |
| **Inputs Voltage** | Same as power supply |
| **Relay Outputs** | 8 |
| **Max Output Voltage** | 230V AC / 30V DC |
| **Max Output Current** | 10A |
| **External Interfaces** | Modbus RS485, CAN |
| **Communication** | Ethernet 10/100Mbit, WiFi (with external antenna) USB-C (for firmware installation) |
| **Dimensions (WxHxD)** | 126mm x 91mm x 57mm (without plugs) / 126mm x 108mm x 57mm (with plugs) |
| **Mounting Width** | 7 DIN modules |
| **Weight** | 230g |
## Connectors and Components Description [#connectors-and-components-description]
1. **Power Supply Connector (+/GND):** Main power supply for the device (12-24V DC).
2. **IN Screw Terminals (1-38):** Digital inputs.
3. **OUT Screw Terminals (1-8):** Relay outputs.
4. **Modbus RS485 connector:** Modbus RS485 connector for connecting Modbus devices.
5. **CAN bus connector:** CAN bus connector for connecting CAN devices.
6. **USB-C connector:** USB-C connector for connecting to the computer to upload the firmware.
7. **Ethernet Port (RJ45):** for connecting to the LAN.
## Quick Start Guide [#quick-start-guide]
1. **Device Installation:** Mount the device on a DIN rail (qualified person only).
2. **Offline Verification:** Connect a switch to input **IN01** and a light bulb to output **OUT01**. Press the switch – the bulb should change its state.
3. **Network Connection:** Plug a LAN cable into the RJ45 port.
4. **Add to Home Assistant:** Home Assistant discovers the controller on your network — see [Connecting boneIO ESP](/en/docs/home-assistant/boneio-esp). Firmware from [boneio.eu/esp](https://boneio.eu/esp) has no web panel by default. If you want to open the controller in a browser at its IP address, choose the **+ web panel** variant in the installer ([what that means](/en/docs/esp/security)).
## Certificates [#certificates]
* [EU Declaration of Conformity (CE)](https://cdn.boneio.eu/certificates/boneio_esp_8_10_en.pdf)
## What's Next? [#whats-next]
You can find detailed instructions on the dedicated pages. Go ahead and read it!
# Hardware Installation (/en/docs/esp/products/esp_cover/hardware_installation)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
***
## DIN Rail Mounting [#din-rail-mounting]
The boneIO ESP controller is designed for mounting on a standard DIN rail (TS35).
1. Hook the upper clips of the enclosure onto the top edge of the DIN rail.
2. Press the lower part of the enclosure firmly until the latches lock onto the rail with a distinct click.
3. Ensure the module is securely mounted.
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 24V DC power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+24V` output of the power supply to the `+` screw terminal on the boneIO.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO.
4. Double-check the connections and polarity before turning on the power supply.
## Connect Ethernet [#connect-ethernet]
The device communicates with the network using a built-in Ethernet port, which guarantees a stable and reliable connection. To establish connectivity, connect the module to your network switch using a standard Ethernet (RJ45) cable.
1. Connect ethernet cable to LAN port on your controller.
2. Connect other side of ethernet cable to your network switch.
## Connecting Digital Inputs [#connecting-digital-inputs]
Digital inputs are used to connect buttons and sensors. To change the potential used to control the inputs, use the switch on the casing marked `INPUTS`. By default, the inputs are controlled by ground (GND).
> **IMPORTANT: If you want to change the position of the switch - make sure you do it while the device is turned off!**
1. Connect one of the wires from a momentary switch to the common `GND` (ground) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will short the input to ground, which will be interpreted as an "on" signal.
### Logical diagram of connecting digital input [#logical-diagram-of-connecting-digital-input]
### Example: [#example]
Example:
### Example 2: [#example-2]
### Example 3: [#example-3]
## Connecting Relay Outputs (Cover Motors) [#connecting-relay-outputs-cover-motors]
The key feature of the Cover version is that it has 32 relays, which are paired to control up to 16 roller shutter motors. Each pair of relays (e.g., Cover 01`UP`/`DOWN`, Cover 02 `UP`/`DOWN`) is protected by a hardware interlock to prevent simultaneous 'up' and 'down' signals, which protects the motor from damage.
### Protection and Correct Wiring Order [#protection-and-correct-wiring-order]
**It is critical that all overcurrent protection (Miniature Circuit Breakers, MCBs) and residual-current devices (RCDs) are installed in the circuit *before* the boneIO controller.**
The current rating (in Amps) of the overcurrent protection must be sized appropriately for the planned load of the circuit (in this case - cover motors), but at the same time, it **must not exceed the maximum rated current of the relay, which is 10A**.
The correct current flow for the phase (L) wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> UP/DOWN terminal in boneIO
-> COVER`
### Example 1: Controlling a standard cover circuit [#example-1-controlling-a-standard-cover-circuit]
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 10A), to the `COM` terminal of the selected Cover output (e.g., `Cover 01 COM`).
2. Connect the wire leading to the **Cover motor UP** to the `UP` terminal of the same output (e.g., `Cover 01 UP`).
3. Connect the wire leading to the **Cover motor DOWN** to the `DOWN` terminal of the same output (e.g., `Cover 01 DOWN`).
4. Run the **neutral wire (N)** directly to the load (cover engine).
### Logical Diagram [#logical-diagram]
### Safe Connecting of COM and OUT Terminals [#safe-connecting-of-com-and-out-terminals]
In the boneIO controller, version Cover **every two outputs (e.g., Cover 01 UP and DOWN) share a single common power terminal `COM`**. This means that the phase wire (L) from a single circuit breaker supplies a pair of relays - with hardware interlock.
1. **REMEMBER**, ensure that the relevant circuit breakers in the electrical cabinet **are turned off**.
2. Connect the **phase wire (L)**, coming from the overcurrent protection, to the appropriate COM terminal - tighten it with adequate force.
3. Connect the wire leading to your load (e.g., a cover motor) to **its corresponding output terminal** - tighten it with adequate force.
4. Run the neutral (N) wire directly from the neutral bar to the load.
## Connecting Communication Buses [#connecting-communication-buses]
### I2C Bus [#i2c-bus]
For connecting additional sensors and expanders over short distances.
* Connect the `SDA` line to the `SDA` terminal.
* Connect the `SCL` line to the `SCL` terminal.
* Also, connect the `VCC` and `GND` power for the sensor.
### CAN [#can]
Used for communication with industrial HVAC devices and sensors.
* Connect the `L` line of the bus to the `L` terminal on the boneIO.
* Connect the `H` line of the bus to the `H` terminal on the boneIO.
### Modbus RS485 [#modbus-rs485]
Used for communication with industrial and HVAC devices.
* Connect the `A` line of the bus to the `A` terminal on the boneIO.
* Connect the `B` line of the bus to the `B` terminal on the boneIO.
> ESP series devices have undergone Modbus RTU bus testing with 5 connected devices. Using a larger number of Modbus devices connected to an ESP series controller may cause delays in the controller's response (both inputs and outputs). This is due to the specifics of the processor used. In the case of extensive Modbus buses, we recommend splitting them across several devices.
### 1-Wire Bus [#1-wire-bus]
Popular for connecting temperature sensors (e.g., DS18B20).
* Connect the `DATA` line to the `1-Wire` terminal.
* Also, connect `VCC` and `GND` power.
The maximum length of the bus cable is 20m.
## Connecting Analog Inputs [#connecting-analog-inputs]
Analog inputs allow you to read values from sensors that do not operate in a binary (on/off) manner.
### Analog Inputs ADC [#analog-inputs-adc]
The boneIO controller is equipped with three analog inputs, utilizing integrated voltage dividers to support a variety of voltage ranges for connecting different sensors.
| Input Name | ESP32 GPIO Number | Voltage |
| :--------: | :---------------: | :-----: |
| A\_1 | GPIO39 | 0 - 5V |
| A\_2 | GPIO36 | 0 - 10V |
| A\_3 | GPIO35 | 0 - 25V |
## Final Checks [#final-checks]
After completing the installation:
1. Double-check all connections.
2. Ensure there are no short circuits.
3. Turn on the main power (24V DC power supply).
4. The device's OLED screen should light up, indicating it has started successfully.
# Overview and Specification (/en/docs/esp/products/esp_cover/overview)
## boneIO ESP Cover [#boneio-esp-cover]
You can buy the controller -> [HERE](https://store.boneio.eu/product/boneio-esp-cover/?v=288404204e3d)
Leveraging the versatile **ESP32 microcontroller** and the simplicity of **ESPHome**, the boneIO ESP controller provides an incredibly flexible and easy-to-configure core for your smart home automations.
With 35 digital inputs and 16 cover outputs, a single boneIO ESP controller has enough capacity to manage all the automation in an entire house or apartment.\
**The boneIO ESP Cover** is a specialized controller designed for automating roller shutters, blinds, or gates. It features 32 relays paired with a hardware interlock, allowing for the safe control of up to 16 bidirectional motors. The hardware interlock prevents simultaneous activation of the 'up' and 'down' relays for a single motor, protecting it from damage.
For controlling lights and demanding electrical circuits, we offer other dedicated controllers.
## Key Features [#key-features]
* **35 digital inputs** for connecting switches, motion sensors, contact sensors and others.
* **32 relay outputs** paired for controlling **16 roller shutters**.
* **Hardware interlock** for motor protection.
* **3 analog inputs** for integration with analog sensors (e.g., light or wind sensors).
* **Reliable network connection** via an **Ethernet port** and **USB-C**.
* **Wide expansion capabilities** thanks to **Modbus, I2C, CAN and 1-Wire** interfaces.
* Built-in **OLED screen** for a quick overview of the device's status.
* Standard **DIN rail mounting (12 modules)**.
## Use Cases [#use-cases]
The boneIO Cover model is the perfect choice for:
* Complete automation of roller shutters in single-family homes and large apartments.
* Centralized control of all blinds from a single point or via an app.
* Creating schedules for automatic opening and closing of shutters based on time or sunlight.
* Integration with an alarm system to automatically close all shutters when the alarm is armed.
## Technical Specification [#technical-specification]
| Feature | Value |
| ----------------------- | ------------------------------------------------------------------------ |
| **Module** | ESP32 |
| **Power Supply** | 24V DC |
| **Power Consumption** | 3W - 15W |
| **Digital Inputs** | 35 |
| **Inputs Voltage** | 24V DC |
| **Relay Outputs** | 32 (16 pairs with hardware interlock) |
| **Max Output Voltage** | 230V AC / 30V DC |
| **Max Output Current** | 10A |
| **Analog Inputs** | 3 (A\_1 - 0-5V, A\_2 - 0-10V, A\_3 0-25V) |
| **External Interfaces** | Modbus RS485, I2C bus, 1-Wire, CAN (for future use) |
| **Communication** | Ethernet 10/100Mbit, USB-C (for firmware installation) |
| **Dimensions (WxHxD)** | 216mm x 106mm x 57mm (without plugs) / 216mm x 123mm x 57mm (with plugs) |
| **Mounting Width** | 12 DIN modules |
| **Weight** | 800g |
## Connectors and Components Description [#connectors-and-components-description]
1. **Power Supply Connector (VCC/GND):** Main power supply for the device (24V DC).
2. **Cover Up/Down Screw Terminals (1-16):** Cover outputs, grouped in pairs for cover control.
3. **Inputs control switch** - inputs can be controlled either by + or GND.
4. **IN Screw Terminals (1-35):** Digital inputs.
5. **I²C bus connector:** I²C bus connector for connecting I²C devices.
6. **CAN bus connector:** CAN bus connector for connecting CAN devices. **For future use**.
7. **Modbus RS485 connector:** Modbus RS485 connector for connecting Modbus devices.
8. **1-Wire bus connector:** 1-Wire bus connector for connecting 1-Wire devices.
9. **GPIO connector:** GPIO connector for connecting device which can transmit data to ESP32 GPIO. It's pulled down to GND.
10. **ADC connector:** ADC connector for connecting analog sensors to get analog reading of voltage.
11. **OLED Screen:** Displays key information about the device's status, such as IP address, connection status, or CPU load.
12. **Control Button:** Located next to the screen, used to switch between different views on the OLED display.
13. **USB-C Connector:** For connecting to a computer to upload firmware.
14. **Ethernet Port (RJ45):** For connecting to the LAN.
## Quick Start Guide [#quick-start-guide]
1. **Device Installation:** A qualified person must mount the device on a DIN rail.
2. **Network Connection:** Plug a LAN cable into the RJ45 port.
3. **Add to Home Assistant:** Home Assistant discovers the controller on your network — see [Connecting boneIO ESP](/en/docs/home-assistant/boneio-esp). Firmware from [boneio.eu/esp](https://boneio.eu/esp) has no web panel by default. If you want to open the controller in a browser at its IP address, choose the **+ web panel** variant in the installer ([what that means](/en/docs/esp/security)).
4. **Estimate Shutter Movement Time:** Measure the time it takes for the shutter to fully open or close.
5. **Connect the Shutter:** Turn off the shutter's circuit breaker. Connect the shutter motor to the `Cover01 Up/Down` outputs.
6. **Compile and Upload Firmware:** Set the estimated movement time in the configuration and upload the new firmware.
7. **Test the Shutter:** Run the shutter from Home Assistant to verify the configuration.
## Certificates [#certificates]
* [EU Declaration of Conformity (CE)](https://cdn.boneio.eu/certificates/boneio_esp_all_en.pdf)
## What's Next? [#whats-next]
You can find detailed instructions on the dedicated pages. Go ahead and read it!
# Hardware Installation (/en/docs/esp/products/esp_cover_mix/hardware-installation)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
***
## DIN Rail Mounting [#din-rail-mounting]
The boneIO ESP controller is designed for mounting on a standard DIN rail (TS35).
1. Hook the upper clips of the enclosure onto the top edge of the DIN rail.
2. Press the lower part of the enclosure firmly until the latches lock onto the rail with a distinct click.
3. Ensure the module is securely mounted.
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 24V DC power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+24V` output of the power supply to the `+` screw terminal on the boneIO.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO.
4. Double-check the connections and polarity before turning on the power supply.
## Connect Ethernet [#connect-ethernet]
The device communicates with the network using a built-in Ethernet port, which guarantees a stable and reliable connection. To establish connectivity, connect the module to your network switch using a standard Ethernet (RJ45) cable.
1. Connect ethernet cable to LAN port on your controller.
2. Connect other side of ethernet cable to your network switch.
## Connecting Digital Inputs [#connecting-digital-inputs]
Digital inputs are used to connect buttons and sensors. To change the potential used to control the inputs, use the switch on the casing marked `INPUTS`. By default, the inputs are controlled by ground (GND).
> **IMPORTANT: If you want to change the position of the switch - make sure you do it while the device is turned off!**
1. Connect one of the wires from a momentary switch to the common `GND` (ground) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will short the input to ground, which will be interpreted as an "on" signal.
### Logical diagram of connecting digital input [#logical-diagram-of-connecting-digital-input]
### Example: [#example]
### Example 2: [#example-2]
### Example 3: [#example-3]
## Connecting Relay Outputs [#connecting-relay-outputs]
The key feature of the Covermix version is that it has 32 relays in total, but half of them (16) are are paired to control up to 8 roller shutter motors. Each pair of relays (e.g., Cover 01`UP`/`DOWN`, Cover 02 `UP`/`DOWN`) is protected by a hardware interlock to prevent simultaneous 'up' and 'down' signals, which protects the motor from damage. The rest of relays (16) are classic 10A relays which are usually used in lighting circuits. This provides tremendous possibilities for controlling a large number of independent circuits from a single device, saving both space and complexity.
### Protection and Correct Wiring Order [#protection-and-correct-wiring-order]
**It is critical that all overcurrent protection (Miniature Circuit Breakers, MCBs) and residual-current devices (RCDs) are installed in the circuit *before* the boneIO controller.**
The current rating (in Amps) of the overcurrent protection must be sized appropriately for the planned load of the circuit (e.g. cover motors, lighting), but at the same time, it **must not exceed the maximum rated current of the relay, which is 10A**.
The correct current flow for the phase (L) for covers - wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> UP/DOWN terminal in boneIO
-> COVER`
The correct current flow for the phase (L) for relays - wire is as follows:
`RCD Protection
-> Overcurrent Protection (MCB)
-> COM terminal in boneIO
-> OUT terminal in boneIO
-> Load`
### Part 1: Connecting Cover Outputs (OUT1 - OUT16) Cover 1-8 [#part-1-connecting-cover-outputs-out1---out16-cover-1-8]
These outputs are designed to control bidirectional 230V AC motors for roller shutters or blinds. They are grouped in pairs (e.g., OUT1/OUT2, OUT3/OUT4) and feature a **hardware interlock** to prevent the motor from being damaged.
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 10A), to the `COM` terminal of the selected Cover output (e.g., `Cover 01 COM`).
2. Connect the wire leading to the **Cover motor UP** to the `UP` terminal of the same output (e.g., `Cover 01 UP`).
3. Connect the wire leading to the **Cover motor DOWN** to the `DOWN` terminal of the same output (e.g., `Cover 01 DOWN`).
4. Run the **neutral wire (N)** directly to the load (cover engine).
### Logical diagram: [#logical-diagram]
### Part 2: Connecting Relay Outputs (OUT17 - OUT32) [#part-2-connecting-relay-outputs-out17---out32]
These are standard relay outputs for general-purpose use, such as controlling lighting.
1. Connect the **phase wire (L)**, coming from the dedicated overcurrent protection (MCB ≤ 10A), to the `COM` terminal of the selected output (e.g., `COM9` for `OUT17` and `OUT18`).
2. Connect the wire leading to the **load** (e.g., a lamp) to the corresponding output terminal (e.g., `OUT17`).
3. Run the **neutral wire (N)** directly to the load.
### Logical Diagram [#logical-diagram-1]
### Safe Connecting of COM and OUT Terminals [#safe-connecting-of-com-and-out-terminals]
In the boneIO controller, version Covermix **every two outputs (e.g., Cover 01 UP, DOWN) and also outputs dedicated for lights (e. g. OUT17, OUT18) share a single common power terminal `COM`**. This means that the phase wire (L) from a single circuit breaker supplies a pair of relays - with hardware interlock.
1. **REMEMBER**, ensure that the relevant circuit breakers in the electrical cabinet **are turned off**.
2. Connect the **phase wire (L)**, coming from the overcurrent protection, to the appropriate COM terminal - tighten it with adequate force.
3. Connect the wire leading to your load (e.g., cover motor, a light bulb) to **its corresponding output terminal** - tighten it with adequate force.
4. Run the neutral (N) wire directly from the neutral bar to the load.
### Part 1: [#part-1]
### Part 2: [#part-2]
## Connecting Communication Buses [#connecting-communication-buses]
### I2C Bus [#i2c-bus]
For connecting additional sensors and expanders over short distances.
* Connect the `SDA` line to the `SDA` terminal.
* Connect the `SCL` line to the `SCL` terminal.
* Also, connect the `VCC` and `GND` power for the sensor.
### CAN [#can]
Used for communication with industrial HVAC devices and sensors.
* Connect the `L` line of the bus to the `L` terminal on the boneIO.
* Connect the `H` line of the bus to the `H` terminal on the boneIO.
### Modbus RS485 [#modbus-rs485]
Used for communication with industrial and HVAC devices.
* Connect the `A` line of the bus to the `A` terminal on the boneIO.
* Connect the `B` line of the bus to the `B` terminal on the boneIO.
> ESP series devices have undergone Modbus RTU bus testing with 5 connected devices. Using a larger number of Modbus devices connected to an ESP series controller may cause delays in the controller's response (both inputs and outputs). This is due to the specifics of the processor used. In the case of extensive Modbus buses, we recommend splitting them across several devices.
### 1-Wire Bus [#1-wire-bus]
Popular for connecting temperature sensors (e.g., DS18B20).
* Connect the `DATA` line to the `1-Wire` terminal.
* Also, connect `VCC` and `GND` power.
The maximum length of the bus cable is 20m.
## Connecting Analog Inputs [#connecting-analog-inputs]
Analog inputs allow you to read values from sensors that do not operate in a binary (on/off) manner.
### Analog Inputs ADC [#analog-inputs-adc]
The boneIO controller is equipped with three analog inputs, utilizing integrated voltage dividers to support a variety of voltage ranges for connecting different sensors.
| Input Name | ESP32 GPIO Number | Voltage |
| :--------: | :---------------: | :-----: |
| A\_1 | GPIO39 | 0 - 5V |
| A\_2 | GPIO36 | 0 - 10V |
| A\_3 | GPIO35 | 0 - 25V |
## Final Checks [#final-checks]
After completing the installation:
1. Double-check all connections.
2. Ensure there are no short circuits.
3. Turn on the main power (24V DC power supply).
4. The device's OLED screen should light up, indicating it has started successfully.
# Overview and Specification (/en/docs/esp/products/esp_cover_mix/overview)
# boneIO ESP Cover Mix [#boneio-esp-cover-mix]
You can buy the controller -> [HERE](https://store.boneio.eu/product/boneio-esp-cover/?v=288404204e3d)
Utilizing the versatile **ESP32 microcontroller** and the simplicity of **ESPHome** software, the boneIO ESP controller provides an extremely flexible and easy-to-configure core for your smart home automation.
With 35 digital inputs, 8 roller blind outputs, and 16 relay outputs, a single unit has enough power to manage all the automation in a house or apartment. This includes lighting and heating systems, as well as controlling entrance and garage gates by providing a pulse to the drive. It is also possible to control roller blinds thanks to dedicated outputs.
**boneIO ESP Cover Mix** is a versatile controller that combines the features of a standard relay module with a specialized roller blind controller. It features 32 relays, 16 of which are paired with a hardware interlock to control up to 8 bidirectional motors (e.g., roller blinds), while the remaining 16 relays can be used for general purposes, such as controlling lighting circuits.
## Key Features [#key-features]
* **35 digital inputs** for connecting switches, motion sensors, contact sensors and others.
* **Hybrid Outputs:** 32 relays in total, including 8 pairs with a **hardware interlock (motor protection)** for controlling **8 roller shutters** and **16 individual relays (10A)** for general use.
* **3 analog inputs** for integration with analog sensors (e.g., light or wind sensors).
* **Reliable network connection** via an **Ethernet port** and **USB-C**.
* **Wide expansion capabilities** thanks to **Modbus, I2C, CAN and 1-Wire** interfaces.
* Built-in **OLED screen** for a quick overview of the device's status.
* **Standard DIN Rail Mounting (12 modules)**.
## Use Cases [#use-cases]
The boneIO Cover Mix model is perfect choice for:
* Comprehensive automation of roller shutters and lighting in single-family homes and large apartments.
* Creating advanced scenes combining shutter control and lighting.
* Integration with an alarm system to automatically close all shutters when the alarm is armed.
* Integration with various sensors for advanced automation scenarios.
* Automating HVAC systems (heating, ventilation, air conditioning) thanks to Modbus support.
## Technical Specification [#technical-specification]
| Feature | Value |
| ----------------------- | ------------------------------------------------------------------------ |
| **Module** | ESP32 |
| **Power Supply** | 24V DC |
| **Power Consumption** | 3W - 15W |
| **Digital Inputs** | 35 |
| **Inputs Voltage** | 24V DC |
| **Relay Outputs** | 32 (16 general purpose + 8 pairs with hardware interlock) |
| **Max Output Voltage** | 230V AC / 30V DC |
| **Max Output Current** | 10A |
| **Analog Inputs** | 3 (A\_1 - 0-5V, A\_2 - 0-10V, A\_3 0-25V) |
| **External Interfaces** | Modbus RS485, I2C bus, 1-Wire, CAN (for future use) |
| **Communication** | Ethernet 10/100Mbit, USB-C (for firmware installation) |
| **Dimensions (WxHxD)** | 216mm x 106mm x 57mm (without plugs) / 216mm x 123mm x 57mm (with plugs) |
| **Mounting Width** | 12 DIN modules |
| **Weight** | 800g |
## Connectors and Components Description [#connectors-and-components-description]
1. **Power Supply Connector (VCC/GND):** Main power supply for the device (24V DC).
2. **OUT Screw Terminals:** Top part **Cover Up/Down (for cover 1-8)** lower part **Relay outputs 17-32**.
3. **Inputs control switch:** Inputs can be controlled either by + or GND.
4. **IN Screw Terminals (1-35):** Digital inputs.
5. **I²C bus connector:** For connecting I²C devices.
6. **CAN bus connector:** For connecting CAN devices. **For future use**.
7. **Modbus RS485 connector:** For connecting Modbus devices.
8. **1-Wire bus connector:** For connecting 1-Wire devices.
9. **GPIO connector:** For connecting devices that can transmit data to ESP32 GPIO. It's pulled down to GND.
10. **ADC connector:** For connecting analog sensors to get an analog reading of voltage.
11. **OLED Screen:** Displays key information about the device's status.
12. **Control Button:** Used to switch between different views on the OLED display.
13. **USB-C connector:** For connecting to a computer to upload the firmware.
14. **Ethernet Port (RJ45):** For connecting to the LAN.
## Quick Start Guide [#quick-start-guide]
1. **Device Installation:** A qualified person must mount the device on a DIN rail.
2. **Network Connection:** Plug a LAN cable into the RJ45 port.
3. **Add to Home Assistant:** Home Assistant discovers the controller on your network — see [Connecting boneIO ESP](/en/docs/home-assistant/boneio-esp). Firmware from [boneio.eu/esp](https://boneio.eu/esp) has no web panel by default. If you want to open the controller in a browser at its IP address, choose the **+ web panel** variant in the installer ([what that means](/en/docs/esp/security)).
4. **Estimate Shutter Movement Time:** Measure the time it takes for the shutter to fully open or close.
5. **Connect the Shutter:** Turn off the shutter's circuit breaker. Connect the shutter motor to the `Cover01 Up/Down` outputs.
6. **Compile and Upload Firmware:** Set the estimated movement time in the configuration and upload the new firmware.
7. **Test the Shutter:** Run the shutter from Home Assistant to verify the configuration.
## Certificates [#certificates]
* [EU Declaration of Conformity (CE)](https://cdn.boneio.eu/certificates/boneio_esp_all_en.pdf)
## What's Next? [#whats-next]
You can find detailed instructions on the following pages:
* **[Hardware Installation](./hardware-installation):** Detailed wiring diagrams.
* **[Software Setup](./software_setup):** A step-by-step guide to configure your device.
# Hardware Installation (/en/docs/esp/products/input_24_g2/hardware-installation)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
***
## DIN Rail Mounting [#din-rail-mounting]
The boneIO ESP controller is designed for mounting on a standard DIN rail (TS35).
1. Hook the upper clips of the enclosure onto the top edge of the DIN rail.
2. Press the lower part of the enclosure firmly until the latches lock onto the rail with a distinct click.
3. Ensure the module is securely mounted.
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 12-24V DC power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+` output of the power supply to the `+` screw terminal on the boneIO.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO.
4. Double-check the connections and polarity before turning on the power supply.
## Connect Ethernet [#connect-ethernet]
The device communicates with the network using a built-in Ethernet port, which guarantees a stable and reliable connection. To establish connectivity, connect the module to your network switch using a standard Ethernet (RJ45) cable.
1. Connect ethernet cable to LAN port on your controller.
2. Connect other side of ethernet cable to your network switch.
## Connecting Digital Inputs [#connecting-digital-inputs]
Digital inputs are used for connecting switches and sensors. By default, they are ground-controlled.
1. Connect one of the wires from a momentary switch to the common `GND` (ground) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will short the input to ground, which will be interpreted as an "on" signal.
### Logical diagram of connecting digital input [#logical-diagram-of-connecting-digital-input]
### GND or + [#gnd-or-]
Input behavior can be changed via the internal switch. Please see the switch location below.
* Down: GND control.
* Up: High-potential control.
### Example: [#example]
### Example 2: [#example-2]
### Example 3: [#example-3]
## Connecting Communication Buses [#connecting-communication-buses]
### Modbus RS485 [#modbus-rs485]
Used for communication with industrial and HVAC devices.
* Connect the `A` line of the bus to the `A` terminal on the boneIO.
* Connect the `B` line of the bus to the `B` terminal on the boneIO.
> ESP series devices have undergone Modbus RTU bus testing with 5 connected devices. Using a larger number of Modbus devices connected to an ESP series controller may cause delays in the controller's response (both inputs and outputs). This is due to the specifics of the processor used. In the case of extensive Modbus buses, we recommend splitting them across several devices.
### CAN [#can]
Used for communication with industrial HVAC devices and sensors.
* Connect the `L` line of the bus to the `L` terminal on the boneIO.
* Connect the `H` line of the bus to the `H` terminal on the boneIO.
## Final Checks [#final-checks]
After completing the installation:
1. Double-check all connections.
2. Ensure there are no short circuits.
3. Turn on the main power (24V DC power supply).
# Overview and Specification (/en/docs/esp/products/input_24_g2/overview)
# boneIO ESP Input24 gen2 [#boneio-esp-input24-gen2]
You can buy the controller -> [HERE](https://store.boneio.eu/product/boneio-esp-input24-gen2/?v=288404204e3d)
Leveraging the versatile **ESP32-S3 microcontroller** and the simplicity of **ESPHome**, the boneIO ESP Input24 gen2 controller provides an incredibly easy way to expand number of inputs in your Home Automation system.
Thanks to 24 digital inputs placed in an extremely small enclosure - we significantly increase the system's potential. The controller can be used for button control or as a central unit for handling motion sensors and reed switches!
The **boneIO Input24** was primarily designed as a device to increase the number of inputs supported by the system.
## Key Features [#key-features]
* **24 digital inputs** For connecting switches, motion sensors, contact sensors and others.
* Reliable network connection via **Ethernet** and **WiFi** (with external antenna).
* Wide expansion capabilities thanks to **Modbus, and CAN interfaces.**
* **USB-C port** for easy firmware installation.
* Compact **7-module DIN rail** enclosure.
## Use Cases [#use-cases]
The boneIO ESP Input24 gen2 controller is the perfect choice for:
* Integration with an alarm system by collecting signals from sensors.
* Integration with various sensors for advanced automation scenarios.
* Automating HVAC systems (heating, ventilation, air conditioning) thanks to Modbus support.
## Technical Specification [#technical-specification]
| Feature | Value |
| ----------------------- | ------------------------------------------------------------------------ |
| **Module** | ESP32-S3 |
| **Power Supply** | 12-24V DC |
| **Power Consumption** | Max. 7W |
| **Digital Inputs** | 24 |
| **External Interfaces** | Modbus RS485, CAN |
| **Communication** | Ethernet 10/100Mbit, Wi-Fi (with external antenna), USB-C (for firmware) |
| **Dimensions (WxHxD)** | 126mm x 91mm x 57mm (without plugs) / 126mm x 108mm x 57mm (with plugs) |
| **Mounting Width** | 7 DIN modules |
| **Weight** | 230g |
## Connectors and Components Description [#connectors-and-components-description]
1. **Power Connector (VCC/GND):** Main device power supply (12-24V DC).
2. **IN (1-8) Screw Terminals:** Digital inputs for buttons or sensors.
3. **Modbus RS485 Connector:** Modbus connector for connecting Modbus devices.
4. **CAN Bus Connector:** CAN connector for connecting CAN devices.
5. **USB-C Connector:** For uploading firmware.
6. **Ethernet Port (RJ45):** For connecting to the LAN.
## Quick Start Guide [#quick-start-guide]
1. **Device Installation:** A qualified person must mount the device on a DIN rail.
2. **Connect input:** Connect a switch to input **IN01**. Press the switch – the input should change its state.
3. **Network Connection:** Plug a LAN cable into the RJ45 port.
4. **Add to Home Assistant:** Home Assistant discovers the controller on your network — see [Connecting boneIO ESP](/en/docs/home-assistant/boneio-esp). Firmware from [boneio.eu/esp](https://boneio.eu/esp) has no web panel by default. If you want to open the controller in a browser at its IP address, choose the **+ web panel** variant in the installer ([what that means](/en/docs/esp/security)).
## Certificates [#certificates]
* [EU Declaration of Conformity (CE)](https://cdn.boneio.eu/certificates/boneio_esp_all_en.pdf)
## What's Next? [#whats-next]
You can find detailed instructions on the dedicated pages. Go ahead and read it!
# Actions (/en/docs/black/products/black_24x16a/software_setup/actions)
## What it's all about? [#what-its-all-about]
Actions are best way to made some simple core automations inside of your controller. With them its possible to made some cricital automations
inside of your boneIO Black.
To make it easy i will give you some example and will describe it:
```yaml
- id: IN_01_living_room1
boneio_input: IN_01
actions:
single:
- action: output
pin: OUT_01_living_room_light_1
double:
- action: output
pin: OUT_02_living_room_light_2
long:
- action: output
pin: OUT_03_living_room_light_3
- id: IN_02_living_room2
boneio_input: IN_02
actions:
single:
- action: output
pin: OUT_04_living_room_light_4
long:
- action: output
pin: OUT_01_living_room_light_1
action_output: off
- action: output
pin: OUT_02_living_room_light_2
action_output: off
- action: output
pin: OUT_03_living_room_light_3
action_output: off
- action: output
pin: OUT_04_living_room_light_4
action_output: off
```
What have we achived? By using just 2 buttons we can independly turn on 4 lights, an by single long click of one of them you can turn all of them off.
In the case of `IN_01_living_room1` its really simple, we define each action fo each action type, in our case for `single` click Living room light 1
for `double` Living room light 2 and for `long` click Living room light 3. The default action for `- action: output` type its `toogle`
So by simple click of the button you will change the state of light from on to off etc.
In the case of button 2 - `IN_02_living_room2` with single click you will change state of Living room light 4. But intresting thing will happen if
you `long` click that button. That will turn off all 4 defined lights in living room. There are many possibilities with actions!
If you want to know more - please check documentation.
# Configure areas (/en/docs/black/products/black_24x16a/software_setup/configure-areas)
Areas are rooms or zones that group devices in Home Assistant. The area configuration in boneIO must match the configuration in Home Assistant.
With properly configured areas, you can automatically create a simple dashboard in Home Assistant divided by these areas - all devices from a given area will be automatically grouped together.
## Important information [#important-information]
**Every area name change in Home Assistant requires a name change in the boneIO application!**
Area names must be identical 1:1 with the names in Home Assistant. It's worth configuring areas carefully from the very beginning to avoid problems later.
## How to configure areas? [#how-to-configure-areas]
1. Go to the **Settings** tab
2. Find the **Areas** section
3. Click the **Add area** button or edit an existing one
4. Enter the area name **exactly the same** as in Home Assistant
5. Click **Save**
6. Wait for the application to reload
## Synchronization with Home Assistant [#synchronization-with-home-assistant]
### Before configuring in boneIO [#before-configuring-in-boneio]
1. Open Home Assistant
2. Go to **Settings** → **Areas & zones**
3. Note down the exact names of all areas (case sensitive!)
4. Use the same names in boneIO configuration
### After changing the name in Home Assistant [#after-changing-the-name-in-home-assistant]
If you change an area name in Home Assistant:
1. Open the boneIO interface
2. Go to **Settings** → **Device** → **Areas/Rooms**
3. Edit the corresponding area
4. Change the name to the new one (same as in HA)
5. Save and wait for reload
## Export and Import areas [#export-and-import-areas]
You can transfer area configuration between devices:
1. On the first device: click **Export** in the Areas section
2. Save the YAML file
3. On the second device: click **Import** in the Areas section
4. Load the saved YAML file
5. Save and wait for reload
## Best practices [#best-practices]
* **Plan ahead** - think through area names before starting configuration
* **Use simple names** - avoid special characters and diacritics
* **Be consistent** - use the same naming convention across all devices
* **Document changes** - save an export after each major change as a backup
# Configure binary sensors (/en/docs/black/products/black_24x16a/software_setup/configure-binary-sensors)
Binary sensors are ideal for devices with two states: motion sensors, reed switches, flood sensors, etc.
## How to add or edit a binary sensor? [#how-to-add-or-edit-a-binary-sensor]
1. Go to **Settings** → **Control** → **Local Inputs**
2. Click **Add New** or the edit icon next to an existing sensor
3. Fill in the configuration form
## Basic settings [#basic-settings]
### Display Name [#display-name]
Friendly name for the sensor, e.g.:
* `Living Room Motion Sensor`
* `Front Door`
* `Bedroom Window`
This name will be visible in the interface and Home Assistant.
### BoneIO Input [#boneio-input]
Select the physical input from the dropdown:
* `IN_01`, `IN_02`, `IN_03`, ... `IN_56` (depending on model)
**Avoid inputs with limitations** (IN\_01, IN\_02, IN\_09, IN\_10, IN\_19, IN\_20, IN\_21, IN\_29–IN\_34) for reed switches and motion sensors that may be active at controller startup.
### Area / Room [#area--room]
Select an area from the dropdown - the sensor will be automatically assigned to this area in Home Assistant.
### Bounce Time [#bounce-time]
Contact debounce time (default: 120ms). For motion sensors and reed switches, usually no change is needed.
### Device Class [#device-class]
Device class in Home Assistant - affects icon and behavior:
| Device Class | Icon | Use Case |
| ------------- | --------- | ----------------------- |
| **motion** | Motion | Motion sensors |
| **door** | Door | Door reed switches |
| **window** | Window | Window reed switches |
| **opening** | Opening | General opening sensors |
| **moisture** | Water | Flood sensors |
| **smoke** | Smoke | Smoke detectors |
| **gas** | Gas | Gas detectors |
| **occupancy** | Occupancy | Occupancy sensors |
| **vibration** | Vibration | Vibration sensors |
| **tamper** | Tamper | Tamper sensors |
## Options [#options]
### Show in HA [#show-in-ha]
Enable to make the sensor visible in Home Assistant (enabled by default).
### Inverted [#inverted]
Invert sensor logic:
* Normal: active input = sensor ON
* Inverted: active input = sensor OFF
Useful when a reed switch is mounted in reverse.
### Initial Send [#initial-send]
Send sensor state at controller startup.
## Actions - Pressed and Released [#actions---pressed-and-released]
Binary sensors have two action tabs:
### Pressed [#pressed]
Actions executed when the sensor changes to active state (e.g., motion detected, door opened).
### Released [#released]
Actions executed when the sensor changes to inactive state (e.g., no motion, door closed).
## How to add an action? [#how-to-add-an-action]
1. Go to the **Pressed** or **Released** tab
2. Click **Add Action**
3. Select the action type and configure parameters
### Action types [#action-types]
| Action Type | Description |
| ---------------------- | -------------------------------------- |
| **output** | Control an output (light, switch) |
| **cover** | Control a cover |
| **virtual\_switch** | Set a virtual switch (ON, OFF, TOGGLE) |
| **mqtt** | Send an MQTT message |
| **output\_over\_mqtt** | Control an output via MQTT |
| **cover\_over\_mqtt** | Control a cover via MQTT |
| **remote\_output** | Control an output on a remote device |
| **remote\_cover** | Control a cover on a remote device |
Every action can also have conditions (time, date, state, sun) and, on binary sensors, a delay. The full list of types, values and options is in [Actions](/en/docs/black/current/configuration/event#actions).
## Configuration examples [#configuration-examples]
### Example 1: Hallway motion sensor [#example-1-hallway-motion-sensor]
1. **Display Name**: `Hallway Motion Sensor`
2. **BoneIO Input**: `IN_05` (avoid inputs with limitations)
3. **Area / Room**: `Hallway`
4. **Device Class**: `motion`
**Actions:**
* **Pressed**: ON `Hallway Light`
* **Released**: OFF `Hallway Light`
### Example 2: Front door reed switch [#example-2-front-door-reed-switch]
1. **Display Name**: `Front Door`
2. **BoneIO Input**: `IN_06`
3. **Area / Room**: `Entrance`
4. **Device Class**: `door`
5. **Inverted**: ✅ (if reed switch shows reversed)
No actions - just state monitoring in Home Assistant.
### Example 3: Flood sensor [#example-3-flood-sensor]
1. **Display Name**: `Bathroom Flood Sensor`
2. **BoneIO Input**: `IN_07`
3. **Area / Room**: `Bathroom`
4. **Device Class**: `moisture`
**Actions:**
* **Pressed**: OFF `Main Water Valve` (automatic valve closure when water detected)
After saving, the sensor will appear in the table and be available in Home Assistant with the appropriate icon and device class.
# Configure events (/en/docs/black/products/black_24x16a/software_setup/configure-events)
Events allow you to assign different actions to a single button depending on the click type.
## How to add or edit an event? [#how-to-add-or-edit-an-event]
1. Go to **Settings** → **Control** → **Local Inputs**
2. Click **Add New** or the edit icon next to an existing event
3. Fill in the configuration form
## Basic settings [#basic-settings]
### Display Name [#display-name]
Friendly name for the event, e.g.:
* `Living Room Button`
* `Bedroom Switch`
* `Doorbell`
This name will be visible in the interface and Home Assistant.
### BoneIO Input [#boneio-input]
Select the physical input from the dropdown:
* `IN_01`, `IN_02`, `IN_03`, ... `IN_56` (depending on model)
Inputs already used by other events or binary sensors are automatically hidden from the list.
### Area / Room [#area--room]
Select an area from the dropdown - the event will be automatically assigned to this area in Home Assistant.
## Actions - click tabs [#actions---click-tabs]
The form has separate tabs for each click type:
### Single (Single click) [#single-single-click]
Actions executed after a single button click.
### Double (Double click) [#double-double-click]
Actions executed after a quick double click.
### Triple (Triple click) [#triple-triple-click]
Actions executed after a triple click.
Triple click must be enabled in advanced settings (disabled by default).
### Long (Long press) [#long-long-press]
Actions executed after holding the button for a specified time.
## How to add an action? [#how-to-add-an-action]
1. Go to the appropriate tab (Single, Double, Triple, Long)
2. Click **Add Action**
3. Select the action type and configure parameters
### Action types [#action-types]
| Action Type | Description |
| ---------------------- | -------------------------------------- |
| **output** | Control an output (light, switch) |
| **cover** | Control a cover |
| **virtual\_switch** | Set a virtual switch (ON, OFF, TOGGLE) |
| **mqtt** | Send an MQTT message |
| **output\_over\_mqtt** | Control an output via MQTT |
| **cover\_over\_mqtt** | Control a cover via MQTT |
| **remote\_output** | Control an output on a remote device |
| **remote\_cover** | Control a cover on a remote device |
Every action can also have conditions (time, date, state, sun). The full list of types, values and options is in [Actions](/en/docs/black/current/configuration/event#actions).
### Output action [#output-action]
The most commonly used action - control an output:
| Parameter | Description |
| ---------- | --------------------------------------------- |
| **Output** | Select output from the list |
| **Action** | TOGGLE (toggle), ON (turn on), OFF (turn off) |
### Cover action [#cover-action]
Control a cover:
| Parameter | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Cover** | Select cover from the list |
| **Action** | TOGGLE, OPEN, CLOSE, STOP, TOGGLE\_OPEN, TOGGLE\_CLOSE, SMART\_TOGGLE; for venetian blinds also TILT, TILT\_OPEN, TILT\_CLOSE |
## Sequences [#sequences]
Sequences are advanced click combinations:
| Sequence | Description |
| ------------------- | ------------------------- |
| **Double → Long** | Double click, then hold |
| **Single → Long** | Single click, then hold |
| **Double → Single** | Double click, then single |
Each sequence can have its own actions and optionally send an MQTT event.
## Advanced settings [#advanced-settings]
Click the **Advanced Settings** tab to access additional options:
### Bounce Time [#bounce-time]
Contact debounce time (default: 30ms). Increase if the button generates false clicks.
### Double Click Duration [#double-click-duration]
Maximum time between clicks for a double click (default: 220ms).
This parameter affects single click delay - the controller waits this time to check if a second click will follow.
### Long Press Duration [#long-press-duration]
Hold time for a long click (default: 400ms).
### Sequence Window Duration [#sequence-window-duration]
Time window for sequences (default: 500ms).
### Sequence Mode [#sequence-mode]
| Mode | Description |
| ------------- | ---------------------------------------------- |
| **Immediate** | Actions executed immediately upon detection |
| **Exclusive** | Waits for sequence completion before executing |
### Enable Triple Click [#enable-triple-click]
Enable triple click support (disabled by default).
## Configuration example [#configuration-example]
**Scenario**: A button in the living room controlling lighting.
1. **Display Name**: `Living Room Button`
2. **BoneIO Input**: `IN_04`
3. **Area / Room**: `Living Room`
**Actions:**
* **Single**: Toggle `Living Room Main Light`
* **Double**: Toggle `Living Room Lamp`
* **Long**: OFF `Living Room Main Light`, OFF `Living Room Lamp` (turn off everything)
After saving, the event will appear in the table and be available in Home Assistant.
# Edit configuration (/en/docs/black/products/black_24x16a/software_setup/edit-configuration)
The **Settings** tab contains forms for configuring all controller functions. Here you can configure outputs, inputs, areas, events, and many other options.
## Important configuration rules [#important-configuration-rules]
### Saving changes [#saving-changes]
**Each edit in a given section requires saving and waiting for reload or restart of the application before you start working on the next section.**
After saving changes:
1. Click the **Save** button in the given section
2. Wait for save confirmation
3. Wait for the application to reload or restart
4. Only then proceed to edit the next section
### Export and Import [#export-and-import]
Each configuration section has **Export** and **Import** buttons:
* **Export** - saves the configuration of the given section to a YAML file
* **Import** - loads the configuration from a YAML file
This allows you to:
* Manually copy configuration sections
* Transfer created configurations between devices
* Create backups of individual sections
## Configuration sections [#configuration-sections]
In the Settings tab you will find the following sections:
* **Areas** - defining areas compatible with Home Assistant
* **Outputs** - relay output configuration
* **Covers** - cover and blind configuration
* **Inputs** - digital input configuration
* **Events** - event and automation definitions
* **Binary Sensors** - binary sensor configuration
* **Actions** - action definitions
* And more...
# Events and Binary Sensors (/en/docs/black/products/black_24x16a/software_setup/events-and-binary-sensors)
In boneIO Black you have two types of inputs to choose from: **Events** and **Binary Sensors**. The choice depends on what device you're connecting.
## Events - for buttons [#events---for-buttons]
Events are the best choice for **wall switches**. They allow detection of different click types:
| Click Type | Description |
| ------------- | ---------------------------------- |
| **Single** | Single click |
| **Double** | Double click |
| **Triple** | Triple click |
| **Long** | Long press |
| **Sequences** | Combinations (e.g., double → long) |
**Example**: One button can turn on the main light (single), bedside lamp (double), and turn off all lights (long).
**Events have a minimal delay** for single clicks. The controller waits a short time (\~220ms) to check if another click will follow (double/triple). If you need immediate response, use a binary sensor.
## Binary Sensors - for sensors [#binary-sensors---for-sensors]
Binary sensors are the best choice for devices with two states:
| Device | States |
| ------------------ | --------------------------- |
| **Motion sensor** | Motion detected / No motion |
| **Reed switch** | Open / Closed |
| **Flood sensor** | Dry / Wet |
| **Smoke detector** | OK / Alarm |
**Advantages of binary sensors:**
* ✅ Immediate response (no delay)
* ✅ Actions on press (pressed) and release (released)
* ✅ Different device classes (motion, door, window, smoke, etc.)
## Which to choose? [#which-to-choose]
| Device | Input Type |
| ------------------------- | ------------------------------ |
| Wall switch | **Event** |
| Doorbell | **Event** or **Binary Sensor** |
| Motion sensor | **Binary Sensor** |
| Reed switch (door/window) | **Binary Sensor** |
| Flood sensor | **Binary Sensor** |
| Smoke detector | **Binary Sensor** |
## Input limitations [#input-limitations]
Some inputs on boneIO Black **cannot be active at controller startup**. We do not recommend connecting reed switches or motion sensors to them, as they may be active during startup.
| Inputs with limitations |
| ---------------------------------------------- |
| IN\_01, IN\_02 |
| IN\_09, IN\_10 |
| IN\_19, IN\_20, IN\_21 |
| IN\_29, IN\_30, IN\_31, IN\_32, IN\_33, IN\_34 |
For reed switches and motion sensors, use the remaining inputs (IN\_03 to IN\_08, IN\_11 to IN\_18, IN\_22 to IN\_28, and IN\_35 onwards).
# Events vs Binary Sensors (/en/docs/black/products/black_24x16a/software_setup/events-vs-binary-sensors)
In boneIO Black you have two types of inputs to choose from: **Events** and **Binary Sensors**. The choice depends on what device you're connecting.
## Events - for buttons [#events---for-buttons]
Events are the best choice for **wall switches**. They allow detection of different click types:
| Click Type | Description |
| ------------- | ---------------------------------- |
| **Single** | Single click |
| **Double** | Double click |
| **Triple** | Triple click |
| **Long** | Long press |
| **Sequences** | Combinations (e.g., double → long) |
**Example**: One button can turn on the main light (single), bedside lamp (double), and turn off all lights (long).
**Events have a minimal delay** for single clicks. The controller waits a short time (\~220ms) to check if another click will follow (double/triple). If you need immediate response, use a binary sensor.
## Binary Sensors - for sensors [#binary-sensors---for-sensors]
Binary sensors are the best choice for devices with two states:
| Device | States |
| ------------------ | --------------------------- |
| **Motion sensor** | Motion detected / No motion |
| **Reed switch** | Open / Closed |
| **Flood sensor** | Dry / Wet |
| **Smoke detector** | OK / Alarm |
**Advantages of binary sensors:**
* ✅ Immediate response (no delay)
* ✅ Actions on press (pressed) and release (released)
* ✅ Different device classes (motion, door, window, smoke, etc.)
## Which to choose? [#which-to-choose]
| Device | Input Type |
| ------------------------- | ------------------------------ |
| Wall switch | **Event** |
| Doorbell | **Event** or **Binary Sensor** |
| Motion sensor | **Binary Sensor** |
| Reed switch (door/window) | **Binary Sensor** |
| Flood sensor | **Binary Sensor** |
| Smoke detector | **Binary Sensor** |
## Input limitations [#input-limitations]
Some inputs on boneIO Black **cannot be active at controller startup**. We do not recommend connecting reed switches or motion sensors to them, as they may be active during startup.
| Inputs with limitations |
| ---------------------------------------------- |
| IN\_01, IN\_02 |
| IN\_09, IN\_10 |
| IN\_19, IN\_20, IN\_21 |
| IN\_29, IN\_30, IN\_31, IN\_32, IN\_33, IN\_34 |
For reed switches and motion sensors, use the remaining inputs (IN\_03 to IN\_08, IN\_11 to IN\_18, IN\_22 to IN\_28, and IN\_35 onwards).
# First-time setup (/en/docs/black/products/black_24x16a/software_setup/first-run-wizard)
The first time you open the panel of a new controller, you do not see the panel yet but the **First-time setup** wizard.
It creates the administrator account — the username and password you will sign in with from now on — and helps you get going.
The whole wizard takes a few minutes.
There is no way to skip the wizard. Until it is completed, the controller answers nothing except the wizard itself, so nobody can
change its configuration without a password.
The bar at the top shows how far you are (**Step 2 of 6**, for example). Not every controller sees every step:
| Step | When you see it |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| Start | Always. |
| Account | Always. |
| Which controller is this? | Only if the controller does not yet know which model it is. |
| Import | Only on a controller that still has its factory configuration. |
| Devices | Only on a controller that still has its factory configuration, and only if you did not import a backup. |
| Cloud | Only if boneIO Cloud registration is not already on, and only if you did not import a backup. |
| Done | Always. |
## Start [#start]
The wizard explains that the device has no administrator account yet, and under **What's ahead** lists the steps this controller will go through.
Click **Get started**.
## Account [#account]
Choose the **Username** and **Password** for the panel and type the password again under **Confirm password**.
* the password must be **at least 8 characters** long,
* it must **not contain the username** — the username is visible on the sign-in screen, so a password built from it is easy to guess.
Click **Create account**. From here on there is no way back to this step — the account exists.
The same account also opens the **Node-RED** editor: Node-RED has no accounts of its own, and only panel administrators get in.
**This password is also your SSH password.** On a new controller the wizard sets the same password for the `boneio` user.
Over SSH you always log in as `boneio` (for example `ssh boneio@192.168.1.100`) — the username you typed here is for the panel only.
This happens only once: changing the panel password later does not change the SSH password. For that, use the
[SSH login password](/en/docs/black/current/basic/accounts#ssh-login-password) card in **Settings → Access → User accounts**, or run `passwd` over SSH.
Write the password down somewhere safe.
## Which controller is this? [#which-controller-is-this]
You only see this step if the controller was not told at the factory which model it is. Until you answer, it has no outputs configured.
Pick your model — **32x10A**, **24x16A**, **Cover** or **Cover Mix** — and click **Apply**.
The controller restarts with that model's configuration, which takes up to a minute; the wizard waits and then carries on by itself.
The wizard does not come back to this step, so check the label on the controller first.
{/* SCREENSHOT: en_wizard_board.webp — "Which controller is this?" step with the four models */}
## Import (optional) [#import-optional]
If you are replacing an older boneIO and have a configuration backup from it (a `.tar.gz` file downloaded from
**Settings → Maintenance → Backups** on the old device), drop the file on **Choose a file or drag it here**, or click it to pick the file,
then click **Import configuration**. The controller will take over that configuration after a restart.
Setting up from scratch? Click **Skip**.
If you imported a backup, the Devices and Cloud steps are skipped — the imported configuration already decides them.
## Devices [#devices]
The outputs are already set up for your model. Here you decide what the inputs should do with them:
* **Inputs control outputs** — each input switches one output (a push button turns on a light),
* **Inputs control covers** — pairs of inputs open and close covers,
* **Inputs control covers and outputs** — a mix, on models that have both,
* **Wire nothing — I will do it myself** — leave the inputs empty and configure them later.
Leave **Restore relay and cover state after a restart** on (it is by default) if lights and covers should come back to where they were after a power cut.
Click **Apply**, or **Skip** to leave everything as it is. You can change all of it later in **Settings → Control → Local Inputs**.
## Cloud (optional) [#cloud-optional]
You can register the controller with **boneIO Cloud**. It then gets its own address with a trusted certificate — the browser stops
warning about the connection, and you can install the panel as an app on your phone.
* Registration sends the controller's serial number to boneIO Cloud.
* The controller is still reachable **only on your own network** — nothing is exposed to the internet.
* Your router must not block so-called *DNS rebinding*; if the new address does not open, that is usually the reason.
Click **Enable registration**, or **Skip**. You can turn it on later in **Settings → Access → Web Server**.
After **Enable registration** the controller restarts its HTTPS server with the new certificate. The wizard shows
**Switching the HTTPS server** and holds **Next** while it waits — usually about half a minute, at most three minutes. There is nothing to do, the controller keeps running.
When it is ready, the notice gives you the new address as a link.
If the controller does not know its own network address yet, the wizard says **Registration is saved** instead:
registration starts on the next boot.
## Done [#done]
The wizard confirms **The controller has an owner**, names the account it created, and reminds you that Node-RED takes the same login.
It also says what happened to the SSH password. If it says **The SSH password could not be set**,
SSH login with a password stays closed — contact us on Discord.
How you leave depends on the Cloud step:
* **Without cloud registration**, click **Go to the panel**.
* **With cloud registration**, click **Go to blk….black.boneio.app:8443**. The panel opens at its new address in a new tab.
Sign in there once more with the same password — the browser keeps sign-ins separately for each address.
**Stay at this address** keeps you where you are.
* **If the new address did not answer** (usually DNS rebinding protection on the router), the wizard says so and offers
**Open blk….black.boneio.app:8443 anyway**. The panel keeps working at the current address.
If you imported a configuration or clicked **Apply** in Devices, restart the controller once:
**Settings → Maintenance → Restart and shutdown**. Until then the controller still runs the old configuration.
## Updating from version 1.5? [#updating-from-version-15]
A controller that was already configured before sees a **shorter wizard: Start → Account → Cloud → Done**.
The Cloud step is left out too if cloud registration was already on.
If the 1.5 panel already had a password (`web.auth` in `config.yaml`), there is no wizard at all — sign in with that password.
The wizard only creates the account — your outputs, inputs and actions stay exactly as they were.
If the SSH password of the `boneio` user was still the factory `Black`, the wizard replaces it with your new password too;
if you had already changed it, it is left alone and the wizard says so.
See [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6) for the rest of the checklist.
## Forgot the password? [#forgot-the-password]
Log in over SSH and reset it — see [Accounts and access](/en/docs/black/current/basic/accounts#forgotten-password).
## What's next? [#whats-next]
* [Home Assistant connection](./home-assistant-connection) - connect the controller to Home Assistant
* [Interface navigation](./interface-navigation) - learn about the menu and tabs
* [Accounts and access](/en/docs/black/current/basic/accounts) - add a read-only account for the rest of the household
# Home Assistant Connection (/en/docs/black/products/black_24x16a/software_setup/home-assistant-connection)
The boneIO Black controller communicates with Home Assistant via the MQTT protocol. There are two configuration methods: using a local broker or a remote one (located on HA itself).
Additionally, to make managing the controller from Home Assistant easier, we have prepared a special Add-on for you, which gives you instant access to your boneIO.
## Option 1: MQTT Broker on boneIO Black (default) [#option-1-mqtt-broker-on-boneio-black-default]
**This is the easiest way** - the controller has a built-in Mosquitto MQTT broker that is already configured and running.
### Default configuration [#default-configuration]
By default, the controller is connected to the local MQTT broker:
* **Host**: `localhost`
* **Port**: `1883`
* **Username**: `boneio`
* **Topics**: `boneio/` — set automatically
The broker has three accounts: `boneio` (the one the controller itself uses), `homeassistant` and `mqtt` (for your integrations).
On a controller installed with version 1.6 or later **each account has its own random password**, different on every device — there is no shared default password any more.
That means before you connect Home Assistant you **set a password you know** for the `homeassistant` account.
**Set the MQTT password first.** Go to **Settings** → **Services on this controller** → **MQTT broker (local)**,
in the `homeassistant` card type the new password twice (at least 8 characters) and click **Change Password**.
This is the password you will type into Home Assistant below.
If you change the password of the `boneio` user, leave **Also update boneIO's own configuration** switched on —
the controller then saves the new password in its own configuration and reconnects on its own.
Without it, the controller keeps using the old password and goes offline.
### Connecting Home Assistant to the broker on boneIO [#connecting-home-assistant-to-the-broker-on-boneio]
1. **No Mosquitto add-on needed** — with this option the broker already runs on the controller,
so in Home Assistant you only add the MQTT integration.
2. **Add MQTT integration in Home Assistant**:
* Go to **Settings** → **Devices & Services**
* Click **Add Integration** → search for **MQTT**
* Enter the details:
* **Broker**: boneIO controller IP (e.g., `192.168.1.100`)
* **Port**: `1883`
* **Username**: `homeassistant`
* **Password**: the password you just set for `homeassistant`
* Click **Submit**
Every step with Home Assistant screenshots is in [Connecting boneIO Black](/en/docs/home-assistant/boneio-black) in the Home Assistant guide.
3. **Automatic discovery**:
* The boneIO controller will automatically register all devices with Home Assistant
* Devices will appear in **Settings** → **Devices & Services** → **MQTT**
### Encrypting Home Assistant's connection (TLS) [#encrypting-home-assistants-connection-tls]
Optional. By default Home Assistant talks to the broker on boneIO in plain text on port 1883, password included.
On your own home network that is often fine. If the network is shared, or the traffic crosses a VPN, have the broker accept encrypted connections on port **8883**.
Go to **Settings** → **Services on this controller** → **MQTT broker (local)** and scroll to the **Broker encryption (TLS)** card, below the accounts.
1. **Get a certificate.** Click **Make a certificate on this controller**. It is valid for ten years and covers the controller's names, listed under **Valid for**.
Then click **Download the CA (ca.crt) for clients** — Home Assistant needs that file.
If you would rather use your own certificate, open **Upload my own certificate** (the page shows the openssl commands under **How to make certificates with openssl**).
2. **Pick a mode** under **Mode**:
* **Off** — plain MQTT on port 1883 only, as before.
* **TLS beside plain** — TLS on 8883, and 1883 keeps working. Start here.
* **TLS only on the network** — from the network only TLS on 8883. Plain 1883 stays only for programs on the controller itself, boneIO included.
3. **Move Home Assistant to TLS.** In the MQTT integration, choose **Reconfigure**, set port **8883**, open the advanced options,
enable certificate validation with a custom broker certificate and upload `ca.crt`.
As the broker address use the controller's name exactly as it appears under **Valid for**, for example `boneio-1234.local`.
An IP address works only if it is on that list, and an address from DHCP can change.
4. Once Home Assistant and everything else connects on 8883, switch to **TLS only on the network** if you want plain MQTT closed to the network.
**What it costs:**
* **Every mode change restarts the broker**, which briefly disconnects everyone, Home Assistant included. If the broker does not come back with the new settings, the panel puts the previous ones back and says so.
* **TLS only on the network** cuts off anything still on port 1883 from another machine until you move it to 8883. The panel refuses this mode while boneIO itself connects to this broker in plain text by the controller's network address: first set boneIO's MQTT host to `localhost`, or turn on TLS for its own connection.
* **Node-RED on the controller** reaches the broker from Docker's network, not from `localhost`. Before **TLS only on the network**, move its broker node to port 8883 with TLS and `ca.crt`.
* **A new certificate means a new CA.** Every client that trusts the current `ca.crt` must be given the new one, or it refuses the broker.
If the card says this controller's system helper does not manage the broker's TLS yet, go to **Settings** → **System migrations**,
click **Apply pending migrations** and come back.
## Option 2: MQTT Broker on Home Assistant [#option-2-mqtt-broker-on-home-assistant]
You can connect the controller to an MQTT broker located on Home Assistant or another device.
### Configuring the broker in Home Assistant [#configuring-the-broker-in-home-assistant]
1. **Install Mosquitto Broker** (if you don't have it yet):
* Go to **Settings** → **Apps** → **Install app**
* Search for **Mosquitto broker**
* Click **Install** and **Start**
2. **Create an MQTT user**:
* Go to **Settings** → **People** → **Users**
* Click **Add User**
* Fill in the details:
* **Name**: `boneio`
* **Username**: `boneio`
* **Password**: choose a secure password
* Click **Create**
3. **Add MQTT integration** (if you don't have it yet):
* Go to **Settings** → **Devices & Services**
* MQTT should be automatically detected
* If not, click **Add Integration** → **MQTT**
### Configuring MQTT in boneIO controller [#configuring-mqtt-in-boneio-controller]
1. Go to **Settings** → **Connections** → **MQTT**
2. Enter the broker details:
* **Host**: Home Assistant IP (e.g., `192.168.1.50`)
* **Port**: `1883`
* **Username**: `boneio`
* **Password**: password of the created user
3. Click **Save**. A change of only these four fields needs no restart: boneIO reconnects to the new broker straight away
4. Devices will automatically appear in Home Assistant
If that broker accepts TLS, switch on **Encrypt the connection (TLS)** on the same page.
See [Encryption (TLS)](/en/docs/black/current/configuration/communication#encryption-tls).
### Installation of the boneIO Home Assistant Add-on [#installation-of-the-boneio-home-assistant-add-on]
1. Go to **Settings** → **Apps** → **Install app**
2. Click the three dots in the top right corner
3. Select Repositories
4. Add this URL: [https://github.com/boneio-eu/home-assistant-addons](https://github.com/boneio-eu/home-assistant-addons)
5. Click Add
6. Find the desired add-on and click Install
## Communication between boneIO controllers [#communication-between-boneio-controllers]
If you have multiple boneIO Black controllers and want them to execute commands on each other (e.g., a button on one controller turns on a light on another), **all controllers must be connected to the same MQTT broker**.
### Example configuration for multiple controllers: [#example-configuration-for-multiple-controllers]
1. Choose one MQTT broker (e.g., on Home Assistant or on one of the controllers)
2. Connect all controllers to the same broker
3. Each controller publishes under its own serial number (`boneio/blk…`), so there is nothing to set to keep them apart
4. In actions, you can use **Control Remote Output** and **Control Remote Cover** to control devices on other controllers
## Connection verification [#connection-verification]
After proper configuration:
1. In Home Assistant, go to **Settings** → **Devices & Services** → **MQTT**
2. You should see the **boneIO Black** device with all configured outputs, covers, inputs, and sensors
3. All entities will be automatically available in Home Assistant
The controller uses **MQTT Discovery** - all devices are automatically detected by Home Assistant without the need for manual configuration.
# How to Connect (/en/docs/black/products/black_24x16a/software_setup/how-to-connect)
After connecting your controller to the local network, you can access the boneIO web interface through a web browser. This is the most convenient way to configure and monitor your controller.
## Prerequisites [#prerequisites]
* boneIO controller connected to local network via Ethernet cable
* Network with DHCP service enabled (enabled by default on most routers)
* Computer or mobile device on the same local network
* Web browser (Chrome, Firefox, Safari, Edge)
## Step 1: Connect the controller to the network [#step-1-connect-the-controller-to-the-network]
1. Connect an Ethernet cable to the network port of your boneIO controller
2. Connect the other end of the cable to your router or switch
3. Make sure the controller is powered on
The controller will automatically receive an IP address from the DHCP server on your network.
## Step 2: Find the controller's IP address [#step-2-find-the-controllers-ip-address]
There are two ways to find the controller's IP address:
### Option A: Display on the controller [#option-a-display-on-the-controller]
Press the button next to the display on the controller to scroll through the screens:
* the **network** screen shows the controller's **IP address** (plus the network mask and MAC address),
* the **last screen** shows a **QR code** — scan it with your phone and the panel opens straight away, at the right `https://…:8443` address
(or at the controller's own boneIO Cloud address, if you registered it; on a controller upgraded from 1.5 it is `http://…:8090` until you move the panel behind the proxy).
{/* SCREENSHOT: oled_network.webp — photo of the OLED network screen with the IP address */}
{/* SCREENSHOT: oled_qr.webp — photo of the OLED QR code screen */}
Which screens are shown is set in **Settings** → **Device** → **OLED Display**. Both are on in the factory configuration.
### Option B: Router admin panel [#option-b-router-admin-panel]
Log in to your router's admin panel and find the list of connected devices. The boneIO controller will be visible under a name corresponding to its serial number, starting with `blk`, e.g., `blk8c7df0`.
## Step 3: Open the web interface [#step-3-open-the-web-interface]
1. Open a web browser
2. In the address bar, type the controller's IP address with port 8443, e.g., `https://192.168.1.100:8443`
3. Press Enter
Always type `https://` at the start — without it the page will not open.
### The browser warns about the connection — this is expected [#the-browser-warns-about-the-connection--this-is-expected]
The first time you open the panel, the browser shows a warning such as **"Your connection is not private"**.
The connection **is** encrypted; the browser only warns because the certificate was issued by the controller itself,
not by a company the browser knows.
* **Chrome / Edge**: click **Advanced**, then **Proceed to 192.168.1.100 (unsafe)**
* **Firefox**: click **Advanced…**, then **Accept the Risk and Continue**
* **Safari**: click **Show Details**, then **visit this website**
The controller's certificate is valid for six months, so the browser does not ask again every day.
To get rid of the warning for good, see [HTTPS certificate](/en/docs/black/current/advanced/certificate).
## Step 4: Create your administrator account [#step-4-create-your-administrator-account]
A new controller has no owner yet. Instead of the panel you will see the **First-time setup** wizard.
Until the account exists, the controller's display says so: it shows **Setup required**, **Onboarding needed.**,
**Open in a browser:** and the panel's address. The display does not go dark while that notice is up, and the address
appears as soon as the controller gets one from the router (until then the line reads `http://:8090`, which is only a placeholder). The button still steps through the other screens;
after a minute the notice comes back. Once the account is created, the notice goes away by itself within a few seconds.
{/* SCREENSHOT: oled_setup_required.webp — photo of the OLED showing "Setup required" with the panel address */}
For a moment right at power-on, before that notice, the display may show `SETUP REQUIRED - open :8090` —
ignore the port there and use the address from the notice, or `https://…:8443`.
In the wizard you choose a username and password for the panel. It takes about a minute — see
[First-time setup](./first-run-wizard) for every step.
Do this right away. Until an account exists, **whoever on your network completes the wizard first becomes the owner** of the controller.
After the wizard you land in the main panel showing the controller status.
## Troubleshooting [#troubleshooting]
### I can't find the IP address [#i-cant-find-the-ip-address]
* Make sure the Ethernet cable is properly connected
* Check if the network LED on the controller is lit or blinking
* Restart the controller and wait about 30 seconds to obtain an IP address
### The page won't load [#the-page-wont-load]
* Check if your computer is on the same network as the controller
* Make sure you type `https://` before the IP address and `:8443` after it
* Try clearing your browser cache or use incognito mode
* A warning about the certificate is not an error — see Step 3
### The controller doesn't receive an IP address [#the-controller-doesnt-receive-an-ip-address]
If your network doesn't have a DHCP server, you can connect to the controller via USB cable:
1. Connect a USB cable to the USB port of the controller and to your computer
2. Your computer will receive an IP address from the `192.168.7.x` range
3. The controller will be available at `192.168.7.2` — the panel opens at `http://192.168.7.2:8090`
(if it does not open, restart the controller with the cable plugged in)
4. Connect via SSH and configure a static IP address for the `eth0` interface
This guide does not cover the exact network configuration commands.
## What's next? [#whats-next]
After connecting to the controller, you can proceed to:
* [First-time setup](./first-run-wizard) - every step of the wizard explained
* [Home Assistant connection](./home-assistant-connection) - connect the controller to Home Assistant
* [Interface navigation](./interface-navigation) - learn about the menu and tabs in the web interface
* [Update controller](./update-controller) - check if you have the latest software version
* [Configure controller](./edit-configuration) - configure the controller according to your needs
# Software Setup Introduction (/en/docs/black/products/black_24x16a/software_setup)
**boneIO Black 24x16A is discontinued.** This guide stays for controllers already installed. The boneIO app supports it as before, including the 1.6 updates. For a new installation see the [current controllers](/en/docs/black#choose-your-controller).
# Software Setup [#software-setup]
This section guides you through the software configuration of your **boneIO Black** device. Proper setup is crucial for integrating the controller with your home automation system - Home Assistant.
Our custom software, built to run on the powerful BeagleBone Black, offers a web interface for initial setup and monitoring.
The following guide is divided into several steps. In the first two, you will learn how to connect to the **boneIO** controller and how to connect the controller to the Home Assistant system. In the following steps, you will learn how to configure and adapt your boneIO to your needs.
# Interface navigation (/en/docs/black/products/black_24x16a/software_setup/interface-navigation)
After connecting to the controller, you will see the web interface with a top navigation bar. Below you'll find a description of all available tabs.
On a phone or tablet the same tabs move to a bar at the bottom of the screen — see [On a phone or tablet](#on-a-phone-or-tablet).
## Main menu [#main-menu]
| Tab | Description |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Outputs** | Control relay outputs, covers, and view relay states. |
| **Inputs** | View the state of digital inputs. |
| **Sensors** | Readings from onboard sensors: temperature, current consumption, memory usage, CPU, disk, and Dallas sensors (if connected). |
| **Modbus** | List of connected and configured Modbus devices. |
| **Templates** | Ready-made building blocks such as irrigation. |
| **Diagnostics** | The log, the support bundle and the bus tools (Modbus, I2C, CAN). See [Diagnostics](/en/docs/black/current/basic/logs). |
| **Settings** | Everything you configure, in seven groups — from outputs and schedules to software update, backups and restart. See [Settings](/en/docs/black/current/basic/settings). |
| **Node-RED** | The pre-installed visual automation tool. Shown only when Node-RED is running. |
| **Help** | Link to Discord community and documentation. |
**Where did System, Logs and the YAML editor go?** Since version 1.6 they are all inside the two tabs above:
the old **System** tab is now **Settings → Maintenance**, **Logs** and **Tools** are **Diagnostics**,
and the **YAML editor** is **Settings → Advanced → YAML editor**. Old bookmarks still work — they redirect.
A **read-only** account sees only the first five tabs. Diagnostics, Settings and Node-RED are for administrators — see [Accounts and access](/en/docs/black/current/basic/accounts).
## On a phone or tablet [#on-a-phone-or-tablet]
On a phone, a tablet or a narrow browser window the top bar shows only the
controller's name, and the tabs move to a bar at the bottom, under your thumb:
| Slot | What it opens |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Outputs** | The outputs view |
| **Inputs** | The inputs view |
| **Sensors** or **Templates** | Sensors — or Templates, once you have any; Sensors then moves under **More** |
| **Modbus** | The Modbus view |
| **More** | Everything else: Diagnostics, Settings, Node-RED, Help, and below them the version, serial number and the account you are signed in with |
### Inside the boneIO Dashboard add-on [#inside-the-boneio-dashboard-add-on]
When you open the panel through the **boneIO Dashboard** add-on in Home
Assistant, the bottom bar gets one more slot on the left: **Devices**. It opens
the add-on's device list. To make room, **Sensors** moves under **More**. Opened
through plain Home Assistant ingress, the bar stays as above.
{/* SCREENSHOT: en_bottom_nav_dashboard.webp — the panel inside the boneIO Dashboard add-on on a phone, Devices slot on the left of the bottom bar */}
## Language change [#language-change]
In the top right corner, you'll find flags to change the interface language. Available languages are Polish (PL) and English (EN).
# Naming Inputs (/en/docs/black/products/black_24x16a/software_setup/naming-inputs)
# Why should you name them? [#why-should-you-name-them]
Naming your inputs will make working with the controller much easier. It's a lot easier to remember "Bedroom Button1" than "IN\_04", right?
## Events – event entities [#events--event-entities]
Let's start with event entities. Below is the default configuration from the file:
```
~/boneio/event.yaml
```
```yaml
- id: IN_04
boneio_input: IN_04
actions:
single:
- action: output
pin: OUT_04
- id: IN_05
boneio_input: IN_05
actions:
single:
- action: output
pin: OUT_05
- id: IN_06
boneio_input: IN_06
actions:
single:
- action: output
pin: OUT_06
```
How do you name your input? It's very simple!
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | This part of the configuration is the input name, and you can change it freely. There are many naming approaches. For example, you can change the name to `BedroomButton1` or `IN_04_BedroomButton_1`. |
| `boneio_input` | This is the input number that your name refers to. For now, ignore `actions:` – we'll discuss them later. |
Our example looks like this:
```yaml
- id: IN_04_BedroomButton_1
boneio_input: IN_04
actions:
single:
- action: output
pin: OUT_04
```
## Binary (Binary sensor) [#binary-binary-sensor]
Below is the default configuration from the file:
```
~/boneio/binary_sensor.yaml
```
```yaml
- id: IN_01
boneio_input: IN_01
actions:
pressed:
- action: output
pin: OUT_01
- id: IN_02
boneio_input: IN_02
actions:
pressed:
- action: output
pin: OUT_02
```
| Parameter | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | This part of the configuration is the input name, and you can change it freely. There are many naming approaches. For example, you can change the name to `MotionBedroom` or `IN_01_MotionBedroom`. |
| `boneio_input` | This is the input number that your name refers to. For now, ignore `actions:` – we'll discuss them later. |
Our example looks like this:
```yaml
- id: IN_01_MotionBedroom
boneio_input: IN_01
actions:
pressed:
- action: output
pin: OUT_01
```
# Configure outputs (/en/docs/black/products/black_24x16a/software_setup/naming-outputs)
Outputs are relays that control electrical devices. The boneIO Black 24x16A controller has **24 relays rated at 16A**.
## How to add or edit an output? [#how-to-add-or-edit-an-output]
1. Go to **Settings** → **Control** → **Local Outputs**
2. Click **Add New** or the edit icon next to an existing output
3. Fill in the configuration form
## Basic settings [#basic-settings]
### BoneIO Output [#boneio-output]
Select the physical relay number from the dropdown:
* `OUT_01`, `OUT_02`, `OUT_03`, ... `OUT_24`
**All outputs are occupied** - free one up or select a different device type.
### Output Type [#output-type]
Select the type of device to be controlled:
| Type | Use Case | HA Icon |
| ---------- | ----------------------------- | ---------- |
| **Light** | Lighting | Light bulb |
| **Switch** | Switch (pumps, heaters, etc.) | Switch |
| **Valve** | Water valve | Valve |
The type defines how the output will be displayed in the web interface and Home Assistant.
### Display Name [#display-name]
Friendly name for the output, e.g.:
* `Circulation Pump`
* `Bathroom Heater`
* `Garden Valve`
This name will be visible in the interface and Home Assistant.
### Custom ID [#custom-id]
Technical ID of the output (auto-generated from name):
* Only lowercase letters, numbers, and underscores
* Example: `OUT_01` → name: `Circulation Pump` → ID: `circulation_pump`
**We do not recommend changing the output ID** after it has been created. Changing the ID will cause loss of history in Home Assistant and require reconfiguration of automations.
### Area / Room [#area--room]
Select an area from the dropdown (previously configured in the Areas section).
The output will be automatically assigned to this area in Home Assistant.
## Options [#options]
### Restore State [#restore-state]
Enable to have the output remember its state after controller restart.
* ✅ **Enabled**: After restart, the output returns to its last state (ON/OFF)
* ❌ **Disabled**: After restart, the output will be off
## Advanced settings [#advanced-settings]
Click the **Advanced Settings** tab to access additional options:
* **Interlock Group** - mutual exclusion (only one output in the group can be on)
* **Momentary** - output automatically turns off after a specified time
* **Other options** - depending on output type
## Configuration example [#configuration-example]
**Scenario**: You want to configure a circulation pump on relay OUT\_01.
1. **BoneIO Output**: `OUT_01`
2. **Output Type**: `Switch`
3. **Display Name**: `Circulation Pump`
4. **Area / Room**: `Boiler Room` (previously created in Areas)
5. **Restore State**: ✅ Enabled
After saving, the output will appear in the table and be available in Home Assistant as `switch.circulation_pump` in the "Boiler Room" area.
# Update Controller (/en/docs/black/products/black_24x16a/software_setup/update-controller)
The controller checks for a new version by itself every few hours. You install it with one click —
from Home Assistant or from the controller's own panel.
## Requirements [#requirements]
* The controller must have an internet connection
* You must be signed in to the panel as an **administrator**
* To update from Home Assistant, the controller must be connected to Home Assistant over MQTT
## How to update? [#how-to-update]
### From Home Assistant [#from-home-assistant]
1. In Home Assistant, open **Settings** — available updates are listed at the top,
2. Click the **boneIO Black Firmware** update,
3. Press **Update**,
4. That's all!
### From the web interface [#from-the-web-interface]
1. Open the controller's web interface in your browser
2. Go to **Settings** → **Maintenance** → **Software update**
3. Click **Check for Updates**
4. If a new version is available, read what it changes (**View Release Notes**), then click **Update to \** (for example **Update to 1.6.0**)
The update starts on its own. When it finishes, the application on the controller restarts and the panel reloads.
While the controller is installing and restarting, the panel shows **Update in progress** with the time since it started,
and comes back by itself once the new version is running. If the controller comes back on the old version, the panel says
**The update failed** — the details are in [Diagnostics](/en/docs/black/current/basic/logs).
If your browser shows the old panel after the update, it reloads the new one on its own (**Loading the new version of the panel**);
if it cannot, it asks you to press **Ctrl+Shift+R** (**Cmd+Shift+R** on a Mac).
{/* SCREENSHOT: en_panel_update_in_progress.webp — the "Update in progress" screen with "The controller is installing version …" and the elapsed time */}
**The update does not back up your configuration.** Download a backup first in **Settings → Maintenance → Backups**.
If something is wrong after the update, open **Available Versions** on the same page and install the previous version (the button is **Install**).
## After the update: system migrations [#after-the-update-system-migrations]
Some versions also change settings of the operating system underneath the app — for example firewall rules or SSH hardening.
These changes are called **system migrations**. They run by themselves on the first start after the update; you do not need to do anything.
You can see them in **Settings** → **Maintenance** → **System migrations**.
If a red banner says that **a system update was refused**, the page shows the reason — send it to us
(see [Diagnostics](/en/docs/black/current/basic/logs) for the support bundle).
## Updating from version 1.5? [#updating-from-version-15]
**Update to 1.5.6 first**, then to 1.6. Only 1.5.6 hands the browser over to the new panel cleanly; from older 1.5
versions the old panel may keep coming back after the update until you press **Ctrl+Shift+R**.
Version 1.6 adds accounts, so after the update the panel asks you to create an administrator account first
(unless the 1.5 panel already had a password — then you simply sign in with it).
Follow [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6).
## Important information [#important-information]
* **Do not turn off the controller's power during the update.** A backup power supply is worth having for exactly this — see
[Backup power (UPS)](/en/docs/black/products/black_32x10a/hardware-installation#backup-power-ups--recommended).
* A small update takes a few minutes. Jumping several versions can take over ten minutes, and coming from 1.5 up to an hour,
because the system migrations run on the first start.
* While migrations run, the display shows **Updating** and **Do not power off.** with how far it has got
(**Updating system** with a percentage, if the display is not set up in the configuration). The panel does
not answer until they finish.
* After the update, the application on the controller restarts by itself.
{/* SCREENSHOT: oled_updating.webp — photo of the OLED showing "Updating", "Do not power off." and the percentage */}
## Updating the operating system [#updating-the-operating-system]
Updating boneIO does not update the Debian system and the kernel underneath it. That is a separate card on the same page,
**Operating system** — see [Maintenance → Operating system](/en/docs/black/current/basic/system#operating-system).
Unlike a boneIO update, it does not restart the controller by itself.
## Update via SSH [#update-via-ssh]
If you need to update the controller manually via SSH (e.g., when the web interface update doesn't work), see the [SSH update guide](/en/docs/black/advanced/update-via-ssh).
# Actions (/en/docs/black/products/black_32x10a/software_setup/actions)
## What it's all about? [#what-its-all-about]
Actions are best way to made some simple core automations inside of your controller. With them its possible to made some cricital automations
inside of your boneIO Black.
To make it easy i will give you some example and will describe it:
```yaml
- id: IN_01_living_room1
boneio_input: IN_01
actions:
single:
- action: output
pin: OUT_01_living_room_light_1
double:
- action: output
pin: OUT_02_living_room_light_2
long:
- action: output
pin: OUT_03_living_room_light_3
- id: IN_02_living_room2
boneio_input: IN_02
actions:
single:
- action: output
pin: OUT_04_living_room_light_4
long:
- action: output
pin: OUT_01_living_room_light_1
action_output: off
- action: output
pin: OUT_02_living_room_light_2
action_output: off
- action: output
pin: OUT_03_living_room_light_3
action_output: off
- action: output
pin: OUT_04_living_room_light_4
action_output: off
```
What have we achived? By using just 2 buttons we can independly turn on 4 lights, an by single long click of one of them you can turn all of them off.
In the case of `IN_01_living_room1` its really simple, we define each action fo each action type, in our case for `single` click Living room light 1
for `double` Living room light 2 and for `long` click Living room light 3. The default action for `- action: output` type its `toogle`
So by simple click of the button you will change the state of light from on to off etc.
In the case of button 2 - `IN_02_living_room2` with single click you will change state of Living room light 4. But intresting thing will happen if
you `long` click that button. That will turn off all 4 defined lights in living room. There are many possibilities with actions!
If you want to know more - please check documentation.
# Configure areas (/en/docs/black/products/black_32x10a/software_setup/configure-areas)
Areas are rooms or zones that group devices in Home Assistant. The area configuration in boneIO must match the configuration in Home Assistant.
With properly configured areas, you can automatically create a simple dashboard in Home Assistant divided by these areas - all devices from a given area will be automatically grouped together.
## Important information [#important-information]
**Every area name change in Home Assistant requires a name change in the boneIO application!**
Area names must be identical 1:1 with the names in Home Assistant. It's worth configuring areas carefully from the very beginning to avoid problems later.
## How to configure areas? [#how-to-configure-areas]
1. Go to the **Settings** tab
2. Find the **Areas** section
3. Click the **Add area** button or edit an existing one
4. Enter the area name **exactly the same** as in Home Assistant
5. Click **Save**
6. Wait for the application to reload
## Synchronization with Home Assistant [#synchronization-with-home-assistant]
### Before configuring in boneIO [#before-configuring-in-boneio]
1. Open Home Assistant
2. Go to **Settings** → **Areas & zones**
3. Note down the exact names of all areas (case sensitive!)
4. Use the same names in boneIO configuration
### After changing the name in Home Assistant [#after-changing-the-name-in-home-assistant]
If you change an area name in Home Assistant:
1. Open the boneIO interface
2. Go to **Settings** → **Device** → **Areas/Rooms**
3. Edit the corresponding area
4. Change the name to the new one (same as in HA)
5. Save and wait for reload
## Export and Import areas [#export-and-import-areas]
You can transfer area configuration between devices:
1. On the first device: click **Export** in the Areas section
2. Save the YAML file
3. On the second device: click **Import** in the Areas section
4. Load the saved YAML file
5. Save and wait for reload
## Best practices [#best-practices]
* **Plan ahead** - think through area names before starting configuration
* **Use simple names** - avoid special characters and diacritics
* **Be consistent** - use the same naming convention across all devices
* **Document changes** - save an export after each major change as a backup
# Configure binary sensors (/en/docs/black/products/black_32x10a/software_setup/configure-binary-sensors)
Binary sensors are ideal for devices with two states: motion sensors, reed switches, flood sensors, etc.
## How to add or edit a binary sensor? [#how-to-add-or-edit-a-binary-sensor]
1. Go to **Settings** → **Control** → **Local Inputs**
2. Click **Add New** or the edit icon next to an existing sensor
3. Fill in the configuration form
## Basic settings [#basic-settings]
### Display Name [#display-name]
Friendly name for the sensor, e.g.:
* `Living Room Motion Sensor`
* `Front Door`
* `Bedroom Window`
This name will be visible in the interface and Home Assistant.
### BoneIO Input [#boneio-input]
Select the physical input from the dropdown:
* `IN_01`, `IN_02`, `IN_03`, ... `IN_56` (depending on model)
**Avoid inputs with limitations** (IN\_01, IN\_02, IN\_09, IN\_10, IN\_19, IN\_20, IN\_21, IN\_29–IN\_34) for reed switches and motion sensors that may be active at controller startup.
### Area / Room [#area--room]
Select an area from the dropdown - the sensor will be automatically assigned to this area in Home Assistant.
### Bounce Time [#bounce-time]
Contact debounce time (default: 120ms). For motion sensors and reed switches, usually no change is needed.
### Device Class [#device-class]
Device class in Home Assistant - affects icon and behavior:
| Device Class | Icon | Use Case |
| ------------- | --------- | ----------------------- |
| **motion** | Motion | Motion sensors |
| **door** | Door | Door reed switches |
| **window** | Window | Window reed switches |
| **opening** | Opening | General opening sensors |
| **moisture** | Water | Flood sensors |
| **smoke** | Smoke | Smoke detectors |
| **gas** | Gas | Gas detectors |
| **occupancy** | Occupancy | Occupancy sensors |
| **vibration** | Vibration | Vibration sensors |
| **tamper** | Tamper | Tamper sensors |
## Options [#options]
### Show in HA [#show-in-ha]
Enable to make the sensor visible in Home Assistant (enabled by default).
### Inverted [#inverted]
Invert sensor logic:
* Normal: active input = sensor ON
* Inverted: active input = sensor OFF
Useful when a reed switch is mounted in reverse.
### Initial Send [#initial-send]
Send sensor state at controller startup.
## Actions - Pressed and Released [#actions---pressed-and-released]
Binary sensors have two action tabs:
### Pressed [#pressed]
Actions executed when the sensor changes to active state (e.g., motion detected, door opened).
### Released [#released]
Actions executed when the sensor changes to inactive state (e.g., no motion, door closed).
## How to add an action? [#how-to-add-an-action]
1. Go to the **Pressed** or **Released** tab
2. Click **Add Action**
3. Select the action type and configure parameters
### Action types [#action-types]
| Action Type | Description |
| ---------------------- | -------------------------------------- |
| **output** | Control an output (light, switch) |
| **cover** | Control a cover |
| **virtual\_switch** | Set a virtual switch (ON, OFF, TOGGLE) |
| **mqtt** | Send an MQTT message |
| **output\_over\_mqtt** | Control an output via MQTT |
| **cover\_over\_mqtt** | Control a cover via MQTT |
| **remote\_output** | Control an output on a remote device |
| **remote\_cover** | Control a cover on a remote device |
Every action can also have conditions (time, date, state, sun) and, on binary sensors, a delay. The full list of types, values and options is in [Actions](/en/docs/black/current/configuration/event#actions).
## Configuration examples [#configuration-examples]
### Example 1: Hallway motion sensor [#example-1-hallway-motion-sensor]
1. **Display Name**: `Hallway Motion Sensor`
2. **BoneIO Input**: `IN_05` (avoid inputs with limitations)
3. **Area / Room**: `Hallway`
4. **Device Class**: `motion`
**Actions:**
* **Pressed**: ON `Hallway Light`
* **Released**: OFF `Hallway Light`
### Example 2: Front door reed switch [#example-2-front-door-reed-switch]
1. **Display Name**: `Front Door`
2. **BoneIO Input**: `IN_06`
3. **Area / Room**: `Entrance`
4. **Device Class**: `door`
5. **Inverted**: ✅ (if reed switch shows reversed)
No actions - just state monitoring in Home Assistant.
### Example 3: Flood sensor [#example-3-flood-sensor]
1. **Display Name**: `Bathroom Flood Sensor`
2. **BoneIO Input**: `IN_07`
3. **Area / Room**: `Bathroom`
4. **Device Class**: `moisture`
**Actions:**
* **Pressed**: OFF `Main Water Valve` (automatic valve closure when water detected)
After saving, the sensor will appear in the table and be available in Home Assistant with the appropriate icon and device class.
# Configure events (/en/docs/black/products/black_32x10a/software_setup/configure-events)
Events allow you to assign different actions to a single button depending on the click type.
## How to add or edit an event? [#how-to-add-or-edit-an-event]
1. Go to **Settings** → **Control** → **Local Inputs**
2. Click **Add New** or the edit icon next to an existing event
3. Fill in the configuration form
## Basic settings [#basic-settings]
### Display Name [#display-name]
Friendly name for the event, e.g.:
* `Living Room Button`
* `Bedroom Switch`
* `Doorbell`
This name will be visible in the interface and Home Assistant.
### BoneIO Input [#boneio-input]
Select the physical input from the dropdown:
* `IN_01`, `IN_02`, `IN_03`, ... `IN_56` (depending on model)
Inputs already used by other events or binary sensors are automatically hidden from the list.
### Area / Room [#area--room]
Select an area from the dropdown - the event will be automatically assigned to this area in Home Assistant.
## Actions - click tabs [#actions---click-tabs]
The form has separate tabs for each click type:
### Single (Single click) [#single-single-click]
Actions executed after a single button click.
### Double (Double click) [#double-double-click]
Actions executed after a quick double click.
### Triple (Triple click) [#triple-triple-click]
Actions executed after a triple click.
Triple click must be enabled in advanced settings (disabled by default).
### Long (Long press) [#long-long-press]
Actions executed after holding the button for a specified time.
## How to add an action? [#how-to-add-an-action]
1. Go to the appropriate tab (Single, Double, Triple, Long)
2. Click **Add Action**
3. Select the action type and configure parameters
### Action types [#action-types]
| Action Type | Description |
| ---------------------- | -------------------------------------- |
| **output** | Control an output (light, switch) |
| **cover** | Control a cover |
| **virtual\_switch** | Set a virtual switch (ON, OFF, TOGGLE) |
| **mqtt** | Send an MQTT message |
| **output\_over\_mqtt** | Control an output via MQTT |
| **cover\_over\_mqtt** | Control a cover via MQTT |
| **remote\_output** | Control an output on a remote device |
| **remote\_cover** | Control a cover on a remote device |
Every action can also have conditions (time, date, state, sun). The full list of types, values and options is in [Actions](/en/docs/black/current/configuration/event#actions).
### Output action [#output-action]
The most commonly used action - control an output:
| Parameter | Description |
| ---------- | --------------------------------------------- |
| **Output** | Select output from the list |
| **Action** | TOGGLE (toggle), ON (turn on), OFF (turn off) |
### Cover action [#cover-action]
Control a cover:
| Parameter | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Cover** | Select cover from the list |
| **Action** | TOGGLE, OPEN, CLOSE, STOP, TOGGLE\_OPEN, TOGGLE\_CLOSE, SMART\_TOGGLE; for venetian blinds also TILT, TILT\_OPEN, TILT\_CLOSE |
## Sequences [#sequences]
Sequences are advanced click combinations:
| Sequence | Description |
| ------------------- | ------------------------- |
| **Double → Long** | Double click, then hold |
| **Single → Long** | Single click, then hold |
| **Double → Single** | Double click, then single |
Each sequence can have its own actions and optionally send an MQTT event.
## Advanced settings [#advanced-settings]
Click the **Advanced Settings** tab to access additional options:
### Bounce Time [#bounce-time]
Contact debounce time (default: 30ms). Increase if the button generates false clicks.
### Double Click Duration [#double-click-duration]
Maximum time between clicks for a double click (default: 220ms).
This parameter affects single click delay - the controller waits this time to check if a second click will follow.
### Long Press Duration [#long-press-duration]
Hold time for a long click (default: 400ms).
### Sequence Window Duration [#sequence-window-duration]
Time window for sequences (default: 500ms).
### Sequence Mode [#sequence-mode]
| Mode | Description |
| ------------- | ---------------------------------------------- |
| **Immediate** | Actions executed immediately upon detection |
| **Exclusive** | Waits for sequence completion before executing |
### Enable Triple Click [#enable-triple-click]
Enable triple click support (disabled by default).
## Configuration example [#configuration-example]
**Scenario**: A button in the living room controlling lighting.
1. **Display Name**: `Living Room Button`
2. **BoneIO Input**: `IN_04`
3. **Area / Room**: `Living Room`
**Actions:**
* **Single**: Toggle `Living Room Main Light`
* **Double**: Toggle `Living Room Lamp`
* **Long**: OFF `Living Room Main Light`, OFF `Living Room Lamp` (turn off everything)
After saving, the event will appear in the table and be available in Home Assistant.
# Edit configuration (/en/docs/black/products/black_32x10a/software_setup/edit-configuration)
The **Settings** tab contains forms for configuring all controller functions. Here you can configure outputs, inputs, areas, events, and many other options.
## Important configuration rules [#important-configuration-rules]
### Saving changes [#saving-changes]
**Each edit in a given section requires saving and waiting for reload or restart of the application before you start working on the next section.**
After saving changes:
1. Click the **Save** button in the given section
2. Wait for save confirmation
3. Wait for the application to reload or restart
4. Only then proceed to edit the next section
### Export and Import [#export-and-import]
Each configuration section has **Export** and **Import** buttons:
* **Export** - saves the configuration of the given section to a YAML file
* **Import** - loads the configuration from a YAML file
This allows you to:
* Manually copy configuration sections
* Transfer created configurations between devices
* Create backups of individual sections
## Configuration sections [#configuration-sections]
In the Settings tab you will find the following sections:
* **Areas** - defining areas compatible with Home Assistant
* **Outputs** - relay output configuration
* **Covers** - cover and blind configuration
* **Inputs** - digital input configuration
* **Events** - event and automation definitions
* **Binary Sensors** - binary sensor configuration
* **Actions** - action definitions
* And more...
# Events and Binary Sensors (/en/docs/black/products/black_32x10a/software_setup/events-and-binary-sensors)
In boneIO Black you have two types of inputs to choose from: **Events** and **Binary Sensors**. The choice depends on what device you're connecting.
## Events - for buttons [#events---for-buttons]
Events are the best choice for **wall switches**. They allow detection of different click types:
| Click Type | Description |
| ------------- | ---------------------------------- |
| **Single** | Single click |
| **Double** | Double click |
| **Triple** | Triple click |
| **Long** | Long press |
| **Sequences** | Combinations (e.g., double → long) |
**Example**: One button can turn on the main light (single), bedside lamp (double), and turn off all lights (long).
**Events have a minimal delay** for single clicks. The controller waits a short time (\~220ms) to check if another click will follow (double/triple). If you need immediate response, use a binary sensor.
## Binary Sensors - for sensors [#binary-sensors---for-sensors]
Binary sensors are the best choice for devices with two states:
| Device | States |
| ------------------ | --------------------------- |
| **Motion sensor** | Motion detected / No motion |
| **Reed switch** | Open / Closed |
| **Flood sensor** | Dry / Wet |
| **Smoke detector** | OK / Alarm |
**Advantages of binary sensors:**
* ✅ Immediate response (no delay)
* ✅ Actions on press (pressed) and release (released)
* ✅ Different device classes (motion, door, window, smoke, etc.)
## Which to choose? [#which-to-choose]
| Device | Input Type |
| ------------------------- | ------------------------------ |
| Wall switch | **Event** |
| Doorbell | **Event** or **Binary Sensor** |
| Motion sensor | **Binary Sensor** |
| Reed switch (door/window) | **Binary Sensor** |
| Flood sensor | **Binary Sensor** |
| Smoke detector | **Binary Sensor** |
## Input limitations [#input-limitations]
Some inputs on boneIO Black **cannot be active at controller startup**. We do not recommend connecting reed switches or motion sensors to them, as they may be active during startup.
| Inputs with limitations |
| ---------------------------------------------- |
| IN\_01, IN\_02 |
| IN\_09, IN\_10 |
| IN\_19, IN\_20, IN\_21 |
| IN\_29, IN\_30, IN\_31, IN\_32, IN\_33, IN\_34 |
For reed switches and motion sensors, use the remaining inputs (IN\_03 to IN\_08, IN\_11 to IN\_18, IN\_22 to IN\_28, and IN\_35 onwards).
# Events vs Binary Sensors (/en/docs/black/products/black_32x10a/software_setup/events-vs-binary-sensors)
In boneIO Black you have two types of inputs to choose from: **Events** and **Binary Sensors**. The choice depends on what device you're connecting.
## Events - for buttons [#events---for-buttons]
Events are the best choice for **wall switches**. They allow detection of different click types:
| Click Type | Description |
| ------------- | ---------------------------------- |
| **Single** | Single click |
| **Double** | Double click |
| **Triple** | Triple click |
| **Long** | Long press |
| **Sequences** | Combinations (e.g., double → long) |
**Example**: One button can turn on the main light (single), bedside lamp (double), and turn off all lights (long).
**Events have a minimal delay** for single clicks. The controller waits a short time (\~220ms) to check if another click will follow (double/triple). If you need immediate response, use a binary sensor.
## Binary Sensors - for sensors [#binary-sensors---for-sensors]
Binary sensors are the best choice for devices with two states:
| Device | States |
| ------------------ | --------------------------- |
| **Motion sensor** | Motion detected / No motion |
| **Reed switch** | Open / Closed |
| **Flood sensor** | Dry / Wet |
| **Smoke detector** | OK / Alarm |
**Advantages of binary sensors:**
* ✅ Immediate response (no delay)
* ✅ Actions on press (pressed) and release (released)
* ✅ Different device classes (motion, door, window, smoke, etc.)
## Which to choose? [#which-to-choose]
| Device | Input Type |
| ------------------------- | ------------------------------ |
| Wall switch | **Event** |
| Doorbell | **Event** or **Binary Sensor** |
| Motion sensor | **Binary Sensor** |
| Reed switch (door/window) | **Binary Sensor** |
| Flood sensor | **Binary Sensor** |
| Smoke detector | **Binary Sensor** |
## Input limitations [#input-limitations]
Some inputs on boneIO Black **cannot be active at controller startup**. We do not recommend connecting reed switches or motion sensors to them, as they may be active during startup.
| Inputs with limitations |
| ---------------------------------------------- |
| IN\_01, IN\_02 |
| IN\_09, IN\_10 |
| IN\_19, IN\_20, IN\_21 |
| IN\_29, IN\_30, IN\_31, IN\_32, IN\_33, IN\_34 |
For reed switches and motion sensors, use the remaining inputs (IN\_03 to IN\_08, IN\_11 to IN\_18, IN\_22 to IN\_28, and IN\_35 onwards).
# First-time setup (/en/docs/black/products/black_32x10a/software_setup/first-run-wizard)
The first time you open the panel of a new controller, you do not see the panel yet but the **First-time setup** wizard.
It creates the administrator account — the username and password you will sign in with from now on — and helps you get going.
The whole wizard takes a few minutes.
There is no way to skip the wizard. Until it is completed, the controller answers nothing except the wizard itself, so nobody can
change its configuration without a password.
The bar at the top shows how far you are (**Step 2 of 6**, for example). Not every controller sees every step:
| Step | When you see it |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| Start | Always. |
| Account | Always. |
| Which controller is this? | Only if the controller does not yet know which model it is. |
| Import | Only on a controller that still has its factory configuration. |
| Devices | Only on a controller that still has its factory configuration, and only if you did not import a backup. |
| Cloud | Only if boneIO Cloud registration is not already on, and only if you did not import a backup. |
| Done | Always. |
## Start [#start]
The wizard explains that the device has no administrator account yet, and under **What's ahead** lists the steps this controller will go through.
Click **Get started**.
## Account [#account]
Choose the **Username** and **Password** for the panel and type the password again under **Confirm password**.
* the password must be **at least 8 characters** long,
* it must **not contain the username** — the username is visible on the sign-in screen, so a password built from it is easy to guess.
Click **Create account**. From here on there is no way back to this step — the account exists.
The same account also opens the **Node-RED** editor: Node-RED has no accounts of its own, and only panel administrators get in.
**This password is also your SSH password.** On a new controller the wizard sets the same password for the `boneio` user.
Over SSH you always log in as `boneio` (for example `ssh boneio@192.168.1.100`) — the username you typed here is for the panel only.
This happens only once: changing the panel password later does not change the SSH password. For that, use the
[SSH login password](/en/docs/black/current/basic/accounts#ssh-login-password) card in **Settings → Access → User accounts**, or run `passwd` over SSH.
Write the password down somewhere safe.
## Which controller is this? [#which-controller-is-this]
You only see this step if the controller was not told at the factory which model it is. Until you answer, it has no outputs configured.
Pick your model — **32x10A**, **24x16A**, **Cover** or **Cover Mix** — and click **Apply**.
The controller restarts with that model's configuration, which takes up to a minute; the wizard waits and then carries on by itself.
The wizard does not come back to this step, so check the label on the controller first.
{/* SCREENSHOT: en_wizard_board.webp — "Which controller is this?" step with the four models */}
## Import (optional) [#import-optional]
If you are replacing an older boneIO and have a configuration backup from it (a `.tar.gz` file downloaded from
**Settings → Maintenance → Backups** on the old device), drop the file on **Choose a file or drag it here**, or click it to pick the file,
then click **Import configuration**. The controller will take over that configuration after a restart.
Setting up from scratch? Click **Skip**.
If you imported a backup, the Devices and Cloud steps are skipped — the imported configuration already decides them.
## Devices [#devices]
The outputs are already set up for your model. Here you decide what the inputs should do with them:
* **Inputs control outputs** — each input switches one output (a push button turns on a light),
* **Inputs control covers** — pairs of inputs open and close covers,
* **Inputs control covers and outputs** — a mix, on models that have both,
* **Wire nothing — I will do it myself** — leave the inputs empty and configure them later.
Leave **Restore relay and cover state after a restart** on (it is by default) if lights and covers should come back to where they were after a power cut.
Click **Apply**, or **Skip** to leave everything as it is. You can change all of it later in **Settings → Control → Local Inputs**.
## Cloud (optional) [#cloud-optional]
You can register the controller with **boneIO Cloud**. It then gets its own address with a trusted certificate — the browser stops
warning about the connection, and you can install the panel as an app on your phone.
* Registration sends the controller's serial number to boneIO Cloud.
* The controller is still reachable **only on your own network** — nothing is exposed to the internet.
* Your router must not block so-called *DNS rebinding*; if the new address does not open, that is usually the reason.
Click **Enable registration**, or **Skip**. You can turn it on later in **Settings → Access → Web Server**.
After **Enable registration** the controller restarts its HTTPS server with the new certificate. The wizard shows
**Switching the HTTPS server** and holds **Next** while it waits — usually about half a minute, at most three minutes. There is nothing to do, the controller keeps running.
When it is ready, the notice gives you the new address as a link.
If the controller does not know its own network address yet, the wizard says **Registration is saved** instead:
registration starts on the next boot.
## Done [#done]
The wizard confirms **The controller has an owner**, names the account it created, and reminds you that Node-RED takes the same login.
It also says what happened to the SSH password. If it says **The SSH password could not be set**,
SSH login with a password stays closed — contact us on Discord.
How you leave depends on the Cloud step:
* **Without cloud registration**, click **Go to the panel**.
* **With cloud registration**, click **Go to blk….black.boneio.app:8443**. The panel opens at its new address in a new tab.
Sign in there once more with the same password — the browser keeps sign-ins separately for each address.
**Stay at this address** keeps you where you are.
* **If the new address did not answer** (usually DNS rebinding protection on the router), the wizard says so and offers
**Open blk….black.boneio.app:8443 anyway**. The panel keeps working at the current address.
If you imported a configuration or clicked **Apply** in Devices, restart the controller once:
**Settings → Maintenance → Restart and shutdown**. Until then the controller still runs the old configuration.
## Updating from version 1.5? [#updating-from-version-15]
A controller that was already configured before sees a **shorter wizard: Start → Account → Cloud → Done**.
The Cloud step is left out too if cloud registration was already on.
If the 1.5 panel already had a password (`web.auth` in `config.yaml`), there is no wizard at all — sign in with that password.
The wizard only creates the account — your outputs, inputs and actions stay exactly as they were.
If the SSH password of the `boneio` user was still the factory `Black`, the wizard replaces it with your new password too;
if you had already changed it, it is left alone and the wizard says so.
See [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6) for the rest of the checklist.
## Forgot the password? [#forgot-the-password]
Log in over SSH and reset it — see [Accounts and access](/en/docs/black/current/basic/accounts#forgotten-password).
## What's next? [#whats-next]
* [Home Assistant connection](./home-assistant-connection) - connect the controller to Home Assistant
* [Interface navigation](./interface-navigation) - learn about the menu and tabs
* [Accounts and access](/en/docs/black/current/basic/accounts) - add a read-only account for the rest of the household
# Home Assistant Connection (/en/docs/black/products/black_32x10a/software_setup/home-assistant-connection)
The boneIO Black controller communicates with Home Assistant via the MQTT protocol. There are two configuration methods: using a local broker or a remote one (located on HA itself).
Additionally, to make managing the controller from Home Assistant easier, we have prepared a special Add-on for you, which gives you instant access to your boneIO.
## Option 1: MQTT Broker on boneIO Black (default) [#option-1-mqtt-broker-on-boneio-black-default]
**This is the easiest way** - the controller has a built-in Mosquitto MQTT broker that is already configured and running.
### Default configuration [#default-configuration]
By default, the controller is connected to the local MQTT broker:
* **Host**: `localhost`
* **Port**: `1883`
* **Username**: `boneio`
* **Topics**: `boneio/` — set automatically
The broker has three accounts: `boneio` (the one the controller itself uses), `homeassistant` and `mqtt` (for your integrations).
On a controller installed with version 1.6 or later **each account has its own random password**, different on every device — there is no shared default password any more.
That means before you connect Home Assistant you **set a password you know** for the `homeassistant` account.
**Set the MQTT password first.** Go to **Settings** → **Services on this controller** → **MQTT broker (local)**,
in the `homeassistant` card type the new password twice (at least 8 characters) and click **Change Password**.
This is the password you will type into Home Assistant below.
If you change the password of the `boneio` user, leave **Also update boneIO's own configuration** switched on —
the controller then saves the new password in its own configuration and reconnects on its own.
Without it, the controller keeps using the old password and goes offline.
### Connecting Home Assistant to the broker on boneIO [#connecting-home-assistant-to-the-broker-on-boneio]
1. **No Mosquitto add-on needed** — with this option the broker already runs on the controller,
so in Home Assistant you only add the MQTT integration.
2. **Add MQTT integration in Home Assistant**:
* Go to **Settings** → **Devices & Services**
* Click **Add Integration** → search for **MQTT**
* Enter the details:
* **Broker**: boneIO controller IP (e.g., `192.168.1.100`)
* **Port**: `1883`
* **Username**: `homeassistant`
* **Password**: the password you just set for `homeassistant`
* Click **Submit**
Every step with Home Assistant screenshots is in [Connecting boneIO Black](/en/docs/home-assistant/boneio-black) in the Home Assistant guide.
3. **Automatic discovery**:
* The boneIO controller will automatically register all devices with Home Assistant
* Devices will appear in **Settings** → **Devices & Services** → **MQTT**
### Encrypting Home Assistant's connection (TLS) [#encrypting-home-assistants-connection-tls]
Optional. By default Home Assistant talks to the broker on boneIO in plain text on port 1883, password included.
On your own home network that is often fine. If the network is shared, or the traffic crosses a VPN, have the broker accept encrypted connections on port **8883**.
Go to **Settings** → **Services on this controller** → **MQTT broker (local)** and scroll to the **Broker encryption (TLS)** card, below the accounts.
1. **Get a certificate.** Click **Make a certificate on this controller**. It is valid for ten years and covers the controller's names, listed under **Valid for**.
Then click **Download the CA (ca.crt) for clients** — Home Assistant needs that file.
If you would rather use your own certificate, open **Upload my own certificate** (the page shows the openssl commands under **How to make certificates with openssl**).
2. **Pick a mode** under **Mode**:
* **Off** — plain MQTT on port 1883 only, as before.
* **TLS beside plain** — TLS on 8883, and 1883 keeps working. Start here.
* **TLS only on the network** — from the network only TLS on 8883. Plain 1883 stays only for programs on the controller itself, boneIO included.
3. **Move Home Assistant to TLS.** In the MQTT integration, choose **Reconfigure**, set port **8883**, open the advanced options,
enable certificate validation with a custom broker certificate and upload `ca.crt`.
As the broker address use the controller's name exactly as it appears under **Valid for**, for example `boneio-1234.local`.
An IP address works only if it is on that list, and an address from DHCP can change.
4. Once Home Assistant and everything else connects on 8883, switch to **TLS only on the network** if you want plain MQTT closed to the network.
**What it costs:**
* **Every mode change restarts the broker**, which briefly disconnects everyone, Home Assistant included. If the broker does not come back with the new settings, the panel puts the previous ones back and says so.
* **TLS only on the network** cuts off anything still on port 1883 from another machine until you move it to 8883. The panel refuses this mode while boneIO itself connects to this broker in plain text by the controller's network address: first set boneIO's MQTT host to `localhost`, or turn on TLS for its own connection.
* **Node-RED on the controller** reaches the broker from Docker's network, not from `localhost`. Before **TLS only on the network**, move its broker node to port 8883 with TLS and `ca.crt`.
* **A new certificate means a new CA.** Every client that trusts the current `ca.crt` must be given the new one, or it refuses the broker.
If the card says this controller's system helper does not manage the broker's TLS yet, go to **Settings** → **System migrations**,
click **Apply pending migrations** and come back.
## Option 2: MQTT Broker on Home Assistant [#option-2-mqtt-broker-on-home-assistant]
You can connect the controller to an MQTT broker located on Home Assistant or another device.
### Configuring the broker in Home Assistant [#configuring-the-broker-in-home-assistant]
1. **Install Mosquitto Broker** (if you don't have it yet):
* Go to **Settings** → **Apps** → **Install app**
* Search for **Mosquitto broker**
* Click **Install** and **Start**
2. **Create an MQTT user**:
* Go to **Settings** → **People** → **Users**
* Click **Add User**
* Fill in the details:
* **Name**: `boneio`
* **Username**: `boneio`
* **Password**: choose a secure password
* Click **Create**
3. **Add MQTT integration** (if you don't have it yet):
* Go to **Settings** → **Devices & Services**
* MQTT should be automatically detected
* If not, click **Add Integration** → **MQTT**
### Configuring MQTT in boneIO controller [#configuring-mqtt-in-boneio-controller]
1. Go to **Settings** → **Connections** → **MQTT**
2. Enter the broker details:
* **Host**: Home Assistant IP (e.g., `192.168.1.50`)
* **Port**: `1883`
* **Username**: `boneio`
* **Password**: password of the created user
3. Click **Save**. A change of only these four fields needs no restart: boneIO reconnects to the new broker straight away
4. Devices will automatically appear in Home Assistant
If that broker accepts TLS, switch on **Encrypt the connection (TLS)** on the same page.
See [Encryption (TLS)](/en/docs/black/current/configuration/communication#encryption-tls).
### Installation of the boneIO Home Assistant Add-on [#installation-of-the-boneio-home-assistant-add-on]
1. Go to **Settings** → **Apps** → **Install app**
2. Click the three dots in the top right corner
3. Select Repositories
4. Add this URL: [https://github.com/boneio-eu/home-assistant-addons](https://github.com/boneio-eu/home-assistant-addons)
5. Click Add
6. Find the desired add-on and click Install
## Communication between boneIO controllers [#communication-between-boneio-controllers]
If you have multiple boneIO Black controllers and want them to execute commands on each other (e.g., a button on one controller turns on a light on another), **all controllers must be connected to the same MQTT broker**.
### Example configuration for multiple controllers: [#example-configuration-for-multiple-controllers]
1. Choose one MQTT broker (e.g., on Home Assistant or on one of the controllers)
2. Connect all controllers to the same broker
3. Each controller publishes under its own serial number (`boneio/blk…`), so there is nothing to set to keep them apart
4. In actions, you can use **Control Remote Output** and **Control Remote Cover** to control devices on other controllers
## Connection verification [#connection-verification]
After proper configuration:
1. In Home Assistant, go to **Settings** → **Devices & Services** → **MQTT**
2. You should see the **boneIO Black** device with all configured outputs, covers, inputs, and sensors
3. All entities will be automatically available in Home Assistant
The controller uses **MQTT Discovery** - all devices are automatically detected by Home Assistant without the need for manual configuration.
# Connect to your controller (/en/docs/black/products/black_32x10a/software_setup/how-to-connect)
After connecting your controller to the local network, you can access the boneIO web interface through a web browser. This is the most convenient way to configure and monitor your controller.
## Prerequisites [#prerequisites]
* boneIO controller connected to local network via Ethernet cable
* Network with DHCP service enabled (enabled by default on most routers)
* Computer or mobile device on the same local network
* Web browser (Chrome, Firefox, Safari, Edge)
## Step 1: Connect the controller to the network [#step-1-connect-the-controller-to-the-network]
1. Connect an Ethernet cable to the network port of your boneIO controller
2. Connect the other end of the cable to your router or switch
3. Make sure the controller is powered on
The controller will automatically receive an IP address from the DHCP server on your network.
## Step 2: Find the controller's IP address [#step-2-find-the-controllers-ip-address]
There are two ways to find the controller's IP address:
### Option A: Display on the controller [#option-a-display-on-the-controller]
Press the button next to the display on the controller to scroll through the screens:
* the **network** screen shows the controller's **IP address** (plus the network mask and MAC address),
* the **last screen** shows a **QR code** — scan it with your phone and the panel opens straight away, at the right `https://…:8443` address
(or at the controller's own boneIO Cloud address, if you registered it; on a controller upgraded from 1.5 it is `http://…:8090` until you move the panel behind the proxy).
{/* SCREENSHOT: oled_network.webp — photo of the OLED network screen with the IP address */}
{/* SCREENSHOT: oled_qr.webp — photo of the OLED QR code screen */}
Which screens are shown is set in **Settings** → **Device** → **OLED Display**. Both are on in the factory configuration.
### Option B: Router admin panel [#option-b-router-admin-panel]
Log in to your router's admin panel and find the list of connected devices. The boneIO controller will be visible under a name corresponding to its serial number, starting with `blk`, e.g., `blk8c7df0`.
## Step 3: Open the web interface [#step-3-open-the-web-interface]
1. Open a web browser
2. In the address bar, type the controller's IP address with port 8443, e.g., `https://192.168.1.100:8443`
3. Press Enter
Always type `https://` at the start — without it the page will not open.
### The browser warns about the connection — this is expected [#the-browser-warns-about-the-connection--this-is-expected]
The first time you open the panel, the browser shows a warning such as **"Your connection is not private"**.
The connection **is** encrypted; the browser only warns because the certificate was issued by the controller itself,
not by a company the browser knows.
* **Chrome / Edge**: click **Advanced**, then **Proceed to 192.168.1.100 (unsafe)**
* **Firefox**: click **Advanced…**, then **Accept the Risk and Continue**
* **Safari**: click **Show Details**, then **visit this website**
The controller's certificate is valid for six months, so the browser does not ask again every day.
To get rid of the warning for good, see [HTTPS certificate](/en/docs/black/current/advanced/certificate).
## Step 4: Create your administrator account [#step-4-create-your-administrator-account]
A new controller has no owner yet. Instead of the panel you will see the **First-time setup** wizard.
Until the account exists, the controller's display says so: it shows **Setup required**, **Onboarding needed.**,
**Open in a browser:** and the panel's address. The display does not go dark while that notice is up, and the address
appears as soon as the controller gets one from the router (until then the line reads `http://:8090`, which is only a placeholder). The button still steps through the other screens;
after a minute the notice comes back. Once the account is created, the notice goes away by itself within a few seconds.
{/* SCREENSHOT: oled_setup_required.webp — photo of the OLED showing "Setup required" with the panel address */}
For a moment right at power-on, before that notice, the display may show `SETUP REQUIRED - open :8090` —
ignore the port there and use the address from the notice, or `https://…:8443`.
In the wizard you choose a username and password for the panel. It takes about a minute — see
[First-time setup](./first-run-wizard) for every step.
Do this right away. Until an account exists, **whoever on your network completes the wizard first becomes the owner** of the controller.
After the wizard you land in the main panel showing the controller status.
## Troubleshooting [#troubleshooting]
### I can't find the IP address [#i-cant-find-the-ip-address]
* Make sure the Ethernet cable is properly connected
* Check if the network LED on the controller is lit or blinking
* Restart the controller and wait about 30 seconds to obtain an IP address
### The page won't load [#the-page-wont-load]
* Check if your computer is on the same network as the controller
* Make sure you type `https://` before the IP address and `:8443` after it
* Try clearing your browser cache or use incognito mode
* A warning about the certificate is not an error — see Step 3
### The controller doesn't receive an IP address [#the-controller-doesnt-receive-an-ip-address]
If your network doesn't have a DHCP server, you can connect to the controller via USB cable:
1. Connect a USB cable to the USB port of the controller and to your computer
2. Your computer will receive an IP address from the `192.168.7.x` range
3. The controller will be available at `192.168.7.2` — the panel opens at `http://192.168.7.2:8090`
(if it does not open, restart the controller with the cable plugged in)
4. Connect via SSH and configure a static IP address for the `eth0` interface
This guide does not cover the exact network configuration commands.
## What's next? [#whats-next]
After connecting to the controller, you can proceed to:
* [First-time setup](./first-run-wizard) - every step of the wizard explained
* [Home Assistant connection](./home-assistant-connection) - connect the controller to Home Assistant
* [Interface navigation](./interface-navigation) - learn about the menu and tabs in the web interface
* [Update controller](./update-controller) - check if you have the latest software version
* [Configure controller](./edit-configuration) - configure the controller according to your needs
# Software Setup Introduction (/en/docs/black/products/black_32x10a/software_setup)
# Software Setup [#software-setup]
This section guides you through the software configuration of your **boneIO Black** device. Proper setup is crucial for integrating the controller with your home automation system - Home Assistant.
Our custom software, built to run on the powerful BeagleBone Black, offers a web interface for initial setup and monitoring.
The following guide is divided into several steps. In the first two, you will learn how to connect to the **boneIO** controller and how to connect the controller to the Home Assistant system. In the following steps, you will learn how to configure and adapt your boneIO to your needs.
# Interface navigation (/en/docs/black/products/black_32x10a/software_setup/interface-navigation)
After connecting to the controller, you will see the web interface with a top navigation bar. Below you'll find a description of all available tabs.
On a phone or tablet the same tabs move to a bar at the bottom of the screen — see [On a phone or tablet](#on-a-phone-or-tablet).
## Main menu [#main-menu]
| Tab | Description |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Outputs** | Control relay outputs, covers, and view relay states. |
| **Inputs** | View the state of digital inputs. |
| **Sensors** | Readings from onboard sensors: temperature, current consumption, memory usage, CPU, disk, and Dallas sensors (if connected). |
| **Modbus** | List of connected and configured Modbus devices. |
| **Templates** | Ready-made building blocks such as irrigation. |
| **Diagnostics** | The log, the support bundle and the bus tools (Modbus, I2C, CAN). See [Diagnostics](/en/docs/black/current/basic/logs). |
| **Settings** | Everything you configure, in seven groups — from outputs and schedules to software update, backups and restart. See [Settings](/en/docs/black/current/basic/settings). |
| **Node-RED** | The pre-installed visual automation tool. Shown only when Node-RED is running. |
| **Help** | Link to Discord community and documentation. |
**Where did System, Logs and the YAML editor go?** Since version 1.6 they are all inside the two tabs above:
the old **System** tab is now **Settings → Maintenance**, **Logs** and **Tools** are **Diagnostics**,
and the **YAML editor** is **Settings → Advanced → YAML editor**. Old bookmarks still work — they redirect.
A **read-only** account sees only the first five tabs. Diagnostics, Settings and Node-RED are for administrators — see [Accounts and access](/en/docs/black/current/basic/accounts).
## On a phone or tablet [#on-a-phone-or-tablet]
On a phone, a tablet or a narrow browser window the top bar shows only the
controller's name, and the tabs move to a bar at the bottom, under your thumb:
| Slot | What it opens |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Outputs** | The outputs view |
| **Inputs** | The inputs view |
| **Sensors** or **Templates** | Sensors — or Templates, once you have any; Sensors then moves under **More** |
| **Modbus** | The Modbus view |
| **More** | Everything else: Diagnostics, Settings, Node-RED, Help, and below them the version, serial number and the account you are signed in with |
### Inside the boneIO Dashboard add-on [#inside-the-boneio-dashboard-add-on]
When you open the panel through the **boneIO Dashboard** add-on in Home
Assistant, the bottom bar gets one more slot on the left: **Devices**. It opens
the add-on's device list. To make room, **Sensors** moves under **More**. Opened
through plain Home Assistant ingress, the bar stays as above.
{/* SCREENSHOT: en_bottom_nav_dashboard.webp — the panel inside the boneIO Dashboard add-on on a phone, Devices slot on the left of the bottom bar */}
## Language change [#language-change]
In the top right corner, you'll find flags to change the interface language. Available languages are Polish (PL) and English (EN).
# Naming Inputs (/en/docs/black/products/black_32x10a/software_setup/naming-inputs)
# Why should you name them? [#why-should-you-name-them]
Naming your inputs will make working with the controller much easier. It's a lot easier to remember "Bedroom Button1" than "IN\_04", right?
## Events – event entities [#events--event-entities]
Let's start with event entities. Below is the default configuration from the file:
```
~/boneio/event.yaml
```
```yaml
- id: IN_04
boneio_input: IN_04
actions:
single:
- action: output
pin: OUT_04
- id: IN_05
boneio_input: IN_05
actions:
single:
- action: output
pin: OUT_05
- id: IN_06
boneio_input: IN_06
actions:
single:
- action: output
pin: OUT_06
```
How do you name your input? It's very simple!
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | This part of the configuration is the input name, and you can change it freely. There are many naming approaches. For example, you can change the name to `BedroomButton1` or `IN_04_BedroomButton_1`. |
| `boneio_input` | This is the input number that your name refers to. For now, ignore `actions:` – we'll discuss them later. |
Our example looks like this:
```yaml
- id: IN_04_BedroomButton_1
boneio_input: IN_04
actions:
single:
- action: output
pin: OUT_04
```
## Binary (Binary sensor) [#binary-binary-sensor]
Below is the default configuration from the file:
```
~/boneio/binary_sensor.yaml
```
```yaml
- id: IN_01
boneio_input: IN_01
actions:
pressed:
- action: output
pin: OUT_01
- id: IN_02
boneio_input: IN_02
actions:
pressed:
- action: output
pin: OUT_02
```
| Parameter | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | This part of the configuration is the input name, and you can change it freely. There are many naming approaches. For example, you can change the name to `MotionBedroom` or `IN_01_MotionBedroom`. |
| `boneio_input` | This is the input number that your name refers to. For now, ignore `actions:` – we'll discuss them later. |
Our example looks like this:
```yaml
- id: IN_01_MotionBedroom
boneio_input: IN_01
actions:
pressed:
- action: output
pin: OUT_01
```
# Configure outputs (/en/docs/black/products/black_32x10a/software_setup/naming-outputs)
Outputs are relays that control electrical devices. The boneIO Black 32x10A controller has **32 relays rated at 10A**.
## How to add or edit an output? [#how-to-add-or-edit-an-output]
1. Go to **Settings** → **Control** → **Local Outputs**
2. Click **Add New** or the edit icon next to an existing output
3. Fill in the configuration form
## Basic settings [#basic-settings]
### BoneIO Output [#boneio-output]
Select the physical relay number from the dropdown:
* `OUT_01`, `OUT_02`, `OUT_03`, ... `OUT_32`
**All outputs are occupied** - free one up or select a different device type.
### Output Type [#output-type]
Select the type of device to be controlled:
| Type | Use Case | HA Icon |
| ---------- | ----------------------------- | ---------- |
| **Light** | Lighting | Light bulb |
| **Switch** | Switch (pumps, heaters, etc.) | Switch |
| **Valve** | Water valve | Valve |
The type defines how the output will be displayed in the web interface and Home Assistant.
### Display Name [#display-name]
Friendly name for the output, e.g.:
* `Kitchen`
* `Living Room TV`
* `Bedroom Lamp`
This name will be visible in the interface and Home Assistant.
### Custom ID [#custom-id]
Technical ID of the output (auto-generated from name):
* Only lowercase letters, numbers, and underscores
* Example: `OUT_01` → name: `Kitchen` → ID: `kitchen`
**We do not recommend changing the output ID** after it has been created. Changing the ID will cause loss of history in Home Assistant and require reconfiguration of automations.
### Area / Room [#area--room]
Select an area from the dropdown (previously configured in the Areas section).
The output will be automatically assigned to this area in Home Assistant.
## Options [#options]
### Restore State [#restore-state]
Enable to have the output remember its state after controller restart.
* ✅ **Enabled**: After restart, the output returns to its last state (ON/OFF)
* ❌ **Disabled**: After restart, the output will be off
## Advanced settings [#advanced-settings]
Click the **Advanced Settings** tab to access additional options:
* **Interlock Group** - mutual exclusion (only one output in the group can be on)
* **Momentary** - output automatically turns off after a specified time
* **Other options** - depending on output type
## Configuration example [#configuration-example]
**Scenario**: You want to configure kitchen lighting on relay OUT\_01.
1. **BoneIO Output**: `OUT_01`
2. **Output Type**: `Light`
3. **Display Name**: `Kitchen`
4. **Area / Room**: `Kitchen` (previously created in Areas)
5. **Restore State**: ✅ Enabled
After saving, the output will appear in the table and be available in Home Assistant as `light.kitchen` in the "Kitchen" area.
# Update boneIO (/en/docs/black/products/black_32x10a/software_setup/update-controller)
The controller checks for a new version by itself every few hours. You install it with one click —
from Home Assistant or from the controller's own panel.
## Requirements [#requirements]
* The controller must have an internet connection
* You must be signed in to the panel as an **administrator**
* To update from Home Assistant, the controller must be connected to Home Assistant over MQTT
## How to update? [#how-to-update]
### From Home Assistant [#from-home-assistant]
1. In Home Assistant, open **Settings** — available updates are listed at the top,
2. Click the **boneIO Black Firmware** update,
3. Press **Update**,
4. That's all!
### From the web interface [#from-the-web-interface]
1. Open the controller's web interface in your browser
2. Go to **Settings** → **Maintenance** → **Software update**
3. Click **Check for Updates**
4. If a new version is available, read what it changes (**View Release Notes**), then click **Update to \** (for example **Update to 1.6.0**)
The update starts on its own. When it finishes, the application on the controller restarts and the panel reloads.
While the controller is installing and restarting, the panel shows **Update in progress** with the time since it started,
and comes back by itself once the new version is running. If the controller comes back on the old version, the panel says
**The update failed** — the details are in [Diagnostics](/en/docs/black/current/basic/logs).
If your browser shows the old panel after the update, it reloads the new one on its own (**Loading the new version of the panel**);
if it cannot, it asks you to press **Ctrl+Shift+R** (**Cmd+Shift+R** on a Mac).
{/* SCREENSHOT: en_panel_update_in_progress.webp — the "Update in progress" screen with "The controller is installing version …" and the elapsed time */}
**The update does not back up your configuration.** Download a backup first in **Settings → Maintenance → Backups**.
If something is wrong after the update, open **Available Versions** on the same page and install the previous version (the button is **Install**).
## After the update: system migrations [#after-the-update-system-migrations]
Some versions also change settings of the operating system underneath the app — for example firewall rules or SSH hardening.
These changes are called **system migrations**. They run by themselves on the first start after the update; you do not need to do anything.
You can see them in **Settings** → **Maintenance** → **System migrations**.
If a red banner says that **a system update was refused**, the page shows the reason — send it to us
(see [Diagnostics](/en/docs/black/current/basic/logs) for the support bundle).
## Updating from version 1.5? [#updating-from-version-15]
**Update to 1.5.6 first**, then to 1.6. Only 1.5.6 hands the browser over to the new panel cleanly; from older 1.5
versions the old panel may keep coming back after the update until you press **Ctrl+Shift+R**.
Version 1.6 adds accounts, so after the update the panel asks you to create an administrator account first
(unless the 1.5 panel already had a password — then you simply sign in with it).
Follow [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6).
## Important information [#important-information]
* **Do not turn off the controller's power during the update.** A backup power supply is worth having for exactly this — see
[Backup power (UPS)](/en/docs/black/products/black_32x10a/hardware-installation#backup-power-ups--recommended).
* A small update takes a few minutes. Jumping several versions can take over ten minutes, and coming from 1.5 up to an hour,
because the system migrations run on the first start.
* While migrations run, the display shows **Updating** and **Do not power off.** with how far it has got
(**Updating system** with a percentage, if the display is not set up in the configuration). The panel does
not answer until they finish.
* After the update, the application on the controller restarts by itself.
{/* SCREENSHOT: oled_updating.webp — photo of the OLED showing "Updating", "Do not power off." and the percentage */}
## Updating the operating system [#updating-the-operating-system]
Updating boneIO does not update the Debian system and the kernel underneath it. That is a separate card on the same page,
**Operating system** — see [Maintenance → Operating system](/en/docs/black/current/basic/system#operating-system).
Unlike a boneIO update, it does not restart the controller by itself.
## Update via SSH [#update-via-ssh]
If you need to update the controller manually via SSH (e.g., when the web interface update doesn't work), see the [SSH update guide](/en/docs/black/advanced/update-via-ssh).
# Connecting the sensor in the Black ecosystem (/en/docs/edge/products/tempandhumidity/software_setup/black)
## Configuration of boneIO Edge Temperature & Humidity [#configuration-of-boneio-edge-temperature--humidity]
### 1. Changing the address. [#1-changing-the-address]
We begin the process by changing the address. To do this, we will use the tool built into the boneIO Black application.
* From the top menu, select Tools,
* Next, select Modbus,
* Then select Configure,
* Select the device model - boneIO Edge Sensor (Temp & Humidity),
* In the "current address" field, enter 1, in the "new address" field - your chosen address from the 1-247 range,
* Use the "Set New Address" button.
* Disconnect the supply voltage from the sensor - after reconnecting it, the sensor will have the new address.
Done! The device address has been changed. Now we can proceed to the actual sensor configuration.
### 2. Adding the sensor [#2-adding-the-sensor]
* Go to the Settings menu,
* From the menu on the left, select "Modbus Devices,"
* Next, open the new device wizard with the "Add New" button,
* Fill in the Name, area, and address (the one you defined earlier) - Select "BONEIO-EDGE-TEMP" as the model,
* Confirm the operation with the "Add Element" button.
### Done! [#done]
Sensor added! The device will appear among the Modbus devices as well as in Home Assistant.
# Sensor configuration in boneIO ESP (/en/docs/edge/products/tempandhumidity/software_setup/esp)
## Configuration of boneIO Edge Temperature & Humidity [#configuration-of-boneio-edge-temperature--humidity]
1. Adding the sensor.
To add the sensor to the controller, we must edit its configuration. To do this, open the controller's yaml file in your chosen editor. All we need to do is add the appropriate package from our GitHub. Link to the package repository can be found here: [https://github.com/boneIO-eu/esphome\_packages/tree/main](https://github.com/boneIO-eu/esphome_packages/tree/main)
We add the package for the boneIO Edge Temperature & Humidity sensor:
boneio\_edge\_temp:
url: [https://github.com/boneIO-eu/esphome-packages/](https://github.com/boneIO-eu/esphome-packages/)
files:
* path: boneio-edge-temp.yaml
vars:
modbus\_controller\_id: 'boneio\_edge\_temp'
device\_name: 'boneIO Edge Temp'
modbus\_device\_id: 'boneio\_edge\_temp'
modbus\_device\_address: '0x01' #CHANGE THIS
modbus\_id: 'boneio\_modbus'
update\_interval: '60s'
2. Changing the address.
After adding the sensor to the configuration, its address must be changed. To do this, you must:
* In the ESPHome menu, in the address field where 1 is displayed, enter your own address.
* Disconnect the sensor's power and reconnect it - this will trigger the address change.
* Then, in the YAML configuration, enter the address of our sensor and perform the compilation.
* After compiling, the sensor entities will be available in the ESPHome menu.
# Connecting the sensor in other applications (/en/docs/edge/products/tempandhumidity/software_setup/other)
## Adding boneIO Edge Temperature & Humidity to another system. [#adding-boneio-edge-temperature--humidity-to-another-system]
At boneIO, we value open solutions, so for anyone who wants to connect our sensors to other devices, we provide all the necessary information.
In the table below, you will find a map of all our sensor's registers - essential for configuring it and querying it correctly.
## Register table [#register-table]
All registers are Holding type registers.
| Register Address | Parameter | Data Format & Range | Register Type |
| ---------------- | ----------------------- | -------------------------------------------- | ------------- |
| 0x0000 (0) | Humidity | \[0.1 %RH, S\_WORD] | (R) |
| 0x0001 (1) | Temperature | \[0.1 °C, S\_WORD] | (R) |
| 0x0064 (100) | Slave ID | \[1-247] | (R/W) |
| 0x0065 (101) | Baud Rate | \[0=2400, 1=4800, 2=9600, 3=19200] | (R/W) |
| 0x0066 (102) | LED Mode | \[0=disabled, 1=enabled, 2=flashing, 3=auto] | (R/W) |
| 0x0067 (103) | Firmware Version | \[e.g. 0x0002 = v0.2] | (R) |
| 0x0068 (104) | Temperature Calibration | \[0.1 °C offset, S\_WORD] | (R/W) |
| 0x0069 (105) | Humidity Calibration | \[0.1 %RH offset, S\_WORD] | (R/W) |
# Hardware Installation (/en/docs/esp/products/dimmer/gen1/hardware_installation)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
***
## DIN Rail Mounting [#din-rail-mounting]
The boneIO ESP controller is designed for mounting on a standard DIN rail (TS35).
1. Hook the upper clips of the enclosure onto the top edge of the DIN rail.
2. Press the lower part of the enclosure firmly until the latches lock onto the rail with a distinct click.
3. Ensure the module is securely mounted.
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 12-24V DC power supply. All power terminals should be powered from single power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+` output of the power supply to the `+` screw terminal on the boneIO ESP.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO ESP.
4. Double-check the connections and polarity before turning on the power supply.
**NEVER CONNECT THE USB-C PORT WITH THE POWER SUPPLY CONNECTED!!!**
The USB-C port is dedicated to flashing firmware. This should be done ONLY with the controller's power supply disconnected. Using the USB-C port with the power connector plugged in risks DAMAGING the controller!
## Connect Ethernet [#connect-ethernet]
The device communicates with the network using a built-in Ethernet port, which guarantees a stable and reliable connection. To establish connectivity, connect the module to your network switch using a standard Ethernet (RJ45) cable.
1. Connect ethernet cable to LAN port on your controller.
2. Connect other side of ethernet cable to your network switch.
## Connecting Digital Inputs [#connecting-digital-inputs]
Digital inputs are used for connecting switches and sensors. They are ground-controlled.
1. Connect one of the wires from a momentary switch to the common `GND` (ground) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will short the input to ground, which will be interpreted as an "on" signal.
### Logical diagram of connecting digital input [#logical-diagram-of-connecting-digital-input]
## Connecting LED Strips [#connecting-led-strips]
The dimmer is divided into two independent sections, **Left** and **Right**, each with 4 PWM channels. Each section is protected by a 10A fuse and includes an INA219 sensor for power measurement.
> **IMPORTANT:** Mixing channels or power from the left and right sections is not allowed and may damage the device.
Each section has its own set of terminals:
* **VCC:** The common positive terminal for the LED strips in that section.
* **CH1-CH4:** The negative PWM output channels.
**Current Limits:**
* Max current per channel: **2A**
* Max total current per section (4 channels): **10A**
### Single Color (White) LED Strips [#single-color-white-led-strips]
Each channel can control a separate single-color LED strip.
* Connect the positive (`+`) wire of the LED strip to the `VCC` (common positive) terminal of a section.
* Connect the negative (`-`) wire of the LED strip to the desired PWM channel (e.g., `CH1`).
### RGB/RGBW LED Strips [#rgbrgbw-led-strips]
One section (4 channels) can control one RGBW strip or one RGB strip (using 3 channels).
* Connect the common anode (`+`) of the strip to the `VCC` terminal.
* Connect the R, G, B, and W wires to the `CH1`, `CH2`, `CH3`, and `CH4` terminals respectively.
### CCT (Tunable White) LED Strips [#cct-tunable-white-led-strips]
A CCT strip has two channels (warm white and cool white).
* Connect the common anode (`+`) of the strip to the `VCC` terminal.
* Connect the warm white wire to one channel (e.g., `CH1`).
* Connect the cool white wire to another channel (e.g., `CH2`).
## Fuse Replacement [#fuse-replacement]
The device is protected by two 10A fuses, one for each 4-channel section. If the outputs in one section stop working, check the corresponding fuse.
1. **Turn off the power** to the device.
2. Carefully open the enclosure.
3. Locate the blown fuse and replace it with a new 10A mini-blade fuse.
## Final Checks [#final-checks]
After completing the installation:
1. Double-check all connections.
2. Ensure there are no short circuits.
3. Turn on the main power (24V DC power supply).
# Overview and Specification (/en/docs/esp/products/dimmer/gen1/overview)
## boneIO Dimmer Gen1 [#boneio-dimmer-gen1]
The boneIO Dimmer Gen1 is a professional 8-channel PWM controller designed for automating LED lighting. It allows for precise control over single-color, RGB, or RGBW LED strips, enabling the creation of advanced lighting scenes. The device is divided into two sections, each with 4 channels, and is equipped with digital inputs for connecting wall switches.
## Key Features [#key-features]
* **8 digital inputs** for connecting momentary switches or sensors.
* **8 PWM output channels** organized in two sections of 4 channels.
* **High current capacity:** up to 5A per channel and 10A per section.
* Reliable network connection via **Ethernet** and **Wi-Fi**.
* **USB-C port** for easy firmware installation.
* Compact **7-module DIN rail** enclosure.
## Use Cases [#use-cases]
* Advanced control of single-color or multi-color (RGB/RGBW) LED strips.
* Creating dynamic lighting scenes and animations.
* Integrating LED lighting with a smart home system.
* Manual control of lighting using traditional wall switches.
## Technical Specification [#technical-specification]
| Feature | Value |
| ---------------------- | ----------------------------------------------------------------------- |
| **Module** | ESP32 |
| **Power Supply** | 12-24V DC |
| **Power Consumption** | Max. 7W (excluding LED strip consumption) |
| **Digital Inputs** | 8 |
| **PWM Channels** | 8 (2 sections x 4 channels) |
| **Max Output Voltage** | 24V DC |
| **Max Output Current** | 5A per channel / 10A per section |
| **PWM Frequency** | 10Hz – 40MHz |
| **Communication** | Ethernet 10/100Mbit, Wi-Fi, USB-C (for firmware) |
| **Dimensions (WxHxD)** | 126mm x 91mm x 57mm (without plugs) / 126mm x 108mm x 57mm (with plugs) |
| **Mounting Width** | 7 DIN modules |
| **Weight** | 230g |
## Connectors and Components Description [#connectors-and-components-description]
1. **Power Connector (VCC/GND):** Main device power supply (12-24V DC).
2. **Power Connector for Section L:** Power supply connection.
3. **Output Channel Screw Terminals - CHL1-CHL4:** PWM outputs for connecting LED strips.
4. **Power Connector for Section R:** Power supply connection.
5. **Output Channel Screw Terminals - CHR1-CHR4:** PWM outputs for connecting LED strips.
6. **IN (1-8) Screw Terminals:** Digital inputs for buttons or sensors.
7. **USB-C Connector:** For uploading firmware.
8. **Ethernet Port (RJ45):** For connecting to the LAN.
**NEVER CONNECT THE USB-C PORT WITH THE POWER SUPPLY CONNECTED!!!**
The USB-C port is dedicated to flashing firmware. This should be done ONLY with the controller's power supply disconnected. Using the USB-C port with the power connector plugged in risks DAMAGING the controller!
## Quick Start Guide [#quick-start-guide]
1. **Device Installation:** Mount the device on a DIN rail and connect the 12-24V DC power supply.
2. **Connect LED Strips:** Connect your LED strips to the PWM output channels.
3. **Connect Switches:** Connect momentary switches to the digital inputs for manual control.
4. **Network Connection:** Plug a LAN cable into the RJ45 port or configure Wi-Fi.
5. **Accessing the Web Panel:** Find the device's IP address and enter it into a browser to access the web interface.
## Certificates [#certificates]
* [EU Declaration of Conformity (CE)](https://cdn.boneio.eu/certificates/boneio_esp_all_en.pdf)
# Actions (/en/docs/black/products/black_cover_mix/software_setup/actions)
## What it's all about? [#what-its-all-about]
Actions are best way to made some simple core automations inside of your controller. With them its possible to made some cricital automations
inside of your boneIO Black.
To make it easy i will give you some example and will describe it:
```yaml
- id: IN_01_living_room1
boneio_input: IN_01
actions:
single:
- action: output
pin: OUT_01_living_room_light_1
double:
- action: output
pin: OUT_02_living_room_light_2
long:
- action: output
pin: OUT_03_living_room_light_3
- id: IN_02_living_room2
boneio_input: IN_02
actions:
single:
- action: output
pin: OUT_04_living_room_light_4
long:
- action: output
pin: OUT_01_living_room_light_1
action_output: off
- action: output
pin: OUT_02_living_room_light_2
action_output: off
- action: output
pin: OUT_03_living_room_light_3
action_output: off
- action: output
pin: OUT_04_living_room_light_4
action_output: off
```
What have we achived? By using just 2 buttons we can independly turn on 4 lights, an by single long click of one of them you can turn all of them off.
In the case of `IN_01_living_room1` its really simple, we define each action fo each action type, in our case for `single` click Living room light 1
for `double` Living room light 2 and for `long` click Living room light 3. The default action for `- action: output` type its `toogle`
So by simple click of the button you will change the state of light from on to off etc.
In the case of button 2 - `IN_02_living_room2` with single click you will change state of Living room light 4. But intresting thing will happen if
you `long` click that button. That will turn off all 4 defined lights in living room. There are many possibilities with actions!
If you want to know more - please check documentation.
# Configure areas (/en/docs/black/products/black_cover_mix/software_setup/configure-areas)
Areas are rooms or zones that group devices in Home Assistant. The area configuration in boneIO must match the configuration in Home Assistant.
With properly configured areas, you can automatically create a simple dashboard in Home Assistant divided by these areas - all devices from a given area will be automatically grouped together.
## Important information [#important-information]
**Every area name change in Home Assistant requires a name change in the boneIO application!**
Area names must be identical 1:1 with the names in Home Assistant. It's worth configuring areas carefully from the very beginning to avoid problems later.
## How to configure areas? [#how-to-configure-areas]
1. Go to the **Settings** tab
2. Find the **Areas** section
3. Click the **Add area** button or edit an existing one
4. Enter the area name **exactly the same** as in Home Assistant
5. Click **Save**
6. Wait for the application to reload
## Synchronization with Home Assistant [#synchronization-with-home-assistant]
### Before configuring in boneIO [#before-configuring-in-boneio]
1. Open Home Assistant
2. Go to **Settings** → **Areas & zones**
3. Note down the exact names of all areas (case sensitive!)
4. Use the same names in boneIO configuration
### After changing the name in Home Assistant [#after-changing-the-name-in-home-assistant]
If you change an area name in Home Assistant:
1. Open the boneIO interface
2. Go to **Settings** → **Device** → **Areas/Rooms**
3. Edit the corresponding area
4. Change the name to the new one (same as in HA)
5. Save and wait for reload
## Export and Import areas [#export-and-import-areas]
You can transfer area configuration between devices:
1. On the first device: click **Export** in the Areas section
2. Save the YAML file
3. On the second device: click **Import** in the Areas section
4. Load the saved YAML file
5. Save and wait for reload
## Best practices [#best-practices]
* **Plan ahead** - think through area names before starting configuration
* **Use simple names** - avoid special characters and diacritics
* **Be consistent** - use the same naming convention across all devices
* **Document changes** - save an export after each major change as a backup
# Configure binary sensors (/en/docs/black/products/black_cover_mix/software_setup/configure-binary-sensors)
Binary sensors are ideal for devices with two states: motion sensors, reed switches, flood sensors, etc.
## How to add or edit a binary sensor? [#how-to-add-or-edit-a-binary-sensor]
1. Go to **Settings** → **Control** → **Local Inputs**
2. Click **Add New** or the edit icon next to an existing sensor
3. Fill in the configuration form
## Basic settings [#basic-settings]
### Display Name [#display-name]
Friendly name for the sensor, e.g.:
* `Living Room Motion Sensor`
* `Front Door`
* `Bedroom Window`
This name will be visible in the interface and Home Assistant.
### BoneIO Input [#boneio-input]
Select the physical input from the dropdown:
* `IN_01`, `IN_02`, `IN_03`, ... `IN_56` (depending on model)
**Avoid inputs with limitations** (IN\_01, IN\_02, IN\_09, IN\_10, IN\_19, IN\_20, IN\_21, IN\_29–IN\_34) for reed switches and motion sensors that may be active at controller startup.
### Area / Room [#area--room]
Select an area from the dropdown - the sensor will be automatically assigned to this area in Home Assistant.
### Bounce Time [#bounce-time]
Contact debounce time (default: 120ms). For motion sensors and reed switches, usually no change is needed.
### Device Class [#device-class]
Device class in Home Assistant - affects icon and behavior:
| Device Class | Icon | Use Case |
| ------------- | --------- | ----------------------- |
| **motion** | Motion | Motion sensors |
| **door** | Door | Door reed switches |
| **window** | Window | Window reed switches |
| **opening** | Opening | General opening sensors |
| **moisture** | Water | Flood sensors |
| **smoke** | Smoke | Smoke detectors |
| **gas** | Gas | Gas detectors |
| **occupancy** | Occupancy | Occupancy sensors |
| **vibration** | Vibration | Vibration sensors |
| **tamper** | Tamper | Tamper sensors |
## Options [#options]
### Show in HA [#show-in-ha]
Enable to make the sensor visible in Home Assistant (enabled by default).
### Inverted [#inverted]
Invert sensor logic:
* Normal: active input = sensor ON
* Inverted: active input = sensor OFF
Useful when a reed switch is mounted in reverse.
### Initial Send [#initial-send]
Send sensor state at controller startup.
## Actions - Pressed and Released [#actions---pressed-and-released]
Binary sensors have two action tabs:
### Pressed [#pressed]
Actions executed when the sensor changes to active state (e.g., motion detected, door opened).
### Released [#released]
Actions executed when the sensor changes to inactive state (e.g., no motion, door closed).
## How to add an action? [#how-to-add-an-action]
1. Go to the **Pressed** or **Released** tab
2. Click **Add Action**
3. Select the action type and configure parameters
### Action types [#action-types]
| Action Type | Description |
| ---------------------- | -------------------------------------- |
| **output** | Control an output (light, switch) |
| **cover** | Control a cover |
| **virtual\_switch** | Set a virtual switch (ON, OFF, TOGGLE) |
| **mqtt** | Send an MQTT message |
| **output\_over\_mqtt** | Control an output via MQTT |
| **cover\_over\_mqtt** | Control a cover via MQTT |
| **remote\_output** | Control an output on a remote device |
| **remote\_cover** | Control a cover on a remote device |
Every action can also have conditions (time, date, state, sun) and, on binary sensors, a delay. The full list of types, values and options is in [Actions](/en/docs/black/current/configuration/event#actions).
## Configuration examples [#configuration-examples]
### Example 1: Hallway motion sensor [#example-1-hallway-motion-sensor]
1. **Display Name**: `Hallway Motion Sensor`
2. **BoneIO Input**: `IN_05` (avoid inputs with limitations)
3. **Area / Room**: `Hallway`
4. **Device Class**: `motion`
**Actions:**
* **Pressed**: ON `Hallway Light`
* **Released**: OFF `Hallway Light`
### Example 2: Front door reed switch [#example-2-front-door-reed-switch]
1. **Display Name**: `Front Door`
2. **BoneIO Input**: `IN_06`
3. **Area / Room**: `Entrance`
4. **Device Class**: `door`
5. **Inverted**: ✅ (if reed switch shows reversed)
No actions - just state monitoring in Home Assistant.
### Example 3: Flood sensor [#example-3-flood-sensor]
1. **Display Name**: `Bathroom Flood Sensor`
2. **BoneIO Input**: `IN_07`
3. **Area / Room**: `Bathroom`
4. **Device Class**: `moisture`
**Actions:**
* **Pressed**: OFF `Main Water Valve` (automatic valve closure when water detected)
After saving, the sensor will appear in the table and be available in Home Assistant with the appropriate icon and device class.
# Configure covers (/en/docs/black/products/black_cover_mix/software_setup/configure-covers)
The boneIO Black Cover Mix controller allows configuration of **8 covers or blinds**. Each cover can operate as a regular cover (TIME\_BASED) or a venetian blind with tilt function (VENETIAN).
## How to add or edit a cover? [#how-to-add-or-edit-a-cover]
1. Go to **Settings** → **Control** → **Covers**
2. Click **Add New** or the edit icon next to an existing cover
3. Fill in the configuration form
## Basic settings [#basic-settings]
### Display Name [#display-name]
Friendly name for the cover, e.g.:
* `Living Room Cover`
* `Bedroom Blind`
* `Terrace Awning`
This name will be visible in the interface and Home Assistant.
### Custom ID [#custom-id]
Technical ID of the cover (optional):
* If not provided, it will be auto-generated as `cover_{open_relay}_{close_relay}`
* Only lowercase letters, numbers, and underscores
* Example: `living_room_cover`
**We do not recommend changing the cover ID** after it has been created. Changing the ID will cause loss of history in Home Assistant and require reconfiguration of automations.
### Area / Room [#area--room]
Select an area from the dropdown - the cover will be automatically assigned to this area in Home Assistant.
### Platform [#platform]
Select the cover type:
| Platform | Description | Use Case |
| --------------- | --------------------------------- | --------------------------------- |
| **TIME\_BASED** | Regular time-controlled cover | Covers, awnings, curtains |
| **VENETIAN** | Venetian blind with tilt function | Blinds with adjustable slat angle |
**TIME\_BASED** is the most popular choice for regular covers. Choose **VENETIAN** only if you have blinds with adjustable slat angle (tilt).
### Open Relay [#open-relay]
Select the output responsible for opening (up):
* `cover_01_up`, `cover_02_up`, ... `cover_08_up`
### Close Relay [#close-relay]
Select the output responsible for closing (down):
* `cover_01_down`, `cover_02_down`, ... `cover_08_down`
**Make sure you select a pair of relays for the same cover!** E.g., for cover 1: `cover_01_up` and `cover_01_down`.
### Open Time [#open-time]
Time required for full opening of the cover, e.g.:
* `30s` - 30 seconds
* `45s` - 45 seconds
* `1m` - 1 minute
**Minimum: 1 second**
### Close Time [#close-time]
Time required for full closing of the cover, e.g.:
* `30s` - 30 seconds
* `45s` - 45 seconds
**Minimum: 1 second**
**How to measure time?** Use a stopwatch and measure how long it takes for full opening/closing of the cover. Add 1-2 seconds margin.
### Tilt Duration (VENETIAN only) [#tilt-duration-venetian-only]
Time required for full slat rotation (venetian blinds only), e.g.:
* `500ms` - 500 milliseconds
* `1s` - 1 second
**Minimum: 10 milliseconds**
This field appears only when you select **VENETIAN** platform.
## Advanced settings [#advanced-settings]
Click the **Advanced Settings** tab to access additional options:
### Device Class [#device-class]
Device type in Home Assistant (affects icon):
| Device Class | Icon | Use Case |
| ------------ | ------- | ------------------- |
| **window** | Window | Windows |
| **blind** | Blind | Blinds |
| **curtain** | Curtain | Curtains, drapes |
| **shutter** | Shutter | External shutters |
| **awning** | Awning | Awnings |
| **garage** | Garage | Garage doors |
| **gate** | Gate | Entry gates |
| **shade** | Shade | Sun shades |
| **door** | Door | Doors |
| **damper** | Damper | Ventilation dampers |
### Other advanced options [#other-advanced-options]
* **Restore State** - restore state after restart
* **Show in HA** - visibility in Home Assistant
* **Other parameters** - platform-dependent
## Configuration examples [#configuration-examples]
### Example 1: Regular cover in living room [#example-1-regular-cover-in-living-room]
1. **Display Name**: `Living Room Cover`
2. **Area / Room**: `Living Room`
3. **Platform**: `TIME_BASED`
4. **Open Relay**: `cover_01_up`
5. **Close Relay**: `cover_01_down`
6. **Open Time**: `30s`
7. **Close Time**: `30s`
8. **Device Class**: `shutter`
### Example 2: Venetian blind in bedroom [#example-2-venetian-blind-in-bedroom]
1. **Display Name**: `Bedroom Blind`
2. **Area / Room**: `Bedroom`
3. **Platform**: `VENETIAN`
4. **Open Relay**: `cover_02_up`
5. **Close Relay**: `cover_02_down`
6. **Open Time**: `25s`
7. **Close Time**: `25s`
8. **Tilt Duration**: `800ms`
9. **Device Class**: `blind`
After saving, the covers will appear in the table and be available in Home Assistant in the corresponding areas.
# Configure events (/en/docs/black/products/black_cover_mix/software_setup/configure-events)
Events allow you to assign different actions to a single button depending on the click type.
## How to add or edit an event? [#how-to-add-or-edit-an-event]
1. Go to **Settings** → **Control** → **Local Inputs**
2. Click **Add New** or the edit icon next to an existing event
3. Fill in the configuration form
## Basic settings [#basic-settings]
### Display Name [#display-name]
Friendly name for the event, e.g.:
* `Living Room Button`
* `Bedroom Switch`
* `Doorbell`
This name will be visible in the interface and Home Assistant.
### BoneIO Input [#boneio-input]
Select the physical input from the dropdown:
* `IN_01`, `IN_02`, `IN_03`, ... `IN_56` (depending on model)
Inputs already used by other events or binary sensors are automatically hidden from the list.
### Area / Room [#area--room]
Select an area from the dropdown - the event will be automatically assigned to this area in Home Assistant.
## Actions - click tabs [#actions---click-tabs]
The form has separate tabs for each click type:
### Single (Single click) [#single-single-click]
Actions executed after a single button click.
### Double (Double click) [#double-double-click]
Actions executed after a quick double click.
### Triple (Triple click) [#triple-triple-click]
Actions executed after a triple click.
Triple click must be enabled in advanced settings (disabled by default).
### Long (Long press) [#long-long-press]
Actions executed after holding the button for a specified time.
## How to add an action? [#how-to-add-an-action]
1. Go to the appropriate tab (Single, Double, Triple, Long)
2. Click **Add Action**
3. Select the action type and configure parameters
### Action types [#action-types]
| Action Type | Description |
| ---------------------- | -------------------------------------- |
| **output** | Control an output (light, switch) |
| **cover** | Control a cover |
| **virtual\_switch** | Set a virtual switch (ON, OFF, TOGGLE) |
| **mqtt** | Send an MQTT message |
| **output\_over\_mqtt** | Control an output via MQTT |
| **cover\_over\_mqtt** | Control a cover via MQTT |
| **remote\_output** | Control an output on a remote device |
| **remote\_cover** | Control a cover on a remote device |
Every action can also have conditions (time, date, state, sun). The full list of types, values and options is in [Actions](/en/docs/black/current/configuration/event#actions).
### Output action [#output-action]
The most commonly used action - control an output:
| Parameter | Description |
| ---------- | --------------------------------------------- |
| **Output** | Select output from the list |
| **Action** | TOGGLE (toggle), ON (turn on), OFF (turn off) |
### Cover action [#cover-action]
Control a cover:
| Parameter | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Cover** | Select cover from the list |
| **Action** | TOGGLE, OPEN, CLOSE, STOP, TOGGLE\_OPEN, TOGGLE\_CLOSE, SMART\_TOGGLE; for venetian blinds also TILT, TILT\_OPEN, TILT\_CLOSE |
## Sequences [#sequences]
Sequences are advanced click combinations:
| Sequence | Description |
| ------------------- | ------------------------- |
| **Double → Long** | Double click, then hold |
| **Single → Long** | Single click, then hold |
| **Double → Single** | Double click, then single |
Each sequence can have its own actions and optionally send an MQTT event.
## Advanced settings [#advanced-settings]
Click the **Advanced Settings** tab to access additional options:
### Bounce Time [#bounce-time]
Contact debounce time (default: 30ms). Increase if the button generates false clicks.
### Double Click Duration [#double-click-duration]
Maximum time between clicks for a double click (default: 220ms).
This parameter affects single click delay - the controller waits this time to check if a second click will follow.
### Long Press Duration [#long-press-duration]
Hold time for a long click (default: 400ms).
### Sequence Window Duration [#sequence-window-duration]
Time window for sequences (default: 500ms).
### Sequence Mode [#sequence-mode]
| Mode | Description |
| ------------- | ---------------------------------------------- |
| **Immediate** | Actions executed immediately upon detection |
| **Exclusive** | Waits for sequence completion before executing |
### Enable Triple Click [#enable-triple-click]
Enable triple click support (disabled by default).
## Configuration example [#configuration-example]
**Scenario**: A button in the living room controlling lighting.
1. **Display Name**: `Living Room Button`
2. **BoneIO Input**: `IN_04`
3. **Area / Room**: `Living Room`
**Actions:**
* **Single**: Toggle `Living Room Main Light`
* **Double**: Toggle `Living Room Lamp`
* **Long**: OFF `Living Room Main Light`, OFF `Living Room Lamp` (turn off everything)
After saving, the event will appear in the table and be available in Home Assistant.
# Edit configuration (/en/docs/black/products/black_cover_mix/software_setup/edit-configuration)
The **Settings** tab contains forms for configuring all controller functions. Here you can configure outputs, inputs, areas, events, and many other options.
## Important configuration rules [#important-configuration-rules]
### Saving changes [#saving-changes]
**Each edit in a given section requires saving and waiting for reload or restart of the application before you start working on the next section.**
After saving changes:
1. Click the **Save** button in the given section
2. Wait for save confirmation
3. Wait for the application to reload or restart
4. Only then proceed to edit the next section
### Export and Import [#export-and-import]
Each configuration section has **Export** and **Import** buttons:
* **Export** - saves the configuration of the given section to a YAML file
* **Import** - loads the configuration from a YAML file
This allows you to:
* Manually copy configuration sections
* Transfer created configurations between devices
* Create backups of individual sections
## Configuration sections [#configuration-sections]
In the Settings tab you will find the following sections:
* **Areas** - defining areas compatible with Home Assistant
* **Outputs** - relay output configuration
* **Covers** - cover and blind configuration
* **Inputs** - digital input configuration
* **Events** - event and automation definitions
* **Binary Sensors** - binary sensor configuration
* **Actions** - action definitions
* And more...
# Events and Binary Sensors (/en/docs/black/products/black_cover_mix/software_setup/events-and-binary-sensors)
In boneIO Black you have two types of inputs to choose from: **Events** and **Binary Sensors**. The choice depends on what device you're connecting.
## Events - for buttons [#events---for-buttons]
Events are the best choice for **wall switches**. They allow detection of different click types:
| Click Type | Description |
| ------------- | ---------------------------------- |
| **Single** | Single click |
| **Double** | Double click |
| **Triple** | Triple click |
| **Long** | Long press |
| **Sequences** | Combinations (e.g., double → long) |
**Example**: One button can turn on the main light (single), bedside lamp (double), and turn off all lights (long).
**Events have a minimal delay** for single clicks. The controller waits a short time (\~220ms) to check if another click will follow (double/triple). If you need immediate response, use a binary sensor.
## Binary Sensors - for sensors [#binary-sensors---for-sensors]
Binary sensors are the best choice for devices with two states:
| Device | States |
| ------------------ | --------------------------- |
| **Motion sensor** | Motion detected / No motion |
| **Reed switch** | Open / Closed |
| **Flood sensor** | Dry / Wet |
| **Smoke detector** | OK / Alarm |
**Advantages of binary sensors:**
* ✅ Immediate response (no delay)
* ✅ Actions on press (pressed) and release (released)
* ✅ Different device classes (motion, door, window, smoke, etc.)
## Which to choose? [#which-to-choose]
| Device | Input Type |
| ------------------------- | ------------------------------ |
| Wall switch | **Event** |
| Doorbell | **Event** or **Binary Sensor** |
| Motion sensor | **Binary Sensor** |
| Reed switch (door/window) | **Binary Sensor** |
| Flood sensor | **Binary Sensor** |
| Smoke detector | **Binary Sensor** |
## Input limitations [#input-limitations]
Some inputs on boneIO Black **cannot be active at controller startup**. We do not recommend connecting reed switches or motion sensors to them, as they may be active during startup.
| Inputs with limitations |
| ---------------------------------------------- |
| IN\_01, IN\_02 |
| IN\_09, IN\_10 |
| IN\_19, IN\_20, IN\_21 |
| IN\_29, IN\_30, IN\_31, IN\_32, IN\_33, IN\_34 |
For reed switches and motion sensors, use the remaining inputs (IN\_03 to IN\_08, IN\_11 to IN\_18, IN\_22 to IN\_28, and IN\_35 onwards).
# Events vs Binary Sensors (/en/docs/black/products/black_cover_mix/software_setup/events-vs-binary-sensors)
In boneIO Black you have two types of inputs to choose from: **Events** and **Binary Sensors**. The choice depends on what device you're connecting.
## Events - for buttons [#events---for-buttons]
Events are the best choice for **wall switches**. They allow detection of different click types:
| Click Type | Description |
| ------------- | ---------------------------------- |
| **Single** | Single click |
| **Double** | Double click |
| **Triple** | Triple click |
| **Long** | Long press |
| **Sequences** | Combinations (e.g., double → long) |
**Example**: One button can turn on the main light (single), bedside lamp (double), and turn off all lights (long).
**Events have a minimal delay** for single clicks. The controller waits a short time (\~220ms) to check if another click will follow (double/triple). If you need immediate response, use a binary sensor.
## Binary Sensors - for sensors [#binary-sensors---for-sensors]
Binary sensors are the best choice for devices with two states:
| Device | States |
| ------------------ | --------------------------- |
| **Motion sensor** | Motion detected / No motion |
| **Reed switch** | Open / Closed |
| **Flood sensor** | Dry / Wet |
| **Smoke detector** | OK / Alarm |
**Advantages of binary sensors:**
* ✅ Immediate response (no delay)
* ✅ Actions on press (pressed) and release (released)
* ✅ Different device classes (motion, door, window, smoke, etc.)
## Which to choose? [#which-to-choose]
| Device | Input Type |
| ------------------------- | ------------------------------ |
| Wall switch | **Event** |
| Doorbell | **Event** or **Binary Sensor** |
| Motion sensor | **Binary Sensor** |
| Reed switch (door/window) | **Binary Sensor** |
| Flood sensor | **Binary Sensor** |
| Smoke detector | **Binary Sensor** |
## Input limitations [#input-limitations]
Some inputs on boneIO Black **cannot be active at controller startup**. We do not recommend connecting reed switches or motion sensors to them, as they may be active during startup.
| Inputs with limitations |
| ---------------------------------------------- |
| IN\_01, IN\_02 |
| IN\_09, IN\_10 |
| IN\_19, IN\_20, IN\_21 |
| IN\_29, IN\_30, IN\_31, IN\_32, IN\_33, IN\_34 |
For reed switches and motion sensors, use the remaining inputs (IN\_03 to IN\_08, IN\_11 to IN\_18, IN\_22 to IN\_28, and IN\_35 onwards).
# First-time setup (/en/docs/black/products/black_cover_mix/software_setup/first-run-wizard)
The first time you open the panel of a new controller, you do not see the panel yet but the **First-time setup** wizard.
It creates the administrator account — the username and password you will sign in with from now on — and helps you get going.
The whole wizard takes a few minutes.
There is no way to skip the wizard. Until it is completed, the controller answers nothing except the wizard itself, so nobody can
change its configuration without a password.
The bar at the top shows how far you are (**Step 2 of 6**, for example). Not every controller sees every step:
| Step | When you see it |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| Start | Always. |
| Account | Always. |
| Which controller is this? | Only if the controller does not yet know which model it is. |
| Import | Only on a controller that still has its factory configuration. |
| Devices | Only on a controller that still has its factory configuration, and only if you did not import a backup. |
| Cloud | Only if boneIO Cloud registration is not already on, and only if you did not import a backup. |
| Done | Always. |
## Start [#start]
The wizard explains that the device has no administrator account yet, and under **What's ahead** lists the steps this controller will go through.
Click **Get started**.
## Account [#account]
Choose the **Username** and **Password** for the panel and type the password again under **Confirm password**.
* the password must be **at least 8 characters** long,
* it must **not contain the username** — the username is visible on the sign-in screen, so a password built from it is easy to guess.
Click **Create account**. From here on there is no way back to this step — the account exists.
The same account also opens the **Node-RED** editor: Node-RED has no accounts of its own, and only panel administrators get in.
**This password is also your SSH password.** On a new controller the wizard sets the same password for the `boneio` user.
Over SSH you always log in as `boneio` (for example `ssh boneio@192.168.1.100`) — the username you typed here is for the panel only.
This happens only once: changing the panel password later does not change the SSH password. For that, use the
[SSH login password](/en/docs/black/current/basic/accounts#ssh-login-password) card in **Settings → Access → User accounts**, or run `passwd` over SSH.
Write the password down somewhere safe.
## Which controller is this? [#which-controller-is-this]
You only see this step if the controller was not told at the factory which model it is. Until you answer, it has no outputs configured.
Pick your model — **32x10A**, **24x16A**, **Cover** or **Cover Mix** — and click **Apply**.
The controller restarts with that model's configuration, which takes up to a minute; the wizard waits and then carries on by itself.
The wizard does not come back to this step, so check the label on the controller first.
{/* SCREENSHOT: en_wizard_board.webp — "Which controller is this?" step with the four models */}
## Import (optional) [#import-optional]
If you are replacing an older boneIO and have a configuration backup from it (a `.tar.gz` file downloaded from
**Settings → Maintenance → Backups** on the old device), drop the file on **Choose a file or drag it here**, or click it to pick the file,
then click **Import configuration**. The controller will take over that configuration after a restart.
Setting up from scratch? Click **Skip**.
If you imported a backup, the Devices and Cloud steps are skipped — the imported configuration already decides them.
## Devices [#devices]
The outputs are already set up for your model. Here you decide what the inputs should do with them:
* **Inputs control outputs** — each input switches one output (a push button turns on a light),
* **Inputs control covers** — pairs of inputs open and close covers,
* **Inputs control covers and outputs** — a mix, on models that have both,
* **Wire nothing — I will do it myself** — leave the inputs empty and configure them later.
Leave **Restore relay and cover state after a restart** on (it is by default) if lights and covers should come back to where they were after a power cut.
Click **Apply**, or **Skip** to leave everything as it is. You can change all of it later in **Settings → Control → Local Inputs**.
## Cloud (optional) [#cloud-optional]
You can register the controller with **boneIO Cloud**. It then gets its own address with a trusted certificate — the browser stops
warning about the connection, and you can install the panel as an app on your phone.
* Registration sends the controller's serial number to boneIO Cloud.
* The controller is still reachable **only on your own network** — nothing is exposed to the internet.
* Your router must not block so-called *DNS rebinding*; if the new address does not open, that is usually the reason.
Click **Enable registration**, or **Skip**. You can turn it on later in **Settings → Access → Web Server**.
After **Enable registration** the controller restarts its HTTPS server with the new certificate. The wizard shows
**Switching the HTTPS server** and holds **Next** while it waits — usually about half a minute, at most three minutes. There is nothing to do, the controller keeps running.
When it is ready, the notice gives you the new address as a link.
If the controller does not know its own network address yet, the wizard says **Registration is saved** instead:
registration starts on the next boot.
## Done [#done]
The wizard confirms **The controller has an owner**, names the account it created, and reminds you that Node-RED takes the same login.
It also says what happened to the SSH password. If it says **The SSH password could not be set**,
SSH login with a password stays closed — contact us on Discord.
How you leave depends on the Cloud step:
* **Without cloud registration**, click **Go to the panel**.
* **With cloud registration**, click **Go to blk….black.boneio.app:8443**. The panel opens at its new address in a new tab.
Sign in there once more with the same password — the browser keeps sign-ins separately for each address.
**Stay at this address** keeps you where you are.
* **If the new address did not answer** (usually DNS rebinding protection on the router), the wizard says so and offers
**Open blk….black.boneio.app:8443 anyway**. The panel keeps working at the current address.
If you imported a configuration or clicked **Apply** in Devices, restart the controller once:
**Settings → Maintenance → Restart and shutdown**. Until then the controller still runs the old configuration.
## Updating from version 1.5? [#updating-from-version-15]
A controller that was already configured before sees a **shorter wizard: Start → Account → Cloud → Done**.
The Cloud step is left out too if cloud registration was already on.
If the 1.5 panel already had a password (`web.auth` in `config.yaml`), there is no wizard at all — sign in with that password.
The wizard only creates the account — your outputs, inputs and actions stay exactly as they were.
If the SSH password of the `boneio` user was still the factory `Black`, the wizard replaces it with your new password too;
if you had already changed it, it is left alone and the wizard says so.
See [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6) for the rest of the checklist.
## Forgot the password? [#forgot-the-password]
Log in over SSH and reset it — see [Accounts and access](/en/docs/black/current/basic/accounts#forgotten-password).
## What's next? [#whats-next]
* [Home Assistant connection](./home-assistant-connection) - connect the controller to Home Assistant
* [Interface navigation](./interface-navigation) - learn about the menu and tabs
* [Accounts and access](/en/docs/black/current/basic/accounts) - add a read-only account for the rest of the household
# Home Assistant Connection (/en/docs/black/products/black_cover_mix/software_setup/home-assistant-connection)
The boneIO Black controller communicates with Home Assistant via the MQTT protocol. There are two configuration methods: using a local broker or a remote one (located on HA itself).
Additionally, to make managing the controller from Home Assistant easier, we have prepared a special Add-on for you, which gives you instant access to your boneIO.
## Option 1: MQTT Broker on boneIO Black (default) [#option-1-mqtt-broker-on-boneio-black-default]
**This is the easiest way** - the controller has a built-in Mosquitto MQTT broker that is already configured and running.
### Default configuration [#default-configuration]
By default, the controller is connected to the local MQTT broker:
* **Host**: `localhost`
* **Port**: `1883`
* **Username**: `boneio`
* **Topics**: `boneio/` — set automatically
The broker has three accounts: `boneio` (the one the controller itself uses), `homeassistant` and `mqtt` (for your integrations).
On a controller installed with version 1.6 or later **each account has its own random password**, different on every device — there is no shared default password any more.
That means before you connect Home Assistant you **set a password you know** for the `homeassistant` account.
**Set the MQTT password first.** Go to **Settings** → **Services on this controller** → **MQTT broker (local)**,
in the `homeassistant` card type the new password twice (at least 8 characters) and click **Change Password**.
This is the password you will type into Home Assistant below.
If you change the password of the `boneio` user, leave **Also update boneIO's own configuration** switched on —
the controller then saves the new password in its own configuration and reconnects on its own.
Without it, the controller keeps using the old password and goes offline.
### Connecting Home Assistant to the broker on boneIO [#connecting-home-assistant-to-the-broker-on-boneio]
1. **No Mosquitto add-on needed** — with this option the broker already runs on the controller,
so in Home Assistant you only add the MQTT integration.
2. **Add MQTT integration in Home Assistant**:
* Go to **Settings** → **Devices & Services**
* Click **Add Integration** → search for **MQTT**
* Enter the details:
* **Broker**: boneIO controller IP (e.g., `192.168.1.100`)
* **Port**: `1883`
* **Username**: `homeassistant`
* **Password**: the password you just set for `homeassistant`
* Click **Submit**
Every step with Home Assistant screenshots is in [Connecting boneIO Black](/en/docs/home-assistant/boneio-black) in the Home Assistant guide.
3. **Automatic discovery**:
* The boneIO controller will automatically register all devices with Home Assistant
* Devices will appear in **Settings** → **Devices & Services** → **MQTT**
### Encrypting Home Assistant's connection (TLS) [#encrypting-home-assistants-connection-tls]
Optional. By default Home Assistant talks to the broker on boneIO in plain text on port 1883, password included.
On your own home network that is often fine. If the network is shared, or the traffic crosses a VPN, have the broker accept encrypted connections on port **8883**.
Go to **Settings** → **Services on this controller** → **MQTT broker (local)** and scroll to the **Broker encryption (TLS)** card, below the accounts.
1. **Get a certificate.** Click **Make a certificate on this controller**. It is valid for ten years and covers the controller's names, listed under **Valid for**.
Then click **Download the CA (ca.crt) for clients** — Home Assistant needs that file.
If you would rather use your own certificate, open **Upload my own certificate** (the page shows the openssl commands under **How to make certificates with openssl**).
2. **Pick a mode** under **Mode**:
* **Off** — plain MQTT on port 1883 only, as before.
* **TLS beside plain** — TLS on 8883, and 1883 keeps working. Start here.
* **TLS only on the network** — from the network only TLS on 8883. Plain 1883 stays only for programs on the controller itself, boneIO included.
3. **Move Home Assistant to TLS.** In the MQTT integration, choose **Reconfigure**, set port **8883**, open the advanced options,
enable certificate validation with a custom broker certificate and upload `ca.crt`.
As the broker address use the controller's name exactly as it appears under **Valid for**, for example `boneio-1234.local`.
An IP address works only if it is on that list, and an address from DHCP can change.
4. Once Home Assistant and everything else connects on 8883, switch to **TLS only on the network** if you want plain MQTT closed to the network.
**What it costs:**
* **Every mode change restarts the broker**, which briefly disconnects everyone, Home Assistant included. If the broker does not come back with the new settings, the panel puts the previous ones back and says so.
* **TLS only on the network** cuts off anything still on port 1883 from another machine until you move it to 8883. The panel refuses this mode while boneIO itself connects to this broker in plain text by the controller's network address: first set boneIO's MQTT host to `localhost`, or turn on TLS for its own connection.
* **Node-RED on the controller** reaches the broker from Docker's network, not from `localhost`. Before **TLS only on the network**, move its broker node to port 8883 with TLS and `ca.crt`.
* **A new certificate means a new CA.** Every client that trusts the current `ca.crt` must be given the new one, or it refuses the broker.
If the card says this controller's system helper does not manage the broker's TLS yet, go to **Settings** → **System migrations**,
click **Apply pending migrations** and come back.
## Option 2: MQTT Broker on Home Assistant [#option-2-mqtt-broker-on-home-assistant]
You can connect the controller to an MQTT broker located on Home Assistant or another device.
### Configuring the broker in Home Assistant [#configuring-the-broker-in-home-assistant]
1. **Install Mosquitto Broker** (if you don't have it yet):
* Go to **Settings** → **Apps** → **Install app**
* Search for **Mosquitto broker**
* Click **Install** and **Start**
2. **Create an MQTT user**:
* Go to **Settings** → **People** → **Users**
* Click **Add User**
* Fill in the details:
* **Name**: `boneio`
* **Username**: `boneio`
* **Password**: choose a secure password
* Click **Create**
3. **Add MQTT integration** (if you don't have it yet):
* Go to **Settings** → **Devices & Services**
* MQTT should be automatically detected
* If not, click **Add Integration** → **MQTT**
### Configuring MQTT in boneIO controller [#configuring-mqtt-in-boneio-controller]
1. Go to **Settings** → **Connections** → **MQTT**
2. Enter the broker details:
* **Host**: Home Assistant IP (e.g., `192.168.1.50`)
* **Port**: `1883`
* **Username**: `boneio`
* **Password**: password of the created user
3. Click **Save**. A change of only these four fields needs no restart: boneIO reconnects to the new broker straight away
4. Devices will automatically appear in Home Assistant
If that broker accepts TLS, switch on **Encrypt the connection (TLS)** on the same page.
See [Encryption (TLS)](/en/docs/black/current/configuration/communication#encryption-tls).
### Installation of the boneIO Home Assistant Add-on [#installation-of-the-boneio-home-assistant-add-on]
1. Go to **Settings** → **Apps** → **Install app**
2. Click the three dots in the top right corner
3. Select Repositories
4. Add this URL: [https://github.com/boneio-eu/home-assistant-addons](https://github.com/boneio-eu/home-assistant-addons)
5. Click Add
6. Find the desired add-on and click Install
## Communication between boneIO controllers [#communication-between-boneio-controllers]
If you have multiple boneIO Black controllers and want them to execute commands on each other (e.g., a button on one controller turns on a light on another), **all controllers must be connected to the same MQTT broker**.
### Example configuration for multiple controllers: [#example-configuration-for-multiple-controllers]
1. Choose one MQTT broker (e.g., on Home Assistant or on one of the controllers)
2. Connect all controllers to the same broker
3. Each controller publishes under its own serial number (`boneio/blk…`), so there is nothing to set to keep them apart
4. In actions, you can use **Control Remote Output** and **Control Remote Cover** to control devices on other controllers
## Connection verification [#connection-verification]
After proper configuration:
1. In Home Assistant, go to **Settings** → **Devices & Services** → **MQTT**
2. You should see the **boneIO Black** device with all configured outputs, covers, inputs, and sensors
3. All entities will be automatically available in Home Assistant
The controller uses **MQTT Discovery** - all devices are automatically detected by Home Assistant without the need for manual configuration.
# How to Connect (/en/docs/black/products/black_cover_mix/software_setup/how-to-connect)
After connecting your controller to the local network, you can access the boneIO web interface through a web browser. This is the most convenient way to configure and monitor your controller.
## Prerequisites [#prerequisites]
* boneIO controller connected to local network via Ethernet cable
* Network with DHCP service enabled (enabled by default on most routers)
* Computer or mobile device on the same local network
* Web browser (Chrome, Firefox, Safari, Edge)
## Step 1: Connect the controller to the network [#step-1-connect-the-controller-to-the-network]
1. Connect an Ethernet cable to the network port of your boneIO controller
2. Connect the other end of the cable to your router or switch
3. Make sure the controller is powered on
The controller will automatically receive an IP address from the DHCP server on your network.
## Step 2: Find the controller's IP address [#step-2-find-the-controllers-ip-address]
There are two ways to find the controller's IP address:
### Option A: Display on the controller [#option-a-display-on-the-controller]
Press the button next to the display on the controller to scroll through the screens:
* the **network** screen shows the controller's **IP address** (plus the network mask and MAC address),
* the **last screen** shows a **QR code** — scan it with your phone and the panel opens straight away, at the right `https://…:8443` address
(or at the controller's own boneIO Cloud address, if you registered it; on a controller upgraded from 1.5 it is `http://…:8090` until you move the panel behind the proxy).
{/* SCREENSHOT: oled_network.webp — photo of the OLED network screen with the IP address */}
{/* SCREENSHOT: oled_qr.webp — photo of the OLED QR code screen */}
Which screens are shown is set in **Settings** → **Device** → **OLED Display**. Both are on in the factory configuration.
### Option B: Router admin panel [#option-b-router-admin-panel]
Log in to your router's admin panel and find the list of connected devices. The boneIO controller will be visible under a name corresponding to its serial number, starting with `blk`, e.g., `blk8c7df0`.
## Step 3: Open the web interface [#step-3-open-the-web-interface]
1. Open a web browser
2. In the address bar, type the controller's IP address with port 8443, e.g., `https://192.168.1.100:8443`
3. Press Enter
Always type `https://` at the start — without it the page will not open.
### The browser warns about the connection — this is expected [#the-browser-warns-about-the-connection--this-is-expected]
The first time you open the panel, the browser shows a warning such as **"Your connection is not private"**.
The connection **is** encrypted; the browser only warns because the certificate was issued by the controller itself,
not by a company the browser knows.
* **Chrome / Edge**: click **Advanced**, then **Proceed to 192.168.1.100 (unsafe)**
* **Firefox**: click **Advanced…**, then **Accept the Risk and Continue**
* **Safari**: click **Show Details**, then **visit this website**
The controller's certificate is valid for six months, so the browser does not ask again every day.
To get rid of the warning for good, see [HTTPS certificate](/en/docs/black/current/advanced/certificate).
## Step 4: Create your administrator account [#step-4-create-your-administrator-account]
A new controller has no owner yet. Instead of the panel you will see the **First-time setup** wizard.
Until the account exists, the controller's display says so: it shows **Setup required**, **Onboarding needed.**,
**Open in a browser:** and the panel's address. The display does not go dark while that notice is up, and the address
appears as soon as the controller gets one from the router (until then the line reads `http://:8090`, which is only a placeholder). The button still steps through the other screens;
after a minute the notice comes back. Once the account is created, the notice goes away by itself within a few seconds.
{/* SCREENSHOT: oled_setup_required.webp — photo of the OLED showing "Setup required" with the panel address */}
For a moment right at power-on, before that notice, the display may show `SETUP REQUIRED - open :8090` —
ignore the port there and use the address from the notice, or `https://…:8443`.
In the wizard you choose a username and password for the panel. It takes about a minute — see
[First-time setup](./first-run-wizard) for every step.
Do this right away. Until an account exists, **whoever on your network completes the wizard first becomes the owner** of the controller.
After the wizard you land in the main panel showing the controller status.
## Troubleshooting [#troubleshooting]
### I can't find the IP address [#i-cant-find-the-ip-address]
* Make sure the Ethernet cable is properly connected
* Check if the network LED on the controller is lit or blinking
* Restart the controller and wait about 30 seconds to obtain an IP address
### The page won't load [#the-page-wont-load]
* Check if your computer is on the same network as the controller
* Make sure you type `https://` before the IP address and `:8443` after it
* Try clearing your browser cache or use incognito mode
* A warning about the certificate is not an error — see Step 3
### The controller doesn't receive an IP address [#the-controller-doesnt-receive-an-ip-address]
If your network doesn't have a DHCP server, you can connect to the controller via USB cable:
1. Connect a USB cable to the USB port of the controller and to your computer
2. Your computer will receive an IP address from the `192.168.7.x` range
3. The controller will be available at `192.168.7.2` — the panel opens at `http://192.168.7.2:8090`
(if it does not open, restart the controller with the cable plugged in)
4. Connect via SSH and configure a static IP address for the `eth0` interface
This guide does not cover the exact network configuration commands.
## What's next? [#whats-next]
After connecting to the controller, you can proceed to:
* [First-time setup](./first-run-wizard) - every step of the wizard explained
* [Home Assistant connection](./home-assistant-connection) - connect the controller to Home Assistant
* [Interface navigation](./interface-navigation) - learn about the menu and tabs in the web interface
* [Update controller](./update-controller) - check if you have the latest software version
* [Configure controller](./edit-configuration) - configure the controller according to your needs
# Software Setup Introduction (/en/docs/black/products/black_cover_mix/software_setup)
# Software Setup [#software-setup]
This section guides you through the software configuration of your **boneIO Black** device. Proper setup is crucial for integrating the controller with your home automation system - Home Assistant.
Our custom software, built to run on the powerful BeagleBone Black, offers a web interface for initial setup and monitoring.
The following guide is divided into several steps. In the first two, you will learn how to connect to the **boneIO** controller and how to connect the controller to the Home Assistant system. In the following steps, you will learn how to configure and adapt your boneIO to your needs.
# Interface navigation (/en/docs/black/products/black_cover_mix/software_setup/interface-navigation)
After connecting to the controller, you will see the web interface with a top navigation bar. Below you'll find a description of all available tabs.
On a phone or tablet the same tabs move to a bar at the bottom of the screen — see [On a phone or tablet](#on-a-phone-or-tablet).
## Main menu [#main-menu]
| Tab | Description |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Outputs** | Control relay outputs, covers, and view relay states. |
| **Inputs** | View the state of digital inputs. |
| **Sensors** | Readings from onboard sensors: temperature, current consumption, memory usage, CPU, disk, and Dallas sensors (if connected). |
| **Modbus** | List of connected and configured Modbus devices. |
| **Templates** | Ready-made building blocks such as irrigation. |
| **Diagnostics** | The log, the support bundle and the bus tools (Modbus, I2C, CAN). See [Diagnostics](/en/docs/black/current/basic/logs). |
| **Settings** | Everything you configure, in seven groups — from outputs and schedules to software update, backups and restart. See [Settings](/en/docs/black/current/basic/settings). |
| **Node-RED** | The pre-installed visual automation tool. Shown only when Node-RED is running. |
| **Help** | Link to Discord community and documentation. |
**Where did System, Logs and the YAML editor go?** Since version 1.6 they are all inside the two tabs above:
the old **System** tab is now **Settings → Maintenance**, **Logs** and **Tools** are **Diagnostics**,
and the **YAML editor** is **Settings → Advanced → YAML editor**. Old bookmarks still work — they redirect.
A **read-only** account sees only the first five tabs. Diagnostics, Settings and Node-RED are for administrators — see [Accounts and access](/en/docs/black/current/basic/accounts).
## On a phone or tablet [#on-a-phone-or-tablet]
On a phone, a tablet or a narrow browser window the top bar shows only the
controller's name, and the tabs move to a bar at the bottom, under your thumb:
| Slot | What it opens |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Outputs** | The outputs view |
| **Inputs** | The inputs view |
| **Sensors** or **Templates** | Sensors — or Templates, once you have any; Sensors then moves under **More** |
| **Modbus** | The Modbus view |
| **More** | Everything else: Diagnostics, Settings, Node-RED, Help, and below them the version, serial number and the account you are signed in with |
### Inside the boneIO Dashboard add-on [#inside-the-boneio-dashboard-add-on]
When you open the panel through the **boneIO Dashboard** add-on in Home
Assistant, the bottom bar gets one more slot on the left: **Devices**. It opens
the add-on's device list. To make room, **Sensors** moves under **More**. Opened
through plain Home Assistant ingress, the bar stays as above.
{/* SCREENSHOT: en_bottom_nav_dashboard.webp — the panel inside the boneIO Dashboard add-on on a phone, Devices slot on the left of the bottom bar */}
## Language change [#language-change]
In the top right corner, you'll find flags to change the interface language. Available languages are Polish (PL) and English (EN).
# Naming Inputs (/en/docs/black/products/black_cover_mix/software_setup/naming-inputs)
# Why should you name them? [#why-should-you-name-them]
Naming your inputs will make working with the controller much easier. It's a lot easier to remember "Bedroom Button1" than "IN\_04", right?
## Events – event entities [#events--event-entities]
Let's start with event entities. Below is the default configuration from the file:
```
~/boneio/event.yaml
```
```yaml
- id: IN_04
boneio_input: IN_04
actions:
single:
- action: output
pin: OUT_04
- id: IN_05
boneio_input: IN_05
actions:
single:
- action: output
pin: OUT_05
- id: IN_06
boneio_input: IN_06
actions:
single:
- action: output
pin: OUT_06
```
How do you name your input? It's very simple!
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | This part of the configuration is the input name, and you can change it freely. There are many naming approaches. For example, you can change the name to `BedroomButton1` or `IN_04_BedroomButton_1`. |
| `boneio_input` | This is the input number that your name refers to. For now, ignore `actions:` – we'll discuss them later. |
Our example looks like this:
```yaml
- id: IN_04_BedroomButton_1
boneio_input: IN_04
actions:
single:
- action: output
pin: OUT_04
```
## Binary (Binary sensor) [#binary-binary-sensor]
Below is the default configuration from the file:
```
~/boneio/binary_sensor.yaml
```
```yaml
- id: IN_01
boneio_input: IN_01
actions:
pressed:
- action: output
pin: OUT_01
- id: IN_02
boneio_input: IN_02
actions:
pressed:
- action: output
pin: OUT_02
```
| Parameter | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | This part of the configuration is the input name, and you can change it freely. There are many naming approaches. For example, you can change the name to `MotionBedroom` or `IN_01_MotionBedroom`. |
| `boneio_input` | This is the input number that your name refers to. For now, ignore `actions:` – we'll discuss them later. |
Our example looks like this:
```yaml
- id: IN_01_MotionBedroom
boneio_input: IN_01
actions:
pressed:
- action: output
pin: OUT_01
```
# Configure outputs (/en/docs/black/products/black_cover_mix/software_setup/naming-outputs)
The boneIO Black Cover Mix controller has:
* **16 cover outputs** (8 covers, each with 2 relays: up/down)
* **16 regular relays rated at 10A** (OUT\_17 to OUT\_32)
## Cover outputs (cover\_01 to cover\_08) [#cover-outputs-cover_01-to-cover_08]
**You don't need to change cover output names** - they are automatically configured as:
* `cover_01_up` / `cover_01_down`
* `cover_02_up` / `cover_02_down`
* ... to `cover_08_up` / `cover_08_down`
These outputs are used internally by the cover configuration and **do not require editing**, unless you have specific needs.
**For cover outputs, you can go directly to cover configuration** - outputs are already properly configured.
## Regular relays (OUT\_17 to OUT\_32) [#regular-relays-out_17-to-out_32]
For regular relays **you can configure outputs** the same way as in 32x10A or 24x16A controllers.
### How to add or edit a regular output? [#how-to-add-or-edit-a-regular-output]
1. Go to **Settings** → **Control** → **Local Outputs**
2. Click **Add New** or the edit icon next to an existing output
3. Fill in the configuration form
### Available relays [#available-relays]
Select the physical relay number from the dropdown:
* `OUT_17`, `OUT_18`, `OUT_19`, ... `OUT_32`
### Output Type [#output-type]
Select the type of device:
| Type | Use Case | HA Icon |
| ---------- | ----------------------------- | ---------- |
| **Light** | Lighting | Light bulb |
| **Switch** | Switch (pumps, heaters, etc.) | Switch |
| **Valve** | Water valve | Valve |
### Display Name and ID [#display-name-and-id]
* **Display Name**: Friendly name, e.g., `Bathroom Light`
* **Custom ID**: Auto-generated from name (only lowercase letters, numbers, underscores)
**We do not recommend changing the output ID** after it has been created. Changing the ID will cause loss of history in Home Assistant and require reconfiguration of automations.
### Area / Room [#area--room]
Select an area from the dropdown - the output will be automatically assigned to this area in Home Assistant.
### Options [#options]
* **Restore State**: Enable to have the output remember its state after restart
## Configuration example [#configuration-example]
**Scenario**: You want to configure bathroom lighting on relay OUT\_17.
1. **BoneIO Output**: `OUT_17`
2. **Output Type**: `Light`
3. **Display Name**: `Bathroom Light`
4. **Area / Room**: `Bathroom`
5. **Restore State**: ✅ Enabled
After saving, the output will appear in the table and be available in Home Assistant as `light.bathroom_light` in the "Bathroom" area.
# Update Controller (/en/docs/black/products/black_cover_mix/software_setup/update-controller)
The controller checks for a new version by itself every few hours. You install it with one click —
from Home Assistant or from the controller's own panel.
## Requirements [#requirements]
* The controller must have an internet connection
* You must be signed in to the panel as an **administrator**
* To update from Home Assistant, the controller must be connected to Home Assistant over MQTT
## How to update? [#how-to-update]
### From Home Assistant [#from-home-assistant]
1. In Home Assistant, open **Settings** — available updates are listed at the top,
2. Click the **boneIO Black Firmware** update,
3. Press **Update**,
4. That's all!
### From the web interface [#from-the-web-interface]
1. Open the controller's web interface in your browser
2. Go to **Settings** → **Maintenance** → **Software update**
3. Click **Check for Updates**
4. If a new version is available, read what it changes (**View Release Notes**), then click **Update to \** (for example **Update to 1.6.0**)
The update starts on its own. When it finishes, the application on the controller restarts and the panel reloads.
While the controller is installing and restarting, the panel shows **Update in progress** with the time since it started,
and comes back by itself once the new version is running. If the controller comes back on the old version, the panel says
**The update failed** — the details are in [Diagnostics](/en/docs/black/current/basic/logs).
If your browser shows the old panel after the update, it reloads the new one on its own (**Loading the new version of the panel**);
if it cannot, it asks you to press **Ctrl+Shift+R** (**Cmd+Shift+R** on a Mac).
{/* SCREENSHOT: en_panel_update_in_progress.webp — the "Update in progress" screen with "The controller is installing version …" and the elapsed time */}
**The update does not back up your configuration.** Download a backup first in **Settings → Maintenance → Backups**.
If something is wrong after the update, open **Available Versions** on the same page and install the previous version (the button is **Install**).
## After the update: system migrations [#after-the-update-system-migrations]
Some versions also change settings of the operating system underneath the app — for example firewall rules or SSH hardening.
These changes are called **system migrations**. They run by themselves on the first start after the update; you do not need to do anything.
You can see them in **Settings** → **Maintenance** → **System migrations**.
If a red banner says that **a system update was refused**, the page shows the reason — send it to us
(see [Diagnostics](/en/docs/black/current/basic/logs) for the support bundle).
## Updating from version 1.5? [#updating-from-version-15]
**Update to 1.5.6 first**, then to 1.6. Only 1.5.6 hands the browser over to the new panel cleanly; from older 1.5
versions the old panel may keep coming back after the update until you press **Ctrl+Shift+R**.
Version 1.6 adds accounts, so after the update the panel asks you to create an administrator account first
(unless the 1.5 panel already had a password — then you simply sign in with it).
Follow [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6).
## Important information [#important-information]
* **Do not turn off the controller's power during the update.** A backup power supply is worth having for exactly this — see
[Backup power (UPS)](/en/docs/black/products/black_32x10a/hardware-installation#backup-power-ups--recommended).
* A small update takes a few minutes. Jumping several versions can take over ten minutes, and coming from 1.5 up to an hour,
because the system migrations run on the first start.
* While migrations run, the display shows **Updating** and **Do not power off.** with how far it has got
(**Updating system** with a percentage, if the display is not set up in the configuration). The panel does
not answer until they finish.
* After the update, the application on the controller restarts by itself.
{/* SCREENSHOT: oled_updating.webp — photo of the OLED showing "Updating", "Do not power off." and the percentage */}
## Updating the operating system [#updating-the-operating-system]
Updating boneIO does not update the Debian system and the kernel underneath it. That is a separate card on the same page,
**Operating system** — see [Maintenance → Operating system](/en/docs/black/current/basic/system#operating-system).
Unlike a boneIO update, it does not restart the controller by itself.
## Update via SSH [#update-via-ssh]
If you need to update the controller manually via SSH (e.g., when the web interface update doesn't work), see the [SSH update guide](/en/docs/black/advanced/update-via-ssh).
# Hardware Installation (/en/docs/esp/products/dimmer/gen2/hardware_installation)
## Key Safety Principals [#key-safety-principals]
> **IMPORTANT: PROFESSIONAL INSTALLATION REQUIRED**
>
> We emphasize in the strongest possible terms: safety is the absolute priority. All activities related to connecting the device to an electrical installation **must be performed exclusively by a qualified electrician** who holds the appropriate certifications. Installation by unqualified individuals poses a risk of electric shock, equipment damage, or fire. The manufacturer assumes no liability for damages resulting from an improper installation.
This applies in particular to:
* Connecting the power supply to the controller.
* Connecting high-voltage circuits (110V/230V) to the controller's outputs.
* All installation work inside the electrical cabinet (distribution board).
Attempting to modify an electrical installation without the proper qualifications is illegal, extremely dangerous, and creates a real hazard that can lead to:
* **Electric shock, severe personal injury, or death.**
* **Permanent damage to the boneIO controller and all connected equipment.**
* **A significant fire hazard resulting in property damage.**
* **Voiding the product warranty and potential issues with property insurance claims.**
**The manufacturer of boneIO assumes no liability whatsoever for material damages, personal injury, or loss of life resulting from an installation performed contrary to these guidelines and applicable safety standards.**
Please treat this warning with the utmost seriousness.
***
## DIN Rail Mounting [#din-rail-mounting]
The boneIO ESP controller is designed for mounting on a standard DIN rail (TS35).
1. Hook the upper clips of the enclosure onto the top edge of the DIN rail.
2. Press the lower part of the enclosure firmly until the latches lock onto the rail with a distinct click.
3. Ensure the module is securely mounted.
## Power Supply Connection [#power-supply-connection]
The device requires a stabilized 12-24V DC power supply. All power terminals should be powered from single power supply.
1. Ensure the power supply is disconnected from the 230V/110V mains.
2. Connect the `+` output of the power supply to the `+` screw terminal on the boneIO ESP.
3. Connect the `GND` (ground) output of the power supply to the `GND` screw terminal on the boneIO ESP.
4. Double-check the connections and polarity before turning on the power supply.
**NEVER CONNECT THE USB-C PORT WITH THE POWER SUPPLY CONNECTED!!!**
The USB-C port is dedicated to flashing firmware. This should be done ONLY with the controller's power supply disconnected. Using the USB-C port with the power connector plugged in risks DAMAGING the controller!
## Connect Ethernet [#connect-ethernet]
The device communicates with the network using a built-in Ethernet port, which guarantees a stable and reliable connection. To establish connectivity, connect the module to your network switch using a standard Ethernet (RJ45) cable.
1. Connect ethernet cable to LAN port on your controller.
2. Connect other side of ethernet cable to your network switch.
## Connecting Digital Inputs [#connecting-digital-inputs]
Digital inputs are used for connecting switches and sensors. By default, they are ground-controlled.
1. Connect one of the wires from a momentary switch to the common `GND` (ground) terminal.
2. Connect the other wire to the desired input terminal (e.g., `IN01`).
3. Pressing the switch will short the input to ground, which will be interpreted as an "on" signal.
### Logical diagram of connecting digital input [#logical-diagram-of-connecting-digital-input]
### GND or + [#gnd-or-]
Input behavior can be changed via the internal switch. Please see the switch location below.
* Down: GND control.
* Up: High-potential control.
### Example 1 - Push button: [#example-1---push-button]
### Example 2: [#example-2]
### Example 3: [#example-3]
## Connecting LED Strips [#connecting-led-strips]
The dimmer is divided into two independent sections, Left and Right, each with 4 PWM channels. Both L and R sections are separated from each other and protected by a separate 10-amp fuse.
> **IMPORTANT:** Mixing channels or power supplies from the left and right sections is prohibited and may damage the device.
Each section has its own set of connectors:
* **VCC/+:** The common positive terminal for the LED strips in that section.
* **CH1-CH4:** Negative PWM output channels.
**Current Limits:**
* Maximum total current per section (4 channels): **10A**
How to interpret this? We'll discuss this using the Left Section as an example. The 10-amp protection means that the total combined current passing through all channels (CHL1, CHL2, CHL3, CHL4) can be 10A.
Below, we will present a few potential configurations to definitively explain the technical parameters of the outputs.
| CHL1 | CHL2 | CHL3 | CHL4 | SUMA |
| ---- | ---- | ---- | ---- | ---- |
| 2A | 2A | 3A | 3A | 10A |
| 5A | 5A | 0A | 0A | 10A |
| 7A | 1A | 1A | 1A | 10A |
### Single Color (White) LED Strips [#single-color-white-led-strips]
Each channel can control a separate single-color LED strip.
* Connect the positive (`+`) wire of the LED strip to the `VCC` (common positive) terminal of a section.
* Connect the negative (`-`) wire of the LED strip to the desired PWM channel (e.g., `CH1`).
### RGB/RGBW LED Strips [#rgbrgbw-led-strips]
One section (4 channels) can control one RGBW strip or one RGB strip (using 3 channels).
* Connect the common anode (`+`) of the strip to the `VCC` terminal.
* Connect the R, G, B, and W wires to the `CH1`, `CH2`, `CH3`, and `CH4` terminals respectively.
### CCT (Tunable White) LED Strips [#cct-tunable-white-led-strips]
A CCT strip has two channels (warm white and cool white).
* Connect the common anode (`+`) of the strip to the `VCC` terminal.
* Connect the warm white wire to one channel (e.g., `CH1`).
* Connect the cool white wire to another channel (e.g., `CH2`).
## Fuse Replacement [#fuse-replacement]
The device is protected by two 10A fuses, one for each 4-channel section. If the outputs in one section stop working, check the corresponding fuse.
1. **Turn off the power** to the device.
2. Carefully open the enclosure.
3. Locate the blown fuse and replace it with a new 10A mini-blade fuse.
## Connecting Communication Buses [#connecting-communication-buses]
### Modbus RS485 [#modbus-rs485]
Used for communication with industrial and HVAC devices.
* Connect the `A` line of the bus to the `A` terminal on the boneIO.
* Connect the `B` line of the bus to the `B` terminal on the boneIO.
> ESP series devices have undergone Modbus RTU bus testing with 5 connected devices. Using a larger number of Modbus devices connected to an ESP series controller may cause delays in the controller's response (both inputs and outputs). This is due to the specifics of the processor used. In the case of extensive Modbus buses, we recommend splitting them across several devices.
### CAN [#can]
Used for communication with industrial HVAC devices and sensors.
* Connect the `L` line of the bus to the `L` terminal on the boneIO.
* Connect the `H` line of the bus to the `H` terminal on the boneIO.
## Final Checks [#final-checks]
After completing the installation:
1. Double-check all connections.
2. Ensure there are no short circuits.
3. Turn on the main power (24V DC power supply).
# Overview and Specification (/en/docs/esp/products/dimmer/gen2/overview)
## boneIO ESP Dimmer gen2 [#boneio-esp-dimmer-gen2]
You can buy the controller -> [HERE](https://store.boneio.eu/product/boneio-8x10a-gen2/?v=288404204e3d)
The boneIO ESP Dimmer gen2 is a professional 8-channel PWM controller designed for automating LED lighting. It allows for precise control over single-color, RGB, or RGBW LED strips, enabling the creation of advanced lighting scenes. The device is divided into two sections, each with 4 channels, and is equipped with digital inputs for connecting wall switches.
## Key Features [#key-features]
* **8 digital inputs** for connecting momentary switches or sensors.
* **8 PWM output channels** organized in two sections of 4 channels.
* **High current capacity:** up to 10A per channel and 10A per section.
* Reliable network connection via **Ethernet** and **WiFi** (with external antenna).
* Wide expansion capabilities thanks to **Modbus, and CAN interfaces.**
* **USB-C port** for easy firmware installation.
* Compact **7-module DIN rail** enclosure.
## Use Cases [#use-cases]
* Advanced control of single-color or multi-color (RGB/RGBW) LED strips.
* Creating dynamic lighting scenes and animations.
* Integrating LED lighting with a smart home system.
* Manual control of lighting using traditional wall switches.
* Automating HVAC systems (heating, ventilation, air conditioning) thanks to Modbus and CAN support.
## Technical Specification [#technical-specification]
| Feature | Value |
| ----------------------- | ------------------------------------------------------------------------ |
| **Module** | ESP32-S3 |
| **Power Supply** | 12-24V DC |
| **Power Consumption** | Max. 7W (excluding LED strip consumption) |
| **Digital Inputs** | 8 |
| **PWM Channels** | 8 (2 sections x 4 channels) |
| **Max Output Voltage** | 24V DC |
| **Max Output Current** | 10A per channel / 10A per section |
| **PWM Frequency** | 10Hz – 40MHz |
| **External Interfaces** | Modbus RS485, CAN |
| **Communication** | Ethernet 10/100Mbit, Wi-Fi (with external antenna), USB-C (for firmware) |
| **Dimensions (WxHxD)** | 126mm x 91mm x 57mm (without plugs) / 126mm x 108mm x 57mm (with plugs) |
| **Mounting Width** | 7 DIN modules |
| **Weight** | 230g |
## Connectors and Components Description [#connectors-and-components-description]
1. **Power Connector (VCC/GND):** Main device power supply (12-24V DC).
2. **Power Connector for Section L:** Power supply connection.
3. **Output Channel Screw Terminals - CHL1-CHL4:** PWM outputs for connecting LED strips.
4. **Power Connector for Section R:** Power supply connection.
5. **Output Channel Screw Terminals - CHR1-CHR4:** PWM outputs for connecting LED strips.
6. **IN (1-8) Screw Terminals:** Digital inputs for buttons or sensors.
7. **Modbus RS485 Connector:** Modbus connector for connecting Modbus devices.
8. **CAN Bus Connector:** CAN connector for connecting CAN devices.
9. **USB-C Connector:** For uploading firmware.
10. **Ethernet Port (RJ45):** For connecting to the LAN.
**NEVER CONNECT THE USB-C PORT WITH THE POWER SUPPLY CONNECTED!!!**
The USB-C port is dedicated to flashing firmware. This should be done ONLY with the controller's power supply disconnected. Using the USB-C port with the power connector plugged in risks DAMAGING the controller!
## Quick Start Guide [#quick-start-guide]
1. **Device Installation:** Mount the device on a DIN rail and connect the 12-24V DC power supply.
2. **Connect LED Strips:** Connect your LED strips to the PWM output channels.
3. **Connect Switches:** Connect momentary switches to the digital inputs for manual control.
4. **Network Connection:** Plug a LAN cable into the RJ45 port or configure Wi-Fi.
5. **Add to Home Assistant:** Home Assistant discovers the controller on your network — see [Connecting boneIO ESP](/en/docs/home-assistant/boneio-esp). Firmware from [boneio.eu/esp](https://boneio.eu/esp) has no web panel by default. If you want to open the controller in a browser at its IP address, choose the **+ web panel** variant in the installer ([what that means](/en/docs/esp/security)).
## Certificates [#certificates]
* [EU Declaration of Conformity (CE)](https://cdn.boneio.eu/certificates/boneio_esp_all_en.pdf)
# Internal Automations (/en/docs/esp/products/esp_24_16/software_setup/create-automations)
## What are Internal Automations? [#what-are-internal-automations]
Internal automations are a powerful way to create simple, core automations that run directly on your boneIO ESP controller. This means they will work even if your main smart home hub (like Home Assistant) is offline. They are perfect for critical functions, like turning on a light with a wall switch.
### Basic Automation: Toggling a Light [#basic-automation-toggling-a-light]
Let's start with a default configuration that links a button press to a light.
```yaml
binary_sensor:
- platform: gpio
name: 'IN_01_Bedroom_Button1'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_press: # This is our automation trigger
- if:
condition:
switch.is_on: local_control # the Local control switch in Home Assistant
then:
- light.toggle: light_01 # This is the action to perform
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
```
In the `on_press:` section, we define what happens when the button is pressed.\
The action `- light.toggle: light_01` will toggle the state of the light with the ID `light_01`.
The `switch.is_on: local_control` condition is the **Local control** switch the
boneIO configuration shows in Home Assistant — turned off, inputs only report
their state ([more](/en/docs/home-assistant/boneio-esp#local-control)). In your
own automation that should always run, you can leave the condition out.
The same logic applies to switches. The only difference is that the action would be `- switch.toggle: switch_01`. Simple!
## Advanced Automation: Multi-Click [#advanced-automation-multi-click]
ESPHome allows you to define multiple actions for a single button based on how it's pressed (single, double, or long press). This is done using the `on_multi_click` component.
Let's configure one button (`in_01`) to control three different lights.
### 1. The Goal [#1-the-goal]
* **Single Click**: Toggle `light_01`.
* **Double Click**: Toggle `light_02`.
* **Long Press**: Toggle `light_03`.
### 2. The Configuration [#2-the-configuration]
First, ensure you have your lights defined. Then, in your `binary_sensor` configuration, replace `on_press` with `on_multi_click`.
```yaml
# Ensure these lights are defined elsewhere in your config
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
- platform: binary
name: 'Light 02'
output: out_02
id: light_02
- platform: binary
name: 'Light 03'
output: out_03
id: light_03
# Now, configure the multi-click automation
binary_sensor:
- platform: gpio
name: 'IN_01_Multi_Click_Button'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_multi_click:
# Note: The order matters! ESPHome checks from top to bottom.
# It's best to define the most complex patterns (longest clicks) first.
# 1. Long Click Action
- timing:
- ON for at least 1.4s
then:
- logger.log: 'Long Click Detected, toggling Light 3'
- light.toggle: light_03
# 2. Double Click Action
- timing:
- ON for at most 1s
- OFF for at most 0.5s
- ON for at most 1s
- OFF for at least 0.2s
then:
- logger.log: 'Double Click Detected, toggling Light 2'
- light.toggle: light_02
# 3. Single Click Action
- timing:
- ON for at most 1s
- OFF for at least 0.5s
then:
- logger.log: 'Single Click Detected, toggling Light 1'
- light.toggle: light_01
```
### 3. How It Works [#3-how-it-works]
The `on_multi_click` automation checks a sequence of `timing` blocks from top to bottom. The first one that matches the user's button press pattern is executed.
* `timing`: This defines the pattern of ON (pressed) and OFF (released) states. You can adjust the time values (e.g., `at most 1s`, `at least 0.5s`) to fine-tune the responsiveness, but the defaults are usually a good starting point.
* `then`: This block contains the actions to be performed when the `timing` pattern is matched. We've included a `logger.log` action, which is very helpful for debugging your automations in the device logs.
By arranging the clicks from most complex (long press) to least complex (single press), you ensure that a long press doesn't also trigger the single press action.
# Connect your boneIO ESP (/en/docs/esp/products/esp_24_16/software_setup/how-to-connect)
# Let's install the ESPHome Device Builder! [#lets-install-the-esphome-device-builder]
There are 3 options to connect to your boneIO ESP:
1. [Using Home Assistant addon](#using-home-assistant-addon)
2. [Using Esphome Device Builder on your PC](#using-esphome-device-builder-on-your-pc)
## ESPHome Device Builder in Home Assistant [#esphome-device-builder-in-home-assistant]
Installing the ESPHome Device Builder add-on is pretty simple. Just follow these steps:
1. Go to the **Settings > Add-ons** section in your Home Assistant.
2. Click the **Add-on Store** button in the bottom right corner.
3. In the search bar, type `ESPHome` and select the add-on from the official repository. Make sure you don't use beta or dev versions, as they are for testing purposes only.
4. Click **Install**.
After the installation is complete, go to the **Configuration** tab and enable the **Start on boot** and **Show in sidebar** options. This will make it easier to access ESPHome Device Builder in the future.
Finally, go to the **Info** tab and click **Start** to run the add-on. You will now see ESPHome Device Builder in your sidebar!
## ESPHome Device Builder on Your PC [#esphome-device-builder-on-your-pc]
If you don't use Home Assistant (HA), you can still edit your boneIO ESP's configuration.
Editing Esphome config without HA, just on your PC is also possible. Similar instruction is here: [https://esphome.io/guides/getting\_started\_command\_line](https://esphome.io/guides/getting_started_command_line)
On your PC, you will need one of the following:
* for Linux: Docker,
* for Windows: Python 3.13 installed.
### Windows [#windows]
We assume that you are running Windows 10 or 11 - its important to have your administrative privileges, also you need internet connection.
Let's do it step by step!
1. Download Python installer from Python download page for Windows Choose Windows installer according to your operating system version (most common is 64-bit).
2. Choose both options available in installer. “Use admin priviliges when installing py.exe” and “Add python.exe to PATH”. Click “Install now”.
3. Verify Python installation Open Powershell or CMD and type:
```powershell
python --version
```
If properly installed output would look like (with your Python version):
```powershell
Python 3.13.2
```
4. Prepare Esphome for Python. In Powershell prompt type:
```powershell
mkdir $env:USERPROFILE\esphome
cd $env:USERPROFILE\esphome
pip3 install wheel esphome pillow==10.2.0
```
in CMD:
```cmd
mkdir %USERPROFILE%\esphome
cd %USERPROFILE%\esphome
pip3 install wheel esphome pillow==10.2.0
```
5. ESPHome should work now - lets test it! Do it by typeing:
```powershell
esphome version
```
The output should looks like:
```powershell
Version: 2025.x.x
```
The version will differ for you. It's depends on your current version.
Now you’re good to execute next steps.
#### Run ESPHome Dashboard \[!toc] [#run-esphome-dashboard-toc]
In powershell type:
```powershell
cd $env:USERPROFILE\esphome
esphome dashboard .
```
or in CMD
```cmd
cd %USERPROFILE%\esphome
esphome dashboard .
```
Check it out opening page in your web browser [http://127.0.0.1:6052](http://127.0.0.1:6052) If it’s loaded then you can go to next section: [Connect with Esphome Addon](#connect-with-esphome-addon) or if you prefer USB installation go to [USB Only installation](#usb-only-installation).
#### Upgrade ESPHome \[!toc] [#upgrade-esphome-toc]
To upgrade your ESPHome in windows you need to:
```powershell
pip3 install --upgrade esphome
```
### Linux [#linux]
Fetch Esphome docker image / Linux / Mac OS
Run following command in terminal:
```bash
docker pull ghcr.io/esphome/esphome
```
Run Esphome dashboard
Now let’s start Esphome dashboard. Make directory where your config would be stored eg /home/me/esphome
In Linux based system:
```bash
docker run --rm --privileged --network host -v "/home/me/esphome":/config -it ghcr.io/esphome/esphome dashboard .
```
Now in Chrome open website:
under Linux [http://0.0.0.0:6052/](http://0.0.0.0:6052/)
## Connect with ESPHome Device Builder [#connect-with-esphome-device-builder]
**Note**: For this to work your home network must support mDNS. Your PC and boneIO is in same subnet (same VLAN) in most cases it’d work. boneIO has to be connected to your network and working.
1. Find your new boneIO device in the dashboard.
2. Click Adopt
3. Choose name for our new device
4. Click Adopt
5. Now it will prompt for install new software
6. After install there will be logs visible, you can click stop now
Next, set a password and an encryption key on the controller: until you do, anyone on your network can flash it. See [Security](/en/docs/esp/security#after-adoption-in-esphome-builder).
It’s ready, you can edit your config by clicking Edit on your boneIO device.
### Running boneIO without Home Assistant [#running-boneio-without-home-assistant]
If you don’t have HA, then in config find line:
```yaml
api:
```
and add `reboot_timeout: 0s` to it, so it’d look like:
`reboot_timeout: 0s` is default option in our precompiled binaries.
```yaml
api:
reboot_timeout: 0s
```
## USB-Only Installation [#usb-only-installation]
If you don’t want to setup network in boneIO then go with those steps. You'd need to have Esphome dashboard running. For Esphome firmware installation you’d need internet connection on your PC!
1. Go to [https://boneio.eu/esp](https://boneio.eu/esp)
2. Choose your board and choose option "Download yaml for this firmware" in the end.
3. In the top right corner choose Download raw file
4. Copy it to your Esphome directory eg C:/Users/me/esphome. After pasting it, it should appear in Esphome dashboard.
5. Now you can Edit and Install firmware using "Plug into this computer" option. If you need to install some drivers, then Esphome website should show what to download to get it work.
# Edit config file (/en/docs/esp/products/esp_24_16/software_setup/how-to-edit-config)
# Configuration file [#configuration-file]
The configuration file might look big and complicated, but it's really not. The file itself is separated into sections, which we will describe below.
For our example, we will use `boneio-24x16_switches_v0_7.yaml`.
So let's begin. Here is the whole config file:
```yaml
substitutions:
name: boneio-24-sw-07
friendly_name: 'BoneIO ESP 24x16 Switches'
serial_prefix: 'esp' #Don't change it.
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.24x16-switches
version: '0.7'
esp32:
board: nodemcu-32s
framework:
type: esp-idf
ethernet:
id: eth
type: LAN8720
mdc_pin: GPIO23
mdio_pin: GPIO18
clk:
pin: GPIO0
mode: CLK_EXT_IN
phy_addr: 1
power_pin: GPIO16
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-24x16_switches_v0_7.yaml@latest
import_full_config: true
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.7.1
files: [
'devices/buzzer.yaml',
'devices/serial_no.yaml',
'devices_v0_7/display.yaml',
'devices_v0_7/i2c.yaml',
'devices_v0_7-v0_9/ina219.yaml',
'devices_v0_7-v0_9/lm75b.yaml',
'devices_v0_7-v0_9/pcf_with_mcp.yaml',
'boards/24x16_output.yaml',
# 'devices_v0_7-v0_9/one_wire.yaml',
]
logger:
api:
reboot_timeout: 0s
ota:
- platform: esphome
- platform: web_server
web_server:
port: 80
local: true
time:
- platform: homeassistant
timezone: Europe/Warsaw
id: homeassistant_time
switch:
- platform: output
name: 'Switch 01'
output: out_01
id: switch_01
- platform: output
name: 'Switch 02'
output: out_02
id: switch_02
- platform: output
name: 'Switch 03'
output: out_03
id: switch_03
- platform: output
name: 'Switch 04'
output: out_04
id: switch_04
- platform: output
name: 'Switch 05'
output: out_05
id: switch_05
- platform: output
name: 'Switch 06'
output: out_06
id: switch_06
- platform: output
name: 'Switch 07'
output: out_07
id: switch_07
- platform: output
name: 'Switch 08'
output: out_08
id: switch_08
- platform: output
name: 'Switch 09'
output: out_09
id: switch_09
- platform: output
name: 'Switch 10'
output: out_10
id: switch_10
- platform: output
name: 'Switch 11'
output: out_11
id: switch_11
- platform: output
name: 'Switch 12'
output: out_12
id: switch_12
- platform: output
name: 'Switch 13'
output: out_13
id: switch_13
- platform: output
name: 'Switch 14'
output: out_14
id: switch_14
- platform: output
name: 'Switch 15'
output: out_15
id: switch_15
- platform: output
name: 'Switch 16'
output: out_16
id: switch_16
- platform: output
name: 'Switch 17'
output: out_17
id: switch_17
- platform: output
name: 'Switch 18'
output: out_18
id: switch_18
- platform: output
name: 'Switch 19'
output: out_19
id: switch_19
- platform: output
name: 'Switch 20'
output: out_20
id: switch_20
- platform: output
name: 'Switch 21'
output: out_21
id: switch_21
- platform: output
name: 'Switch 22'
output: out_22
id: switch_22
- platform: output
name: 'Switch 23'
output: out_23
id: switch_23
- platform: output
name: 'Switch 24'
output: out_24
id: switch_24
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_01
- platform: gpio
name: 'IN_02'
id: in_02
pin:
pcf8574: pcf_inputs_1to14
number: 1
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_02
- platform: gpio
name: 'IN_03'
id: in_03
pin:
pcf8574: pcf_inputs_1to14
number: 2
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_03
- platform: gpio
name: 'IN_04'
id: in_04
pin:
pcf8574: pcf_inputs_1to14
number: 3
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_04
- platform: gpio
name: 'IN_05'
id: in_05
pin:
pcf8574: pcf_inputs_1to14
number: 4
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_05
- platform: gpio
name: 'IN_06'
id: in_06
pin:
pcf8574: pcf_inputs_1to14
number: 5
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_06
- platform: gpio
name: 'IN_07'
id: in_07
pin:
pcf8574: pcf_inputs_1to14
number: 6
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_07
- platform: gpio
name: 'IN_08'
id: in_08
pin:
pcf8574: pcf_inputs_1to14
number: 8
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_08
- platform: gpio
name: 'IN_09'
id: in_09
pin:
pcf8574: pcf_inputs_1to14
number: 9
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_09
- platform: gpio
name: 'IN_10'
id: in_10
pin:
pcf8574: pcf_inputs_1to14
number: 10
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_10
- platform: gpio
name: 'IN_11'
id: in_11
pin:
pcf8574: pcf_inputs_1to14
number: 11
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_11
- platform: gpio
name: 'IN_12'
id: in_12
pin:
pcf8574: pcf_inputs_1to14
number: 12
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_12
- platform: gpio
name: 'IN_13'
id: in_13
pin:
pcf8574: pcf_inputs_1to14
number: 13
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_13
- platform: gpio
name: 'IN_14'
id: in_14
pin:
pcf8574: pcf_inputs_1to14
number: 14
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_14
- platform: gpio
name: 'IN_15'
id: in_15
pin:
pcf8574: pcf_inputs_15to28
number: 6
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_15
- platform: gpio
name: 'IN_16'
id: in_16
pin:
pcf8574: pcf_inputs_15to28
number: 5
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_16
- platform: gpio
name: 'IN_17'
id: in_17
pin:
pcf8574: pcf_inputs_15to28
number: 4
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_17
- platform: gpio
name: 'IN_18'
id: in_18
pin:
pcf8574: pcf_inputs_15to28
number: 3
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_18
- platform: gpio
name: 'IN_19'
id: in_19
pin:
pcf8574: pcf_inputs_15to28
number: 2
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_19
- platform: gpio
name: 'IN_20'
id: in_20
pin:
pcf8574: pcf_inputs_15to28
number: 1
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_20
- platform: gpio
name: 'IN_21'
id: in_21
pin:
pcf8574: pcf_inputs_15to28
number: 0
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_21
- platform: gpio
name: 'IN_22'
id: in_22
pin:
pcf8574: pcf_inputs_15to28
number: 8
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_22
- platform: gpio
name: 'IN_23'
id: in_23
pin:
pcf8574: pcf_inputs_15to28
number: 9
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_23
- platform: gpio
name: 'IN_24'
id: in_24
pin:
pcf8574: pcf_inputs_15to28
number: 10
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_24
- platform: gpio
name: 'IN_25'
id: in_25
pin:
pcf8574: pcf_inputs_15to28
number: 11
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_26'
id: in_26
pin:
pcf8574: pcf_inputs_15to28
number: 12
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_27'
id: in_27
pin:
pcf8574: pcf_inputs_15to28
number: 13
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_28'
id: in_28
pin:
pcf8574: pcf_inputs_15to28
number: 14
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_29'
id: in_29
pin:
pcf8574: pcf_inputs_28to35_menu
number: 0
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_30'
id: in_30
pin:
pcf8574: pcf_inputs_28to35_menu
number: 1
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_31'
id: in_31
pin:
pcf8574: pcf_inputs_28to35_menu
number: 2
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_32'
id: in_32
pin:
pcf8574: pcf_inputs_28to35_menu
number: 3
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_33'
pin:
pcf8574: pcf_inputs_28to35_menu
number: 4
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_34'
pin:
pcf8574: pcf_inputs_28to35_menu
number: 5
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_35'
pin:
pcf8574: pcf_inputs_28to35_menu
number: 6
mode:
input: true
inverted: true
######################
### MODBUS SECTION ###
######################
# UNCOMMENT BELOW TO USE MODBUS
# uart:
# id: uart_pin14_15
# rx_pin: GPIO14
# tx_pin: GPIO15
# baud_rate: 9600
# stop_bits: 1
# modbus:
# send_wait_time: 200ms
# uart_id: uart_pin14_15
# id: boneio_modbus
# modbus_controller:
# - id: YOURDEVICE ID
# address: 0x09
# modbus_id: mod_bus
# setup_priority: -10
# update_interval: 60s
```
### substitutions [#substitutions]
```yaml
substitutions:
name: boneio-24-sw-07
friendly_name: 'BoneIO ESP 24x16 Switches'
serial_prefix: 'esp' #Don't change it.
```
This part is mainly responsible for the name of your controller.\
You should focus on `friendly_name`. You should write the exact name of your boneIO here. The name depends on your needs.\
It could be "boneIO ESP 24x16" if you have one boneIO ESP controller, or for example, "boneIO ESP 1st-floor".
### esphome [#esphome]
```yaml
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.24x16-switches
version: '0.7'
```
There are definitions for your controller. You shouldn't change `name` or `friendly_name`. The line `name_add_mac_suffix:` will add a MAC suffix to the controller's name, which is useful for identifying your controller. `project:` is the place where you define the type and version of your controller.
### esp32 [#esp32]
```yaml
esp32:
board: nodemcu-32s
framework:
type: esp-idf
```
Definition of the ESP32 board and the required framework.
### Ethernet [#ethernet]
```yaml
ethernet:
id: eth
type: LAN8720
mdc_pin: GPIO23
mdio_pin: GPIO18
clk:
pin: GPIO0
mode: CLK_EXT_IN
phy_addr: 1
power_pin: GPIO16
```
This part is responsible for the description of your controller's Ethernet port - you shouldn't change anything here.
### dashboard\_import [#dashboard_import]
```yaml
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-24x16_switches_v0_7.yaml@latest
import_full_config: true
```
This is the place where the address for our GitHub repository is defined. The config and all additional packages are downloaded from there. There is nothing to change here.
### packages [#packages]
```yaml
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.7.1
files: [
'devices/buzzer.yaml',
'devices/serial_no.yaml',
'devices_v0_7/display.yaml',
'devices_v0_7/i2c.yaml',
'devices_v0_7-v0_9/ina219.yaml',
'devices_v0_7-v0_9/lm75b.yaml',
'devices_v0_7-v0_9/pcf_with_mcp.yaml',
'boards/24x16_output.yaml',
# 'devices_v0_7-v0_9/one_wire.yaml',
]
```
Here are definitions of all packages used by boneIO, with the address to our GitHub. One thing that might interest you is uncommenting the `# 'devices_v0_7-v0_9/one_wire.yaml'` section if you would like to use a one-wire sensor.
### logger [#logger]
```yaml
logger:
```
In case of troubleshooting, you can increase the log level to `INFO`, `WARN`, or `DEBUG`. This can be very useful in some cases.
### api [#api]
```yaml
api:
reboot_timeout: 0s
```
Here, the reboot timeout is defined for when the controller loses connection with HA.
If you want your boneIO to restart after losing connection with Home Assistant, you should enter a value that suits you here.
For WiFi connections, the value should not be zero. For LAN connections, not rebooting does not negatively affect the connection with Home Assistant in most cases.
### ota [#ota]
```yaml
ota:
- platform: esphome
- platform: web_server
```
Part responsible for Over The Air updates. The `web_server` platform allows updating via the device's web panel.
### web\_server [#web_server]
```yaml
web_server:
port: 80
local: true
version: 3
```
Part responsible for enabling the web server of the controller.
### time [#time]
```yaml
time:
- platform: homeassistant
timezone: Europe/Warsaw
id: homeassistant_time
```
This section is responsible for selecting your controller's time zone. Adjust it to your location.
### Modbus Section [#modbus-section]
```yaml
######################
### MODBUS SECTION ###
######################
# UNCOMMENT BELOW TO USE MODBUS
# uart:
# id: uart_pin14_15
# rx_pin: GPIO14
# tx_pin: GPIO15
# baud_rate: 9600
# stop_bits: 1
# modbus:
# send_wait_time: 200ms
# uart_id: uart_pin14_15
# id: boneio_modbus
# modbus_controller:
# - id: YOURDEVICE ID
# address: 0x09
# modbus_id: mod_bus
# setup_priority: -10
# update_interval: 60s
```
This section is responsible for Modbus. If you plan to use it, you should first uncomment it.\
Then, please check our Modbus tutorial: [Modbus with Esphome packages](/docs/esp/advanced/esphome-packages)
# Software setup (/en/docs/esp/products/esp_24_16/software_setup)
## You've just received your boneIO ESP! [#youve-just-received-your-boneio-esp]
Here are some steps witch will help you to handle it!
Device will come to you with alredy preinstalled ESPHome. boneIO is provided with default configuration, you need to adjust it for your needs.
Software installed on the device might be outdated. It's always good thing to update it.
Below you will find some necessary steps to start with boneiO ESP:
# Naming the Inputs (/en/docs/esp/products/esp_24_16/software_setup/naming-binary)
## Why should you name your inputs? [#why-should-you-name-your-inputs]
Naming your inputs makes working with the controller much easier. It's simpler to remember "Bedroom Button 1" than "IN\_01", right?
### Binary Sensors [#binary-sensors]
Let's look at the default configuration for your inputs, which are defined as `binary_sensor` components.
Here is a complete example of a single input configuration. The most important line for you is `name: 'My First Button'`.
```yaml twoslash lineNumbers
binary_sensor:
- platform: gpio
name: 'My First Button'
// ^? "This is the friendly name for your input"
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_press:
then:
- switch.toggle: switch_01
```
### Configuration Explained [#configuration-explained]
| Section | Description |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `binary_sensor:` | This is the main header for all your binary sensor (input) definitions. |
| `- platform: gpio` | This specifies that the sensor is connected to a General Purpose Input/Output pin. |
| `name: 'My First Button'` | This is the friendly name for your input. It will be visible in Home Assistant and is much easier to identify. You can change it to something descriptive like `'Bedroom Button 1'` or `'IN_01_Living_Room_Motion'`. This is the most important part for you to customize. |
| `id: in_01` | This is a unique identifier used within ESPHome. It's essential for referring to this input in automations, such as the `on_press` action. |
| `pin:` | This section defines the physical pin the sensor is connected to. This part is pre-configured for the boneIO hardware and should not be changed. |
| `inverted: true` | This inverts the logic of the input. It's useful for certain devices like motion sensors, which might have a normally open or normally closed state. |
| `on_press:` | This is an automation that defines what happens when the input is triggered (e.g., a button is pressed). We will cover this in more detail in the automations guide. |
# Defining Outputs (/en/docs/esp/products/esp_24_16/software_setup/naming-outputs)
## What are outputs? [#what-are-outputs]
Outputs are the executive parts of our controller.
Controlling the outputs of the boneio ESP 24x16A module
On other pages, you will find instructions for controlling the other boneio ESP modules.
## Why should you name them? [#why-should-you-name-them]
Naming your outputs will make working with the controller much easier. It's much easier to remember "Bedroom light" than "Light 01", right?
In our examples, we focus on a part of the configuration, which you can then adjust to your entire configuration.
Let's get started!
### 24x16A [#24x16a]
We have prepared a configuration file for you where all outputs are defined as switches. This is the most common use case for the 24x16A model, which is often used to control sockets or high-power devices.
Of course, you can easily change some of them to lights. We will explain how to do that!
Below is a part of the default configuration from the `boneio-24x16_switches_v0_7.yaml` file.
We are looking for the part with the `switch:` header.
```yaml
switch:
- platform: output
name: 'Switch 01'
output: out_01
id: switch_01
- platform: output
name: 'Switch 02'
output: out_02
id: switch_02
- platform: output
name: 'Switch 03'
output: out_03
id: switch_03
- platform: output
name: 'Switch 04'
output: out_04
id: switch_04
- platform: output
name: 'Switch 05'
output: out_05
id: switch_05
- platform: output
name: 'Switch 06'
output: out_06
id: switch_06
```
| Parameter | Description |
| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `- platform: output` | Defines the component type. `output` creates a basic switch entity that controls a GPIO pin. |
| `name: 'Switch 01'` | This is the friendly name for your switch. You can change it freely. There are many naming approaches. For example, you can change it to `Living_Room_Socket` or `Switch_01_Circulation_Pump`. |
| `output: out_01` | This links the switch to a specific physical relay output. |
| `id: switch_01` | This is a unique identifier used in the ESPHome configuration to control this switch from other components. |
### I'd like to get 10 lights and 14 switches! [#id-like-to-get-10-lights-and-14-switches]
You need to adjust your configuration file a little bit. It's really simple and very useful. Let's assume we want to change the first 10 switches to lights in our `boneio-24x16_switches_v0_7.yaml` file.
As you've learned, the header (`light:` or `switch:`) describes the output type. To make the change, you need to move the definitions for the first 10 outputs under a new `light:` header and change their platform from `output` to `binary`.
```yaml
# First, we define the lights
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
- platform: binary
name: 'Light 02'
output: out_02
id: light_02
# ...and so on, up to Light 10
- platform: binary
name: 'Light 10'
output: out_10
id: light_10
# Then, we define the remaining switches
switch:
- platform: output
name: 'Switch 11'
output: out_11
id: switch_11
- platform: output
name: 'Switch 12'
output: out_12
id: switch_12
# ...and so on, up to Switch 24
- platform: output
name: 'Switch 24'
output: out_24
id: switch_24
```
So what have we done? We created a `light:` section for the first 10 relays and changed their platform to `binary`. The rest of the relays (11-24) remain in the `switch:` section with the `output` platform. As a result, we have lights from relay 1 to 10 and switches from relay 11 to 24!
# Actions (/en/docs/black/products/black_cover/software_setup/actions)
## What it's all about? [#what-its-all-about]
Actions are best way to made some simple core automations inside of your controller. With them its possible to made some cricital automations
inside of your boneIO Black.
To make it easy i will give you some example and will describe it:
```yaml
- id: IN_01_living_room1
boneio_input: IN_01
actions:
single:
- action: output
pin: OUT_01_living_room_light_1
double:
- action: output
pin: OUT_02_living_room_light_2
long:
- action: output
pin: OUT_03_living_room_light_3
- id: IN_02_living_room2
boneio_input: IN_02
actions:
single:
- action: output
pin: OUT_04_living_room_light_4
long:
- action: output
pin: OUT_01_living_room_light_1
action_output: off
- action: output
pin: OUT_02_living_room_light_2
action_output: off
- action: output
pin: OUT_03_living_room_light_3
action_output: off
- action: output
pin: OUT_04_living_room_light_4
action_output: off
```
What have we achived? By using just 2 buttons we can independly turn on 4 lights, an by single long click of one of them you can turn all of them off.
In the case of `IN_01_living_room1` its really simple, we define each action fo each action type, in our case for `single` click Living room light 1
for `double` Living room light 2 and for `long` click Living room light 3. The default action for `- action: output` type its `toogle`
So by simple click of the button you will change the state of light from on to off etc.
In the case of button 2 - `IN_02_living_room2` with single click you will change state of Living room light 4. But intresting thing will happen if
you `long` click that button. That will turn off all 4 defined lights in living room. There are many possibilities with actions!
If you want to know more - please check documentation.
# Configure areas (/en/docs/black/products/black_cover/software_setup/configure-areas)
Areas are rooms or zones that group devices in Home Assistant. The area configuration in boneIO must match the configuration in Home Assistant.
With properly configured areas, you can automatically create a simple dashboard in Home Assistant divided by these areas - all devices from a given area will be automatically grouped together.
## Important information [#important-information]
**Every area name change in Home Assistant requires a name change in the boneIO application!**
Area names must be identical 1:1 with the names in Home Assistant. It's worth configuring areas carefully from the very beginning to avoid problems later.
## How to configure areas? [#how-to-configure-areas]
1. Go to the **Settings** tab
2. Find the **Areas** section
3. Click the **Add area** button or edit an existing one
4. Enter the area name **exactly the same** as in Home Assistant
5. Click **Save**
6. Wait for the application to reload
## Synchronization with Home Assistant [#synchronization-with-home-assistant]
### Before configuring in boneIO [#before-configuring-in-boneio]
1. Open Home Assistant
2. Go to **Settings** → **Areas & zones**
3. Note down the exact names of all areas (case sensitive!)
4. Use the same names in boneIO configuration
### After changing the name in Home Assistant [#after-changing-the-name-in-home-assistant]
If you change an area name in Home Assistant:
1. Open the boneIO interface
2. Go to **Settings** → **Device** → **Areas/Rooms**
3. Edit the corresponding area
4. Change the name to the new one (same as in HA)
5. Save and wait for reload
## Export and Import areas [#export-and-import-areas]
You can transfer area configuration between devices:
1. On the first device: click **Export** in the Areas section
2. Save the YAML file
3. On the second device: click **Import** in the Areas section
4. Load the saved YAML file
5. Save and wait for reload
## Best practices [#best-practices]
* **Plan ahead** - think through area names before starting configuration
* **Use simple names** - avoid special characters and diacritics
* **Be consistent** - use the same naming convention across all devices
* **Document changes** - save an export after each major change as a backup
# Configure binary sensors (/en/docs/black/products/black_cover/software_setup/configure-binary-sensors)
Binary sensors are ideal for devices with two states: motion sensors, reed switches, flood sensors, etc.
## How to add or edit a binary sensor? [#how-to-add-or-edit-a-binary-sensor]
1. Go to **Settings** → **Control** → **Local Inputs**
2. Click **Add New** or the edit icon next to an existing sensor
3. Fill in the configuration form
## Basic settings [#basic-settings]
### Display Name [#display-name]
Friendly name for the sensor, e.g.:
* `Living Room Motion Sensor`
* `Front Door`
* `Bedroom Window`
This name will be visible in the interface and Home Assistant.
### BoneIO Input [#boneio-input]
Select the physical input from the dropdown:
* `IN_01`, `IN_02`, `IN_03`, ... `IN_56` (depending on model)
**Avoid inputs with limitations** (IN\_01, IN\_02, IN\_09, IN\_10, IN\_19, IN\_20, IN\_21, IN\_29–IN\_34) for reed switches and motion sensors that may be active at controller startup.
### Area / Room [#area--room]
Select an area from the dropdown - the sensor will be automatically assigned to this area in Home Assistant.
### Bounce Time [#bounce-time]
Contact debounce time (default: 120ms). For motion sensors and reed switches, usually no change is needed.
### Device Class [#device-class]
Device class in Home Assistant - affects icon and behavior:
| Device Class | Icon | Use Case |
| ------------- | --------- | ----------------------- |
| **motion** | Motion | Motion sensors |
| **door** | Door | Door reed switches |
| **window** | Window | Window reed switches |
| **opening** | Opening | General opening sensors |
| **moisture** | Water | Flood sensors |
| **smoke** | Smoke | Smoke detectors |
| **gas** | Gas | Gas detectors |
| **occupancy** | Occupancy | Occupancy sensors |
| **vibration** | Vibration | Vibration sensors |
| **tamper** | Tamper | Tamper sensors |
## Options [#options]
### Show in HA [#show-in-ha]
Enable to make the sensor visible in Home Assistant (enabled by default).
### Inverted [#inverted]
Invert sensor logic:
* Normal: active input = sensor ON
* Inverted: active input = sensor OFF
Useful when a reed switch is mounted in reverse.
### Initial Send [#initial-send]
Send sensor state at controller startup.
## Actions - Pressed and Released [#actions---pressed-and-released]
Binary sensors have two action tabs:
### Pressed [#pressed]
Actions executed when the sensor changes to active state (e.g., motion detected, door opened).
### Released [#released]
Actions executed when the sensor changes to inactive state (e.g., no motion, door closed).
## How to add an action? [#how-to-add-an-action]
1. Go to the **Pressed** or **Released** tab
2. Click **Add Action**
3. Select the action type and configure parameters
### Action types [#action-types]
| Action Type | Description |
| ---------------------- | -------------------------------------- |
| **output** | Control an output (light, switch) |
| **cover** | Control a cover |
| **virtual\_switch** | Set a virtual switch (ON, OFF, TOGGLE) |
| **mqtt** | Send an MQTT message |
| **output\_over\_mqtt** | Control an output via MQTT |
| **cover\_over\_mqtt** | Control a cover via MQTT |
| **remote\_output** | Control an output on a remote device |
| **remote\_cover** | Control a cover on a remote device |
Every action can also have conditions (time, date, state, sun) and, on binary sensors, a delay. The full list of types, values and options is in [Actions](/en/docs/black/current/configuration/event#actions).
## Configuration examples [#configuration-examples]
### Example 1: Hallway motion sensor [#example-1-hallway-motion-sensor]
1. **Display Name**: `Hallway Motion Sensor`
2. **BoneIO Input**: `IN_05` (avoid inputs with limitations)
3. **Area / Room**: `Hallway`
4. **Device Class**: `motion`
**Actions:**
* **Pressed**: ON `Hallway Light`
* **Released**: OFF `Hallway Light`
### Example 2: Front door reed switch [#example-2-front-door-reed-switch]
1. **Display Name**: `Front Door`
2. **BoneIO Input**: `IN_06`
3. **Area / Room**: `Entrance`
4. **Device Class**: `door`
5. **Inverted**: ✅ (if reed switch shows reversed)
No actions - just state monitoring in Home Assistant.
### Example 3: Flood sensor [#example-3-flood-sensor]
1. **Display Name**: `Bathroom Flood Sensor`
2. **BoneIO Input**: `IN_07`
3. **Area / Room**: `Bathroom`
4. **Device Class**: `moisture`
**Actions:**
* **Pressed**: OFF `Main Water Valve` (automatic valve closure when water detected)
After saving, the sensor will appear in the table and be available in Home Assistant with the appropriate icon and device class.
# Configure covers (/en/docs/black/products/black_cover/software_setup/configure-covers)
The boneIO Black Cover controller allows configuration of **8 covers or blinds**. Each cover can operate as a regular cover (TIME\_BASED) or a venetian blind with tilt function (VENETIAN).
## How to add or edit a cover? [#how-to-add-or-edit-a-cover]
1. Go to **Settings** → **Control** → **Covers**
2. Click **Add New** or the edit icon next to an existing cover
3. Fill in the configuration form
## Basic settings [#basic-settings]
### Display Name [#display-name]
Friendly name for the cover, e.g.:
* `Living Room Cover`
* `Bedroom Blind`
* `Terrace Awning`
This name will be visible in the interface and Home Assistant.
### Custom ID [#custom-id]
Technical ID of the cover (optional):
* If not provided, it will be auto-generated as `cover_{open_relay}_{close_relay}`
* Only lowercase letters, numbers, and underscores
* Example: `living_room_cover`
**We do not recommend changing the cover ID** after it has been created. Changing the ID will cause loss of history in Home Assistant and require reconfiguration of automations.
### Area / Room [#area--room]
Select an area from the dropdown - the cover will be automatically assigned to this area in Home Assistant.
### Platform [#platform]
Select the cover type:
| Platform | Description | Use Case |
| --------------- | --------------------------------- | --------------------------------- |
| **TIME\_BASED** | Regular time-controlled cover | Covers, awnings, curtains |
| **VENETIAN** | Venetian blind with tilt function | Blinds with adjustable slat angle |
**TIME\_BASED** is the most popular choice for regular covers. Choose **VENETIAN** only if you have blinds with adjustable slat angle (tilt).
### Open Relay [#open-relay]
Select the output responsible for opening (up):
* `cover_01_up`, `cover_02_up`, ... `cover_08_up`
### Close Relay [#close-relay]
Select the output responsible for closing (down):
* `cover_01_down`, `cover_02_down`, ... `cover_08_down`
**Make sure you select a pair of relays for the same cover!** E.g., for cover 1: `cover_01_up` and `cover_01_down`.
### Open Time [#open-time]
Time required for full opening of the cover, e.g.:
* `30s` - 30 seconds
* `45s` - 45 seconds
* `1m` - 1 minute
**Minimum: 1 second**
### Close Time [#close-time]
Time required for full closing of the cover, e.g.:
* `30s` - 30 seconds
* `45s` - 45 seconds
**Minimum: 1 second**
**How to measure time?** Use a stopwatch and measure how long it takes for full opening/closing of the cover. Add 1-2 seconds margin.
### Tilt Duration (VENETIAN only) [#tilt-duration-venetian-only]
Time required for full slat rotation (venetian blinds only), e.g.:
* `500ms` - 500 milliseconds
* `1s` - 1 second
**Minimum: 10 milliseconds**
This field appears only when you select **VENETIAN** platform.
## Advanced settings [#advanced-settings]
Click the **Advanced Settings** tab to access additional options:
### Device Class [#device-class]
Device type in Home Assistant (affects icon):
| Device Class | Icon | Use Case |
| ------------ | ------- | ------------------- |
| **window** | Window | Windows |
| **blind** | Blind | Blinds |
| **curtain** | Curtain | Curtains, drapes |
| **shutter** | Shutter | External shutters |
| **awning** | Awning | Awnings |
| **garage** | Garage | Garage doors |
| **gate** | Gate | Entry gates |
| **shade** | Shade | Sun shades |
| **door** | Door | Doors |
| **damper** | Damper | Ventilation dampers |
### Other advanced options [#other-advanced-options]
* **Restore State** - restore state after restart
* **Show in HA** - visibility in Home Assistant
* **Other parameters** - platform-dependent
## Configuration examples [#configuration-examples]
### Example 1: Regular cover in living room [#example-1-regular-cover-in-living-room]
1. **Display Name**: `Living Room Cover`
2. **Area / Room**: `Living Room`
3. **Platform**: `TIME_BASED`
4. **Open Relay**: `cover_01_up`
5. **Close Relay**: `cover_01_down`
6. **Open Time**: `30s`
7. **Close Time**: `30s`
8. **Device Class**: `shutter`
### Example 2: Venetian blind in bedroom [#example-2-venetian-blind-in-bedroom]
1. **Display Name**: `Bedroom Blind`
2. **Area / Room**: `Bedroom`
3. **Platform**: `VENETIAN`
4. **Open Relay**: `cover_02_up`
5. **Close Relay**: `cover_02_down`
6. **Open Time**: `25s`
7. **Close Time**: `25s`
8. **Tilt Duration**: `800ms`
9. **Device Class**: `blind`
After saving, the covers will appear in the table and be available in Home Assistant in the corresponding areas.
# Configure events (/en/docs/black/products/black_cover/software_setup/configure-events)
Events allow you to assign different actions to a single button depending on the click type.
## How to add or edit an event? [#how-to-add-or-edit-an-event]
1. Go to **Settings** → **Control** → **Local Inputs**
2. Click **Add New** or the edit icon next to an existing event
3. Fill in the configuration form
## Basic settings [#basic-settings]
### Display Name [#display-name]
Friendly name for the event, e.g.:
* `Living Room Button`
* `Bedroom Switch`
* `Doorbell`
This name will be visible in the interface and Home Assistant.
### BoneIO Input [#boneio-input]
Select the physical input from the dropdown:
* `IN_01`, `IN_02`, `IN_03`, ... `IN_56` (depending on model)
Inputs already used by other events or binary sensors are automatically hidden from the list.
### Area / Room [#area--room]
Select an area from the dropdown - the event will be automatically assigned to this area in Home Assistant.
## Actions - click tabs [#actions---click-tabs]
The form has separate tabs for each click type:
### Single (Single click) [#single-single-click]
Actions executed after a single button click.
### Double (Double click) [#double-double-click]
Actions executed after a quick double click.
### Triple (Triple click) [#triple-triple-click]
Actions executed after a triple click.
Triple click must be enabled in advanced settings (disabled by default).
### Long (Long press) [#long-long-press]
Actions executed after holding the button for a specified time.
## How to add an action? [#how-to-add-an-action]
1. Go to the appropriate tab (Single, Double, Triple, Long)
2. Click **Add Action**
3. Select the action type and configure parameters
### Action types [#action-types]
| Action Type | Description |
| ---------------------- | -------------------------------------- |
| **output** | Control an output (light, switch) |
| **cover** | Control a cover |
| **virtual\_switch** | Set a virtual switch (ON, OFF, TOGGLE) |
| **mqtt** | Send an MQTT message |
| **output\_over\_mqtt** | Control an output via MQTT |
| **cover\_over\_mqtt** | Control a cover via MQTT |
| **remote\_output** | Control an output on a remote device |
| **remote\_cover** | Control a cover on a remote device |
Every action can also have conditions (time, date, state, sun). The full list of types, values and options is in [Actions](/en/docs/black/current/configuration/event#actions).
### Output action [#output-action]
The most commonly used action - control an output:
| Parameter | Description |
| ---------- | --------------------------------------------- |
| **Output** | Select output from the list |
| **Action** | TOGGLE (toggle), ON (turn on), OFF (turn off) |
### Cover action [#cover-action]
Control a cover:
| Parameter | Description |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Cover** | Select cover from the list |
| **Action** | TOGGLE, OPEN, CLOSE, STOP, TOGGLE\_OPEN, TOGGLE\_CLOSE, SMART\_TOGGLE; for venetian blinds also TILT, TILT\_OPEN, TILT\_CLOSE |
## Sequences [#sequences]
Sequences are advanced click combinations:
| Sequence | Description |
| ------------------- | ------------------------- |
| **Double → Long** | Double click, then hold |
| **Single → Long** | Single click, then hold |
| **Double → Single** | Double click, then single |
Each sequence can have its own actions and optionally send an MQTT event.
## Advanced settings [#advanced-settings]
Click the **Advanced Settings** tab to access additional options:
### Bounce Time [#bounce-time]
Contact debounce time (default: 30ms). Increase if the button generates false clicks.
### Double Click Duration [#double-click-duration]
Maximum time between clicks for a double click (default: 220ms).
This parameter affects single click delay - the controller waits this time to check if a second click will follow.
### Long Press Duration [#long-press-duration]
Hold time for a long click (default: 400ms).
### Sequence Window Duration [#sequence-window-duration]
Time window for sequences (default: 500ms).
### Sequence Mode [#sequence-mode]
| Mode | Description |
| ------------- | ---------------------------------------------- |
| **Immediate** | Actions executed immediately upon detection |
| **Exclusive** | Waits for sequence completion before executing |
### Enable Triple Click [#enable-triple-click]
Enable triple click support (disabled by default).
## Configuration example [#configuration-example]
**Scenario**: A button in the living room controlling lighting.
1. **Display Name**: `Living Room Button`
2. **BoneIO Input**: `IN_04`
3. **Area / Room**: `Living Room`
**Actions:**
* **Single**: Toggle `Living Room Main Light`
* **Double**: Toggle `Living Room Lamp`
* **Long**: OFF `Living Room Main Light`, OFF `Living Room Lamp` (turn off everything)
After saving, the event will appear in the table and be available in Home Assistant.
# Edit configuration (/en/docs/black/products/black_cover/software_setup/edit-configuration)
The **Settings** tab contains forms for configuring all controller functions. Here you can configure outputs, inputs, areas, events, and many other options.
## Important configuration rules [#important-configuration-rules]
### Saving changes [#saving-changes]
**Each edit in a given section requires saving and waiting for reload or restart of the application before you start working on the next section.**
After saving changes:
1. Click the **Save** button in the given section
2. Wait for save confirmation
3. Wait for the application to reload or restart
4. Only then proceed to edit the next section
### Export and Import [#export-and-import]
Each configuration section has **Export** and **Import** buttons:
* **Export** - saves the configuration of the given section to a YAML file
* **Import** - loads the configuration from a YAML file
This allows you to:
* Manually copy configuration sections
* Transfer created configurations between devices
* Create backups of individual sections
## Configuration sections [#configuration-sections]
In the Settings tab you will find the following sections:
* **Areas** - defining areas compatible with Home Assistant
* **Outputs** - relay output configuration
* **Covers** - cover and blind configuration
* **Inputs** - digital input configuration
* **Events** - event and automation definitions
* **Binary Sensors** - binary sensor configuration
* **Actions** - action definitions
* And more...
# Events and Binary Sensors (/en/docs/black/products/black_cover/software_setup/events-and-binary-sensors)
In boneIO Black you have two types of inputs to choose from: **Events** and **Binary Sensors**. The choice depends on what device you're connecting.
## Events - for buttons [#events---for-buttons]
Events are the best choice for **wall switches**. They allow detection of different click types:
| Click Type | Description |
| ------------- | ---------------------------------- |
| **Single** | Single click |
| **Double** | Double click |
| **Triple** | Triple click |
| **Long** | Long press |
| **Sequences** | Combinations (e.g., double → long) |
**Example**: One button can turn on the main light (single), bedside lamp (double), and turn off all lights (long).
**Events have a minimal delay** for single clicks. The controller waits a short time (\~220ms) to check if another click will follow (double/triple). If you need immediate response, use a binary sensor.
## Binary Sensors - for sensors [#binary-sensors---for-sensors]
Binary sensors are the best choice for devices with two states:
| Device | States |
| ------------------ | --------------------------- |
| **Motion sensor** | Motion detected / No motion |
| **Reed switch** | Open / Closed |
| **Flood sensor** | Dry / Wet |
| **Smoke detector** | OK / Alarm |
**Advantages of binary sensors:**
* ✅ Immediate response (no delay)
* ✅ Actions on press (pressed) and release (released)
* ✅ Different device classes (motion, door, window, smoke, etc.)
## Which to choose? [#which-to-choose]
| Device | Input Type |
| ------------------------- | ------------------------------ |
| Wall switch | **Event** |
| Doorbell | **Event** or **Binary Sensor** |
| Motion sensor | **Binary Sensor** |
| Reed switch (door/window) | **Binary Sensor** |
| Flood sensor | **Binary Sensor** |
| Smoke detector | **Binary Sensor** |
## Input limitations [#input-limitations]
Some inputs on boneIO Black **cannot be active at controller startup**. We do not recommend connecting reed switches or motion sensors to them, as they may be active during startup.
| Inputs with limitations |
| ---------------------------------------------- |
| IN\_01, IN\_02 |
| IN\_09, IN\_10 |
| IN\_19, IN\_20, IN\_21 |
| IN\_29, IN\_30, IN\_31, IN\_32, IN\_33, IN\_34 |
For reed switches and motion sensors, use the remaining inputs (IN\_03 to IN\_08, IN\_11 to IN\_18, IN\_22 to IN\_28, and IN\_35 onwards).
# Events vs Binary Sensors (/en/docs/black/products/black_cover/software_setup/events-vs-binary-sensors)
In boneIO Black you have two types of inputs to choose from: **Events** and **Binary Sensors**. The choice depends on what device you're connecting.
## Events - for buttons [#events---for-buttons]
Events are the best choice for **wall switches**. They allow detection of different click types:
| Click Type | Description |
| ------------- | ---------------------------------- |
| **Single** | Single click |
| **Double** | Double click |
| **Triple** | Triple click |
| **Long** | Long press |
| **Sequences** | Combinations (e.g., double → long) |
**Example**: One button can turn on the main light (single), bedside lamp (double), and turn off all lights (long).
**Events have a minimal delay** for single clicks. The controller waits a short time (\~220ms) to check if another click will follow (double/triple). If you need immediate response, use a binary sensor.
## Binary Sensors - for sensors [#binary-sensors---for-sensors]
Binary sensors are the best choice for devices with two states:
| Device | States |
| ------------------ | --------------------------- |
| **Motion sensor** | Motion detected / No motion |
| **Reed switch** | Open / Closed |
| **Flood sensor** | Dry / Wet |
| **Smoke detector** | OK / Alarm |
**Advantages of binary sensors:**
* ✅ Immediate response (no delay)
* ✅ Actions on press (pressed) and release (released)
* ✅ Different device classes (motion, door, window, smoke, etc.)
## Which to choose? [#which-to-choose]
| Device | Input Type |
| ------------------------- | ------------------------------ |
| Wall switch | **Event** |
| Doorbell | **Event** or **Binary Sensor** |
| Motion sensor | **Binary Sensor** |
| Reed switch (door/window) | **Binary Sensor** |
| Flood sensor | **Binary Sensor** |
| Smoke detector | **Binary Sensor** |
## Input limitations [#input-limitations]
Some inputs on boneIO Black **cannot be active at controller startup**. We do not recommend connecting reed switches or motion sensors to them, as they may be active during startup.
| Inputs with limitations |
| ---------------------------------------------- |
| IN\_01, IN\_02 |
| IN\_09, IN\_10 |
| IN\_19, IN\_20, IN\_21 |
| IN\_29, IN\_30, IN\_31, IN\_32, IN\_33, IN\_34 |
For reed switches and motion sensors, use the remaining inputs (IN\_03 to IN\_08, IN\_11 to IN\_18, IN\_22 to IN\_28, and IN\_35 onwards).
# First-time setup (/en/docs/black/products/black_cover/software_setup/first-run-wizard)
The first time you open the panel of a new controller, you do not see the panel yet but the **First-time setup** wizard.
It creates the administrator account — the username and password you will sign in with from now on — and helps you get going.
The whole wizard takes a few minutes.
There is no way to skip the wizard. Until it is completed, the controller answers nothing except the wizard itself, so nobody can
change its configuration without a password.
The bar at the top shows how far you are (**Step 2 of 6**, for example). Not every controller sees every step:
| Step | When you see it |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| Start | Always. |
| Account | Always. |
| Which controller is this? | Only if the controller does not yet know which model it is. |
| Import | Only on a controller that still has its factory configuration. |
| Devices | Only on a controller that still has its factory configuration, and only if you did not import a backup. |
| Cloud | Only if boneIO Cloud registration is not already on, and only if you did not import a backup. |
| Done | Always. |
## Start [#start]
The wizard explains that the device has no administrator account yet, and under **What's ahead** lists the steps this controller will go through.
Click **Get started**.
## Account [#account]
Choose the **Username** and **Password** for the panel and type the password again under **Confirm password**.
* the password must be **at least 8 characters** long,
* it must **not contain the username** — the username is visible on the sign-in screen, so a password built from it is easy to guess.
Click **Create account**. From here on there is no way back to this step — the account exists.
The same account also opens the **Node-RED** editor: Node-RED has no accounts of its own, and only panel administrators get in.
**This password is also your SSH password.** On a new controller the wizard sets the same password for the `boneio` user.
Over SSH you always log in as `boneio` (for example `ssh boneio@192.168.1.100`) — the username you typed here is for the panel only.
This happens only once: changing the panel password later does not change the SSH password. For that, use the
[SSH login password](/en/docs/black/current/basic/accounts#ssh-login-password) card in **Settings → Access → User accounts**, or run `passwd` over SSH.
Write the password down somewhere safe.
## Which controller is this? [#which-controller-is-this]
You only see this step if the controller was not told at the factory which model it is. Until you answer, it has no outputs configured.
Pick your model — **32x10A**, **24x16A**, **Cover** or **Cover Mix** — and click **Apply**.
The controller restarts with that model's configuration, which takes up to a minute; the wizard waits and then carries on by itself.
The wizard does not come back to this step, so check the label on the controller first.
{/* SCREENSHOT: en_wizard_board.webp — "Which controller is this?" step with the four models */}
## Import (optional) [#import-optional]
If you are replacing an older boneIO and have a configuration backup from it (a `.tar.gz` file downloaded from
**Settings → Maintenance → Backups** on the old device), drop the file on **Choose a file or drag it here**, or click it to pick the file,
then click **Import configuration**. The controller will take over that configuration after a restart.
Setting up from scratch? Click **Skip**.
If you imported a backup, the Devices and Cloud steps are skipped — the imported configuration already decides them.
## Devices [#devices]
The outputs are already set up for your model. Here you decide what the inputs should do with them:
* **Inputs control outputs** — each input switches one output (a push button turns on a light),
* **Inputs control covers** — pairs of inputs open and close covers,
* **Inputs control covers and outputs** — a mix, on models that have both,
* **Wire nothing — I will do it myself** — leave the inputs empty and configure them later.
Leave **Restore relay and cover state after a restart** on (it is by default) if lights and covers should come back to where they were after a power cut.
Click **Apply**, or **Skip** to leave everything as it is. You can change all of it later in **Settings → Control → Local Inputs**.
## Cloud (optional) [#cloud-optional]
You can register the controller with **boneIO Cloud**. It then gets its own address with a trusted certificate — the browser stops
warning about the connection, and you can install the panel as an app on your phone.
* Registration sends the controller's serial number to boneIO Cloud.
* The controller is still reachable **only on your own network** — nothing is exposed to the internet.
* Your router must not block so-called *DNS rebinding*; if the new address does not open, that is usually the reason.
Click **Enable registration**, or **Skip**. You can turn it on later in **Settings → Access → Web Server**.
After **Enable registration** the controller restarts its HTTPS server with the new certificate. The wizard shows
**Switching the HTTPS server** and holds **Next** while it waits — usually about half a minute, at most three minutes. There is nothing to do, the controller keeps running.
When it is ready, the notice gives you the new address as a link.
If the controller does not know its own network address yet, the wizard says **Registration is saved** instead:
registration starts on the next boot.
## Done [#done]
The wizard confirms **The controller has an owner**, names the account it created, and reminds you that Node-RED takes the same login.
It also says what happened to the SSH password. If it says **The SSH password could not be set**,
SSH login with a password stays closed — contact us on Discord.
How you leave depends on the Cloud step:
* **Without cloud registration**, click **Go to the panel**.
* **With cloud registration**, click **Go to blk….black.boneio.app:8443**. The panel opens at its new address in a new tab.
Sign in there once more with the same password — the browser keeps sign-ins separately for each address.
**Stay at this address** keeps you where you are.
* **If the new address did not answer** (usually DNS rebinding protection on the router), the wizard says so and offers
**Open blk….black.boneio.app:8443 anyway**. The panel keeps working at the current address.
If you imported a configuration or clicked **Apply** in Devices, restart the controller once:
**Settings → Maintenance → Restart and shutdown**. Until then the controller still runs the old configuration.
## Updating from version 1.5? [#updating-from-version-15]
A controller that was already configured before sees a **shorter wizard: Start → Account → Cloud → Done**.
The Cloud step is left out too if cloud registration was already on.
If the 1.5 panel already had a password (`web.auth` in `config.yaml`), there is no wizard at all — sign in with that password.
The wizard only creates the account — your outputs, inputs and actions stay exactly as they were.
If the SSH password of the `boneio` user was still the factory `Black`, the wizard replaces it with your new password too;
if you had already changed it, it is left alone and the wizard says so.
See [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6) for the rest of the checklist.
## Forgot the password? [#forgot-the-password]
Log in over SSH and reset it — see [Accounts and access](/en/docs/black/current/basic/accounts#forgotten-password).
## What's next? [#whats-next]
* [Home Assistant connection](./home-assistant-connection) - connect the controller to Home Assistant
* [Interface navigation](./interface-navigation) - learn about the menu and tabs
* [Accounts and access](/en/docs/black/current/basic/accounts) - add a read-only account for the rest of the household
# Home Assistant Connection (/en/docs/black/products/black_cover/software_setup/home-assistant-connection)
The boneIO Black controller communicates with Home Assistant via the MQTT protocol. There are two configuration methods: using a local broker or a remote one (located on HA itself).
Additionally, to make managing the controller from Home Assistant easier, we have prepared a special Add-on for you, which gives you instant access to your boneIO.
## Option 1: MQTT Broker on boneIO Black (default) [#option-1-mqtt-broker-on-boneio-black-default]
**This is the easiest way** - the controller has a built-in Mosquitto MQTT broker that is already configured and running.
### Default configuration [#default-configuration]
By default, the controller is connected to the local MQTT broker:
* **Host**: `localhost`
* **Port**: `1883`
* **Username**: `boneio`
* **Topics**: `boneio/` — set automatically
The broker has three accounts: `boneio` (the one the controller itself uses), `homeassistant` and `mqtt` (for your integrations).
On a controller installed with version 1.6 or later **each account has its own random password**, different on every device — there is no shared default password any more.
That means before you connect Home Assistant you **set a password you know** for the `homeassistant` account.
**Set the MQTT password first.** Go to **Settings** → **Services on this controller** → **MQTT broker (local)**,
in the `homeassistant` card type the new password twice (at least 8 characters) and click **Change Password**.
This is the password you will type into Home Assistant below.
If you change the password of the `boneio` user, leave **Also update boneIO's own configuration** switched on —
the controller then saves the new password in its own configuration and reconnects on its own.
Without it, the controller keeps using the old password and goes offline.
### Connecting Home Assistant to the broker on boneIO [#connecting-home-assistant-to-the-broker-on-boneio]
1. **No Mosquitto add-on needed** — with this option the broker already runs on the controller,
so in Home Assistant you only add the MQTT integration.
2. **Add MQTT integration in Home Assistant**:
* Go to **Settings** → **Devices & Services**
* Click **Add Integration** → search for **MQTT**
* Enter the details:
* **Broker**: boneIO controller IP (e.g., `192.168.1.100`)
* **Port**: `1883`
* **Username**: `homeassistant`
* **Password**: the password you just set for `homeassistant`
* Click **Submit**
Every step with Home Assistant screenshots is in [Connecting boneIO Black](/en/docs/home-assistant/boneio-black) in the Home Assistant guide.
3. **Automatic discovery**:
* The boneIO controller will automatically register all devices with Home Assistant
* Devices will appear in **Settings** → **Devices & Services** → **MQTT**
### Encrypting Home Assistant's connection (TLS) [#encrypting-home-assistants-connection-tls]
Optional. By default Home Assistant talks to the broker on boneIO in plain text on port 1883, password included.
On your own home network that is often fine. If the network is shared, or the traffic crosses a VPN, have the broker accept encrypted connections on port **8883**.
Go to **Settings** → **Services on this controller** → **MQTT broker (local)** and scroll to the **Broker encryption (TLS)** card, below the accounts.
1. **Get a certificate.** Click **Make a certificate on this controller**. It is valid for ten years and covers the controller's names, listed under **Valid for**.
Then click **Download the CA (ca.crt) for clients** — Home Assistant needs that file.
If you would rather use your own certificate, open **Upload my own certificate** (the page shows the openssl commands under **How to make certificates with openssl**).
2. **Pick a mode** under **Mode**:
* **Off** — plain MQTT on port 1883 only, as before.
* **TLS beside plain** — TLS on 8883, and 1883 keeps working. Start here.
* **TLS only on the network** — from the network only TLS on 8883. Plain 1883 stays only for programs on the controller itself, boneIO included.
3. **Move Home Assistant to TLS.** In the MQTT integration, choose **Reconfigure**, set port **8883**, open the advanced options,
enable certificate validation with a custom broker certificate and upload `ca.crt`.
As the broker address use the controller's name exactly as it appears under **Valid for**, for example `boneio-1234.local`.
An IP address works only if it is on that list, and an address from DHCP can change.
4. Once Home Assistant and everything else connects on 8883, switch to **TLS only on the network** if you want plain MQTT closed to the network.
**What it costs:**
* **Every mode change restarts the broker**, which briefly disconnects everyone, Home Assistant included. If the broker does not come back with the new settings, the panel puts the previous ones back and says so.
* **TLS only on the network** cuts off anything still on port 1883 from another machine until you move it to 8883. The panel refuses this mode while boneIO itself connects to this broker in plain text by the controller's network address: first set boneIO's MQTT host to `localhost`, or turn on TLS for its own connection.
* **Node-RED on the controller** reaches the broker from Docker's network, not from `localhost`. Before **TLS only on the network**, move its broker node to port 8883 with TLS and `ca.crt`.
* **A new certificate means a new CA.** Every client that trusts the current `ca.crt` must be given the new one, or it refuses the broker.
If the card says this controller's system helper does not manage the broker's TLS yet, go to **Settings** → **System migrations**,
click **Apply pending migrations** and come back.
## Option 2: MQTT Broker on Home Assistant [#option-2-mqtt-broker-on-home-assistant]
You can connect the controller to an MQTT broker located on Home Assistant or another device.
### Configuring the broker in Home Assistant [#configuring-the-broker-in-home-assistant]
1. **Install Mosquitto Broker** (if you don't have it yet):
* Go to **Settings** → **Apps** → **Install app**
* Search for **Mosquitto broker**
* Click **Install** and **Start**
2. **Create an MQTT user**:
* Go to **Settings** → **People** → **Users**
* Click **Add User**
* Fill in the details:
* **Name**: `boneio`
* **Username**: `boneio`
* **Password**: choose a secure password
* Click **Create**
3. **Add MQTT integration** (if you don't have it yet):
* Go to **Settings** → **Devices & Services**
* MQTT should be automatically detected
* If not, click **Add Integration** → **MQTT**
### Configuring MQTT in boneIO controller [#configuring-mqtt-in-boneio-controller]
1. Go to **Settings** → **Connections** → **MQTT**
2. Enter the broker details:
* **Host**: Home Assistant IP (e.g., `192.168.1.50`)
* **Port**: `1883`
* **Username**: `boneio`
* **Password**: password of the created user
3. Click **Save**. A change of only these four fields needs no restart: boneIO reconnects to the new broker straight away
4. Devices will automatically appear in Home Assistant
If that broker accepts TLS, switch on **Encrypt the connection (TLS)** on the same page.
See [Encryption (TLS)](/en/docs/black/current/configuration/communication#encryption-tls).
### Installation of the boneIO Home Assistant Add-on [#installation-of-the-boneio-home-assistant-add-on]
1. Go to **Settings** → **Apps** → **Install app**
2. Click the three dots in the top right corner
3. Select Repositories
4. Add this URL: [https://github.com/boneio-eu/home-assistant-addons](https://github.com/boneio-eu/home-assistant-addons)
5. Click Add
6. Find the desired add-on and click Install
## Communication between boneIO controllers [#communication-between-boneio-controllers]
If you have multiple boneIO Black controllers and want them to execute commands on each other (e.g., a button on one controller turns on a light on another), **all controllers must be connected to the same MQTT broker**.
### Example configuration for multiple controllers: [#example-configuration-for-multiple-controllers]
1. Choose one MQTT broker (e.g., on Home Assistant or on one of the controllers)
2. Connect all controllers to the same broker
3. Each controller publishes under its own serial number (`boneio/blk…`), so there is nothing to set to keep them apart
4. In actions, you can use **Control Remote Output** and **Control Remote Cover** to control devices on other controllers
## Connection verification [#connection-verification]
After proper configuration:
1. In Home Assistant, go to **Settings** → **Devices & Services** → **MQTT**
2. You should see the **boneIO Black** device with all configured outputs, covers, inputs, and sensors
3. All entities will be automatically available in Home Assistant
The controller uses **MQTT Discovery** - all devices are automatically detected by Home Assistant without the need for manual configuration.
# How to Connect (/en/docs/black/products/black_cover/software_setup/how-to-connect)
After connecting your controller to the local network, you can access the boneIO web interface through a web browser. This is the most convenient way to configure and monitor your controller.
## Prerequisites [#prerequisites]
* boneIO controller connected to local network via Ethernet cable
* Network with DHCP service enabled (enabled by default on most routers)
* Computer or mobile device on the same local network
* Web browser (Chrome, Firefox, Safari, Edge)
## Step 1: Connect the controller to the network [#step-1-connect-the-controller-to-the-network]
1. Connect an Ethernet cable to the network port of your boneIO controller
2. Connect the other end of the cable to your router or switch
3. Make sure the controller is powered on
The controller will automatically receive an IP address from the DHCP server on your network.
## Step 2: Find the controller's IP address [#step-2-find-the-controllers-ip-address]
There are two ways to find the controller's IP address:
### Option A: Display on the controller [#option-a-display-on-the-controller]
Press the button next to the display on the controller to scroll through the screens:
* the **network** screen shows the controller's **IP address** (plus the network mask and MAC address),
* the **last screen** shows a **QR code** — scan it with your phone and the panel opens straight away, at the right `https://…:8443` address
(or at the controller's own boneIO Cloud address, if you registered it; on a controller upgraded from 1.5 it is `http://…:8090` until you move the panel behind the proxy).
{/* SCREENSHOT: oled_network.webp — photo of the OLED network screen with the IP address */}
{/* SCREENSHOT: oled_qr.webp — photo of the OLED QR code screen */}
Which screens are shown is set in **Settings** → **Device** → **OLED Display**. Both are on in the factory configuration.
### Option B: Router admin panel [#option-b-router-admin-panel]
Log in to your router's admin panel and find the list of connected devices. The boneIO controller will be visible under a name corresponding to its serial number, starting with `blk`, e.g., `blk8c7df0`.
## Step 3: Open the web interface [#step-3-open-the-web-interface]
1. Open a web browser
2. In the address bar, type the controller's IP address with port 8443, e.g., `https://192.168.1.100:8443`
3. Press Enter
Always type `https://` at the start — without it the page will not open.
### The browser warns about the connection — this is expected [#the-browser-warns-about-the-connection--this-is-expected]
The first time you open the panel, the browser shows a warning such as **"Your connection is not private"**.
The connection **is** encrypted; the browser only warns because the certificate was issued by the controller itself,
not by a company the browser knows.
* **Chrome / Edge**: click **Advanced**, then **Proceed to 192.168.1.100 (unsafe)**
* **Firefox**: click **Advanced…**, then **Accept the Risk and Continue**
* **Safari**: click **Show Details**, then **visit this website**
The controller's certificate is valid for six months, so the browser does not ask again every day.
To get rid of the warning for good, see [HTTPS certificate](/en/docs/black/current/advanced/certificate).
## Step 4: Create your administrator account [#step-4-create-your-administrator-account]
A new controller has no owner yet. Instead of the panel you will see the **First-time setup** wizard.
Until the account exists, the controller's display says so: it shows **Setup required**, **Onboarding needed.**,
**Open in a browser:** and the panel's address. The display does not go dark while that notice is up, and the address
appears as soon as the controller gets one from the router (until then the line reads `http://:8090`, which is only a placeholder). The button still steps through the other screens;
after a minute the notice comes back. Once the account is created, the notice goes away by itself within a few seconds.
{/* SCREENSHOT: oled_setup_required.webp — photo of the OLED showing "Setup required" with the panel address */}
For a moment right at power-on, before that notice, the display may show `SETUP REQUIRED - open :8090` —
ignore the port there and use the address from the notice, or `https://…:8443`.
In the wizard you choose a username and password for the panel. It takes about a minute — see
[First-time setup](./first-run-wizard) for every step.
Do this right away. Until an account exists, **whoever on your network completes the wizard first becomes the owner** of the controller.
After the wizard you land in the main panel showing the controller status.
## Troubleshooting [#troubleshooting]
### I can't find the IP address [#i-cant-find-the-ip-address]
* Make sure the Ethernet cable is properly connected
* Check if the network LED on the controller is lit or blinking
* Restart the controller and wait about 30 seconds to obtain an IP address
### The page won't load [#the-page-wont-load]
* Check if your computer is on the same network as the controller
* Make sure you type `https://` before the IP address and `:8443` after it
* Try clearing your browser cache or use incognito mode
* A warning about the certificate is not an error — see Step 3
### The controller doesn't receive an IP address [#the-controller-doesnt-receive-an-ip-address]
If your network doesn't have a DHCP server, you can connect to the controller via USB cable:
1. Connect a USB cable to the USB port of the controller and to your computer
2. Your computer will receive an IP address from the `192.168.7.x` range
3. The controller will be available at `192.168.7.2` — the panel opens at `http://192.168.7.2:8090`
(if it does not open, restart the controller with the cable plugged in)
4. Connect via SSH and configure a static IP address for the `eth0` interface
This guide does not cover the exact network configuration commands.
## What's next? [#whats-next]
After connecting to the controller, you can proceed to:
* [First-time setup](./first-run-wizard) - every step of the wizard explained
* [Home Assistant connection](./home-assistant-connection) - connect the controller to Home Assistant
* [Interface navigation](./interface-navigation) - learn about the menu and tabs in the web interface
* [Update controller](./update-controller) - check if you have the latest software version
* [Configure controller](./edit-configuration) - configure the controller according to your needs
# Software Setup Introduction (/en/docs/black/products/black_cover/software_setup)
# Software Setup [#software-setup]
This section guides you through the software configuration of your **boneIO Black** device. Proper setup is crucial for integrating the controller with your home automation system - Home Assistant.
Our custom software, built to run on the powerful BeagleBone Black, offers a web interface for initial setup and monitoring.
The following guide is divided into several steps. In the first two, you will learn how to connect to the **boneIO** controller and how to connect the controller to the Home Assistant system. In the following steps, you will learn how to configure and adapt your boneIO to your needs.
# Interface navigation (/en/docs/black/products/black_cover/software_setup/interface-navigation)
After connecting to the controller, you will see the web interface with a top navigation bar. Below you'll find a description of all available tabs.
On a phone or tablet the same tabs move to a bar at the bottom of the screen — see [On a phone or tablet](#on-a-phone-or-tablet).
## Main menu [#main-menu]
| Tab | Description |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Outputs** | Control relay outputs, covers, and view relay states. |
| **Inputs** | View the state of digital inputs. |
| **Sensors** | Readings from onboard sensors: temperature, current consumption, memory usage, CPU, disk, and Dallas sensors (if connected). |
| **Modbus** | List of connected and configured Modbus devices. |
| **Templates** | Ready-made building blocks such as irrigation. |
| **Diagnostics** | The log, the support bundle and the bus tools (Modbus, I2C, CAN). See [Diagnostics](/en/docs/black/current/basic/logs). |
| **Settings** | Everything you configure, in seven groups — from outputs and schedules to software update, backups and restart. See [Settings](/en/docs/black/current/basic/settings). |
| **Node-RED** | The pre-installed visual automation tool. Shown only when Node-RED is running. |
| **Help** | Link to Discord community and documentation. |
**Where did System, Logs and the YAML editor go?** Since version 1.6 they are all inside the two tabs above:
the old **System** tab is now **Settings → Maintenance**, **Logs** and **Tools** are **Diagnostics**,
and the **YAML editor** is **Settings → Advanced → YAML editor**. Old bookmarks still work — they redirect.
A **read-only** account sees only the first five tabs. Diagnostics, Settings and Node-RED are for administrators — see [Accounts and access](/en/docs/black/current/basic/accounts).
## On a phone or tablet [#on-a-phone-or-tablet]
On a phone, a tablet or a narrow browser window the top bar shows only the
controller's name, and the tabs move to a bar at the bottom, under your thumb:
| Slot | What it opens |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Outputs** | The outputs view |
| **Inputs** | The inputs view |
| **Sensors** or **Templates** | Sensors — or Templates, once you have any; Sensors then moves under **More** |
| **Modbus** | The Modbus view |
| **More** | Everything else: Diagnostics, Settings, Node-RED, Help, and below them the version, serial number and the account you are signed in with |
### Inside the boneIO Dashboard add-on [#inside-the-boneio-dashboard-add-on]
When you open the panel through the **boneIO Dashboard** add-on in Home
Assistant, the bottom bar gets one more slot on the left: **Devices**. It opens
the add-on's device list. To make room, **Sensors** moves under **More**. Opened
through plain Home Assistant ingress, the bar stays as above.
{/* SCREENSHOT: en_bottom_nav_dashboard.webp — the panel inside the boneIO Dashboard add-on on a phone, Devices slot on the left of the bottom bar */}
## Language change [#language-change]
In the top right corner, you'll find flags to change the interface language. Available languages are Polish (PL) and English (EN).
# Naming Inputs (/en/docs/black/products/black_cover/software_setup/naming-inputs)
# Why should you name them? [#why-should-you-name-them]
Naming your inputs will make working with the controller much easier. It's a lot easier to remember "Bedroom Button1" than "IN\_04", right?
## Events – event entities [#events--event-entities]
Let's start with event entities. Below is the default configuration from the file:
```
~/boneio/event.yaml
```
```yaml
- id: IN_04
boneio_input: IN_04
actions:
single:
- action: output
pin: OUT_04
- id: IN_05
boneio_input: IN_05
actions:
single:
- action: output
pin: OUT_05
- id: IN_06
boneio_input: IN_06
actions:
single:
- action: output
pin: OUT_06
```
How do you name your input? It's very simple!
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | This part of the configuration is the input name, and you can change it freely. There are many naming approaches. For example, you can change the name to `BedroomButton1` or `IN_04_BedroomButton_1`. |
| `boneio_input` | This is the input number that your name refers to. For now, ignore `actions:` – we'll discuss them later. |
Our example looks like this:
```yaml
- id: IN_04_BedroomButton_1
boneio_input: IN_04
actions:
single:
- action: output
pin: OUT_04
```
## Binary (Binary sensor) [#binary-binary-sensor]
Below is the default configuration from the file:
```
~/boneio/binary_sensor.yaml
```
```yaml
- id: IN_01
boneio_input: IN_01
actions:
pressed:
- action: output
pin: OUT_01
- id: IN_02
boneio_input: IN_02
actions:
pressed:
- action: output
pin: OUT_02
```
| Parameter | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | This part of the configuration is the input name, and you can change it freely. There are many naming approaches. For example, you can change the name to `MotionBedroom` or `IN_01_MotionBedroom`. |
| `boneio_input` | This is the input number that your name refers to. For now, ignore `actions:` – we'll discuss them later. |
Our example looks like this:
```yaml
- id: IN_01_MotionBedroom
boneio_input: IN_01
actions:
pressed:
- action: output
pin: OUT_01
```
# Configure cover outputs (/en/docs/black/products/black_cover/software_setup/naming-outputs)
The boneIO Black Cover controller has **16 cover outputs** (8 covers, each with 2 relays: up/down).
## Do I need to configure outputs? [#do-i-need-to-configure-outputs]
**You don't need to change cover output names** - they are automatically configured as:
* `cover_01_up` / `cover_01_down`
* `cover_02_up` / `cover_02_down`
* ... etc.
These outputs are used internally by the cover configuration and **do not require editing**, unless you have specific needs.
**You can go directly to cover configuration** - cover outputs are already properly configured and ready to use.
## When to change output names? [#when-to-change-output-names]
Changing cover output names is only needed in specific cases:
* When you want to use a custom configuration
* When you need special naming for integrations
In most cases **you can skip this section** and go directly to cover configuration, where you'll give friendly names to your covers (e.g., "Living Room Cover", "Bedroom Cover").
## Go to cover configuration [#go-to-cover-configuration]
To configure your covers (give them names, assign to areas, set travel times), proceed to the next documentation section.
# Update Controller (/en/docs/black/products/black_cover/software_setup/update-controller)
The controller checks for a new version by itself every few hours. You install it with one click —
from Home Assistant or from the controller's own panel.
## Requirements [#requirements]
* The controller must have an internet connection
* You must be signed in to the panel as an **administrator**
* To update from Home Assistant, the controller must be connected to Home Assistant over MQTT
## How to update? [#how-to-update]
### From Home Assistant [#from-home-assistant]
1. In Home Assistant, open **Settings** — available updates are listed at the top,
2. Click the **boneIO Black Firmware** update,
3. Press **Update**,
4. That's all!
### From the web interface [#from-the-web-interface]
1. Open the controller's web interface in your browser
2. Go to **Settings** → **Maintenance** → **Software update**
3. Click **Check for Updates**
4. If a new version is available, read what it changes (**View Release Notes**), then click **Update to \** (for example **Update to 1.6.0**)
The update starts on its own. When it finishes, the application on the controller restarts and the panel reloads.
While the controller is installing and restarting, the panel shows **Update in progress** with the time since it started,
and comes back by itself once the new version is running. If the controller comes back on the old version, the panel says
**The update failed** — the details are in [Diagnostics](/en/docs/black/current/basic/logs).
If your browser shows the old panel after the update, it reloads the new one on its own (**Loading the new version of the panel**);
if it cannot, it asks you to press **Ctrl+Shift+R** (**Cmd+Shift+R** on a Mac).
{/* SCREENSHOT: en_panel_update_in_progress.webp — the "Update in progress" screen with "The controller is installing version …" and the elapsed time */}
**The update does not back up your configuration.** Download a backup first in **Settings → Maintenance → Backups**.
If something is wrong after the update, open **Available Versions** on the same page and install the previous version (the button is **Install**).
## After the update: system migrations [#after-the-update-system-migrations]
Some versions also change settings of the operating system underneath the app — for example firewall rules or SSH hardening.
These changes are called **system migrations**. They run by themselves on the first start after the update; you do not need to do anything.
You can see them in **Settings** → **Maintenance** → **System migrations**.
If a red banner says that **a system update was refused**, the page shows the reason — send it to us
(see [Diagnostics](/en/docs/black/current/basic/logs) for the support bundle).
## Updating from version 1.5? [#updating-from-version-15]
**Update to 1.5.6 first**, then to 1.6. Only 1.5.6 hands the browser over to the new panel cleanly; from older 1.5
versions the old panel may keep coming back after the update until you press **Ctrl+Shift+R**.
Version 1.6 adds accounts, so after the update the panel asks you to create an administrator account first
(unless the 1.5 panel already had a password — then you simply sign in with it).
Follow [Upgrading from 1.5 to 1.6](/en/docs/black/current/install/upgrade-1-5-to-1-6).
## Important information [#important-information]
* **Do not turn off the controller's power during the update.** A backup power supply is worth having for exactly this — see
[Backup power (UPS)](/en/docs/black/products/black_32x10a/hardware-installation#backup-power-ups--recommended).
* A small update takes a few minutes. Jumping several versions can take over ten minutes, and coming from 1.5 up to an hour,
because the system migrations run on the first start.
* While migrations run, the display shows **Updating** and **Do not power off.** with how far it has got
(**Updating system** with a percentage, if the display is not set up in the configuration). The panel does
not answer until they finish.
* After the update, the application on the controller restarts by itself.
{/* SCREENSHOT: oled_updating.webp — photo of the OLED showing "Updating", "Do not power off." and the percentage */}
## Updating the operating system [#updating-the-operating-system]
Updating boneIO does not update the Debian system and the kernel underneath it. That is a separate card on the same page,
**Operating system** — see [Maintenance → Operating system](/en/docs/black/current/basic/system#operating-system).
Unlike a boneIO update, it does not restart the controller by itself.
## Update via SSH [#update-via-ssh]
If you need to update the controller manually via SSH (e.g., when the web interface update doesn't work), see the [SSH update guide](/en/docs/black/advanced/update-via-ssh).
# Internal Automations (/en/docs/esp/products/esp_32_10/software_setup/creating-automations)
## What are Internal Automations? [#what-are-internal-automations]
Internal automations are a powerful way to create simple, core automations that run directly on your boneIO ESP controller. This means they will work even if your main smart home hub (like Home Assistant) is offline. They are perfect for critical functions, like turning on a light with a wall switch.
### Basic Automation: Toggling a Light [#basic-automation-toggling-a-light]
Let's start with a default configuration that links a button press to a light.
```yaml
binary_sensor:
- platform: gpio
name: 'IN_01_Bedroom_Button1'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_press: # This is our automation trigger
- if:
condition:
switch.is_on: local_control # the Local control switch in Home Assistant
then:
- light.toggle: light_01 # This is the action to perform
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
```
In the `on_press:` section, we define what happens when the button is pressed.\
The action `- light.toggle: light_01` will toggle the state of the light with the ID `light_01`.
The `switch.is_on: local_control` condition is the **Local control** switch the
boneIO configuration shows in Home Assistant — turned off, inputs only report
their state ([more](/en/docs/home-assistant/boneio-esp#local-control)). In your
own automation that should always run, you can leave the condition out.
The same logic applies to switches. The only difference is that the action would be `- switch.toggle: switch_01`. Simple!
## Advanced Automation: Multi-Click [#advanced-automation-multi-click]
ESPHome allows you to define multiple actions for a single button based on how it's pressed (single, double, or long press). This is done using the `on_multi_click` component.
Let's configure one button (`in_01`) to control three different lights.
### 1. The Goal [#1-the-goal]
* **Single Click**: Toggle `light_01`.
* **Double Click**: Toggle `light_02`.
* **Long Press**: Toggle `light_03`.
### 2. The Configuration [#2-the-configuration]
First, ensure you have your lights defined. Then, in your `binary_sensor` configuration, replace `on_press` with `on_multi_click`.
```yaml
# Ensure these lights are defined elsewhere in your config
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
- platform: binary
name: 'Light 02'
output: out_02
id: light_02
- platform: binary
name: 'Light 03'
output: out_03
id: light_03
# Now, configure the multi-click automation
binary_sensor:
- platform: gpio
name: 'IN_01_Multi_Click_Button'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_multi_click:
# Note: The order matters! ESPHome checks from top to bottom.
# It's best to define the most complex patterns (longest clicks) first.
# 1. Long Click Action
- timing:
- ON for at least 1.4s
then:
- logger.log: 'Long Click Detected, toggling Light 3'
- light.toggle: light_03
# 2. Double Click Action
- timing:
- ON for at most 1s
- OFF for at most 0.5s
- ON for at most 1s
- OFF for at least 0.2s
then:
- logger.log: 'Double Click Detected, toggling Light 2'
- light.toggle: light_02
# 3. Single Click Action
- timing:
- ON for at most 1s
- OFF for at least 0.5s
then:
- logger.log: 'Single Click Detected, toggling Light 1'
- light.toggle: light_01
```
### 3. How It Works [#3-how-it-works]
The `on_multi_click` automation checks a sequence of `timing` blocks from top to bottom. The first one that matches the user's button press pattern is executed.
* `timing`: This defines the pattern of ON (pressed) and OFF (released) states. You can adjust the time values (e.g., `at most 1s`, `at least 0.5s`) to fine-tune the responsiveness, but the defaults are usually a good starting point.
* `then`: This block contains the actions to be performed when the `timing` pattern is matched. We've included a `logger.log` action, which is very helpful for debugging your automations in the device logs.
By arranging the clicks from most complex (long press) to least complex (single press), you ensure that a long press doesn't also trigger the single press action.
# Connect boneIO ESP (/en/docs/esp/products/esp_32_10/software_setup/how-to-connect)
# Let's install the ESPHome Device Builder! [#lets-install-the-esphome-device-builder]
There are 3 options to connect to your boneIO ESP:
1. [Using Home Assistant addon](#using-home-assistant-addon)
2. [Using Esphome Device Builder on your PC](#using-esphome-device-builder-on-your-pc)
## ESPHome Device Builder in Home Assistant [#esphome-device-builder-in-home-assistant]
Installing the ESPHome Device Builder add-on is pretty simple. Just follow these steps:
1. Go to the **Settings > Add-ons** section in your Home Assistant.
2. Click the **Add-on Store** button in the bottom right corner.
3. In the search bar, type `ESPHome` and select the add-on from the official repository. Make sure you don't use beta or dev versions, as they are for testing purposes only.
4. Click **Install**.
After the installation is complete, go to the **Configuration** tab and enable the **Start on boot** and **Show in sidebar** options. This will make it easier to access ESPHome Device Builder in the future.
Finally, go to the **Info** tab and click **Start** to run the add-on. You will now see ESPHome Device Builder in your sidebar!
## ESPHome Device Builder on Your PC [#esphome-device-builder-on-your-pc]
If you don't use Home Assistant (HA), you can still edit your boneIO ESP's configuration.
Editing Esphome config without HA, just on your PC is also possible. Similar instruction is here: [https://esphome.io/guides/getting\_started\_command\_line](https://esphome.io/guides/getting_started_command_line)
On your PC, you will need one of the following:
* for Linux: Docker,
* for Windows: Python 3.13 installed.
### Windows [#windows]
We assume that you are running Windows 10 or 11 - its important to have your administrative privileges, also you need internet connection.
Let's do it step by step!
1. Download Python installer from Python download page for Windows Choose Windows installer according to your operating system version (most common is 64-bit).
2. Choose both options available in installer. “Use admin priviliges when installing py.exe” and “Add python.exe to PATH”. Click “Install now”.
3. Verify Python installation Open Powershell or CMD and type:
```powershell
python --version
```
If properly installed output would look like (with your Python version):
```powershell
Python 3.13.2
```
4. Prepare Esphome for Python. In Powershell prompt type:
```powershell
mkdir $env:USERPROFILE\esphome
cd $env:USERPROFILE\esphome
pip3 install wheel esphome pillow==10.2.0
```
in CMD:
```cmd
mkdir %USERPROFILE%\esphome
cd %USERPROFILE%\esphome
pip3 install wheel esphome pillow==10.2.0
```
5. ESPHome should work now - lets test it! Do it by typeing:
```powershell
esphome version
```
The output should looks like:
```powershell
Version: 2025.x.x
```
The version will differ for you. It's depends on your current version.
Now you’re good to execute next steps.
#### Run ESPHome Dashboard \[!toc] [#run-esphome-dashboard-toc]
In powershell type:
```powershell
cd $env:USERPROFILE\esphome
esphome dashboard .
```
or in CMD
```cmd
cd %USERPROFILE%\esphome
esphome dashboard .
```
Check it out opening page in your web browser [http://127.0.0.1:6052](http://127.0.0.1:6052) If it’s loaded then you can go to next section: [Connect with Esphome Addon](#connect-with-esphome-addon) or if you prefer USB installation go to [USB Only installation](#usb-only-installation).
#### Upgrade ESPHome \[!toc] [#upgrade-esphome-toc]
To upgrade your ESPHome in windows you need to:
```powershell
pip3 install --upgrade esphome
```
### Linux [#linux]
Fetch Esphome docker image / Linux / Mac OS
Run following command in terminal:
```bash
docker pull ghcr.io/esphome/esphome
```
Run Esphome dashboard
Now let’s start Esphome dashboard. Make directory where your config would be stored eg /home/me/esphome
In Linux based system:
```bash
docker run --rm --privileged --network host -v "/home/me/esphome":/config -it ghcr.io/esphome/esphome dashboard .
```
Now in Chrome open website:
under Linux [http://0.0.0.0:6052/](http://0.0.0.0:6052/)
## Connect with ESPHome Device Builder [#connect-with-esphome-device-builder]
**Note**: For this to work your home network must support mDNS. Your PC and boneIO is in same subnet (same VLAN) in most cases it’d work. boneIO has to be connected to your network and working.
1. Find your new boneIO device in the dashboard.
2. Click Adopt
3. Choose name for our new device
4. Click Adopt
5. Now it will prompt for install new software
6. After install there will be logs visible, you can click stop now
Next, set a password and an encryption key on the controller: until you do, anyone on your network can flash it. See [Security](/en/docs/esp/security#after-adoption-in-esphome-builder).
It’s ready, you can edit your config by clicking Edit on your boneIO device.
### Running boneIO without Home Assistant [#running-boneio-without-home-assistant]
If you don’t have HA, then in config find line:
```yaml
api:
```
and add `reboot_timeout: 0s` to it, so it’d look like:
`reboot_timeout: 0s` is default option in our precompiled binaries.
```yaml
api:
reboot_timeout: 0s
```
## USB-Only Installation [#usb-only-installation]
If you don’t want to setup network in boneIO then go with those steps. You'd need to have Esphome dashboard running. For Esphome firmware installation you’d need internet connection on your PC!
1. Go to [https://boneio.eu/esp](https://boneio.eu/esp)
2. Choose your board and choose option "Download yaml for this firmware" in the end.
3. In the top right corner choose Download raw file
4. Copy it to your Esphome directory eg C:/Users/me/esphome. After pasting it, it should appear in Esphome dashboard.
5. Now you can Edit and Install firmware using "Plug into this computer" option. If you need to install some drivers, then Esphome website should show what to download to get it work.
# Edit config file (/en/docs/esp/products/esp_32_10/software_setup/how-to-edit-config)
# Configuration file [#configuration-file]
The configuration file might look big and complicated, but it's really not. The file itself is separated into sections, which we will describe below.
For our example, we will use `boneio-32x10_lights_v0_7.yaml`.
So let's begin. Here is the whole config file:
```yaml
substitutions:
name: boneio-32-l-07
friendly_name: 'BoneIO ESP 32x10 Lights'
serial_prefix: 'esp' #Don't change it.
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.32x10-lights
version: '0.7'
esp32:
board: nodemcu-32s
ethernet:
id: eth
type: LAN8720
mdc_pin: GPIO23
mdio_pin: GPIO18
clk_mode: GPIO0_IN
phy_addr: 1
power_pin: GPIO16
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-32x10_lights_v0_7.yaml@latest
import_full_config: true
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.6.0
files: [
'devices/buzzer.yaml',
'devices/serial_no.yaml',
'devices_v0_7/display.yaml',
'devices_v0_7/i2c.yaml',
'devices_v0_7-v0_9/ina219.yaml',
'devices_v0_7-v0_9/lm75b.yaml',
'devices_v0_7-v0_9/pcf.yaml',
'boards/output/out01_02.yaml',
'boards/output/out03_04.yaml',
'boards/output/out05_06.yaml',
'boards/output/out07_08.yaml',
'boards/output/out09_10.yaml',
'boards/output/out11_12.yaml',
'boards/output/out13_14.yaml',
'boards/output/out15_16.yaml',
'boards/output/out17_18.yaml',
'boards/output/out19_20.yaml',
'boards/output/out21_22.yaml',
'boards/output/out23_24.yaml',
'boards/output/out25_26.yaml',
'boards/output/out27_28.yaml',
'boards/output/out29_30.yaml',
'boards/output/out31_32.yaml',
# 'devices_v0_7-v0_9/one_wire.yaml',
]
logger:
api:
reboot_timeout: 0s
ota:
- platform: esphome
web_server:
port: 80
local: true
version: 3
time:
- platform: homeassistant
timezone: Europe/Warsaw
id: homeassistant_time
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_press:
- if:
condition:
switch.is_on: local_control
then:
- light.toggle: light_01
######################
### MODBUS SECTION ###
######################
# UNCOMMENT BELOW TO USE MODBUS
# uart:
# id: uart_pin14_15
# rx_pin: GPIO14
# tx_pin: GPIO15
# baud_rate: 9600
# stop_bits: 1
# modbus:
# send_wait_time: 200ms
# uart_id: uart_pin14_15
# id: boneio_modbus
# modbus_controller:
# - id: YOURDEVICE ID
# address: 0x09
# modbus_id: mod_bus
# setup_priority: -10
# update_interval: 60s
```
### substitutions [#substitutions]
```yaml
substitutions:
name: boneio-32-l-07
friendly_name: 'BoneIO ESP 32x10 Lights'
serial_prefix: 'esp' #Don't change it.
```
This part is mainly responsible for the name of your controller.\
You should focus on `friendly_name`. You should write the exact name of your boneIO here. The name depends on your needs.\
It could be "boneIO ESP" if you have one boneIO ESP controller, or for example, "boneIO ESP 1st-floor".
### esphome [#esphome]
```yaml
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.32x10-lights
version: '0.7'
```
There are definitions for your controller. You shouldn't change `name` or `friendly_name`. The line `name_add_mac_suffix:` will add a MAC suffix to the controller's name, which is useful for identifying your controller. `project:` is the place where you define the type and version of your controller.
### esp32 [#esp32]
```yaml
esp32:
board: nodemcu-32s
```
Definition of the ESP32 board.
### Ethernet [#ethernet]
```yaml
ethernet:
id: eth
type: LAN8720
mdc_pin: GPIO23
mdio_pin: GPIO18
clk_mode: GPIO0_IN
phy_addr: 1
power_pin: GPIO16
```
This part is responsible for the description of your controller's Ethernet port - you shouldn't change anything here.
### dashboard\_import [#dashboard_import]
```yaml
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-32x10_lights_v0_7.yaml@latest
import_full_config: true
```
This is the place where the address for our GitHub repository is defined. The config and all additional packages are downloaded from there. There is nothing to change here.
### packages [#packages]
```yaml
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.7.1
files: [
'devices/buzzer.yaml',
'devices/serial_no.yaml',
'devices_v0_7/display.yaml',
'devices_v0_7/i2c.yaml',
'devices_v0_7-v0_9/ina219.yaml',
'devices_v0_7-v0_9/lm75b.yaml',
'devices_v0_7-v0_9/pcf.yaml',
'boards/output/out01_02.yaml',
'boards/output/out03_04.yaml',
'boards/output/out05_06.yaml',
'boards/output/out07_08.yaml',
'boards/output/out09_10.yaml',
'boards/output/out11_12.yaml',
'boards/output/out13_14.yaml',
'boards/output/out15_16.yaml',
'boards/output/out17_18.yaml',
'boards/output/out19_20.yaml',
'boards/output/out21_22.yaml',
'boards/output/out23_24.yaml',
'boards/output/out25_26.yaml',
'boards/output/out27_28.yaml',
'boards/output/out29_30.yaml',
'boards/output/out31_32.yaml',
# 'devices_v0_7-v0_9/one_wire.yaml',
]
```
Here are definitions of all packages used by boneIO, with the address to our GitHub. One thing that might interest you is uncommenting the `# 'devices_v0_7-v0_9/one_wire.yaml'` section if you would like to use a one-wire sensor.
### logger [#logger]
```yaml
logger:
```
In case of troubleshooting, you can increase the log level to `INFO` or `WARN` or `DEBUG`. This can be very useful in some cases.
### api [#api]
```yaml
api:
reboot_timeout: 0s
```
Here, the reboot timeout is defined for when the controller loses connection with HA.
If you want your boneIO to restart after losing connection with Home Assistant, you should enter a value that suits you here.
For WiFi connections, the value should not be zero. For LAN connections, not rebooting does not negatively affect the connection with Home Assistant in most cases.
### ota [#ota]
```yaml
ota:
- platform: esphome
```
Part responsible for Over The Air updates.
### web\_server [#web_server]
```yaml
web_server:
port: 80
local: true
version: 3
```
Part responsible for enabling the web server of the controller.
### time [#time]
```yaml
time:
- platform: homeassistant
timezone: Europe/Warsaw
id: homeassistant_time
```
This section is responsible for selecting your controller's time zone. Adjust it to your location.
### Modbus Section [#modbus-section]
```yaml
######################
### MODBUS SECTION ###
######################
# UNCOMMENT BELOW TO USE MODBUS
# uart:
# id: uart_pin14_15
# rx_pin: GPIO14
# tx_pin: GPIO15
# baud_rate: 9600
# stop_bits: 1
# modbus:
# send_wait_time: 200ms
# uart_id: uart_pin14_15
# id: boneio_modbus
```
This section is responsible for Modbus. If you plan to use it, you should first uncomment it.
```yaml
######################
### MODBUS SECTION ###
######################
# UNCOMMENT BELOW TO USE MODBUS
uart:
id: uart_pin14_15
rx_pin: GPIO14
tx_pin: GPIO15
baud_rate: 9600
stop_bits: 1
modbus:
send_wait_time: 200ms
uart_id: uart_pin14_15
id: boneio_modbus
```
Then, please check our Modbus tutorial: [Modbus with Esphome packages](/docs/esp/advanced/esphome-packages)
# Software setup (/en/docs/esp/products/esp_32_10/software_setup)
## You've just received your boneIO ESP! [#youve-just-received-your-boneio-esp]
Here are some steps witch will help you to handle it!
Device will come to you with alredy preinstalled ESPHome. boneIO is provided with default configuration, you need to adjust it for your needs.
Software installed on the device might be outdated. It's always good thing to update it.
Below you will find some necessary steps to start with boneiO ESP:
# Naming the Inputs (/en/docs/esp/products/esp_32_10/software_setup/naming-binary)
## Why should you name your inputs? [#why-should-you-name-your-inputs]
Naming your inputs makes working with the controller much easier. It's simpler to remember "Bedroom Button 1" than "IN\_01", right?
### Binary Sensors [#binary-sensors]
Let's look at the default configuration for your inputs, which are defined as `binary_sensor` components.
Here is a complete example of a single input configuration. The most important line for you is `name: 'My First Button'`.
```yaml
binary_sensor:
- platform: gpio
name: 'My First Button'
"This is the friendly name for your input"
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_press:
then:
```
### Configuration Explained [#configuration-explained]
| Section | Description |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `binary_sensor:` | This is the main header for all your binary sensor (input) definitions. |
| `- platform: gpio` | This specifies that the sensor is connected to a General Purpose Input/Output pin. |
| `name: 'My First Button'` | This is the friendly name for your input. It will be visible in Home Assistant and is much easier to identify. You can change it to something descriptive like `'Bedroom Button 1'` or `'IN_01_Living_Room_Motion'`. This is the most important part for you to customize. |
| `id: in_01` | This is a unique identifier used within ESPHome. It's essential for referring to this input in automations, such as the `on_press` action. |
| `pin:` | This section defines the physical pin the sensor is connected to. This part is pre-configured for the boneIO hardware and should not be changed. |
| `inverted: true` | This inverts the logic of the input. It's useful for certain devices like motion sensors, which might have a normally open or normally closed state. |
| `on_press:` | This is an automation that defines what happens when the input is triggered (e.g., a button is pressed). We will cover this in more detail in the automations guide. |
# Defining Outputs (/en/docs/esp/products/esp_32_10/software_setup/naming-outputs)
## What are outputs? [#what-are-outputs]
Outputs are the executive parts of our controller.
Controlling the outputs of the boneioESP 32x10A module
On other pages, you will find instructions for controlling the other boneio ESP modules.
## Why should you name them? [#why-should-you-name-them]
Naming your outputs will make working with the controller much easier. It's much easier to remember "Bedroom light" than "Light 01", right?
In our examples, we focus on a part of the configuration, which you can then adjust to your entire configuration.
Let's get started!
### 32x10A [#32x10a]
We prepared for you two types of the configuration file.\
What you should choose depends on what you will use as your outputs.\
Usually 32x10A controller its used for lights, so we prepared for you configuration with 32 light outputs!\
But if you want to use it as controling device for some sort of switches etc? No problem! \
We got also version with 32 switches!
But what if you want to use 20 outputs as lights and 12 as switches? We dont have configuration for you... But we will explain how you can prepare one for yourself!
Below is a part of the default configuration in the file:
```
boneio-32x10_lights_v0_7.yaml
```
We are looking for part with header `light:`
```yaml
light:
- platform: binary
name: "Light 01"
output: out_01
id: light_01
- platform: binary
name: "Light 02"
output: out_02
id: light_02
- platform: binary
name: "Light 03"
output: out_03
id: light_03
- platform: binary
name: "Light 04"
output: out_04
id: light_04
- platform: binary
name: "Light 05"
output: out_05
id: light_05
- platform: binary
name: "Light 06"
output: out_06
id: light_06
```
| Parameter | Description |
| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `- platform: binary` | Defines the component type. `binary` is used for simple on/off entities, such as lights. |
| `name: 'Light 01'` | This is the friendly name for the output, which will be visible in Home-Assistant. You can change it freely, for example to `Bedroom` or `OUT_01_Bedroom`. |
| `output: out_01` | This links the light to a specific physical relay output defined in another part of the configuration. |
| `id: light_01` | This is a unique identifier used in the ESPHome configuration. It allows this light to be controlled from automations or other components (e.g., `light.toggle: light_01`). |
```
boneio-32x10_switches_0_7.yaml
```
We are looking for part with header `switch:`
```yaml
switch:
- platform: output
name: "Switch 01"
output: out_01
id: switch_01
- platform: output
name: "Switch 02"
output: out_02
id: switch_02
- platform: output
name: "Switch 03"
output: out_03
id: switch_03
- platform: output
name: "Switch 04"
output: out_04
id: switch_04
- platform: output
name: "Switch 05"
output: out_05
id: switch_05
- platform: output
name: "Switch 06"
output: out_06
id: switch_06
```
| Parameter | Description |
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `- platform: output` | Defines the component type. `output` creates a switch entity which controls a GPIO pin. |
| `name: 'Switch 01'` | This is the friendly name for your switch. You can change it freely. There are many naming approaches. For example, you can change it to `Circulation_pump` or `Switch_01_Circulation_pump`. |
| `output: out_01` | This links the switch to a specific physical relay output. |
| `id: switch_01` | This is a unique identifier used in the ESPHome configuration to control this switch from other components. |
### Id like to get 10 switches and 22 lights! [#id-like-to-get-10-switches-and-22-lights]
You need to adjust your configuration file a little bit. Its really simple, and really usefull. Lets make a assumption that we to change from our `boneio-32x10_lights_v0_7.yaml` 10 lights to switche's.
As you can learn from this tutorial, the header its what describes the oputput, we are useing `switch` and `light here`. If you look at the standard lights configuration, you will notice that its start with header `light:`, then there are definitions of our relays. For our tutorial we gonna change last 10 lights to relays. Below the configuration:
```yaml
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
- platform: binary
name: 'Light 02'
output: out_02
id: light_02
...
...
...
- platform: binary
name: 'Light 21'
output: out_21
id: light_21
- platform: binary
name: 'Light 22'
output: out_22
id: light_22
switch:
- platform: binary
name: 'Switch 01'
output: out_23
id: switch_01
- platform: binary
name: 'Switch 02'
output: out_24
id: switch_02
...
...
...
- platform: binary
name: 'Switch 09'
output: out_31
id: switch_0
- platform: binary
name: 'Switch 10`
output: out_32
id: switch_32
```
So what have we done? The first part is the same as in the default lights configuration, but before 'out\_23' we added the 'switch:' header. We also changed the platform from 'binary' to 'output' and adjusted the names and IDs so everything matches. As a result, we got lights from relay 1 to 22 and switches from relay 23 to 32!
# Internal Automations (/en/docs/esp/products/esp_8_g2/software_setup/creating-automations)
## What are Internal Automations? [#what-are-internal-automations]
Internal automations are a powerful way to create simple, core automations that run directly on your boneIO ESP controller. This means they will work even if your main smart home hub (like Home Assistant) is offline. They are perfect for critical functions, like turning on a light with a wall switch.
### Basic Automation: Toggling a Light [#basic-automation-toggling-a-light]
Let's start with a default configuration that links a button press to a light.
```yaml
binary_sensor:
- platform: gpio
name: 'IN_01_Bedroom_Button1'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_press: # This is our automation trigger
- if:
condition:
switch.is_on: local_control # the Local control switch in Home Assistant
then:
- light.toggle: light_01 # This is the action to perform
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
```
In the `on_press:` section, we define what happens when the button is pressed.\
The action `- light.toggle: light_01` will toggle the state of the light with the ID `light_01`.
The `switch.is_on: local_control` condition is the **Local control** switch the
boneIO configuration shows in Home Assistant — turned off, inputs only report
their state ([more](/en/docs/home-assistant/boneio-esp#local-control)). In your
own automation that should always run, you can leave the condition out.
The same logic applies to switches. The only difference is that the action would be `- switch.toggle: switch_01`. Simple!
## Advanced Automation: Multi-Click [#advanced-automation-multi-click]
ESPHome allows you to define multiple actions for a single button based on how it's pressed (single, double, or long press). This is done using the `on_multi_click` component.
Let's configure one button (`in_01`) to control three different lights.
### 1. The Goal [#1-the-goal]
* **Single Click**: Toggle `light_01`.
* **Double Click**: Toggle `light_02`.
* **Long Press**: Toggle `light_03`.
### 2. The Configuration [#2-the-configuration]
First, ensure you have your lights defined. Then, in your `binary_sensor` configuration, replace `on_press` with `on_multi_click`.
```yaml
# Ensure these lights are defined elsewhere in your config
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
- platform: binary
name: 'Light 02'
output: out_02
id: light_02
- platform: binary
name: 'Light 03'
output: out_03
id: light_03
# Now, configure the multi-click automation
binary_sensor:
- platform: gpio
name: 'IN_01_Multi_Click_Button'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_multi_click:
# Note: The order matters! ESPHome checks from top to bottom.
# It's best to define the most complex patterns (longest clicks) first.
# 1. Long Click Action
- timing:
- ON for at least 1.4s
then:
- logger.log: 'Long Click Detected, toggling Light 3'
- light.toggle: light_03
# 2. Double Click Action
- timing:
- ON for at most 1s
- OFF for at most 0.5s
- ON for at most 1s
- OFF for at least 0.2s
then:
- logger.log: 'Double Click Detected, toggling Light 2'
- light.toggle: light_02
# 3. Single Click Action
- timing:
- ON for at most 1s
- OFF for at least 0.5s
then:
- logger.log: 'Single Click Detected, toggling Light 1'
- light.toggle: light_01
```
### 3. How It Works [#3-how-it-works]
The `on_multi_click` automation checks a sequence of `timing` blocks from top to bottom. The first one that matches the user's button press pattern is executed.
* `timing`: This defines the pattern of ON (pressed) and OFF (released) states. You can adjust the time values (e.g., `at most 1s`, `at least 0.5s`) to fine-tune the responsiveness, but the defaults are usually a good starting point.
* `then`: This block contains the actions to be performed when the `timing` pattern is matched. We've included a `logger.log` action, which is very helpful for debugging your automations in the device logs.
By arranging the clicks from most complex (long press) to least complex (single press), you ensure that a long press doesn't also trigger the single press action.
# Connect boneIO ESP (/en/docs/esp/products/esp_8_g2/software_setup/how-to-connect)
# Let's install the ESPHome Device Builder! [#lets-install-the-esphome-device-builder]
There are 3 options to connect to your boneIO ESP:
1. [Using Home Assistant addon](#using-home-assistant-addon)
2. [Using Esphome Device Builder on your PC](#using-esphome-device-builder-on-your-pc)
## ESPHome Device Builder in Home Assistant [#esphome-device-builder-in-home-assistant]
Installing the ESPHome Device Builder add-on is pretty simple. Just follow these steps:
1. Go to the **Settings > Add-ons** section in your Home Assistant.
2. Click the **Add-on Store** button in the bottom right corner.
3. In the search bar, type `ESPHome` and select the add-on from the official repository. Make sure you don't use beta or dev versions, as they are for testing purposes only.
4. Click **Install**.
After the installation is complete, go to the **Configuration** tab and enable the **Start on boot** and **Show in sidebar** options. This will make it easier to access ESPHome Device Builder in the future.
Finally, go to the **Info** tab and click **Start** to run the add-on. You will now see ESPHome Device Builder in your sidebar!
## ESPHome Device Builder on Your PC [#esphome-device-builder-on-your-pc]
If you don't use Home Assistant (HA), you can still edit your boneIO ESP's configuration.
Editing Esphome config without HA, just on your PC is also possible. Similar instruction is here: [https://esphome.io/guides/getting\_started\_command\_line](https://esphome.io/guides/getting_started_command_line)
On your PC, you will need one of the following:
* for Linux: Docker,
* for Windows: Python 3.13 installed.
### Windows [#windows]
We assume that you are running Windows 10 or 11 - its important to have your administrative privileges, also you need internet connection.
Let's do it step by step!
1. Download Python installer from Python download page for Windows Choose Windows installer according to your operating system version (most common is 64-bit).
2. Choose both options available in installer. “Use admin priviliges when installing py.exe” and “Add python.exe to PATH”. Click “Install now”.
3. Verify Python installation Open Powershell or CMD and type:
```powershell
python --version
```
If properly installed output would look like (with your Python version):
```powershell
Python 3.13.2
```
4. Prepare Esphome for Python. In Powershell prompt type:
```powershell
mkdir $env:USERPROFILE\esphome
cd $env:USERPROFILE\esphome
pip3 install wheel esphome pillow==10.2.0
```
in CMD:
```cmd
mkdir %USERPROFILE%\esphome
cd %USERPROFILE%\esphome
pip3 install wheel esphome pillow==10.2.0
```
5. ESPHome should work now - lets test it! Do it by typeing:
```powershell
esphome version
```
The output should looks like:
```powershell
Version: 2025.x.x
```
The version will differ for you. It's depends on your current version.
Now you’re good to execute next steps.
#### Run ESPHome Dashboard \[!toc] [#run-esphome-dashboard-toc]
In powershell type:
```powershell
cd $env:USERPROFILE\esphome
esphome dashboard .
```
or in CMD
```cmd
cd %USERPROFILE%\esphome
esphome dashboard .
```
Check it out opening page in your web browser [http://127.0.0.1:6052](http://127.0.0.1:6052) If it’s loaded then you can go to next section: [Connect with Esphome Addon](#connect-with-esphome-addon) or if you prefer USB installation go to [USB Only installation](#usb-only-installation).
#### Upgrade ESPHome \[!toc] [#upgrade-esphome-toc]
To upgrade your ESPHome in windows you need to:
```powershell
pip3 install --upgrade esphome
```
### Linux [#linux]
Fetch Esphome docker image / Linux / Mac OS
Run following command in terminal:
```bash
docker pull ghcr.io/esphome/esphome
```
Run Esphome dashboard
Now let’s start Esphome dashboard. Make directory where your config would be stored eg /home/me/esphome
In Linux based system:
```bash
docker run --rm --privileged --network host -v "/home/me/esphome":/config -it ghcr.io/esphome/esphome dashboard .
```
Now in Chrome open website:
under Linux [http://0.0.0.0:6052/](http://0.0.0.0:6052/)
## Connect with ESPHome Device Builder [#connect-with-esphome-device-builder]
**Note**: For this to work your home network must support mDNS. Your PC and boneIO is in same subnet (same VLAN) in most cases it’d work. boneIO has to be connected to your network and working.
1. Find your new boneIO device in the dashboard.
2. Click Adopt
3. Choose name for our new device
4. Click Adopt
5. Now it will prompt for install new software
6. After install there will be logs visible, you can click stop now
Next, set a password and an encryption key on the controller: until you do, anyone on your network can flash it. See [Security](/en/docs/esp/security#after-adoption-in-esphome-builder).
It’s ready, you can edit your config by clicking Edit on your boneIO device.
### Running boneIO without Home Assistant [#running-boneio-without-home-assistant]
If you don’t have HA, then in config find line:
```yaml
api:
```
and add `reboot_timeout: 0s` to it, so it’d look like:
`reboot_timeout: 0s` is default option in our precompiled binaries.
```yaml
api:
reboot_timeout: 0s
```
## USB-Only Installation [#usb-only-installation]
If you don’t want to setup network in boneIO then go with those steps. You'd need to have Esphome dashboard running. For Esphome firmware installation you’d need internet connection on your PC!
1. Go to [https://boneio.eu/esp](https://boneio.eu/esp)
2. Choose your board and choose option "Download yaml for this firmware" in the end.
3. In the top right corner choose Download raw file
4. Copy it to your Esphome directory eg C:/Users/me/esphome. After pasting it, it should appear in Esphome dashboard.
5. Now you can Edit and Install firmware using "Plug into this computer" option. If you need to install some drivers, then Esphome website should show what to download to get it work.
# Edit config file (/en/docs/esp/products/esp_8_g2/software_setup/how-to-edit-config)
# Configuration file [#configuration-file]
The configuration file might look big and complicated, but it's really not. The file itself is separated into sections, described below.
For our example, we will use `boneio-8x10A_v0_1.yaml`.
So let's begin. Here is the whole config file:
```yaml
ssubstitutions:
name: boneio-8-s-01
friendly_name: 'BoneIO ESP 8x10A Switches'
serial_prefix: 'espm' #Don't change it.
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.8_10-switches
version: '0.1'
esp32:
board: esp32dev
framework:
type: esp-idf
ethernet:
id: eth
type: LAN8720
mdc_pin: GPIO23
mdio_pin: GPIO18
clk:
pin: GPIO0
mode: CLK_EXT_IN
phy_addr: 1
power_pin: GPIO16
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-8x10A_v0_1.yaml@latest
import_full_config: true
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.7.1
files:
[
'devices/buzzer.yaml',
'devices/serial_no.yaml',
'devices/dimmer_i2c.yaml',
'devices_v0_7-v0_9/lm75b.yaml',
]
logger:
api:
reboot_timeout: 0s
ota:
- platform: esphome
- platform: web_server
web_server:
port: 80
local: true
time:
- platform: homeassistant
timezone: Europe/Warsaw
id: homeassistant_time
mcp23017:
- id: 'mcp1'
address: 0x20
# Individual outputs
switch:
- platform: gpio
name: 'OUT 1'
id: out_01
pin:
mcp23xxx: mcp1
number: 8
mode:
output: true
inverted: false
- platform: gpio
name: 'OUT 2'
id: out_02
pin:
mcp23xxx: mcp1
number: 9
mode:
output: true
inverted: false
- platform: gpio
name: 'OUT 3'
id: out_03
pin:
mcp23xxx: mcp1
number: 10
mode:
output: true
inverted: false
- platform: gpio
name: 'OUT 4'
id: out_04
pin:
mcp23xxx: mcp1
number: 11
mode:
output: true
inverted: false
- platform: gpio
name: 'OUT 5'
id: out_05
pin:
mcp23xxx: mcp1
number: 12
mode:
output: true
inverted: false
- platform: gpio
name: 'OUT 6'
id: out_06
pin:
mcp23xxx: mcp1
number: 13
mode:
output: true
inverted: false
- platform: gpio
name: 'OUT 7'
id: out_07
pin:
mcp23xxx: mcp1
number: 14
mode:
output: true
inverted: false
- platform: gpio
name: 'OUT 8'
id: out_08
pin:
mcp23xxx: mcp1
number: 15
mode:
output: true
inverted: false
binary_sensor:
- platform: gpio
name: 'IN 01'
id: in_01
pin:
mcp23xxx: mcp1
number: 0
mode:
input: true
inverted: false
- platform: gpio
name: 'IN 02'
id: in_02
pin:
mcp23xxx: mcp1
number: 1
mode:
input: true
inverted: false
- platform: gpio
name: 'IN 03'
id: in_03
pin:
mcp23xxx: mcp1
number: 2
mode:
input: true
inverted: false
- platform: gpio
name: 'IN 04'
id: in_04
pin:
mcp23xxx: mcp1
number: 3
mode:
input: true
inverted: false
- platform: gpio
name: 'IN 05'
id: in_05
pin:
mcp23xxx: mcp1
number: 4
mode:
input: true
inverted: false
- platform: gpio
name: 'IN 06'
id: in_06
pin:
mcp23xxx: mcp1
number: 5
mode:
input: true
inverted: false
- platform: gpio
name: 'IN 07'
id: in_07
pin:
mcp23xxx: mcp1
number: 6
mode:
input: true
inverted: false
- platform: gpio
name: 'IN 08'
id: in_08
pin:
mcp23xxx: mcp1
number: 7
mode:
input: true
inverted: false
```
### substitutions [#substitutions]
```yaml
ssubstitutions:
name: boneio-8-s-01
friendly_name: 'BoneIO ESP 8x10A Switches'
serial_prefix: 'espm' #Don't change it.
```
This part is mainly responsible for the name of your controller.\
You should focus on `friendly_name`. Write the exact name of your boneIO here. The name depends on your needs.\
It could be `boneIO ESP` if you have one boneIO ESP controller, or for example, `boneIO ESP 1st-floor`.
### esphome [#esphome]
```yaml
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.8_10-switches
version: '0.1'
```
There are definitions for your controller. You shouldn't change `name` or `friendly_name`. The line `name_add_mac_suffix:` will add a MAC suffix to the controller's name, which is useful for identifying your controller. `project:` is the place where you define the type and version of your controller.
### esp32 [#esp32]
```yaml
esp32:
board: esp32dev
framework:
type: esp-idf
```
Definition of the ESP32 board.
### Ethernet [#ethernet]
```yaml
ethernet:
id: eth
type: LAN8720
mdc_pin: GPIO23
mdio_pin: GPIO18
clk:
pin: GPIO0
mode: CLK_EXT_IN
phy_addr: 1
power_pin: GPIO16
```
This part is responsible for the description of your controller's Ethernet port - you shouldn't change anything here.
### dashboard\_import [#dashboard_import]
```yaml
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-8x10A_v0_1.yaml@latest
import_full_config: true
```
This is the place where the address for our GitHub repository is defined. The config and all additional packages are downloaded from there. There is nothing to change here.
### packages [#packages]
```yaml
ackages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.7.1
files:
[
'devices/buzzer.yaml',
'devices/serial_no.yaml',
'devices/dimmer_i2c.yaml',
'devices_v0_7-v0_9/lm75b.yaml',
]
```
Here are definitions of all packages used by boneIO, with the address to our GitHub.
### logger [#logger]
```yaml
logger:
```
In case of troubleshooting, you can increase the log level to `INFO` or `WARN` or `DEBUG`. This can be very useful in some cases.
### api [#api]
```yaml
api:
reboot_timeout: 0s
```
Use this setting to specify how long the controller should wait before rebooting after losing the connection to Home Assistant. Please enter a value appropriate for your setup.
For WiFi users, we advise against using zero. For wired (LAN) connections, disabling the reboot (setting it to 0) usually does not impact stability.
### ota [#ota]
```yaml
ota:
- platform: esphome
- platform: web_server
```
Part responsible for Over The Air updates.
### web\_server [#web_server]
```yaml
web_server:
port: 80
local: true
```
Part responsible for enabling the web server of the controller.
### Modbus Section [#modbus-section]
```yaml
######################
### MODBUS SECTION ###
######################
# UNCOMMENT BELOW TO USE MODBUS
# uart:
# id: uart_pin14_15
# rx_pin: GPIO14
# tx_pin: GPIO15
# baud_rate: 9600
# stop_bits: 1
# modbus:
# send_wait_time: 200ms
# uart_id: uart_pin14_15
# id: boneio_modbus
```
This section is responsible for Modbus. If you plan to use it, you should first uncomment it.
```yaml
######################
### MODBUS SECTION ###
######################
# UNCOMMENT BELOW TO USE MODBUS
uart:
id: uart_pin14_15
rx_pin: GPIO14
tx_pin: GPIO15
baud_rate: 9600
stop_bits: 1
modbus:
send_wait_time: 200ms
uart_id: uart_pin14_15
id: boneio_modbus
```
Then, please check our Modbus tutorial: [Modbus with Esphome packages](/docs/esp/advanced/esphome-packages)
# Software setup (/en/docs/esp/products/esp_8_g2/software_setup)
## You've just received your boneIO ESP! [#youve-just-received-your-boneio-esp]
Here are some steps witch will help you to handle it!
Device will come to you with alredy preinstalled ESPHome. boneIO is provided with default configuration, you need to adjust it for your needs.
Software installed on the device might be outdated. It's always good thing to update it.
Below you will find some necessary steps to start with boneiO ESP:
# Naming the Inputs (/en/docs/esp/products/esp_8_g2/software_setup/naming-binary)
## Why should you name your inputs? [#why-should-you-name-your-inputs]
Naming your inputs makes working with the controller much easier. It's simpler to remember "Bedroom Button 1" than "IN\_01", right?
### Binary Sensors [#binary-sensors]
Let's look at the default configuration for your inputs, which are defined as `binary_sensor` components.
Here is a complete example of a single input configuration. The most important line for you is `name: 'My First Button'`.
```yaml
binary_sensor:
- platform: gpio
name: 'My First Button'
"This is the friendly name for your input"
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_press:
then:
```
### Configuration Explained [#configuration-explained]
| Section | Description |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `binary_sensor:` | This is the main header for all your binary sensor (input) definitions. |
| `- platform: gpio` | This specifies that the sensor is connected to a General Purpose Input/Output pin. |
| `name: 'My First Button'` | This is the friendly name for your input. It will be visible in Home Assistant and is much easier to identify. You can change it to something descriptive like `'Bedroom Button 1'` or `'IN_01_Living_Room_Motion'`. This is the most important part for you to customize. |
| `id: in_01` | This is a unique identifier used within ESPHome. It's essential for referring to this input in automations, such as the `on_press` action. |
| `pin:` | This section defines the physical pin the sensor is connected to. This part is pre-configured for the boneIO hardware and should not be changed. |
| `inverted: true` | This inverts the logic of the input. It's useful for certain devices like motion sensors, which might have a normally open or normally closed state. |
| `on_press:` | This is an automation that defines what happens when the input is triggered (e.g., a button is pressed). We will cover this in more detail in the automations guide. |
# Defining Outputs (/en/docs/esp/products/esp_8_g2/software_setup/naming-outputs)
## What are outputs? [#what-are-outputs]
Outputs are the executive parts of our controller.
## Why should you name them? [#why-should-you-name-them]
Naming your outputs will make working with the controller much easier. It's much easier to remember "Bedroom light" than "Light 01", right?
In our examples, we focus on a part of the configuration, which you can then adjust to your entire configuration.
Let's get started!
### 8x10A gen2 [#8x10a-gen2]
We offer two variants of configuration files, the choice of which depends on the planned usage of the controller's outputs.
Since the 8x10A gen2 model is most commonly used for lighting control, the default configuration defines 8 'light' type outputs.
However, if you plan to use the controller to handle other devices (e.g., valves, pumps, or general relays), we have also prepared an alternative version with 8 'switch' type outputs.
Below is a part of the default configuration in the file:
```
boneio-8x10A_gen2_lights-v0_1.yaml
```
We are looking for part with header `light:`
```yaml
light:
- platform: binary
name: "Light 01"
output: out_01
id: light_01
- platform: binary
name: "Light 02"
output: out_02
id: light_02
- platform: binary
name: "Light 03"
output: out_03
id: light_03
- platform: binary
name: "Light 04"
output: out_04
id: light_04
- platform: binary
name: "Light 05"
output: out_05
id: light_05
- platform: binary
name: "Light 06"
output: out_06
id: light_06
```
| Parameter | Description |
| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `- platform: binary` | Defines the component type. `binary` is used for simple on/off entities, such as lights. |
| `name: 'Light 01'` | This is the friendly name for the output, which will be visible in Home-Assistant. You can change it freely, for example to `Bedroom` or `OUT_01_Bedroom`. |
| `output: out_01` | This links the light to a specific physical relay output defined in another part of the configuration. |
| `id: light_01` | This is a unique identifier used in the ESPHome configuration. It allows this light to be controlled from automations or other components (e.g., `light.toggle: light_01`). |
```
boneio-32x10_switches_0_7.yaml
```
We are looking for part with header `switch:`
```yaml
switch:
- platform: output
name: "Switch 01"
output: out_01
id: switch_01
- platform: output
name: "Switch 02"
output: out_02
id: switch_02
- platform: output
name: "Switch 03"
output: out_03
id: switch_03
- platform: output
name: "Switch 04"
output: out_04
id: switch_04
- platform: output
name: "Switch 05"
output: out_05
id: switch_05
- platform: output
name: "Switch 06"
output: out_06
id: switch_06
```
| Parameter | Description |
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `- platform: output` | Defines the component type. `output` creates a switch entity which controls a GPIO pin. |
| `name: 'Switch 01'` | This is the friendly name for your switch. You can change it freely. There are many naming approaches. For example, you can change it to `Circulation_pump` or `Switch_01_Circulation_pump`. |
| `output: out_01` | This links the switch to a specific physical relay output. |
| `id: switch_01` | This is a unique identifier used in the ESPHome configuration to control this switch from other components. |
### How to set 4 outputs as lights and 4 as switches? [#how-to-set-4-outputs-as-lights-and-4-as-switches]
If you need a specific output split that isn't available in the pre-made settings (e.g., 4+4), you can use manual configuration mode. See how to customize the device to your needs in a few steps.
You need to adjust your configuration file a little bit. Its really simple, and really usefull. Lets make a assumption that we to change from our `boneio-8x10A_gen2_lights-v0_1.yaml` 4 lights to switche's.
As you can learn from this tutorial, the header its what describes the oputput, we are useing `switch` and `light here`. If you look at the standard lights configuration, you will notice that its start with header `light:`, then there are definitions of our relays. For our tutorial we gonna change last 10 lights to relays. Below the configuration:
```yaml
light:
- platform: binary
name: 'Light 01'
output: out_01
id: light_01
- platform: binary
name: 'Light 02'
output: out_02
id: light_02
- platform: binary
name: 'Light 03'
output: out_03
id: light_03
- platform: binary
name: 'Light 04'
output: out_04
id: light_04
switch:
- platform: binary
name: 'Switch 01'
output: out_05
id: switch_01
- platform: binary
name: 'Switch 02'
output: out_06
id: switch_02
- platform: binary
name: 'Switch 03'
output: out_07
id: switch_03
- platform: binary
name: 'Switch 04`
output: out_08
id: switch_04
```
So what have we done? The first part is the same as in the default lights configuration, but before 'out\_05' we added the 'switch:' header. We also changed the platform from 'binary' to 'output' and adjusted the names and IDs so everything matches. As a result, we got lights from relay 1 to 4 and switches from relay 5 to 8!
# Internal Automations (/en/docs/esp/products/esp_cover/software_setup/create-automations)
## Advanced Automation with Multi-Click [#advanced-automation-with-multi-click]
For more advanced control, you can use ESPHome's `on_multi_click` feature. This allows you to assign different actions to short and long presses of a momentary switch, giving you full control over movement and tilt with just two buttons.
Here is a recommended configuration that provides intuitive control:
```yaml
binary_sensor:
# UP Button
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_multi_click:
- timing:
- ON for at least 2s # Long press
then:
- lambda: |
auto call = id(cover_01).make_call();
if(id(cover_01).current_operation == COVER_OPERATION_IDLE){
call.set_command_open();
}
else {
call.set_command_stop();
}
call.perform();
- timing:
- ON for at most 0.4s # Short press
- OFF for at least 0.1s
then:
- lambda: |
auto call = id(cover_01).make_call();
if (id(cover_01).current_operation == COVER_OPERATION_IDLE){
if (id(cover_01).tilt < 1.0){
float new_tilt = std::min(id(cover_01).tilt + 0.1f, 1.0f);
call.set_tilt(new_tilt);
}
}
else {
call.set_command_stop();
}
call.perform();
# DOWN Button
- platform: gpio
name: 'IN_02'
id: in_02
pin:
pcf8574: pcf_inputs_1to14
number: 1
mode:
input: true
inverted: true
on_multi_click:
- timing:
- ON for at least 2s # Long press
then:
- lambda: |
auto call = id(cover_01).make_call();
if(id(cover_01).current_operation == COVER_OPERATION_IDLE){
call.set_command_close();
}
else {
call.set_command_stop();
}
call.perform();
- timing:
- ON for at most 0.4s # Short press
- OFF for at least 0.1s
then:
- lambda: |
auto call = id(cover_01).make_call();
if (id(cover_01).current_operation == COVER_OPERATION_IDLE){
if (id(cover_01).tilt > 0.0){
float new_tilt = std::max(id(cover_01).tilt - 0.1f, 0.0f);
call.set_tilt(new_tilt);
}
}
else {
call.set_command_stop();
}
call.perform();
```
### How It Works: [#how-it-works]
This configuration uses two buttons (`IN_01` for UP and `IN_02` for DOWN) to control a single cover (`cover_01`).
* **Long Press (Up/Down Button):**
* If the cover is idle, it starts moving **up** or **down**.
* If the cover is already moving, it **stops**.
* **Short Press (Up/Down Button):**
* If the cover is idle, it adjusts the **tilt** of the slats (lamellas) in 10% increments. This is perfect for Venetian blinds.
* If the cover is moving, it **stops**.
# Connect your boneIO ESP (/en/docs/esp/products/esp_cover/software_setup/how-to-connect)
# Let's install the ESPHome Device Builder! [#lets-install-the-esphome-device-builder]
There are 3 options to connect to your boneIO ESP:
1. [Using Home Assistant addon](#using-home-assistant-addon)
2. [Using Esphome Device Builder on your PC](#using-esphome-device-builder-on-your-pc)
## ESPHome Device Builder in Home Assistant [#esphome-device-builder-in-home-assistant]
Installing the ESPHome Device Builder add-on is pretty simple. Just follow these steps:
1. Go to the **Settings > Add-ons** section in your Home Assistant.
2. Click the **Add-on Store** button in the bottom right corner.
3. In the search bar, type `ESPHome` and select the add-on from the official repository. Make sure you don't use beta or dev versions, as they are for testing purposes only.
4. Click **Install**.
After the installation is complete, go to the **Configuration** tab and enable the **Start on boot** and **Show in sidebar** options. This will make it easier to access ESPHome Device Builder in the future.
Finally, go to the **Info** tab and click **Start** to run the add-on. You will now see ESPHome Device Builder in your sidebar!
## ESPHome Device Builder on Your PC [#esphome-device-builder-on-your-pc]
If you don't use Home Assistant (HA), you can still edit your boneIO ESP's configuration.
Editing Esphome config without HA, just on your PC is also possible. Similar instruction is here: [https://esphome.io/guides/getting\_started\_command\_line](https://esphome.io/guides/getting_started_command_line)
On your PC, you will need one of the following:
* for Linux: Docker,
* for Windows: Python 3.13 installed.
### Windows [#windows]
We assume that you are running Windows 10 or 11 - its important to have your administrative privileges, also you need internet connection.
Let's do it step by step!
1. Download Python installer from Python download page for Windows Choose Windows installer according to your operating system version (most common is 64-bit).
2. Choose both options available in installer. “Use admin priviliges when installing py.exe” and “Add python.exe to PATH”. Click “Install now”.
3. Verify Python installation Open Powershell or CMD and type:
```powershell
python --version
```
If properly installed output would look like (with your Python version):
```powershell
Python 3.13.2
```
4. Prepare Esphome for Python. In Powershell prompt type:
```powershell
mkdir $env:USERPROFILE\esphome
cd $env:USERPROFILE\esphome
pip3 install wheel esphome pillow==10.2.0
```
in CMD:
```cmd
mkdir %USERPROFILE%\esphome
cd %USERPROFILE%\esphome
pip3 install wheel esphome pillow==10.2.0
```
5. ESPHome should work now - lets test it! Do it by typeing:
```powershell
esphome version
```
The output should looks like:
```powershell
Version: 2025.x.x
```
The version will differ for you. It's depends on your current version.
Now you’re good to execute next steps.
#### Run ESPHome Dashboard \[!toc] [#run-esphome-dashboard-toc]
In powershell type:
```powershell
cd $env:USERPROFILE\esphome
esphome dashboard .
```
or in CMD
```cmd
cd %USERPROFILE%\esphome
esphome dashboard .
```
Check it out opening page in your web browser [http://127.0.0.1:6052](http://127.0.0.1:6052) If it’s loaded then you can go to next section: [Connect with Esphome Addon](#connect-with-esphome-addon) or if you prefer USB installation go to [USB Only installation](#usb-only-installation).
#### Upgrade ESPHome \[!toc] [#upgrade-esphome-toc]
To upgrade your ESPHome in windows you need to:
```powershell
pip3 install --upgrade esphome
```
### Linux [#linux]
Fetch Esphome docker image / Linux / Mac OS
Run following command in terminal:
```bash
docker pull ghcr.io/esphome/esphome
```
Run Esphome dashboard
Now let’s start Esphome dashboard. Make directory where your config would be stored eg /home/me/esphome
In Linux based system:
```bash
docker run --rm --privileged --network host -v "/home/me/esphome":/config -it ghcr.io/esphome/esphome dashboard .
```
Now in Chrome open website:
under Linux [http://0.0.0.0:6052/](http://0.0.0.0:6052/)
## Connect with ESPHome Device Builder [#connect-with-esphome-device-builder]
**Note**: For this to work your home network must support mDNS. Your PC and boneIO is in same subnet (same VLAN) in most cases it’d work. boneIO has to be connected to your network and working.
1. Find your new boneIO device in the dashboard.
2. Click Adopt
3. Choose name for our new device
4. Click Adopt
5. Now it will prompt for install new software
6. After install there will be logs visible, you can click stop now
Next, set a password and an encryption key on the controller: until you do, anyone on your network can flash it. See [Security](/en/docs/esp/security#after-adoption-in-esphome-builder).
It’s ready, you can edit your config by clicking Edit on your boneIO device.
### Running boneIO without Home Assistant [#running-boneio-without-home-assistant]
If you don’t have HA, then in config find line:
```yaml
api:
```
and add `reboot_timeout: 0s` to it, so it’d look like:
`reboot_timeout: 0s` is default option in our precompiled binaries.
```yaml
api:
reboot_timeout: 0s
```
## USB-Only Installation [#usb-only-installation]
If you don’t want to setup network in boneIO then go with those steps. You'd need to have Esphome dashboard running. For Esphome firmware installation you’d need internet connection on your PC!
1. Go to [https://boneio.eu/esp](https://boneio.eu/esp)
2. Choose your board and choose option "Download yaml for this firmware" in the end.
3. In the top right corner choose Download raw file
4. Copy it to your Esphome directory eg C:/Users/me/esphome. After pasting it, it should appear in Esphome dashboard.
5. Now you can Edit and Install firmware using "Plug into this computer" option. If you need to install some drivers, then Esphome website should show what to download to get it work.
# Edit config file (/en/docs/esp/products/esp_cover/software_setup/how-to-edit-config)
# The Configuration File [#the-configuration-file]
The configuration file might seem large and complicated, but it's actually quite straightforward. The file is divided into sections, which we will describe below.
As an example, we will use `boneio-cover_v0_7.yaml`.
Here is the complete configuration file:
```yaml
substitutions:
name: boneio-c-07
friendly_name: 'BoneIO ESP Cover'
serial_prefix: 'esp' #Don't change it.
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.32x10-cover
version: '0.7'
esp32:
board: nodemcu-32s
framework:
type: esp-idf
ethernet:
id: eth
type: LAN8720
mdc_pin: GPIO23
mdio_pin: GPIO18
clk:
pin: GPIO0
mode: CLK_EXT_IN
phy_addr: 1
power_pin: GPIO16
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-cover_v0_7.yaml@latest
import_full_config: true
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.7.1
files: [
'devices/buzzer.yaml',
'devices/serial_no.yaml',
'devices_v0_7/display.yaml',
'devices_v0_7/i2c.yaml',
'devices_v0_7-v0_9/ina219.yaml',
'devices_v0_7-v0_9/lm75b.yaml',
'devices_v0_7-v0_9/pcf.yaml',
'boards/cover/out01_02.yaml',
'boards/cover/out03_04.yaml',
'boards/cover/out05_06.yaml',
'boards/cover/out07_08.yaml',
'boards/cover/out09_10.yaml',
'boards/cover/out11_12.yaml',
'boards/cover/out13_14.yaml',
'boards/cover/out15_16.yaml',
'boards/cover/out17_18.yaml',
'boards/cover/out19_20.yaml',
'boards/cover/out21_22.yaml',
'boards/cover/out23_24.yaml',
'boards/cover/out25_26.yaml',
'boards/cover/out27_28.yaml',
'boards/cover/out29_30.yaml',
'boards/cover/out31_32.yaml',
# 'devices_v0_7-v0_9/one_wire.yaml',
]
logger:
api:
reboot_timeout: 0s
ota:
- platform: esphome
- platform: web_server
web_server:
port: 80
local: true
time:
- platform: homeassistant
timezone: Europe/Warsaw
id: homeassistant_time
cover:
- platform: time_based
name: 'Cover 01'
id: cover_01
open_action:
- switch.turn_on: cover_open_01_out01
open_duration: 10s
close_action:
- switch.turn_on: cover_close_01_out02
close_duration: 10s
stop_action:
- switch.turn_off: cover_open_01_out01
- switch.turn_off: cover_close_01_out02
# ... (configurations for Cover 02 to Cover 16 are similar)
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_press:
then:
- cover.open: cover_01
on_release:
then:
- cover.stop: cover_01
- platform: gpio
name: 'IN_02'
id: in_02
pin:
pcf8574: pcf_inputs_1to14
number: 1
mode:
input: true
inverted: true
on_press:
then:
- cover.close: cover_01
on_release:
then:
- cover.stop: cover_01
# ... (configurations for inputs IN_03 to IN_32 are similar)
######################
### MODBUS SECTION ###
######################
# UNCOMMENT BELOW TO USE MODBUS
# uart:
# id: uart_pin14_15
# rx_pin: GPIO14
# tx_pin: GPIO15
# baud_rate: 9600
# stop_bits: 1
# modbus:
# send_wait_time: 200ms
# uart_id: uart_pin14_15
# id: boneio_modbus
```
### substitutions [#substitutions]
This section is mainly for naming your controller. You should focus on `friendly_name`. Enter the exact name of your boneIO here. The name depends on your needs. It could be "boneIO ESP Cover" if you have one, or for example, "boneIO Cover 1st floor".
### esphome [#esphome]
This contains definitions for your controller. You shouldn't change `name` or `friendly_name`. The `name_add_mac_suffix:` line will add a MAC suffix to the controller's name, which is useful for identification. `project:` is where you define the type and version of your controller.
### ethernet [#ethernet]
This section describes your controller's Ethernet port—you shouldn't change anything here.
### packages [#packages]
This section defines all the packages used by boneIO, along with the address to our GitHub. One thing that might interest you is uncommenting the `# 'devices_v0_7-v0_9/one_wire.yaml'` section if you want to use a one-wire sensor.
### logger, api, ota, web\_server, time [#logger-api-ota-web_server-time]
These are standard ESPHome sections. You can increase the log level in `logger` for troubleshooting, set a reboot timeout in `api` if the controller loses connection to HA, and set your timezone in `time`.
### cover [#cover]
This is the main section for configuring your roller shutters. Each `cover` entity is defined here.
* `platform: time_based`: This means the cover's position is estimated based on the time it takes to open or close.
* `name: 'Cover 01'`: The friendly name that will appear in Home Assistant.
* `open_duration` / `close_duration`: **This is important!** You must measure the time it takes for your shutter to fully open and close and enter the values here (e.g., `25s`).
* `open_action` / `close_action` / `stop_action`: These define which relays are activated to control the motor. This is pre-configured and should not be changed.
### Advanced: Venetian Blinds with Tilt Control [#advanced-venetian-blinds-with-tilt-control]
Standard ESPHome covers do not support tilt control out of the box. To enable this functionality, we use a custom component created by [bruxy70](https://github.com/bruxy70/Venetian-Blinds-Control), which adds the `venetian_blinds` platform.
#### 1. Add the Custom Component [#1-add-the-custom-component]
First, you need to tell ESPHome where to download the custom component from. Add the following `external_components` block to the very top of your configuration file:
```yaml
external_components:
- source:
type: git
url: https://github.com/bruxy70/Venetian-Blinds-Control
ref: master
components: [venetian_blinds]
# ... rest of your configuration (substitutions, esphome, etc.)
```
#### 2. Configure the Cover for Venetian Blinds [#2-configure-the-cover-for-venetian-blinds]
Next, find the cover you want to modify and make the following changes:
* Change the `platform` from `time_based` to `venetian_blinds`.
* Add the `tilt_duration` parameter. This is the time in milliseconds it takes for the slats to go from fully closed to fully open.
```yaml
cover:
- platform: venetian_blinds # Changed from time_based
name: 'Blind 01'
id: blind_01
open_action:
- switch.turn_on: cover_open_01_out01
open_duration: 60s # Use a safe, long value for calibration
close_action:
- switch.turn_on: cover_close_01_out02
close_duration: 60s # Use a safe, long value for calibration
tilt_duration: 2000ms # Added for tilt control
stop_action:
- switch.turn_off: cover_open_01_out01
- switch.turn_off: cover_close_01_out02
```
#### 3. Calibrate Durations [#3-calibrate-durations]
For the tilt and position to work accurately, you must calibrate the `open_duration`, `close_duration`, and `tilt_duration`.
**Always have the venetian blind fully open before you begin!**
1. Set `open_duration` and `close_duration` to a safe, long value (e.g., `60s`) and compile the firmware.
2. **Measure Closing Time:** Use a stopwatch and time how long it takes for the blind to go from fully open to fully closed. Note this value.
3. **Measure Opening and Tilt Time:** Start the blind opening. Note the time it takes for the slats to tilt from closed to open (this is your `tilt_duration`). Then, let it continue and note the total time it takes to fully open (this is your `open_duration`).
4. Update your configuration with the measured times, recompile, and upload. Your venetian blind is now calibrated!
### binary\_sensor [#binary_sensor]
This section defines the physical inputs (e.g., wall switches). Each input is linked to a cover action.
* `on_press`: Defines what happens when a button is pressed (e.g., `cover.open: cover_01`).
* `on_release`: Defines what happens when the button is released (e.g., `cover.stop: cover_01`). This is useful for stopping the shutter at any position.
You can freely reassign which input controls which cover by changing the `id` in the `on_press` and `on_release` actions.
### Modbus Section [#modbus-section]
This section is for Modbus. If you plan to use it, you should first uncomment it. Then, check out our Modbus tutorial: [Modbus with Esphome packages](/docs/esp/advanced/esphome-packages)
# Software setup (/en/docs/esp/products/esp_cover/software_setup)
## You've just received your boneIO ESP! [#youve-just-received-your-boneio-esp]
Here are some steps witch will help you to handle it!
Device will come to you with alredy preinstalled ESPHome. boneIO is provided with default configuration, you need to adjust it for your needs.
Software installed on the device might be outdated. It's always good thing to update it.
Below you will find some necessary steps to start with boneiO ESP:
# Naming the Inputs (/en/docs/esp/products/esp_cover/software_setup/naming-binary)
## Why should you name your inputs? [#why-should-you-name-your-inputs]
Naming your inputs makes working with the controller much easier. It's simpler to remember "Bedroom Button 1" than "IN\_01", right?
### Binary Sensors Explained [#binary-sensors-explained]
Let's look at the default configuration for your inputs, which are defined as `binary_sensor` components. The most important line for you is `name: 'My First Button'`.
```yaml
binary_sensor:
- platform: gpio
name: "My First Button"
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
mode:
input: true
inverted: true
on_press:
then:
- cover.open: cover_01
on_release:
then:
- cover.stop: cover_01
```
| Section | Description |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name: 'My First Button'` | This is the friendly name for your input. It will be visible in Home Assistant and is much easier to identify. This is the most important part for you to customize. |
| `id: in_01` | A unique identifier used within ESPHome. It's essential for referring to this input in automations, such as the `on_press` action. |
| `pin:` | This section defines the physical pin the sensor is connected to. This part is pre-configured for the boneIO hardware and should not be changed. |
| `on_press:` | An automation that defines what happens when the input is triggered (e.g., a button is pressed). |
| `on_release:` | An automation that defines what happens when the button is released. This is useful for stopping the cover at any position. |
# Set the Covers (/en/docs/esp/products/esp_cover/software_setup/naming-outputs)
## What are outputs? [#what-are-outputs]
Outputs are the executive parts of our controller.
Controlling the outputs of the boneIO ESP Cover module
On other pages, you will find instructions for controlling the other boneio ESP modules.
## Why should you name them? [#why-should-you-name-them]
Naming your outputs will make working with the controller much easier. It's much easier to remember "Living Room Cover" than "Cover 01", right?
In our examples, we focus on a part of the configuration, which you can then adjust to your entire configuration.
Let's get started!
### Roller Shutter Control (`time_based`) [#roller-shutter-control-time_based]
This is the standard configuration for typical roller shutters without tilt control. It uses the `time_based` platform to estimate the cover's position.
```yaml
cover:
- platform: time_based
name: "Living Room Cover"
id: cover_01
open_action:
- switch.turn_on: cover_open_01_out01
open_duration: 22s
close_action:
- switch.turn_on: cover_close_01_out02
close_duration: 21s
stop_action:
- switch.turn_off: cover_open_01_out01
- switch.turn_off: cover_close_01_out02
```
#### Configuration Explained [#configuration-explained]
| Parameter | Description |
| :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- |
| `platform: time_based` | Defines the cover as a standard roller shutter. |
| `name: 'Living Room Cover'` | A friendly name for Home Assistant. Change it to match the location, e.g., `'Bedroom Cover'`. |
| `open_duration` / `close_duration` | **Crucial for calibration!** You must measure the time it takes for the shutter to fully open and close and update these values. |
### Venetian Blinds Control with Tilt (`venetian_blinds`) [#venetian-blinds-control-with-tilt-venetian_blinds]
For venetian blinds, you can control the tilt of the slats using the `venetian_blinds` custom platform. This requires a more advanced setup.
For detailed instructions on how to set up the custom component and calibrate
your venetian blinds, please see the **[How to Edit Config
File](./how-to-edit-config)** guide.
Once configured, your cover block will look like this:
```yaml
cover:
- platform: venetian_blinds
name: "Bedroom Blind"
id: blind_01
open_duration: 22s
close_duration: 21s
tilt_duration: 1500ms
# ... other parameters are pre-configured
```
#### Additional Configuration Parameters [#additional-configuration-parameters]
| Parameter | Description |
| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------- |
| `platform: venetian_blinds` | Defines the cover as a venetian blind with tilt support. |
| `name: 'Bedroom Blind'` | A friendly name for your blind. |
| `tilt_duration` | **Crucial for calibration!** The time in milliseconds it takes for the slats to tilt from fully closed to fully open. |
# Internal Automations (/en/docs/esp/products/input_24_g2/software_setup/create-automations)
## What are Internal Automations? [#what-are-internal-automations]
Internal automations are a powerful way to create simple, core automations that run directly on your boneIO ESP controller. This means they will work even if your main smart home hub (like Home Assistant) is offline. They are perfect for critical functions, like turning on a light with a wall switch.
# Connect boneIO ESP (/en/docs/esp/products/input_24_g2/software_setup/how-to-connect)
# Let's install the ESPHome Device Builder! [#lets-install-the-esphome-device-builder]
There are 3 options to connect to your boneIO ESP:
1. [Using Home Assistant addon](#using-home-assistant-addon)
2. [Using Esphome Device Builder on your PC](#using-esphome-device-builder-on-your-pc)
## ESPHome Device Builder in Home Assistant [#esphome-device-builder-in-home-assistant]
Installing the ESPHome Device Builder add-on is pretty simple. Just follow these steps:
1. Go to the **Settings > Add-ons** section in your Home Assistant.
2. Click the **Add-on Store** button in the bottom right corner.
3. In the search bar, type `ESPHome` and select the add-on from the official repository. Make sure you don't use beta or dev versions, as they are for testing purposes only.
4. Click **Install**.
After the installation is complete, go to the **Configuration** tab and enable the **Start on boot** and **Show in sidebar** options. This will make it easier to access ESPHome Device Builder in the future.
Finally, go to the **Info** tab and click **Start** to run the add-on. You will now see ESPHome Device Builder in your sidebar!
## ESPHome Device Builder on Your PC [#esphome-device-builder-on-your-pc]
If you don't use Home Assistant (HA), you can still edit your boneIO ESP's configuration.
Editing Esphome config without HA, just on your PC is also possible. Similar instruction is here: [https://esphome.io/guides/getting\_started\_command\_line](https://esphome.io/guides/getting_started_command_line)
On your PC, you will need one of the following:
* for Linux: Docker,
* for Windows: Python 3.13 installed.
### Windows [#windows]
We assume that you are running Windows 10 or 11 - its important to have your administrative privileges, also you need internet connection.
Let's do it step by step!
1. Download Python installer from Python download page for Windows Choose Windows installer according to your operating system version (most common is 64-bit).
2. Choose both options available in installer. “Use admin priviliges when installing py.exe” and “Add python.exe to PATH”. Click “Install now”.
3. Verify Python installation Open Powershell or CMD and type:
```powershell
python --version
```
If properly installed output would look like (with your Python version):
```powershell
Python 3.13.2
```
4. Prepare Esphome for Python. In Powershell prompt type:
```powershell
mkdir $env:USERPROFILE\esphome
cd $env:USERPROFILE\esphome
pip3 install wheel esphome pillow==10.2.0
```
in CMD:
```cmd
mkdir %USERPROFILE%\esphome
cd %USERPROFILE%\esphome
pip3 install wheel esphome pillow==10.2.0
```
5. ESPHome should work now - lets test it! Do it by typeing:
```powershell
esphome version
```
The output should looks like:
```powershell
Version: 2025.x.x
```
The version will differ for you. It's depends on your current version.
Now you’re good to execute next steps.
#### Run ESPHome Dashboard \[!toc] [#run-esphome-dashboard-toc]
In powershell type:
```powershell
cd $env:USERPROFILE\esphome
esphome dashboard .
```
or in CMD
```cmd
cd %USERPROFILE%\esphome
esphome dashboard .
```
Check it out opening page in your web browser [http://127.0.0.1:6052](http://127.0.0.1:6052) If it’s loaded then you can go to next section: [Connect with Esphome Addon](#connect-with-esphome-addon) or if you prefer USB installation go to [USB Only installation](#usb-only-installation).
#### Upgrade ESPHome \[!toc] [#upgrade-esphome-toc]
To upgrade your ESPHome in windows you need to:
```powershell
pip3 install --upgrade esphome
```
### Linux [#linux]
Fetch Esphome docker image / Linux / Mac OS
Run following command in terminal:
```bash
docker pull ghcr.io/esphome/esphome
```
Run Esphome dashboard
Now let’s start Esphome dashboard. Make directory where your config would be stored eg /home/me/esphome
In Linux based system:
```bash
docker run --rm --privileged --network host -v "/home/me/esphome":/config -it ghcr.io/esphome/esphome dashboard .
```
Now in Chrome open website:
under Linux [http://0.0.0.0:6052/](http://0.0.0.0:6052/)
## Connect with ESPHome Device Builder [#connect-with-esphome-device-builder]
**Note**: For this to work your home network must support mDNS. Your PC and boneIO is in same subnet (same VLAN) in most cases it’d work. boneIO has to be connected to your network and working.
1. Find your new boneIO device in the dashboard.
2. Click Adopt
3. Choose name for our new device
4. Click Adopt
5. Now it will prompt for install new software
6. After install there will be logs visible, you can click stop now
Next, set a password and an encryption key on the controller: until you do, anyone on your network can flash it. See [Security](/en/docs/esp/security#after-adoption-in-esphome-builder).
It’s ready, you can edit your config by clicking Edit on your boneIO device.
### Running boneIO without Home Assistant [#running-boneio-without-home-assistant]
If you don’t have HA, then in config find line:
```yaml
api:
```
and add `reboot_timeout: 0s` to it, so it’d look like:
`reboot_timeout: 0s` is default option in our precompiled binaries.
```yaml
api:
reboot_timeout: 0s
```
## USB-Only Installation [#usb-only-installation]
If you don’t want to setup network in boneIO then go with those steps. You'd need to have Esphome dashboard running. For Esphome firmware installation you’d need internet connection on your PC!
1. Go to [https://boneio.eu/esp](https://boneio.eu/esp)
2. Choose your board and choose option "Download yaml for this firmware" in the end.
3. In the top right corner choose Download raw file
4. Copy it to your Esphome directory eg C:/Users/me/esphome. After pasting it, it should appear in Esphome dashboard.
5. Now you can Edit and Install firmware using "Plug into this computer" option. If you need to install some drivers, then Esphome website should show what to download to get it work.
# Edit config file (/en/docs/esp/products/input_24_g2/software_setup/how-to-edit-config)
# Configuration file [#configuration-file]
The configuration file might look big and complicated, but it's really not. The file itself is separated into sections, which we will describe below.
For our example, we will use `boneio-dimmer_gen2_8ch-01.yaml`.
So let's begin. Here is the whole config file:
```yaml
substitutions:
#name: boneio-dr-gen2-8ch-01
friendly_name: 'BoneIO Input24'
#serial_prefix: 'dim2' #Don't change it.
#firmware_manifest: 'https://boneio.eu/fwesp/boneio-dr-gen2-8ch-01.json'
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
#name: boneio.dimmer-led-gen2
version: '0.1'
on_boot:
priority: -100
then:
- delay: 5s
- if:
condition:
lambda: 'return id(serial_no) != nullptr;'
then:
- component.update: serial_no
- logger.log: "Serial No updated on boot"
else:
- logger.log: "Serial No component not found"
esp32:
board: esp32-s3-devkitc-1
framework:
type: esp-idf
ethernet:
id: eth
type: W5500
clk_pin: GPIO13
mosi_pin: GPIO39
miso_pin: GPIO38
cs_pin: GPIO12
interrupt_pin: GPIO2
reset_pin: GPIO1
clock_speed: 25MHz
external_components:
- source: github://boneIO-eu/esphome-LM75@main #Original source and thank you note for BTomala https://github.com/boneIO-eu/esphome-lm75
components: [lm75]
i2c:
sda: GPIO10
scl: GPIO11
scan: True
frequency: 400kHz
uart:
id: boneio_uart
rx_pin: GPIO21
tx_pin: GPIO14
baud_rate: 9600
stop_bits: 1
##CAN gpio48 - tx, gpio47 rx, gpio35 stb
modbus:
send_wait_time: 80ms
uart_id: boneio_uart
id: boneio_modbus
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.7.1
files: [
'devices/serial_no.yaml',
# # 'devices/dimmer_i2c.yaml',
]
boneiopackages:
url: https://github.com/boneIO-eu/esphome_packages
ref: main
refresh: 1min
files:
- path: sdm630.yaml
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-dimmer_gen2_8ch-v0_1.yaml@main
import_full_config: true
pcf8574:
- id: 'pcf_inputs'
address: 0x38
# http_request:
# timeout: 7s
# verify_ssl: false
logger:
hardware_uart: UART0
api:
reboot_timeout: 0s
ota:
- platform: esphome
- platform: web_server
# - platform: http_request
# update:
# - id: update_std
# platform: http_request
# name: boneIO FW Update
# update_interval: 3 minutes
# source: ${firmware_manifest}
web_server:
port: 80
version: 3
local: true
debug:
update_interval: 15s
sensor:
- platform: debug
free:
name: "Heap Free"
block:
name: "Heap Max Block"
loop_time:
name: "Loop Time"
- platform: lm75
id: boneIO_temp
name: 'Temperature'
update_interval: 30s
entity_category: diagnostic
on_value_range:
- above: 70.0
then:
- switch.turn_on: buzzer
- below: 70.0
then:
- switch.turn_off: buzzer
switch:
- platform: gpio
id: buzzer
name: 'Buzzer'
pin:
number: GPIO9
mode:
output: true
inverted: false
- platform: gpio
id: can_bus_switch
name: 'CAN Bus Switch'
pin:
number: GPIO35
mode:
output: true
inverted: false
- platform: gpio
name: "CAN RX"
pin: GPIO47
- platform: gpio
name: "CAN TX"
pin: GPIO48
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_02'
id: in_02
pin:
pcf8574: pcf_inputs
number: 1
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_03'
id: in_03
pin:
pcf8574: pcf_inputs
number: 2
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_04'
id: in_04
pin:
pcf8574: pcf_inputs
number: 3
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_05'
id: in_05
pin:
pcf8574: pcf_inputs
number: 4
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_06'
id: in_06
pin:
pcf8574: pcf_inputs
number: 5
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_07'
id: in_07
pin:
pcf8574: pcf_inputs
number: 6
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_08'
id: in_08
pin:
pcf8574: pcf_inputs
number: 7
mode:
input: true
inverted: true
- platform: template
name: CAN Bus Button
id: can_bus_button
# canbus:
# - platform: esp32_can
# tx_pin: GPIO48
# rx_pin: GPIO47
# can_id: 4
# bit_rate: 50kbps
# on_frame:
# - can_id: 5
# then:
# - lambda: |-
# if(x.size() > 0) {
# switch(x[0]) {
# case 0x12: // button release
# id(can_bus_button).publish_state(false);
# break;
# case 0x11: // button press
# id(can_bus_button).publish_state(true);
# break;
# }
# }
# button:
# - platform: template
# name: 'CAN Sensor ON'
# on_press:
# - logger.log: Button Pressed
# - canbus.send: [0x11, 0x22, 0x33]
# - platform: template
# name: 'CAN Sensor OFF'
# on_press:
# - logger.log: Button Pressed
# - canbus.send: [0x12, 0x22, 0x33]
```
### substitutions [#substitutions]
```yaml
substitutions:
name: boneio-dr-gen2-8ch-01
friendly_name: 'BoneIO Dimmer 8ch'
serial_prefix: 'dim2' #Don't change it.
firmware_manifest: 'https://boneio.eu/fwesp/boneio-dr-gen2-8ch-01.json'
```
This part is mainly responsible for the name of your controller.\
You should focus on `friendly_name`. You should write the exact name of your boneIO here. The name depends on your needs.\
It could be "boneIO Dimmer-G2" if you have one boneIO controller, or for example, "boneIO Dimmer-G2 1st-floor".
### esphome [#esphome]
```yaml
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.dimmer-led-gen2
version: '0.1'
on_boot:
priority: -100
then:
- delay: 5s
- if:
condition:
lambda: 'return id(serial_no) != nullptr;'
then:
- component.update: serial_no
- logger.log: "Serial No updated on boot"
else:
- logger.log: "Serial No component not found"
```
There are definitions for your controller. You shouldn't change `name` or `friendly_name`. The line `name_add_mac_suffix:` will add a MAC suffix to the controller's name, which is useful for identifying your controller. `project:` is the place where you define the type and version of your controller.
### esp32 [#esp32]
```yaml
esp32:
board: esp32-s3-devkitc-1
framework:
type: esp-idf
```
Definition of the ESP32 board and the required framework.
### Ethernet [#ethernet]
```yaml
ethernet:
id: eth
type: W5500
clk_pin: GPIO13
mosi_pin: GPIO39
miso_pin: GPIO38
cs_pin: GPIO12
interrupt_pin: GPIO2
reset_pin: GPIO1
clock_speed: 25MHz
```
This part is responsible for the description of your controller's Ethernet port - you shouldn't change anything here.
### dashboard\_import [#dashboard_import]
```yaml
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-dimmer_gen2_8ch-01.yaml@main
import_full_config: true
```
This is the place where the address for our GitHub repository is defined. The config and all additional packages are downloaded from there. There is nothing to change here.
### packages [#packages]
```yaml
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.7.1
files: [
'devices/serial_no.yaml',
# 'devices/dimmer_i2c.yaml',
]
boneiopackages:
url: https://github.com/boneIO-eu/esphome_packages
ref: main
refresh: 1min
files:
- path: sdm630.yaml
```
Here are definitions of all packages used by boneIO, with the address to our GitHub. You can also find there the definitions of modbus devices.
### logger [#logger]
```yaml
logger:
hardware_uart: UART0
```
In case of troubleshooting, you can increase the log level to `INFO`, `WARN`, or `DEBUG`. This can be very useful in some cases.
### api [#api]
```yaml
api:
reboot_timeout: 0s
```
Here, the reboot timeout is defined for when the controller loses connection with HA.
If you want your boneIO to restart after losing connection with Home Assistant, you should enter a value that suits you here.
For WiFi connections, the value should not be zero. For LAN connections, not rebooting does not negatively affect the connection with Home Assistant in most cases.
### ota [#ota]
```yaml
ota:
- platform: esphome
- platform: web_server
# - platform: http_request
```
Part responsible for Over The Air updates. The `web_server` platform allows updating via the device's web panel.
### web\_server [#web_server]
```yaml
web_server:
port: 80
local: true
version: 3
```
Part responsible for enabling the web server of the controller.
### time [#time]
```yaml
time:
- platform: homeassistant
timezone: Europe/Warsaw
id: homeassistant_time
```
This section is responsible for selecting your controller's time zone. Adjust it to your location.
### Modbus Section [#modbus-section]
```yaml
######################
### MODBUS SECTION ###
######################
# UNCOMMENT BELOW TO USE MODBUS
# uart:
# id: uart_pin14_15
# rx_pin: GPIO14
# tx_pin: GPIO15
# baud_rate: 9600
# stop_bits: 1
# modbus:
# send_wait_time: 200ms
# uart_id: uart_pin14_15
# id: boneio_modbus
# modbus_controller:
# - id: YOURDEVICE ID
# address: 0x09
# modbus_id: mod_bus
# setup_priority: -10
# update_interval: 60s
```
This section is responsible for Modbus. If you plan to use it, you should first uncomment it.\
Then, please check our Modbus tutorial: [Modbus with Esphome packages](/docs/esp/advanced/esphome-packages)
# Step by step Guide (/en/docs/esp/products/input_24_g2/software_setup)
## You just received your boneIO ESP Input24 gen2! Here are some steps witch will help you to handle it! [#you-just-received-your-boneio-esp-input24-gen2-here-are-some-steps-witch-will-help-you-to-handle-it]
Device will come to you with already preinstalled ESPHome. boneIO is provided with default configuration, you need to adjust it for your needs.
Below you will find some necessary steps to start with boneIO ESP Input24 gen2:
# How are inputs defined? (/en/docs/esp/products/input_24_g2/software_setup/naming-binary)
## Why should you name your inputs? [#why-should-you-name-your-inputs]
Naming your inputs makes working with the controller much easier. It's simpler to remember "Bedroom Button 1" than "IN\_01", right?
### Binary Sensors [#binary-sensors]
Let's look at the default configuration for your inputs, which are defined as `binary_sensor` components.
Here is a complete example of a single input configuration. The most important line for you is `name: 'My First Button'`.
```yaml
binary_sensor:
- platform: gpio
name: 'My First Button'
"This is the friendly name for your input"
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_press:
then:
```
### Configuration Explained [#configuration-explained]
| Section | Description |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `binary_sensor:` | This is the main header for all your binary sensor (input) definitions. |
| `- platform: gpio` | This specifies that the sensor is connected to a General Purpose Input/Output pin. |
| `name: 'My First Button'` | This is the friendly name for your input. It will be visible in Home Assistant and is much easier to identify. You can change it to something descriptive like `'Bedroom Button 1'` or `'IN_01_Living_Room_Motion'`. This is the most important part for you to customize. |
| `id: in_01` | This is a unique identifier used within ESPHome. It's essential for referring to this input in automations, such as the `on_press` action. |
| `pin:` | This section defines the physical pin the sensor is connected to. This part is pre-configured for the boneIO hardware and should not be changed. |
| `inverted: true` | This inverts the logic of the input. It's useful for certain devices like motion sensors, which might have a normally open or normally closed state. |
| `on_press:` | This is an automation that defines what happens when the input is triggered (e.g., a button is pressed). We will cover this in more detail in the automations guide. |
# Internal Automations (/en/docs/esp/products/esp_cover_mix/software_setup/create-automations)
## Internal Automations [#internal-automations]
The ESP Cover Mix allows for a wide range of internal automations, from simple toggles to advanced multi-click actions. This guide covers the most common use cases for both covers and relays.
***
## Part 1: Automations for Covers [#part-1-automations-for-covers]
### Advanced Control with `on_multi_click` [#advanced-control-with-on_multi_click]
For the most intuitive control of venetian blinds (or standard shutters), you can use ESPHome's `on_multi_click` feature. This allows you to assign different actions to short and long presses of a momentary switch, giving you full control over movement and tilt with just two buttons.
```yaml
binary_sensor:
# UP Button
- platform: gpio
name: 'IN_01'
id: in_01
on_multi_click:
- timing:
- ON for at least 2s # Long press
then:
- lambda: 'id(cover_01).make_call().set_command_open().perform();'
- timing:
- ON for at most 0.4s # Short press
then:
- lambda: 'id(cover_01).make_call().set_command_stop().perform();'
# DOWN Button
- platform: gpio
name: 'IN_02'
id: in_02
on_multi_click:
- timing:
- ON for at least 2s # Long press
then:
- lambda: 'id(cover_01).make_call().set_command_close().perform();'
- timing:
- ON for at most 0.4s # Short press
then:
- lambda: 'id(cover_01).make_call().set_command_stop().perform();'
```
**How It Works:**
* **Long Press:** Fully opens or closes the cover.
* **Short Press:** Stops the cover at its current position.
The example above is simplified. For a more advanced version that includes **tilt control** for venetian blinds, please refer to the `ESP Cover` documentation.
***
## Part 2: Automations for Relays [#part-2-automations-for-relays]
Automations for the general-purpose relays are typically simpler.
### Simple Toggle with `on_press` [#simple-toggle-with-on_press]
The most common automation is to toggle a light or a switch with a single button press.
```yaml
binary_sensor:
- platform: gpio
name: 'Garden Light Switch'
id: in_17
pin:
pcf8574: pcf_inputs_15to32 # Or the correct PCF
number: 2 # Corresponds to IN_17
on_press:
then:
- light.toggle: light_17
```
This configuration will turn `light_17` on if it's off, and off if it's on, every time the button connected to `IN_17` is pressed.
### Using Bistable (On/Off) Switches [#using-bistable-onoff-switches]
If you are using bistable (on/off) switches instead of momentary ones, you can define separate actions for `on_press` (when the switch is turned on) and `on_release` (when it's turned off).
```yaml
binary_sensor:
- platform: gpio
name: 'Garage Power Switch'
id: in_18
on_press:
then:
- switch.turn_on: switch_18
on_release:
then:
- switch.turn_off: switch_18
```
# Connect your boneIO ESP (/en/docs/esp/products/esp_cover_mix/software_setup/how-to-connect)
# Let's install the ESPHome Device Builder! [#lets-install-the-esphome-device-builder]
There are 3 options to connect to your boneIO ESP:
1. [Using Home Assistant addon](#using-home-assistant-addon)
2. [Using Esphome Device Builder on your PC](#using-esphome-device-builder-on-your-pc)
## ESPHome Device Builder in Home Assistant [#esphome-device-builder-in-home-assistant]
Installing the ESPHome Device Builder add-on is pretty simple. Just follow these steps:
1. Go to the **Settings > Add-ons** section in your Home Assistant.
2. Click the **Add-on Store** button in the bottom right corner.
3. In the search bar, type `ESPHome` and select the add-on from the official repository. Make sure you don't use beta or dev versions, as they are for testing purposes only.
4. Click **Install**.
After the installation is complete, go to the **Configuration** tab and enable the **Start on boot** and **Show in sidebar** options. This will make it easier to access ESPHome Device Builder in the future.
Finally, go to the **Info** tab and click **Start** to run the add-on. You will now see ESPHome Device Builder in your sidebar!
## ESPHome Device Builder on Your PC [#esphome-device-builder-on-your-pc]
If you don't use Home Assistant (HA), you can still edit your boneIO ESP's configuration.
Editing Esphome config without HA, just on your PC is also possible. Similar instruction is here: [https://esphome.io/guides/getting\_started\_command\_line](https://esphome.io/guides/getting_started_command_line)
On your PC, you will need one of the following:
* for Linux: Docker,
* for Windows: Python 3.13 installed.
### Windows [#windows]
We assume that you are running Windows 10 or 11 - its important to have your administrative privileges, also you need internet connection.
Let's do it step by step!
1. Download Python installer from Python download page for Windows Choose Windows installer according to your operating system version (most common is 64-bit).
2. Choose both options available in installer. “Use admin priviliges when installing py.exe” and “Add python.exe to PATH”. Click “Install now”.
3. Verify Python installation Open Powershell or CMD and type:
```powershell
python --version
```
If properly installed output would look like (with your Python version):
```powershell
Python 3.13.2
```
4. Prepare Esphome for Python. In Powershell prompt type:
```powershell
mkdir $env:USERPROFILE\esphome
cd $env:USERPROFILE\esphome
pip3 install wheel esphome pillow==10.2.0
```
in CMD:
```cmd
mkdir %USERPROFILE%\esphome
cd %USERPROFILE%\esphome
pip3 install wheel esphome pillow==10.2.0
```
5. ESPHome should work now - lets test it! Do it by typeing:
```powershell
esphome version
```
The output should looks like:
```powershell
Version: 2025.x.x
```
The version will differ for you. It's depends on your current version.
Now you’re good to execute next steps.
#### Run ESPHome Dashboard \[!toc] [#run-esphome-dashboard-toc]
In powershell type:
```powershell
cd $env:USERPROFILE\esphome
esphome dashboard .
```
or in CMD
```cmd
cd %USERPROFILE%\esphome
esphome dashboard .
```
Check it out opening page in your web browser [http://127.0.0.1:6052](http://127.0.0.1:6052) If it’s loaded then you can go to next section: [Connect with Esphome Addon](#connect-with-esphome-addon) or if you prefer USB installation go to [USB Only installation](#usb-only-installation).
#### Upgrade ESPHome \[!toc] [#upgrade-esphome-toc]
To upgrade your ESPHome in windows you need to:
```powershell
pip3 install --upgrade esphome
```
### Linux [#linux]
Fetch Esphome docker image / Linux / Mac OS
Run following command in terminal:
```bash
docker pull ghcr.io/esphome/esphome
```
Run Esphome dashboard
Now let’s start Esphome dashboard. Make directory where your config would be stored eg /home/me/esphome
In Linux based system:
```bash
docker run --rm --privileged --network host -v "/home/me/esphome":/config -it ghcr.io/esphome/esphome dashboard .
```
Now in Chrome open website:
under Linux [http://0.0.0.0:6052/](http://0.0.0.0:6052/)
## Connect with ESPHome Device Builder [#connect-with-esphome-device-builder]
**Note**: For this to work your home network must support mDNS. Your PC and boneIO is in same subnet (same VLAN) in most cases it’d work. boneIO has to be connected to your network and working.
1. Find your new boneIO device in the dashboard.
2. Click Adopt
3. Choose name for our new device
4. Click Adopt
5. Now it will prompt for install new software
6. After install there will be logs visible, you can click stop now
Next, set a password and an encryption key on the controller: until you do, anyone on your network can flash it. See [Security](/en/docs/esp/security#after-adoption-in-esphome-builder).
It’s ready, you can edit your config by clicking Edit on your boneIO device.
### Running boneIO without Home Assistant [#running-boneio-without-home-assistant]
If you don’t have HA, then in config find line:
```yaml
api:
```
and add `reboot_timeout: 0s` to it, so it’d look like:
`reboot_timeout: 0s` is default option in our precompiled binaries.
```yaml
api:
reboot_timeout: 0s
```
## USB-Only Installation [#usb-only-installation]
If you don’t want to setup network in boneIO then go with those steps. You'd need to have Esphome dashboard running. For Esphome firmware installation you’d need internet connection on your PC!
1. Go to [https://boneio.eu/esp](https://boneio.eu/esp)
2. Choose your board and choose option "Download yaml for this firmware" in the end.
3. In the top right corner choose Download raw file
4. Copy it to your Esphome directory eg C:/Users/me/esphome. After pasting it, it should appear in Esphome dashboard.
5. Now you can Edit and Install firmware using "Plug into this computer" option. If you need to install some drivers, then Esphome website should show what to download to get it work.
# Edit config file (/en/docs/esp/products/esp_cover_mix/software_setup/how-to-edit-config)
# The Configuration File [#the-configuration-file]
The configuration file for the ESP Cover Mix might seem large, but it's a logical combination of the ESP Cover and ESP 32x10A modules. This guide will walk you through each section.
As an example, we will use a standard `boneio-cover-mix.yaml` configuration.
## Full Configuration Example [#full-configuration-example]
```yaml
substitutions:
name: boneio-cm-07
friendly_name: 'BoneIO ESP Cover Mix'
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.cover-mix
version: '0.7'
# ... (Standard sections like esp32, ethernet, logger, api, ota, etc.)
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.7.1 # Or latest version
files:
# Common device files
- 'devices/buzzer.yaml'
- 'devices/serial_no.yaml'
# ... other common files
# Cover outputs (Top Part - 8 covers = 16 relays)
- 'boards/cover/out01_02.yaml'
- 'boards/cover/out03_04.yaml'
- 'boards/cover/out05_06.yaml'
- 'boards/cover/out07_08.yaml'
- 'boards/cover/out09_10.yaml'
- 'boards/cover/out11_12.yaml'
- 'boards/cover/out13_14.yaml'
- 'boards/cover/out15_16.yaml'
# Relay outputs (Bottom Part - 16 relays)
- 'boards/output/out17_18.yaml'
- 'boards/output/out19_20.yaml'
- 'boards/output/out21_22.yaml'
- 'boards/output/out23_24.yaml'
- 'boards/output/out25_26.yaml'
- 'boards/output/out27_28.yaml'
- 'boards/output/out29_30.yaml'
- 'boards/output/out31_32.yaml'
# Cover section for shutters/blinds
cover:
- platform: time_based
name: 'Cover 01'
id: cover_01
open_action:
- switch.turn_on: cover_open_01_out01
open_duration: 10s
close_action:
- switch.turn_on: cover_close_01_out02
close_duration: 10s
stop_action:
- switch.turn_off: cover_open_01_out01
- switch.turn_off: cover_close_01_out02
# ... (configurations for Cover 02 to Cover 08)
# Light section for relays
light:
- platform: binary
name: 'Light 17'
output: out_17
id: light_17
# ... (configurations for Light 18 to Light 32)
# Binary sensor section for inputs
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
on_press:
then:
- cover.open: cover_01
on_release:
then:
- cover.stop: cover_01
- platform: gpio
name: 'IN_17'
id: in_17
pin:
pcf8574: pcf_inputs_15to32 # Assuming a different PCF for these inputs
number: 2
on_press:
then:
- light.toggle: light_17
```
## Section Explanations [#section-explanations]
### `substitutions` & `esphome` [#substitutions--esphome]
These sections are for naming your controller. Set a `friendly_name` that makes sense for your setup, like "boneIO Cover Mix 1st Floor". The other parameters are for internal identification and project versioning.
### `packages` [#packages]
This is a key section. It loads the hardware definitions from our GitHub repository. For the Cover Mix, it loads two sets of files:
* **`boards/cover/`**: These define the first 16 relays as 8 pairs for controlling covers.
* **`boards/output/`**: These define relays 17 through 32 as individual outputs for lights, switches, etc.
### `cover` Section [#cover-section]
This section is for configuring your roller shutters and venetian blinds (outputs 1-16).
* `platform: time_based`: Use this for standard roller shutters.
* `name`: Set a friendly name for Home Assistant.
* `open_duration` / `close_duration`: **Crucial for calibration!** You must measure the time it takes for your shutter to fully open and close.
For **venetian blinds with tilt control**, you can use the `venetian_blinds` custom platform. This requires adding an `external_components` block at the top of your file and calibrating the `tilt_duration`. For a detailed guide, see the **[Naming Outputs](./naming-outputs)** page.
### `light` / `switch` Section [#light--switch-section]
This section is for configuring your general-purpose relays (outputs 17-32).
* `platform: binary`: Creates a simple on/off light entity.
* `platform: output`: Creates a simple on/off switch entity.
* `name`: Set a friendly name, e.g., 'Garden Light' or 'Garage Power'.
* `output`: Links the entity to a physical relay, e.g., `out_17`.
### `binary_sensor` Section [#binary_sensor-section]
This defines your physical inputs (wall switches). You can link any input to any cover or light action. For example, `IN_01` can control `cover_01`, while `IN_17` can toggle `light_17`.
# Software setup (/en/docs/esp/products/esp_cover_mix/software_setup)
## You've just received your boneIO ESP! [#youve-just-received-your-boneio-esp]
Here are some steps witch will help you to handle it!
Device will come to you with alredy preinstalled ESPHome. boneIO is provided with default configuration, you need to adjust it for your needs.
Software installed on the device might be outdated. It's always good thing to update it.
Below you will find some necessary steps to start with boneiO ESP:
# How are inputs defined? (/en/docs/esp/products/esp_cover_mix/software_setup/naming-binary)
## Why should you name your inputs? [#why-should-you-name-your-inputs]
Naming your inputs makes working with the controller much easier. It's simpler to remember "Bedroom Button Up" or "Garden Light Switch" than "IN\_01" or "IN\_17", right?
## Binary Sensors Explained [#binary-sensors-explained]
Your physical inputs (like wall switches) are configured in the `binary_sensor:` section of your YAML file. You can link any input to control any output (either a cover or a relay).
### Example 1: Controlling a Cover [#example-1-controlling-a-cover]
Here's how to configure two inputs (`IN_01` and `IN_02`) to control a single cover (`cover_01`) using momentary switches. This is ideal for up/down control.
```yaml
binary_sensor:
# Button to Open Cover 1
- platform: gpio
name: 'Living Room Cover Up'
id: in_01
pin:
pcf8574: pcf_inputs_1to14
number: 0
on_press:
then:
- cover.open: cover_01
on_release:
then:
- cover.stop: cover_01
# Button to Close Cover 1
- platform: gpio
name: 'Living Room Cover Down'
id: in_02
pin:
pcf8574: pcf_inputs_1to14
number: 1
on_press:
then:
- cover.close: cover_01
on_release:
then:
- cover.stop: cover_01
```
**Key Parameters:**
* `name`: Set a friendly name for the switch, e.g., `'Bedroom Blind Up'`.
* `on_press` / `on_release`: These actions control the cover. `on_press` starts the movement, and `on_release` stops it.
### Example 2: Controlling a Relay (Light) [#example-2-controlling-a-relay-light]
Here's how to configure an input (`IN_17`) to toggle a relay (`light_17`) with a single press of a momentary switch.
```yaml
binary_sensor:
- platform: gpio
name: 'Garden Light Switch'
id: in_17
pin:
pcf8574: pcf_inputs_15to32 # Or the correct PCF for this input range
number: 2 # Corresponds to IN_17
on_press:
then:
- light.toggle: light_17
```
**Key Parameters:**
* `name`: Set a friendly name for the switch, e.g., `'Garage Light Switch'`.
* `on_press`: The `light.toggle` action will turn the light on if it's off, and off if it's on.
# Zdefiniuj Wyjścia i Rolety (Cover Mix) (/en/docs/esp/products/esp_cover_mix/software_setup/naming-outputs)
## What are outputs? [#what-are-outputs]
The boneIO ESP Cover Mix has two types of outputs:
* **Cover Outputs (1-16):** Eight pairs of relays designed to control up to 8 roller shutters or venetian blinds.
* **Relay Outputs (17-32):** Sixteen individual relays for general-purpose use, such as lights or switches.
## Why should you name them? [#why-should-you-name-them]
Naming your outputs makes working with the controller much easier. It's simpler to remember "Living Room Cover" or "Garden Light" than "Cover 01" or "Light 17", right?
***
## Part 1: Naming Cover Outputs (1-16) [#part-1-naming-cover-outputs-1-16]
This section covers the top part of the module, which controls up to 8 covers.
### Roller Shutter Control (`time_based`) [#roller-shutter-control-time_based]
This is the standard configuration for typical roller shutters without tilt control.
```yaml
cover:
- platform: time_based
name: 'Living Room Cover'
id: cover_01
open_duration: 22s
close_duration: 21s
# ... other parameters are pre-configured
```
**Key Parameters:**
* `name`: Set a friendly name for Home Assistant, e.g., `'Bedroom Cover'`.
* `open_duration` / `close_duration`: **Crucial for calibration!** You must measure the time it takes for the shutter to fully open and close.
### Venetian Blinds Control with Tilt (`venetian_blinds`) [#venetian-blinds-control-with-tilt-venetian_blinds]
For venetian blinds, you can control the tilt of the slats using the `venetian_blinds` custom platform.
For detailed instructions on how to set up the custom component, see the **[How to Edit Config File](./how-to-edit-config)** guide.
```yaml
cover:
- platform: venetian_blinds
name: 'Bedroom Blind'
id: blind_01
open_duration: 22s
close_duration: 21s
tilt_duration: 1500ms
# ... other parameters are pre-configured
```
**Additional Parameter:**
* `tilt_duration`: **Crucial for calibration!** The time in milliseconds it takes for the slats to tilt from fully closed to fully open.
***
## Part 2: Naming Relay Outputs (17-32) [#part-2-naming-relay-outputs-17-32]
This section covers the bottom part of the module, which provides 16 general-purpose relays.
You can configure these outputs as `light` entities (simple on/off) or `switch` entities.
### As `light` entities [#as-light-entities]
```yaml
light:
- platform: binary
name: "Garden Light"
output: out_17
id: light_17
- platform: binary
name: "Garage Light"
output: out_18
id: light_18
```
**Key Parameters:**
* `name`: The friendly name for the light in Home Assistant.
* `output`: Links the light to a physical relay (`out_17` to `out_32`).
### As `switch` entities [#as-switch-entities]
```yaml
switch:
- platform: output
name: "Circulation Pump"
output: out_17
id: switch_17
- platform: output
name: "Garage Power"
output: out_18
id: switch_18
```
**Key Parameters:**
* `name`: The friendly name for the switch in Home Assistant.
* `output`: Links the switch to a physical relay (`out_17` to `out_32`).
# Internal Automations (/en/docs/esp/products/dimmer/gen1/software_setup/create-automations)
## Czym są Automatyzacje Wewnętrzne? [#czym-są-automatyzacje-wewnętrzne]
Automatyzacje wewnętrzne to potężny sposób na tworzenie prostych, kluczowych automatyzacji, które działają bezpośrednio na Twoim sterowniku boneIO ESP. Oznacza to, że będą działać nawet wtedy, gdy Twoja główna centrala inteligentnego domu (jak Home Assistant) będzie offline. Są idealne do obsługi krytycznych funkcji, takich jak włączanie światła za pomocą przełącznika naściennego.
### Podstawowa automatyzacja: Przełączanie światła [#podstawowa-automatyzacja-przełączanie-światła]
Zacznijmy od domyślnej konfiguracji, która łączy naciśnięcie przycisku ze światłem.
```yaml
binary_sensor:
- platform: gpio
name: 'IN_01_Przycisk_Sypialnia1'
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_press: # To jest nasz wyzwalacz automatyzacji
then:
- light.toggle: lchl_01 # To jest akcja do wykonania
light:
- platform: monochromatic
output: chl01
name: 'CHL 01'
id: chl_01
default_transition_length: 2s
gamma_correct: 0
```
W sekcji `on_press:` definiujemy, co dzieje się po naciśnięciu przycisku.\
Akcja `- light.toggle: lchl_01` przełączy stan światła o identyfikatorze `light_01`.
## Zaawansowana automatyzacja: Multi-Click (Wielokrotne Kliknięcie) [#zaawansowana-automatyzacja-multi-click-wielokrotne-kliknięcie]
ESPHome pozwala zdefiniować wiele akcji dla jednego przycisku w zależności od sposobu jego naciśnięcia (pojedyncze, podwójne lub długie naciśnięcie). Służy do tego komponent `on_multi_click`.
Skonfigurujmy jeden przycisk (`in_01`) do sterowania trzema różnymi światłami.
### 1. Cel [#1-cel]
* **Pojedyncze kliknięcie**: Przełącz `chl_01`.
* **Podwójne kliknięcie**: Przełącz `chl_02`.
* **Długie naciśnięcie**: Przełącz `chl_03`.
### 2. Konfiguracja [#2-konfiguracja]
Najpierw upewnij się, że masz zdefiniowane swoje światła. Następnie w konfiguracji `binary_sensor` zamień `on_press` na `on_multi_click`.
```yaml
# Upewnij się, że te światła są zdefiniowane w innej części Twojej konfiguracji
light:
- platform: monochromatic
output: chl01
name: 'CHL 01'
id: chl_01
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl02
name: 'CHL 02'
id: chl_02
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl03
name: 'CHL 03'
id: chl_03
default_transition_length: 2s
gamma_correct: 0
# Teraz skonfiguruj automatyzację multi-click
binary_sensor:
- platform: gpio
name: 'IN_01_Przycisk_MultiClick'
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_multi_click:
# Uwaga: Kolejność ma znaczenie! ESPHome sprawdza od góry do dołu.
# Najlepiej jest definiować najbardziej złożone wzorce (najdłuższe kliknięcia) jako pierwsze.
# 1. Akcja dla długiego naciśnięcia
- timing:
- ON for at least 1.4s
then:
- logger.log: 'Wykryto długie naciśnięcie, przełączam Światło 1'
- light.toggle: chl_01
# 2. Akcja dla podwójnego kliknięcia
- timing:
- ON for at most 1s
- OFF for at most 0.5s
- ON for at most 1s
- OFF for at least 0.2s
then:
- logger.log: 'Wykryto podwójne kliknięcie, przełączam Światło 2'
- light.toggle: chl_02
# 3. Akcja dla pojedynczego kliknięcia
- timing:
- ON for at most 1s
- OFF for at least 0.5s
then:
- logger.log: 'Wykryto pojedyncze kliknięcie, przełączam Światło 3'
- light.toggle: chl_03
```
### 3. Jak to działa? [#3-jak-to-działa]
Automatyzacja `on_multi_click` sprawdza sekwencję bloków `timing` od góry do dołu. Wykonywany jest pierwszy, który pasuje do wzorca naciśnięcia przycisku przez użytkownika.
* `timing`: Definiuje wzorzec stanów ON (wciśnięty) i OFF (puszczony). Możesz dostosować wartości czasu (np. `at most 1s`, `at least 0.5s`), aby precyzyjnie dostroić responsywność, ale domyślne ustawienia są zazwyczaj dobrym punktem wyjścia.
* `then`: Ten blok zawiera akcje do wykonania, gdy wzorzec `timing` zostanie dopasowany. Dodaliśmy akcję `logger.log`, która jest bardzo pomocna przy debugowaniu automatyzacji w logach urządzenia.
Układając kliknięcia od najbardziej złożonego (długie naciśnięcie) do najprostszego (pojedyncze kliknięcie), zapewniasz, że długie naciśnięcie nie wywoła również akcji pojedynczego kliknięcia.
## Rozjaśnianie świateł przy pomocy przycisku [#rozjaśnianie-świateł-przy-pomocy-przycisku]
```yaml
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs
number: 1
mode:
input: true
inverted: true
on_press:
then:
- while:
condition:
binary_sensor.is_on: in_01
then:
- if:
condition:
lambda: 'return id(chl_01).current_values.get_brightness() >= 0.90f;'
then:
- light.control:
id: chl_01
brightness: 0%
- light.turn_off:
id: chl_01
else:
- light.dim_relative:
id: chl_01
relative_brightness: 5%
transition_length: 0.2s
- delay: 200ms
```
### Jak to działa? [#jak-to-działa]
* **Wyzwalacz `on_press`**: Automatyzacja uruchamia się przy naciśnięciu przycisku i natychmiast wchodzi w pętlę `while`.
* **`while` z warunkiem**: `binary_sensor.is_on: in_01` utrzymuje działanie pętli tak długo, jak długo przycisk jest fizycznie wciśnięty.
* **Próg jasności**: `lambda: 'return id(chl_01).current_values.get_brightness() >= 0.90f;'` odczytuje aktualną jasność światła `chl_01` (0.0–1.0). Gdy osiągnie ≥ 90%, wykonywana jest sekwencja wyłączenia:
* `light.control: brightness: 0%` ustawia jasność na 0 bez przejścia,
* `light.turn_off` wyłącza światło, aby upewnić się, że jest w stanie OFF.
* **Rozjaśnianie krokiem**: Jeśli próg nie został osiągnięty, `light.dim_relative: relative_brightness: 5%` zwiększa jasność o 5% z krótkim przejściem `0.2s`.
* **Kadencja zmian**: `delay: 200ms` ustala tempo powtarzania kroku w pętli (co 200 ms) aż do puszczenia przycisku lub osiągnięcia progu.
#### Wskazówki [#wskazówki]
* Upewnij się, że światło o `id: chl_01` jest zdefiniowane w konfiguracji `light:` (jak w przykładach powyżej).
* Chcesz ściemniać zamiast rozjaśniać? Użyj wartości ujemnej, np. `relative_brightness: -5%`.
* Dostosuj `5%`, `0.2s` i `200ms`, aby zmienić wielkość kroku, płynność i szybkość reakcji.
## Multi-Click: Pojedynczy klik — toggle, krótkie przytrzymanie — ściemnianie [#multi-click-pojedynczy-klik--toggle-krótkie-przytrzymanie--ściemnianie]
Poniższy przykład nie był testowany w środowisku produkcyjnym — może wymagać dostosowań, aby działał poprawnie.
```yaml
binary_sensor:
- platform: gpio
name: 'IN_01_MultiClick_Sciemniaj'
id: in_01
pin:
pcf8574: pcf_inputs
number: 1
mode:
input: true
inverted: true
on_multi_click:
# 1. Krótkie przytrzymanie: ściemnianie podczas trzymania
- timing:
- ON for at least 0.6s
then:
- while:
condition:
binary_sensor.is_on: in_01
then:
- light.dim_relative:
id: chl_01
relative_brightness: -5%
transition_length: 0.2s
- delay: 200ms
# 2. Pojedynczy klik: przełącz światło
- timing:
- ON for at most 0.5s
- OFF for at least 0.2s
then:
- light.toggle: chl_01
```
### Jak to działa? [#jak-to-działa-1]
* **Kolejność wzorców**: Krótszy wzorzec pojedynczego kliknięcia jest na dole, aby nie „przechwytywał” przytrzymania.
* **Ściemniaj podczas trzymania**: Gdy przycisk jest ON co najmniej `0.6s`, zaczyna działać pętla, która co `200ms` zmniejsza jasność o `5%` aż do puszczenia.
* **Dostosowanie progów**: Zmieniaj `0.6s`, `0.5s` i `0.2s`, aby dostroić rozpoznawanie gestów — zależą od typu przycisku i oczekiwanej responsywności.
## Zmiana barwy RGBW przy kliknięciu [#zmiana-barwy-rgbw-przy-kliknięciu]
Poniższy przykład nie był testowany w środowisku produkcyjnym — może wymagać dostosowań, aby działał poprawnie.
```yaml
# Paleta kolorów dostępna jako select (widoczna w Home Assistant)
select:
- platform: template
name: "RGBW Color Preset"
id: rgbw_palette
optimistic: true
options:
- White
- Red
- Green
- Blue
- Cyan
- Magenta
- Yellow
- Amber
- Purple
set_action:
# White (kanał W)
- if:
condition:
lambda: 'return id(rgbw_palette).state == "White";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
white: 100%
red: 0%
green: 0%
blue: 0%
# Red
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Red";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 100%
green: 0%
blue: 0%
white: 0%
# Green
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Green";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 0%
green: 100%
blue: 0%
white: 0%
# Blue
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Blue";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 0%
green: 0%
blue: 100%
white: 0%
# Cyan
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Cyan";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 0%
green: 100%
blue: 100%
white: 0%
# Magenta
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Magenta";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 100%
green: 0%
blue: 100%
white: 0%
# Yellow
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Yellow";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 100%
green: 100%
blue: 0%
white: 0%
# Amber
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Amber";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 100%
green: 60%
blue: 0%
white: 0%
# Purple
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Purple";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 60%
green: 0%
blue: 100%
white: 0%
# Klik = następny kolor z palety
binary_sensor:
- platform: gpio
id: in_01
name: "IN_01_Color_Next"
pin:
pcf8574: pcf_inputs
number: 1
mode:
input: true
inverted: true
on_press:
then:
- select.next: rgbw_palette
```
### Jak to działa? [#jak-to-działa-2]
* **Paleta jako `select`**: Umożliwia wybór i podgląd aktualnego koloru również z poziomu Home Assistant.
* **`select.next` na klik**: Każde naciśnięcie przechodzi do kolejnego presetu i ustawia barwę na `rgbw_l`.
* **Przewidywalność**: Ustalona lista (White, Red, Green, …) ułatwia obsługę i szybki powrót do bieli.
#### Wskazówki [#wskazówki-1]
* Upewnij się, że masz zdefiniowaną lampę `rgbw_l` (typ RGBW) w sekcji `light:`.
* Możesz dodać podwójny klik do szybkiego powrotu na „White” lub długie przytrzymanie do ściemniania/rozjaśniania.
# Connect your boneIO ESP (/en/docs/esp/products/dimmer/gen1/software_setup/how-to-connect)
# Let's install the ESPHome Device Builder! [#lets-install-the-esphome-device-builder]
There are 3 options to connect to your boneIO ESP:
1. [Using Home Assistant addon](#using-home-assistant-addon)
2. [Using Esphome Device Builder on your PC](#using-esphome-device-builder-on-your-pc)
## ESPHome Device Builder in Home Assistant [#esphome-device-builder-in-home-assistant]
Installing the ESPHome Device Builder add-on is pretty simple. Just follow these steps:
1. Go to the **Settings > Add-ons** section in your Home Assistant.
2. Click the **Add-on Store** button in the bottom right corner.
3. In the search bar, type `ESPHome` and select the add-on from the official repository. Make sure you don't use beta or dev versions, as they are for testing purposes only.
4. Click **Install**.
After the installation is complete, go to the **Configuration** tab and enable the **Start on boot** and **Show in sidebar** options. This will make it easier to access ESPHome Device Builder in the future.
Finally, go to the **Info** tab and click **Start** to run the add-on. You will now see ESPHome Device Builder in your sidebar!
## ESPHome Device Builder on Your PC [#esphome-device-builder-on-your-pc]
If you don't use Home Assistant (HA), you can still edit your boneIO ESP's configuration.
Editing Esphome config without HA, just on your PC is also possible. Similar instruction is here: [https://esphome.io/guides/getting\_started\_command\_line](https://esphome.io/guides/getting_started_command_line)
On your PC, you will need one of the following:
* for Linux: Docker,
* for Windows: Python 3.13 installed.
### Windows [#windows]
We assume that you are running Windows 10 or 11 - its important to have your administrative privileges, also you need internet connection.
Let's do it step by step!
1. Download Python installer from Python download page for Windows Choose Windows installer according to your operating system version (most common is 64-bit).
2. Choose both options available in installer. “Use admin priviliges when installing py.exe” and “Add python.exe to PATH”. Click “Install now”.
3. Verify Python installation Open Powershell or CMD and type:
```powershell
python --version
```
If properly installed output would look like (with your Python version):
```powershell
Python 3.13.2
```
4. Prepare Esphome for Python. In Powershell prompt type:
```powershell
mkdir $env:USERPROFILE\esphome
cd $env:USERPROFILE\esphome
pip3 install wheel esphome pillow==10.2.0
```
in CMD:
```cmd
mkdir %USERPROFILE%\esphome
cd %USERPROFILE%\esphome
pip3 install wheel esphome pillow==10.2.0
```
5. ESPHome should work now - lets test it! Do it by typeing:
```powershell
esphome version
```
The output should looks like:
```powershell
Version: 2025.x.x
```
The version will differ for you. It's depends on your current version.
Now you’re good to execute next steps.
#### Run ESPHome Dashboard \[!toc] [#run-esphome-dashboard-toc]
In powershell type:
```powershell
cd $env:USERPROFILE\esphome
esphome dashboard .
```
or in CMD
```cmd
cd %USERPROFILE%\esphome
esphome dashboard .
```
Check it out opening page in your web browser [http://127.0.0.1:6052](http://127.0.0.1:6052) If it’s loaded then you can go to next section: [Connect with Esphome Addon](#connect-with-esphome-addon) or if you prefer USB installation go to [USB Only installation](#usb-only-installation).
#### Upgrade ESPHome \[!toc] [#upgrade-esphome-toc]
To upgrade your ESPHome in windows you need to:
```powershell
pip3 install --upgrade esphome
```
### Linux [#linux]
Fetch Esphome docker image / Linux / Mac OS
Run following command in terminal:
```bash
docker pull ghcr.io/esphome/esphome
```
Run Esphome dashboard
Now let’s start Esphome dashboard. Make directory where your config would be stored eg /home/me/esphome
In Linux based system:
```bash
docker run --rm --privileged --network host -v "/home/me/esphome":/config -it ghcr.io/esphome/esphome dashboard .
```
Now in Chrome open website:
under Linux [http://0.0.0.0:6052/](http://0.0.0.0:6052/)
## Connect with ESPHome Device Builder [#connect-with-esphome-device-builder]
**Note**: For this to work your home network must support mDNS. Your PC and boneIO is in same subnet (same VLAN) in most cases it’d work. boneIO has to be connected to your network and working.
1. Find your new boneIO device in the dashboard.
2. Click Adopt
3. Choose name for our new device
4. Click Adopt
5. Now it will prompt for install new software
6. After install there will be logs visible, you can click stop now
Next, set a password and an encryption key on the controller: until you do, anyone on your network can flash it. See [Security](/en/docs/esp/security#after-adoption-in-esphome-builder).
It’s ready, you can edit your config by clicking Edit on your boneIO device.
### Running boneIO without Home Assistant [#running-boneio-without-home-assistant]
If you don’t have HA, then in config find line:
```yaml
api:
```
and add `reboot_timeout: 0s` to it, so it’d look like:
`reboot_timeout: 0s` is default option in our precompiled binaries.
```yaml
api:
reboot_timeout: 0s
```
## USB-Only Installation [#usb-only-installation]
If you don’t want to setup network in boneIO then go with those steps. You'd need to have Esphome dashboard running. For Esphome firmware installation you’d need internet connection on your PC!
1. Go to [https://boneio.eu/esp](https://boneio.eu/esp)
2. Choose your board and choose option "Download yaml for this firmware" in the end.
3. In the top right corner choose Download raw file
4. Copy it to your Esphome directory eg C:/Users/me/esphome. After pasting it, it should appear in Esphome dashboard.
5. Now you can Edit and Install firmware using "Plug into this computer" option. If you need to install some drivers, then Esphome website should show what to download to get it work.
# Edit config file (/en/docs/esp/products/dimmer/gen1/software_setup/how-to-edit-config)
# Configuration file [#configuration-file]
The configuration file might look big and complicated, but it's really not. The file itself is separated into sections, which we will describe below.
For our example, we will use `boneio-dimmer_8ch-v03.yaml`.
So let's begin. Here is the whole config file:
```yaml
substitutions:
name: boneio-dr-8ch-03
friendly_name: 'BoneIO Dimmer LED'
serial_prefix: 'dim' #Don't change it.
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.dimmer-led
version: '0.3'
esp32:
board: esp32dev
framework:
type: esp-idf
external_components:
- source: github://boneIO-eu/esphome-LM75@main #Original source and thank you note for BTomala https://github.com/boneIO-eu/esphome-lm75
components: [lm75]
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.7.1
files:
[
'devices/serial_no.yaml',
'devices/dimmer_i2c.yaml',
'devices/dimmer_ina219.yaml',
'boards/dimmer_output.yaml',
]
ethernet:
id: eth
type: LAN8720
mdc_pin: GPIO23
mdio_pin: GPIO18
clk:
pin: GPIO0
mode: CLK_EXT_IN
phy_addr: 1
power_pin: GPIO16
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-dimmer_8ch-v0_3.yaml@latest
import_full_config: true
pcf8574:
- id: 'pcf_inputs'
address: 0x38
logger:
api:
reboot_timeout: 0s
ota:
- platform: esphome
- platform: web_server
web_server:
port: 80
local: true
text_sensor:
- platform: version
name: 'boneio-dimmer- Version'
icon: mdi:cube-outline
entity_category: diagnostic
- platform: ethernet_info
ip_address:
entity_category: diagnostic
name: boneio-dimmer IP
- platform: template
name: 'Hostname'
id: hostname
entity_category: diagnostic
lambda: |-
return id(eth).get_use_address();
update_interval: 5min
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs
number: 1
mode:
input: true
inverted: true
on_multi_click:
- timing:
- ON for at least 0.7s
then:
- while:
condition:
binary_sensor.is_on: in_01
then:
- if:
condition:
lambda: 'return id(chl_01).current_values.get_brightness() >= 0.90f;'
then:
- light.turn_on:
id: chl_01
brightness: 5%
transition_length: 0.2s
else:
- light.dim_relative:
id: chl_01
relative_brightness: 5%
transition_length: 0.2s
- delay: 200ms
invalid_cooldown: 0.5s
- timing: #single click
- ON for at most 0.4s
- OFF for at least 0.1s
then:
light.toggle: chl_01
invalid_cooldown: 0.5s
- platform: gpio
name: 'IN_02'
id: in_02
pin:
pcf8574: pcf_inputs
number: 2
mode:
input: true
inverted: true
on_multi_click:
- timing:
- ON for at least 0.7s
then:
- while:
condition:
binary_sensor.is_on: in_02
then:
- if:
condition:
lambda: 'return id(chl_02).current_values.get_brightness() >= 0.90f;'
then:
- light.turn_on:
id: chl_02
brightness: 5%
transition_length: 0.2s
else:
- light.dim_relative:
id: chl_02
relative_brightness: 5%
transition_length: 0.2s
- delay: 200ms
invalid_cooldown: 0.5s
- timing: #single click
- ON for at most 0.4s
- OFF for at least 0.1s
then:
light.toggle: chl_02
invalid_cooldown: 0.5s
- platform: gpio
name: 'IN_03'
id: in_03
pin:
pcf8574: pcf_inputs
number: 3
mode:
input: true
inverted: true
on_multi_click:
- timing:
- ON for at least 0.7s
then:
- while:
condition:
binary_sensor.is_on: in_03
then:
- if:
condition:
lambda: 'return id(chl_03).current_values.get_brightness() >= 0.90f;'
then:
- light.turn_on:
id: chl_03
brightness: 5%
transition_length: 0.2s
else:
- light.dim_relative:
id: chl_03
relative_brightness: 5%
transition_length: 0.2s
- delay: 200ms
invalid_cooldown: 0.5s
- timing: #single click
- ON for at most 0.4s
- OFF for at least 0.1s
then:
light.toggle: chl_03
invalid_cooldown: 0.5s
- platform: gpio
name: 'IN_04'
id: in_04
pin:
pcf8574: pcf_inputs
number: 4
mode:
input: true
inverted: true
on_multi_click:
- timing:
- ON for at least 0.7s
then:
- while:
condition:
binary_sensor.is_on: in_04
then:
- if:
condition:
lambda: 'return id(chl_04).current_values.get_brightness() >= 0.90f;'
then:
- light.turn_on:
id: chl_04
brightness: 5%
transition_length: 0.2s
else:
- light.dim_relative:
id: chl_04
relative_brightness: 5%
transition_length: 0.2s
- delay: 200ms
invalid_cooldown: 0.5s
- timing: #single click
- ON for at most 0.4s
- OFF for at least 0.1s
then:
light.toggle: chl_04
invalid_cooldown: 0.5s
- platform: gpio
name: 'IN_05'
id: in_05
pin:
number: 36
mode:
input: true
inverted: true
on_multi_click:
- timing:
- ON for at least 0.7s
then:
- while:
condition:
binary_sensor.is_on: in_05
then:
- if:
condition:
lambda: 'return id(chr_01).current_values.get_brightness() >= 0.90f;'
then:
- light.turn_on:
id: chr_01
brightness: 5%
transition_length: 0.2s
else:
- light.dim_relative:
id: chr_01
relative_brightness: 5%
transition_length: 0.2s
- delay: 200ms
invalid_cooldown: 0.5s
- timing: #single click
- ON for at most 0.4s
- OFF for at least 0.1s
then:
light.toggle: chr_01
invalid_cooldown: 0.5s
- platform: gpio
name: 'IN_06'
id: in_06
pin:
number: 39
mode:
input: true
inverted: true
on_multi_click:
- timing:
- ON for at least 0.7s
then:
- while:
condition:
binary_sensor.is_on: in_06
then:
- if:
condition:
lambda: 'return id(chr_02).current_values.get_brightness() >= 0.90f;'
then:
- light.turn_on:
id: chr_02
brightness: 5%
transition_length: 0.2s
else:
- light.dim_relative:
id: chr_02
relative_brightness: 5%
transition_length: 0.2s
- delay: 200ms
invalid_cooldown: 0.5s
- timing: #single click
- ON for at most 0.4s
- OFF for at least 0.1s
then:
light.toggle: chr_02
invalid_cooldown: 0.5s
- platform: gpio
name: 'IN_07'
id: in_07
pin:
number: 34
mode:
input: true
inverted: true
on_multi_click:
- timing:
- ON for at least 0.7s
then:
- while:
condition:
binary_sensor.is_on: in_07
then:
- if:
condition:
lambda: 'return id(chr_03).current_values.get_brightness() >= 0.90f;'
then:
- light.turn_on:
id: chr_03
brightness: 5%
transition_length: 0.2s
else:
- light.dim_relative:
id: chr_03
relative_brightness: 5%
transition_length: 0.2s
- delay: 200ms
invalid_cooldown: 0.5s
- timing: #single click
- ON for at most 0.4s
- OFF for at least 0.1s
then:
light.toggle: chr_03
invalid_cooldown: 0.5s
- platform: gpio
name: 'IN_08'
id: in_08
pin:
number: 35
mode:
input: true
inverted: true
on_multi_click:
- timing:
- ON for at least 0.7s
then:
- while:
condition:
binary_sensor.is_on: in_08
then:
- if:
condition:
lambda: 'return id(chr_04).current_values.get_brightness() >= 0.90f;'
then:
- light.turn_on:
id: chr_04
brightness: 5%
transition_length: 0.2s
else:
- light.dim_relative:
id: chr_04
relative_brightness: 5%
transition_length: 0.2s
- delay: 200ms
invalid_cooldown: 0.5s
- timing: #single click
- ON for at most 0.4s
- OFF for at least 0.1s
then:
light.toggle: chr_04
invalid_cooldown: 0.5s
light:
- platform: monochromatic
output: chl01
name: 'CHL 01'
id: chl_01
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl02
name: 'CHL 02'
id: chl_02
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl03
name: 'CHL 03'
id: chl_03
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl04
name: 'CHL 04'
id: chl_04
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr01
name: 'CHR 01'
id: chr_01
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr02
name: 'CHR 02'
id: chr_02
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr03
name: 'CHR 03'
id: chr_03
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr04
name: 'CHR 04'
id: chr_04
default_transition_length: 2s
gamma_correct: 0
sensor:
- platform: lm75
id: boneIO_temp
name: 'Temperature'
update_interval: 30s
entity_category: diagnostic
on_value_range:
- above: 70.0
then:
- switch.turn_on: buzzer
- below: 70.0
then:
- switch.turn_off: buzzer
switch:
- platform: gpio
id: buzzer
name: 'Buzzer'
pin:
pcf8574: pcf_inputs
number: 0
mode:
output: true
inverted: true
```
### substitutions [#substitutions]
```yaml
substitutions:
name: boneio-dr-8ch-03
friendly_name: 'BoneIO Dimmer LED'
serial_prefix: 'dim' #Don't change it.
```
This part is mainly responsible for the name of your controller.\
You should focus on `friendly_name`. You should write the exact name of your boneIO here. The name depends on your needs.\
It could be "boneIO Dimmer-G1" if you have one boneIO controller, or for example, "boneIO Dimmer-G1 1st-floor".
### esphome [#esphome]
```yaml
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.dimmer-led
version: '0.3'
```
There are definitions for your controller. You shouldn't change `name` or `friendly_name`. The line `name_add_mac_suffix:` will add a MAC suffix to the controller's name, which is useful for identifying your controller. `project:` is the place where you define the type and version of your controller.
### esp32 [#esp32]
```yaml
esp32:
board: esp32dev
framework:
type: esp-idf
```
Definition of the ESP32 board and the required framework.
### Ethernet [#ethernet]
```yaml
ethernet:
id: eth
type: LAN8720
mdc_pin: GPIO23
mdio_pin: GPIO18
clk:
pin: GPIO0
mode: CLK_EXT_IN
phy_addr: 1
power_pin: GPIO16
```
This part is responsible for the description of your controller's Ethernet port - you shouldn't change anything here.
### dashboard\_import [#dashboard_import]
```yaml
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-dimmer_8ch-v0_3.yaml@latest
import_full_config: true
```
This is the place where the address for our GitHub repository is defined. The config and all additional packages are downloaded from there. There is nothing to change here.
### packages [#packages]
```yaml
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.7.1
files:
[
'devices/serial_no.yaml',
'devices/dimmer_i2c.yaml',
'devices/dimmer_ina219.yaml',
'boards/dimmer_output.yaml',
]
```
Here are definitions of all packages used by boneIO, with the address to our GitHub. You can also find there the definitions of modbus devices.
### logger [#logger]
```yaml
logger:
```
In case of troubleshooting, you can increase the log level to `INFO`, `WARN`, or `DEBUG`. This can be very useful in some cases.
### api [#api]
```yaml
api:
reboot_timeout: 0s
```
Here, the reboot timeout is defined for when the controller loses connection with HA.
If you want your boneIO to restart after losing connection with Home Assistant, you should enter a value that suits you here.
For WiFi connections, the value should not be zero. For LAN connections, not rebooting does not negatively affect the connection with Home Assistant in most cases.
### ota [#ota]
```yaml
ota:
ota:
- platform: esphome
- platform: web_server
```
Part responsible for Over The Air updates. The `web_server` platform allows updating via the device's web panel.
### web\_server [#web_server]
```yaml
web_server:
port: 80
local: true
```
Part responsible for enabling the web server of the controller.
### time [#time]
```yaml
time:
- platform: homeassistant
timezone: Europe/Warsaw
id: homeassistant_time
```
This section is responsible for selecting your controller's time zone. Adjust it to your location.
# Step by step Guide (/en/docs/esp/products/dimmer/gen1/software_setup)
## You just received your boneIO Dimmer Gen1! Here are some steps witch will help you to handle it! [#you-just-received-your-boneio-dimmer-gen1-here-are-some-steps-witch-will-help-you-to-handle-it]
Device will come to you with alredy preinstalled ESPHome. boneIO is provided with default configuration, you need to adjust it for your needs.
Below you will find some necessary steps to start with boneiO Dimmer Gen1:
# How are inputs defined? (/en/docs/esp/products/dimmer/gen1/software_setup/naming-binary)
## Why should you name your inputs? [#why-should-you-name-your-inputs]
Naming your inputs makes working with the controller much easier. It's simpler to remember "Bedroom Button 1" than "IN\_01", right?
### Binary Sensors [#binary-sensors]
Let's look at the default configuration for your inputs, which are defined as `binary_sensor` components.
Here is a complete example of a single input configuration. The most important line for you is `name: 'My First Button'`.
```yaml
binary_sensor:
- platform: gpio
name: 'My First Button'
"This is the friendly name for your input"
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_press:
then:
```
### Configuration Explained [#configuration-explained]
| Section | Description |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `binary_sensor:` | This is the main header for all your binary sensor (input) definitions. |
| `- platform: gpio` | This specifies that the sensor is connected to a General Purpose Input/Output pin. |
| `name: 'My First Button'` | This is the friendly name for your input. It will be visible in Home Assistant and is much easier to identify. You can change it to something descriptive like `'Bedroom Button 1'` or `'IN_01_Living_Room_Motion'`. This is the most important part for you to customize. |
| `id: in_01` | This is a unique identifier used within ESPHome. It's essential for referring to this input in automations, such as the `on_press` action. |
| `pin:` | This section defines the physical pin the sensor is connected to. This part is pre-configured for the boneIO hardware and should not be changed. |
| `inverted: true` | This inverts the logic of the input. It's useful for certain devices like motion sensors, which might have a normally open or normally closed state. |
| `on_press:` | This is an automation that defines what happens when the input is triggered (e.g., a button is pressed). We will cover this in more detail in the automations guide. |
# LED Lights (/en/docs/esp/products/dimmer/gen1/software_setup/naming-outputs)
## What are outputs? [#what-are-outputs]
Outputs are the executive parts of our controller. As dimmer its specialised in controlling lights, we had prepared configurations for few scenarios!
You can control:
* [8 single LED strips](#boneio-dr-8ch-v03),
* [4 CCT LED Strips](#boneio-dr-4cct-v01),
* [2 RGBW LED Strips](#boneio-dr-rgbw-v03).
### Why should you name them? [#why-should-you-name-them]
Naming your outputs will make working with the controller much easier. It's much easier to remember "Bedroom light" than "CHL 01", right?
In our examples, we focus on a part of the configuration, which you can then adjust to your entire configuration.
Let's get started!
## Configure outputs [#configure-outputs]
We have prepared three types of configuration files for you. Which one you should choose depends on what you will use as your outputs.
In most scenarios - most popular output configuration is 8 single LED Strips, so we prepared a configuration with 8 single LED strips outputs!
### 8 single LED strips [#8-single-led-strips]
Below is a part of the default configuration in the file:
```yaml
boneio-dimmer_8ch-v03.yaml
```
We are looking for the part with the `light:` header.
```yaml
light:
- platform: monochromatic
output: chl01
name: 'CHL 01'
id: chl_01
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl02
name: 'CHL 02'
id: chl_02
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl03
name: 'CHL 03'
id: chl_03
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl04
name: 'CHL 04'
id: chl_04
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr01
name: 'CHR 01'
id: chr_01
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr02
name: 'CHR 02'
id: chr_02
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr03
name: 'CHR 03'
id: chr_03
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr04
name: 'CHR 04'
id: chr_04
default_transition_length: 2s
gamma_correct: 0
```
* `- platform: monochromatic` - Defines the component type. `monochromatic` is used for brightness control of single color LED strip.
* `output: chl01` – This links the light to a specific physical output defined elsewhere in the configuration.
* `name: 'CHL 04'` – This is the friendly name of the output that will be visible in Home Assistant. You can change it freely, for example, to `Bedroom Light` or `CHL_01_Bedroom`.
* `id: chl_01` – This is a unique identifier used within the ESPHome configuration. It allows you to control this light from automations or other components (e.g., `light.toggle: chl_01`).
* `default_transition_length: 2s` - time of the transition on/off.
### 4 CCT LED Strips [#4-cct-led-strips]
Below is a part of the default configuration in the file:
```yaml
boneio-dimmer_4cct-v03.yaml
```
We are looking for the part with the `light` header :
```yaml
light:
- platform: cwww
name: 'CHL_01_02'
id: chl_01_02
cold_white: chl01
warm_white: chl02
cold_white_color_temperature: 6536 K
warm_white_color_temperature: 2000 K
- platform: cwww
name: 'CHL_03_04'
id: chl_03_04
cold_white: chl03
warm_white: chl04
cold_white_color_temperature: 6536 K
warm_white_color_temperature: 2000 K
- platform: cwww
name: 'CHR_01_02'
id: chr_01_02
cold_white: chr01
warm_white: chr02
cold_white_color_temperature: 6536 K
warm_white_color_temperature: 2000 K
- platform: cwww
name: 'CHR_03_04'
id: chr_03_04
cold_white: chr03
warm_white: chr04
cold_white_color_temperature: 6536 K
warm_white_color_temperature: 2000 K
```
* `- platform: cwww` - Defines the component type. `cwww` is used for brightness control, and color temperatoure of the single Cold White / Warm White LED strip.
* `name: 'CHL_01_02'` – This is the friendly name of the output that will be visible in Home Assistant. You can change it freely, for example, to `Bedroom Light` or `CHL_01_02_Bedroom`.
* `id: 'chl_01_02'` – This is a unique identifier used within the ESPHome configuration. It allows you to control this light from automations or other components (e.g., `light.toggle: chl_01`).
* `cold_white: 'chl01'` - This links the light to a specific physical output defined elsewhere in the configuration.
* `warm_white: 'chl02'` - This links the light to a specific physical output defined elsewhere in the configuration.
* `cold_white_color_temperature:` - Here you can set specific color temperature of your cold white led strip.
* `warm_white_color_temperature:` - Here you can set specific color temperature of your warm white led strip.
### 2 RGBW LED Strips [#2-rgbw-led-strips]
Below is a part of the default configuration in the file:
```yaml
boneio-dimmer_2rgbw-v03.yaml
```
We are looking for the part with the `light` header:
```yaml
light:
- platform: rgbw
id: rgbw_l
name: 'RGBW L'
red: chl01
green: chl02
blue: chl03
white: chl04
default_transition_length: 2s
gamma_correct: 0
- platform: rgbw
id: rgbw_r
name: 'RGBW R'
red: chr01
green: chr02
blue: chr03
white: chr04
default_transition_length: 2s
gamma_correct: 0
```
* `- platform: rgbw` - Defines the component type. `rgbw` is used for controling popular RGBW LED strips.
* `name: 'RGBW L'` – This is the friendly name of the output that will be visible in Home Assistant. You can change it freely, for example, to `Bedroom Light` or `RGBW_L_Bedroom`.
* `id: 'rgbw_l'` – This is a unique identifier used within the ESPHome configuration. It allows you to control this light from automations or other components (e.g., `light.toggle: chl_01`).
* `red: 'chl01'` - This links the light color to a specific physical output defined elsewhere in the configuration.
* `green: 'chl02'` - This links the light color to a specific physical output defined elsewhere in the configuration.
* `blue: 'chl03'` - This links the light color to a specific physical output defined elsewhere in the configuration.
* `white: 'chl0'` - This links the light color to a specific physical output defined elsewhere in the configuration.
* `default_transition_length: 2s` - the time of transition.
* `gamma_correct: 0` - Here you can correct gamma of the strip.
### Customize it! [#customize-it]
Do you have 2 CCT strips and one RGBW strip? No problem, just modify the appropriate part of the `yaml` file according to your needs!
```yaml
light:
- platform: rgbw
id: rgbw_l
name: 'RGBW L'
red: chl01
green: chl02
blue: chl03
white: chl04
default_transition_length: 2s
gamma_correct: 0
- platform: cwww
name: 'CHR_01_02'
id: chr_01_02
cold_white: chr01
warm_white: chr02
cold_white_color_temperature: 6536 K
warm_white_color_temperature: 2000 K
- platform: cwww
name: 'CHR_03_04'
id: chr_03_04
cold_white: chr03
warm_white: chr04
cold_white_color_temperature: 6536 K
warm_white_color_temperature: 2000 K
```
What have we done? For the left section of the controller - where we connected the RGBW strip - we applied the configuration from the `boneio-dimmer_gen2_2rgbw-v01.yaml` file. However, for the right section of the controller, we are connecting 2 CCT strips! How did we configure it? It's simple: we used the part of the configuration from the `boneio-dimmer_gen2_4cct-v01.yaml` file that is dedicated to the right section of the controller. Thanks to this, a single boneIO Dimmer supports 2 CCT strips and one RGBW strip!
# Internal Automations (/en/docs/esp/products/dimmer/gen2/software_setup/create-automations)
## What are Internal Automations? [#what-are-internal-automations]
Internal automations are a powerful way to create simple, core automations that run directly on your boneIO ESP controller. This means they will work even if your main smart home hub (like Home Assistant) is offline. They are perfect for critical functions, like turning on a light with a wall switch.
### Basic Automation: Toggling a Light [#basic-automation-toggling-a-light]
Let's start with a default configuration that links a button press to a light.
```yaml
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_press: # This is our automation trigger
then:
- light.toggle: chl_01 # This is the action to perform
light:
- platform: monochromatic
output: chl01
name: 'CHL 01'
id: chl_01
default_transition_length: 2s
gamma_correct: 0
```
In the `on_press:` section, we define what happens when the button is pressed.\
The action `- light.toggle: chl_01` will toggle the state of the light with the ID `chl_01`.
## Advanced Automation: Multi-Click [#advanced-automation-multi-click]
ESPHome allows you to define multiple actions for a single button based on how it's pressed (single, double, or long press). This is done using the `on_multi_click` component.
Let's configure one button (`in_01`) to control three different lights.
### 1. The Goal [#1-the-goal]
* **Single Click**: Toggle `chl_01`.
* **Double Click**: Toggle `chl_02`.
* **Long Press**: Toggle `chl_03`.
### 2. The Configuration [#2-the-configuration]
First, ensure you have your lights defined. Then, in your `binary_sensor` configuration, replace `on_press` with `on_multi_click`.
```yaml
# Ensure these lights are defined elsewhere in your config
light:
- platform: monochromatic
output: chl01
name: 'CHL 01'
id: chl_01
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl02
name: 'CHL 02'
id: chl_02
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl03
name: 'CHL 03'
id: chl_03
default_transition_length: 2s
gamma_correct: 0
# Now, configure the multi-click automation
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_multi_click:
# Note: The order matters! ESPHome checks from top to bottom.
# It's best to define the most complex patterns (longest clicks) first.
# 1. Long Click Action
- timing:
- ON for at least 1.4s
then:
- logger.log: 'Long Click Detected, toggling Light 1'
- light.toggle: chl_01
# 2. Double Click Action
- timing:
- ON for at most 1s
- OFF for at most 0.5s
- ON for at most 1s
- OFF for at least 0.2s
then:
- logger.log: 'Double Click Detected, toggling Light 2'
- light.toggle: chl_02
# 3. Single Click Action
- timing:
- ON for at most 1s
- OFF for at least 0.5s
then:
- logger.log: 'Single Click Detected, toggling Light 3'
- light.toggle: chl_03
```
### 3. How It Works [#3-how-it-works]
The `on_multi_click` automation checks a sequence of `timing` blocks from top to bottom. The first one that matches the user's button press pattern is executed.
* `timing`: This defines the pattern of ON (pressed) and OFF (released) states. You can adjust the time values (e.g., `at most 1s`, `at least 0.5s`) to fine-tune the responsiveness, but the defaults are usually a good starting point.
* `then`: This block contains the actions to be performed when the `timing` pattern is matched. We've included a `logger.log` action, which is very helpful for debugging your automations in the device logs.
By arranging the clicks from most complex (long press) to least complex (single press), you ensure that a long press doesn't also trigger the single press action.
## Brightening lights with a button hold [#brightening-lights-with-a-button-hold]
```yaml
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs
number: 1
mode:
input: true
inverted: true
on_press:
then:
- while:
condition:
binary_sensor.is_on: in_01
then:
- if:
condition:
lambda: 'return id(chl_01).current_values.get_brightness() >= 0.90f;'
then:
- light.control:
id: chl_01
brightness: 0%
- light.turn_off:
id: chl_01
else:
- light.dim_relative:
id: chl_01
relative_brightness: 5%
transition_length: 0.2s
- delay: 200ms
```
### How it works [#how-it-works]
* **`on_press` trigger**: Starts the automation when the button is pressed and immediately enters a `while` loop.
* **`while` with condition**: `binary_sensor.is_on: in_01` keeps looping for as long as the button remains physically pressed.
* **Brightness threshold**: `lambda: 'return id(chl_01).current_values.get_brightness() >= 0.90f;'` reads the current brightness of `chl_01` (0.0–1.0). Once it reaches ≥ 90%, it executes a shutdown sequence:
* `light.control: brightness: 0%` sets brightness to 0 without a transition,
* `light.turn_off` ensures the light is OFF.
* **Step brightening**: If the threshold is not reached, `light.dim_relative: relative_brightness: 5%` increases brightness by 5% with a short `0.2s` transition.
* **Update cadence**: `delay: 200ms` sets the step frequency (every 200 ms) until the button is released or the threshold is reached.
#### Tips [#tips]
* Ensure a light with `id: chl_01` exists in your `light:` configuration (see examples above).
* Want to dim instead of brighten? Use a negative value, e.g. `relative_brightness: -5%`.
* Adjust `5%`, `0.2s`, and `200ms` to change step size, smoothness, and responsiveness.
## Multi-Click: Single click — toggle, short hold — dimming [#multi-click-single-click--toggle-short-hold--dimming]
This code hasn't been tested in real life — it may not work without additional fixes.
```yaml
binary_sensor:
- platform: gpio
name: 'IN_01_MultiClick_Dim'
id: in_01
pin:
pcf8574: pcf_inputs
number: 1
mode:
input: true
inverted: true
on_multi_click:
# 1. Short hold: dim while holding
- timing:
- ON for at least 0.6s
then:
- while:
condition:
binary_sensor.is_on: in_01
then:
- light.dim_relative:
id: chl_01
relative_brightness: -5%
transition_length: 0.2s
- delay: 200ms
# 2. Single click: toggle the light
- timing:
- ON for at most 0.5s
- OFF for at least 0.2s
then:
- light.toggle: chl_01
```
### How it works [#how-it-works-1]
* **Pattern order**: The shorter single-click pattern is placed last so it doesn't intercept the hold gesture.
* **Dim while holding**: After `ON for at least 0.6s`, a loop reduces brightness by `5%` every `200ms` until release.
* **Tuning thresholds**: Adjust `0.6s`, `0.5s`, and `0.2s` to fine-tune gesture detection based on your button hardware and responsiveness needs.
## Change RGBW color on click [#change-rgbw-color-on-click]
This code hasn't been tested in real life — it may not work without additional fixes.
This example cycles through a predictable color palette on each click, so it's easy to reach common presets and return to white.
```yaml
# Color palette exposed as a select (visible in Home Assistant)
select:
- platform: template
name: "RGBW Color Preset"
id: rgbw_palette
optimistic: true
options:
- White
- Red
- Green
- Blue
- Cyan
- Magenta
- Yellow
- Amber
- Purple
set_action:
# White (uses W channel)
- if:
condition:
lambda: 'return id(rgbw_palette).state == "White";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
white: 100%
red: 0%
green: 0%
blue: 0%
# Red
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Red";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 100%
green: 0%
blue: 0%
white: 0%
# Green
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Green";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 0%
green: 100%
blue: 0%
white: 0%
# Blue
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Blue";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 0%
green: 0%
blue: 100%
white: 0%
# Cyan
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Cyan";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 0%
green: 100%
blue: 100%
white: 0%
# Magenta
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Magenta";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 100%
green: 0%
blue: 100%
white: 0%
# Yellow
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Yellow";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 100%
green: 100%
blue: 0%
white: 0%
# Amber
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Amber";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 100%
green: 60%
blue: 0%
white: 0%
# Purple
- if:
condition:
lambda: 'return id(rgbw_palette).state == "Purple";'
then:
- light.turn_on:
id: rgbw_l
brightness: 80%
red: 60%
green: 0%
blue: 100%
white: 0%
# Click = next color in the palette
binary_sensor:
- platform: gpio
id: in_01
name: "IN_01_Color_Next"
pin:
pcf8574: pcf_inputs
number: 1
mode:
input: true
inverted: true
on_press:
then:
- select.next: rgbw_palette
```
### How it works [#how-it-works-2]
* **Palette as `select`**: Lets you view and choose the current color from Home Assistant as well.
* **`select.next` on click**: Each press advances to the next preset and applies it to `rgbw_l`.
* **Predictable set**: A fixed list (White, Red, Green, …) makes operation simple and returning to White easy.
#### Tips [#tips-1]
* Make sure a `rgbw_l` RGBW light is defined in your `light:` configuration.
* Optionally add double-click to jump to White, or a hold to dim/brighten.
# Connect your boneIO ESP (/en/docs/esp/products/dimmer/gen2/software_setup/how-to-connect)
# Let's install the ESPHome Device Builder! [#lets-install-the-esphome-device-builder]
There are 3 options to connect to your boneIO ESP:
1. [Using Home Assistant addon](#using-home-assistant-addon)
2. [Using Esphome Device Builder on your PC](#using-esphome-device-builder-on-your-pc)
## ESPHome Device Builder in Home Assistant [#esphome-device-builder-in-home-assistant]
Installing the ESPHome Device Builder add-on is pretty simple. Just follow these steps:
1. Go to the **Settings > Add-ons** section in your Home Assistant.
2. Click the **Add-on Store** button in the bottom right corner.
3. In the search bar, type `ESPHome` and select the add-on from the official repository. Make sure you don't use beta or dev versions, as they are for testing purposes only.
4. Click **Install**.
After the installation is complete, go to the **Configuration** tab and enable the **Start on boot** and **Show in sidebar** options. This will make it easier to access ESPHome Device Builder in the future.
Finally, go to the **Info** tab and click **Start** to run the add-on. You will now see ESPHome Device Builder in your sidebar!
## ESPHome Device Builder on Your PC [#esphome-device-builder-on-your-pc]
If you don't use Home Assistant (HA), you can still edit your boneIO ESP's configuration.
Editing Esphome config without HA, just on your PC is also possible. Similar instruction is here: [https://esphome.io/guides/getting\_started\_command\_line](https://esphome.io/guides/getting_started_command_line)
On your PC, you will need one of the following:
* for Linux: Docker,
* for Windows: Python 3.13 installed.
### Windows [#windows]
We assume that you are running Windows 10 or 11 - its important to have your administrative privileges, also you need internet connection.
Let's do it step by step!
1. Download Python installer from Python download page for Windows Choose Windows installer according to your operating system version (most common is 64-bit).
2. Choose both options available in installer. “Use admin priviliges when installing py.exe” and “Add python.exe to PATH”. Click “Install now”.
3. Verify Python installation Open Powershell or CMD and type:
```powershell
python --version
```
If properly installed output would look like (with your Python version):
```powershell
Python 3.13.2
```
4. Prepare Esphome for Python. In Powershell prompt type:
```powershell
mkdir $env:USERPROFILE\esphome
cd $env:USERPROFILE\esphome
pip3 install wheel esphome pillow==10.2.0
```
in CMD:
```cmd
mkdir %USERPROFILE%\esphome
cd %USERPROFILE%\esphome
pip3 install wheel esphome pillow==10.2.0
```
5. ESPHome should work now - lets test it! Do it by typeing:
```powershell
esphome version
```
The output should looks like:
```powershell
Version: 2025.x.x
```
The version will differ for you. It's depends on your current version.
Now you’re good to execute next steps.
#### Run ESPHome Dashboard \[!toc] [#run-esphome-dashboard-toc]
In powershell type:
```powershell
cd $env:USERPROFILE\esphome
esphome dashboard .
```
or in CMD
```cmd
cd %USERPROFILE%\esphome
esphome dashboard .
```
Check it out opening page in your web browser [http://127.0.0.1:6052](http://127.0.0.1:6052) If it’s loaded then you can go to next section: [Connect with Esphome Addon](#connect-with-esphome-addon) or if you prefer USB installation go to [USB Only installation](#usb-only-installation).
#### Upgrade ESPHome \[!toc] [#upgrade-esphome-toc]
To upgrade your ESPHome in windows you need to:
```powershell
pip3 install --upgrade esphome
```
### Linux [#linux]
Fetch Esphome docker image / Linux / Mac OS
Run following command in terminal:
```bash
docker pull ghcr.io/esphome/esphome
```
Run Esphome dashboard
Now let’s start Esphome dashboard. Make directory where your config would be stored eg /home/me/esphome
In Linux based system:
```bash
docker run --rm --privileged --network host -v "/home/me/esphome":/config -it ghcr.io/esphome/esphome dashboard .
```
Now in Chrome open website:
under Linux [http://0.0.0.0:6052/](http://0.0.0.0:6052/)
## Connect with ESPHome Device Builder [#connect-with-esphome-device-builder]
**Note**: For this to work your home network must support mDNS. Your PC and boneIO is in same subnet (same VLAN) in most cases it’d work. boneIO has to be connected to your network and working.
1. Find your new boneIO device in the dashboard.
2. Click Adopt
3. Choose name for our new device
4. Click Adopt
5. Now it will prompt for install new software
6. After install there will be logs visible, you can click stop now
Next, set a password and an encryption key on the controller: until you do, anyone on your network can flash it. See [Security](/en/docs/esp/security#after-adoption-in-esphome-builder).
It’s ready, you can edit your config by clicking Edit on your boneIO device.
### Running boneIO without Home Assistant [#running-boneio-without-home-assistant]
If you don’t have HA, then in config find line:
```yaml
api:
```
and add `reboot_timeout: 0s` to it, so it’d look like:
`reboot_timeout: 0s` is default option in our precompiled binaries.
```yaml
api:
reboot_timeout: 0s
```
## USB-Only Installation [#usb-only-installation]
If you don’t want to setup network in boneIO then go with those steps. You'd need to have Esphome dashboard running. For Esphome firmware installation you’d need internet connection on your PC!
1. Go to [https://boneio.eu/esp](https://boneio.eu/esp)
2. Choose your board and choose option "Download yaml for this firmware" in the end.
3. In the top right corner choose Download raw file
4. Copy it to your Esphome directory eg C:/Users/me/esphome. After pasting it, it should appear in Esphome dashboard.
5. Now you can Edit and Install firmware using "Plug into this computer" option. If you need to install some drivers, then Esphome website should show what to download to get it work.
# Edit config file (/en/docs/esp/products/dimmer/gen2/software_setup/how-to-edit-config)
# Configuration file [#configuration-file]
The configuration file might look big and complicated, but it's really not. The file itself is separated into sections, which we will describe below.
For our example, we will use `boneio-dimmer_gen2_8ch-v0_1.yaml`.
So let's begin. Here is the whole config file:
```yaml
substitutions:
name: boneio-dr-gen2-8ch-01
friendly_name: 'BoneIO Dimmer Gen2'
serial_prefix: 'dim2' #Don't change it.
firmware_manifest: 'https://boneio.eu/fwesp/boneio-dr-gen2-8ch-01.json'
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.dimmer-led-gen2
version: '0.1'
on_boot:
priority: -100
then:
- delay: 5s
- if:
condition:
lambda: 'return id(serial_no) != nullptr;'
then:
- component.update: serial_no
- logger.log: "Serial No updated on boot"
else:
- logger.log: "Serial No component not found"
esp32:
board: esp32-s3-devkitc-1
framework:
type: esp-idf
ethernet:
id: eth
type: W5500
clk_pin: GPIO13
mosi_pin: GPIO39
miso_pin: GPIO38
cs_pin: GPIO12
interrupt_pin: GPIO2
reset_pin: GPIO1
clock_speed: 25MHz
i2c:
sda: GPIO10
scl: GPIO11
scan: True
frequency: 400kHz
output:
- platform: ledc
pin: GPIO18
frequency: 1000Hz
inverted: false
id: chl01
- platform: ledc
pin: GPIO17
frequency: 1000Hz
inverted: false
id: chl02
- platform: ledc
pin: GPIO16
frequency: 1000Hz
inverted: false
id: chl03
- platform: ledc
pin: GPIO15
frequency: 1000Hz
inverted: false
id: chl04
- platform: ledc
pin: GPIO7
frequency: 1000Hz
inverted: false
id: chr01
- platform: ledc
pin: GPIO6
frequency: 1000Hz
inverted: false
id: chr02
- platform: ledc
pin: GPIO5
frequency: 1000Hz
inverted: false
id: chr03
- platform: ledc
pin: GPIO4
frequency: 1000Hz
inverted: false
id: chr04
# CAN gpio48 - tx, gpio47 rx, gpio35 stb
# uart:
# id: boneio_uart
# rx_pin: GPIO21
# tx_pin: GPIO14
# baud_rate: 9600
# stop_bits: 1
# modbus:
# send_wait_time: 80ms
# uart_id: boneio_uart
# id: boneio_modbus
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.7.1
files: [
'devices/serial_no.yaml',
]
# boneiopackages:
# url: https://github.com/boneIO-eu/esphome_packages
# ref: main
# refresh: 1min
# files:
# - path: sdm630.yaml
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-dimmer_gen2_8ch-v0_1.yaml@main
import_full_config: true
pcf8574:
- id: 'pcf_inputs'
address: 0x38
logger:
hardware_uart: UART0
api:
reboot_timeout: 0s
ota:
- platform: esphome
- platform: web_server
web_server:
port: 80
version: 3
local: true
light:
- platform: monochromatic
output: chl01
name: 'CHL 01'
id: chl_01
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl02
name: 'CHL 02'
id: chl_02
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl03
name: 'CHL 03'
id: chl_03
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl04
name: 'CHL 04'
id: chl_04
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr01
name: 'CHR 01'
id: chr_01
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr02
name: 'CHR 02'
id: chr_02
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr03
name: 'CHR 03'
id: chr_03
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr04
name: 'CHR 04'
id: chr_04
default_transition_length: 2s
gamma_correct: 0
debug:
update_interval: 15s
sensor:
- platform: debug
free:
name: "Heap Free"
block:
name: "Heap Max Block"
loop_time:
name: "Loop Time"
- platform: lm75b
id: boneIO_temp
name: 'Temperature'
update_interval: 30s
entity_category: diagnostic
on_value_range:
- above: 70.0
then:
- switch.turn_on: buzzer
- below: 70.0
then:
- switch.turn_off: buzzer
switch:
- platform: gpio
id: buzzer
name: 'Buzzer'
pin:
number: GPIO9
mode:
output: true
inverted: false
- platform: gpio
id: can_bus_switch
name: 'CAN Bus Switch'
pin:
number: GPIO35
mode:
output: true
inverted: false
binary_sensor:
- platform: gpio
name: 'IN_01'
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_02'
id: in_02
pin:
pcf8574: pcf_inputs
number: 1
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_03'
id: in_03
pin:
pcf8574: pcf_inputs
number: 2
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_04'
id: in_04
pin:
pcf8574: pcf_inputs
number: 3
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_05'
id: in_05
pin:
pcf8574: pcf_inputs
number: 4
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_06'
id: in_06
pin:
pcf8574: pcf_inputs
number: 5
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_07'
id: in_07
pin:
pcf8574: pcf_inputs
number: 6
mode:
input: true
inverted: true
- platform: gpio
name: 'IN_08'
id: in_08
pin:
pcf8574: pcf_inputs
number: 7
mode:
input: true
inverted: true
```
### substitutions [#substitutions]
```yaml
substitutions:
name: boneio-dr-gen2-8ch-01
friendly_name: 'BoneIO Dimmer Gen2'
serial_prefix: 'dim2' #Don't change it.
firmware_manifest: 'https://boneio.eu/fwesp/boneio-dr-gen2-8ch-01.json'
```
This part is mainly responsible for the name of your controller.\
You should focus on `friendly_name`. You should write the exact name of your boneIO here. The name depends on your needs.\
It could be "boneIO Dimmer-G2" if you have one boneIO controller, or for example, "boneIO Dimmer-G2 1st-floor".
### esphome [#esphome]
```yaml
esphome:
name: '${name}'
friendly_name: '${friendly_name}'
name_add_mac_suffix: true
project:
name: boneio.dimmer-led-gen2
version: '0.1'
on_boot:
priority: -100
then:
- delay: 5s
- if:
condition:
lambda: 'return id(serial_no) != nullptr;'
then:
- component.update: serial_no
- logger.log: "Serial No updated on boot"
else:
- logger.log: "Serial No component not found"
```
There are definitions for your controller. You shouldn't change `name` or `friendly_name`. The line `name_add_mac_suffix:` will add a MAC suffix to the controller's name, which is useful for identifying your controller. `project:` is the place where you define the type and version of your controller.
### esp32 [#esp32]
```yaml
esp32:
board: esp32-s3-devkitc-1
framework:
type: esp-idf
```
Definition of the ESP32 board and the required framework.
### Ethernet [#ethernet]
```yaml
ethernet:
id: eth
type: W5500
clk_pin: GPIO13
mosi_pin: GPIO39
miso_pin: GPIO38
cs_pin: GPIO12
interrupt_pin: GPIO2
reset_pin: GPIO1
clock_speed: 25MHz
```
This part is responsible for the description of your controller's Ethernet port - you shouldn't change anything here.
### dashboard\_import [#dashboard_import]
```yaml
dashboard_import:
package_import_url: github://boneIO-eu/esphome/boneio-dimmer_gen2_8ch-v0_1.yaml@main
import_full_config: true
```
This is the place where the address for our GitHub repository is defined. The config and all additional packages are downloaded from there. There is nothing to change here.
### packages [#packages]
```yaml
packages:
internals_packages:
url: https://github.com/boneIO-eu/esphome
ref: v1.7.1
files: [
'devices/serial_no.yaml',
]
# boneiopackages:
# url: https://github.com/boneIO-eu/esphome_packages
# ref: main
# refresh: 1min
# files:
# - path: sdm630.yaml
```
Here are definitions of all packages used by boneIO, with the address to our GitHub. You can also find there the definitions of modbus devices. In example there is configuration which will allow you to run SDM630 meter - you just need to uncomment it!
### logger [#logger]
```yaml
logger:
hardware_uart: UART0
```
In case of troubleshooting, you can increase the log level to `INFO`, `WARN`, or `DEBUG`. This can be very useful in some cases.
### api [#api]
```yaml
api:
reboot_timeout: 0s
```
Here, the reboot timeout is defined for when the controller loses connection with HA.
If you want your boneIO to restart after losing connection with Home Assistant, you should enter a value that suits you here.
For WiFi connections, the value should not be zero. For LAN connections, not rebooting does not negatively affect the connection with Home Assistant in most cases.
### ota [#ota]
```yaml
ota:
- platform: esphome
- platform: web_server
```
Part responsible for Over The Air updates. The `web_server` platform allows updating via the device's web panel.
### web\_server [#web_server]
```yaml
web_server:
port: 80
local: true
version: 3
```
Part responsible for enabling the web server of the controller.
### Modbus [#modbus]
```yaml
# CAN gpio48 - tx, gpio47 rx, gpio35 stb
# uart:
# id: boneio_uart
# rx_pin: GPIO21
# tx_pin: GPIO14
# baud_rate: 9600
# stop_bits: 1
# modbus:
# send_wait_time: 80ms
# uart_id: boneio_uart
# id: boneio_modbus
```
This section is responsible for Modbus. If you plan to use it, you should first uncomment it.\
Then, please check our Modbus tutorial: [Modbus with Esphome packages](/docs/esp/advanced/esphome-packages)
# Step by step Guide (/en/docs/esp/products/dimmer/gen2/software_setup)
## You just received your boneIO ESP Dimmer gen2! Here are some steps witch will help you to handle it! [#you-just-received-your-boneio-esp-dimmer-gen2-here-are-some-steps-witch-will-help-you-to-handle-it]
Device will come to you with alredy preinstalled ESPHome. boneIO is provided with default configuration, you need to adjust it for your needs.
Below you will find some necessary steps to start with boneiO ESP Dimmer gen2:
# How are inputs defined? (/en/docs/esp/products/dimmer/gen2/software_setup/naming-binary)
## Why should you name your inputs? [#why-should-you-name-your-inputs]
Naming your inputs makes working with the controller much easier. It's simpler to remember "Bedroom Button 1" than "IN\_01", right?
### Binary Sensors [#binary-sensors]
Let's look at the default configuration for your inputs, which are defined as `binary_sensor` components.
Here is a complete example of a single input configuration. The most important line for you is `name: 'My First Button'`.
```yaml
binary_sensor:
- platform: gpio
name: 'My First Button'
"This is the friendly name for your input"
id: in_01
pin:
pcf8574: pcf_inputs
number: 0
mode:
input: true
inverted: true
on_press:
then:
```
### Configuration Explained [#configuration-explained]
| Section | Description |
| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `binary_sensor:` | This is the main header for all your binary sensor (input) definitions. |
| `- platform: gpio` | This specifies that the sensor is connected to a General Purpose Input/Output pin. |
| `name: 'My First Button'` | This is the friendly name for your input. It will be visible in Home Assistant and is much easier to identify. You can change it to something descriptive like `'Bedroom Button 1'` or `'IN_01_Living_Room_Motion'`. This is the most important part for you to customize. |
| `id: in_01` | This is a unique identifier used within ESPHome. It's essential for referring to this input in automations, such as the `on_press` action. |
| `pin:` | This section defines the physical pin the sensor is connected to. This part is pre-configured for the boneIO hardware and should not be changed. |
| `inverted: true` | This inverts the logic of the input. It's useful for certain devices like motion sensors, which might have a normally open or normally closed state. |
| `on_press:` | This is an automation that defines what happens when the input is triggered (e.g., a button is pressed). We will cover this in more detail in the automations guide. |
# LED Lights (/en/docs/esp/products/dimmer/gen2/software_setup/naming-outputs)
## What are outputs? [#what-are-outputs]
Outputs are the executive parts of our controller. As dimmer its specialised in controlling lights, we had prepared configurations for few scenarios!
You can control:
* [8 single LED strips](#boneio-dimmer_gen2_8ch-v0_1),
* [4 CCT LED Strips](#boneio-dimmer_gen2_4cct-v0_1),
* [2 RGBW LED Strips](#boneio-dimmer_gen2_2rgbw-v0_1).
### Why should you name them? [#why-should-you-name-them]
Naming your outputs will make working with the controller much easier. It's much easier to remember "Bedroom light" than "CHL 01", right?
In our examples, we focus on a part of the configuration, which you can then adjust to your entire configuration.
Let's get started!
## Configure outputs [#configure-outputs]
We have prepared three types of configuration files for you. Which one you should choose depends on what you will use as your outputs.
In most scenarios - most popular output configuration is 8 single LED Strips, so we prepared a configuration with 8 single LED strips outputs!
### 8 single LED strips [#8-single-led-strips]
Below is a part of the default configuration in the file:
```yaml
boneio-dimmer_gen2_8ch-v0_1.yaml
```
We are looking for the part with the `light:` header.
```yaml
light:
- platform: monochromatic
output: chl01
name: 'CHL 01'
id: chl_01
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl02
name: 'CHL 02'
id: chl_02
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl03
name: 'CHL 03'
id: chl_03
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chl04
name: 'CHL 04'
id: chl_04
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr01
name: 'CHR 01'
id: chr_01
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr02
name: 'CHR 02'
id: chr_02
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr03
name: 'CHR 03'
id: chr_03
default_transition_length: 2s
gamma_correct: 0
- platform: monochromatic
output: chr04
name: 'CHR 04'
id: chr_04
default_transition_length: 2s
gamma_correct: 0
```
* `- platform: monochromatic` - Defines the component type. `monochromatic` is used for brightness control of single color LED strip.
* `output: chl01` – This links the light to a specific physical output defined elsewhere in the configuration.
* `name: 'CHL 04'` – This is the friendly name of the output that will be visible in Home Assistant. You can change it freely, for example, to `Bedroom Light` or `CHL_01_Bedroom`.
* `id: chl_01` – This is a unique identifier used within the ESPHome configuration. It allows you to control this light from automations or other components (e.g., `light.toggle: chl_01`).
* `default_transition_length: 2s` - time of the transition on/off.
### 4 CCT LED Strips [#4-cct-led-strips]
Below is a part of the default configuration in the file:
```yaml
boneio-dimmer_gen2_4cct-v0_1.yaml
```
We are looking for the part with the `light` header :
```yaml
light:
- platform: cwww
name: 'CHL_01_02'
id: chl_01_02
cold_white: chl01
warm_white: chl02
cold_white_color_temperature: 6536 K
warm_white_color_temperature: 2000 K
- platform: cwww
name: 'CHL_03_04'
id: chl_03_04
cold_white: chl03
warm_white: chl04
cold_white_color_temperature: 6536 K
warm_white_color_temperature: 2000 K
- platform: cwww
name: 'CHR_01_02'
id: chr_01_02
cold_white: chr01
warm_white: chr02
cold_white_color_temperature: 6536 K
warm_white_color_temperature: 2000 K
- platform: cwww
name: 'CHR_03_04'
id: chr_03_04
cold_white: chr03
warm_white: chr04
cold_white_color_temperature: 6536 K
warm_white_color_temperature: 2000 K
```
* `- platform: cwww` - Defines the component type. `cwww` is used for brightness control, and color temperatoure of the single Cold White / Warm White LED strip.
* `name: 'CHL_01_02'` – This is the friendly name of the output that will be visible in Home Assistant. You can change it freely, for example, to `Bedroom Light` or `CHL_01_02_Bedroom`.
* `id: 'chl_01_02'` – This is a unique identifier used within the ESPHome configuration. It allows you to control this light from automations or other components (e.g., `light.toggle: chl_01`).
* `cold_white: 'chl01'` - This links the light to a specific physical output defined elsewhere in the configuration.
* `warm_white: 'chl02'` - This links the light to a specific physical output defined elsewhere in the configuration.
* `cold_white_color_temperature:` - Here you can set specific color temperature of your cold white led strip.
* `warm_white_color_temperature:` - Here you can set specific color temperature of your warm white led strip.
### 2 RGBW LED Strips [#2-rgbw-led-strips]
Below is a part of the default configuration in the file:
```yaml
boneio-dimmer_gen2_2rgbw-v0_1.yaml
```
We are looking for the part with the `light` header:
```yaml
light:
- platform: rgbw
id: rgbw_l
name: 'RGBW L'
red: chl01
green: chl02
blue: chl03
white: chl04
default_transition_length: 2s
gamma_correct: 0
- platform: rgbw
id: rgbw_r
name: 'RGBW R'
red: chr01
green: chr02
blue: chr03
white: chr04
default_transition_length: 2s
gamma_correct: 0
```
* `- platform: rgbw` - Defines the component type. `rgbw` is used for controling popular RGBW LED strips.
* `name: 'RGBW L'` – This is the friendly name of the output that will be visible in Home Assistant. You can change it freely, for example, to `Bedroom Light` or `RGBW_L_Bedroom`.
* `id: 'rgbw_l'` – This is a unique identifier used within the ESPHome configuration. It allows you to control this light from automations or other components (e.g., `light.toggle: chl_01`).
* `red: 'chl01'` - This links the light color to a specific physical output defined elsewhere in the configuration.
* `green: 'chl02'` - This links the light color to a specific physical output defined elsewhere in the configuration.
* `blue: 'chl03'` - This links the light color to a specific physical output defined elsewhere in the configuration.
* `white: 'chl0'` - This links the light color to a specific physical output defined elsewhere in the configuration.
* `default_transition_length: 2s` - the time of transition.
* `gamma_correct: 0` - Here you can correct gamma of the strip.
### Customize it! [#customize-it]
Do you have 2 CCT strips and one RGBW strip? No problem, just modify the appropriate part of the `yaml` file according to your needs!
```yaml
light:
- platform: rgbw
id: rgbw_l
name: 'RGBW L'
red: chl01
green: chl02
blue: chl03
white: chl04
default_transition_length: 2s
gamma_correct: 0
- platform: cwww
name: 'CHR_01_02'
id: chr_01_02
cold_white: chr01
warm_white: chr02
cold_white_color_temperature: 6536 K
warm_white_color_temperature: 2000 K
- platform: cwww
name: 'CHR_03_04'
id: chr_03_04
cold_white: chr03
warm_white: chr04
cold_white_color_temperature: 6536 K
warm_white_color_temperature: 2000 K
```
What have we done? For the left section of the controller - where we connected the RGBW strip - we applied the configuration from the `boneio-dimmer_gen2_2rgbw-v01.yaml` file. However, for the right section of the controller, we are connecting 2 CCT strips! How did we configure it? It's simple: we used the part of the configuration from the `boneio-dimmer_gen2_4cct-v01.yaml` file that is dedicated to the right section of the controller. Thanks to this, a single boneIO Dimmer supports 2 CCT strips and one RGBW strip!