Files
cantabile-ha-addons/cantabile_eebus/DOCS.md
T

97 lines
4.6 KiB
Markdown

# Cantabile EEBUS
The add-on speaks EEBUS with the devices in your home: the grid
operator's control box (§14a EnWG), heat pumps (Vaillant, Viessmann,
Bosch and others), wallboxes and inverters. It shows them in Home
Assistant under Cantabile's names and units, so the Cantabile agent maps
them exactly, and it hands the grid operator's limit to the agent.
## Your consent
In the add-on's configuration, **Cantabile may control devices** is your
consent (the same text as Cantabile's other add-ons and the Cantabile
Hub's setup). Without it the add-on pairs and reads your devices, shows
them in Home Assistant and tells the Cantabile agent about the grid
operator's limit, but writes nothing to them: no command, and not the
grid operator's limit either. The page says so at the top. You can give
or take back the consent there at any time; the add-on restarts with it
and records when.
The add-on sends nothing out of your home: its values go to Home
Assistant, the grid operator's limit to the Cantabile agent on the same
Home Assistant (which shares data with Cantabile only with your consent
in its own configuration).
## Pairing
EEBUS devices trust each other by their SKI (a fingerprint of the
device's certificate). Open the add-on's page (Cantabile EEBUS):
1. Switch EEBUS on in the device's app or menu (for example the
myVAILLANT or ViCare app, or the wallbox's web page). The device
appears under **Found on the network**, or asks to be paired.
2. Compare the SKI on the page with the one the device shows (its app,
display or label; for the control box, the installer or the grid
operator gives it).
3. **Pair**. In the device's app, trust "Cantabile EEBUS bridge" if it
asks. The page shows the bridge's own two SKIs at the bottom: one for
heat pumps, wallboxes and inverters, one for the grid operator's
control box (give that one to the installer).
Each device is paired once; the add-on keeps its own certificate in its
data, so the pairing survives updates. A device's page opens with a link
`#<device>` (from Cantabile's dashboard).
## The grid operator's limit (§14a)
A paired control box is **sealed**: nothing in Home Assistant or Cantabile
lifts its limit, and it can't be unpaired on the page (only the grid
operator, through Cantabile). While it limits the home, the add-on passes
the limit on to the heat pumps and wallboxes at once and the Cantabile
agent plans within it. Without the control box's heartbeat for two
minutes the failsafe limit holds for its failsafe time: the control box's
own values; until it sent them §14a's minimum of 4.2 kW (BNetzA
BK6-22-300) for the shortest time the EEBUS use case allows (2 hours).
Toward the control box the add-on declares the controllable devices'
nominal power: what the heat pumps and wallboxes report (a heat pump's
nominal power, a wallbox's maximum current and phases), else the rating
you enter on a device's page (from its nameplate). It never declares a
guess: while any heat pump or wallbox has no known power, or none is
paired, nothing is declared and the add-on does not offer the grid
operator's use case (LPC); the page's grid card says why ("nominal power
unknown: enter the controllable devices' ratings") and which device needs
a rating. When a limit ends, a wallbox goes back to its own maximum
current, else to the current it had before; if neither is known it stays
and the page says so. While its power is not known, a device's share of a
limit is an equal one (the sum never exceeds the limit), and a W budget is
turned into amps as if on three phases (never more than the budget).
## Protection
Every control of a heat pump or wallbox starts **protected**: Cantabile
never sets a heat pump to 0 W or a wallbox to 0 A. Only you lift a
protection, on the add-on's page, one control at a time; every change is
logged with who and when.
## Options
- **Cantabile may control devices**: your consent, above (off until you
give it).
- **Simulate**: a simulated control box, heat pump and wallbox, with
buttons on the page to send a limit or lose the heartbeat.
- **Read only**: commands are checked and logged, never written.
- **Pass on the grid operator's limit**: on by default.
The add-on uses the host's network: EEBUS devices find it by mDNS and
connect to TCP ports 4712 (the control box) and 4713 (the other
devices). The devices' support differs by model and
firmware; the profiles are untested on real hardware so far.
Open-source components and their licences: see
`/usr/share/doc/cantabile-eebus/THIRD-PARTY-NOTICES.md` in the image.
---
© 2026 Setti Solutions S.R.L, [www.setti.md](https://www.setti.md). All rights reserved.