8.4 KiB
Cantabile Edge Agent
The agent connects this Home Assistant to Cantabile. It reads the devices an installer chose with you, plans your home's energy every 15 minutes (48 hours ahead, from prices, weather and your devices) and, only where you agreed, runs those devices through Home Assistant: heating, charging, the battery.
Before you start
- Mosquitto broker add-on, installed and started (Settings → Add-ons → Add-on store). The agent shows itself in Home Assistant through it: the device "Cantabile" in the area "Cantabile", prices, what Cantabile asked for and why. Without the broker the agent still works, but you don't see it in Home Assistant.
- Your claim code, from the Cantabile card.
Your consent
You give your consent when you install the add-on, in its Configuration tab (Settings → Add-ons → Cantabile Edge Agent → Configuration):
- Share energy data with Cantabile (needed): "Cantabile may receive the energy data of the devices chosen for it." Without it the add-on does not connect to Cantabile at all: nothing is enrolled, read for Cantabile or sent, and the add-on's page says so.
- Cantabile may control devices (optional, separately): "Allow Cantabile to control the devices you choose (heating, charging, battery, shades) within the limits you set."
These are the same texts, in the same version, as on a Cantabile Hub's setup. The add-on records what you agreed to, the texts' version and when, "given at installation in the add-on's configuration", and tells Cantabile. Which devices Cantabile may read or control you choose device by device on the add-on's Devices page. You can take your consent back in the Configuration tab at any time (save and restart the add-on): from then on nothing more is collected or sent.
Options
- Mode:
shadow(default) reads and plans, controls nothing.offonly keeps the connection. Advising and running devices are turned on from Cantabile, never here, and only with your consent. - Claim code: ties this home to your Cantabile account.
- Dashboards: one dashboard, "Cantabile" in the sidebar, with a view for each part your home has: Overview (Cantabile's connection and mode, the plan and the price, power now from solar, grid, battery and home, energy today), Energy (over days and months), Heating & cooling, Devices (Cantabile's devices and their main values, with a link to their settings) and Building (joining a building). It also sets up Home Assistant's Energy dashboard while you have none of your own. Your own dashboards are never changed.
- Cantabile support may open this Home Assistant (off by default): when
you turn it on, Cantabile's support team can open this Home Assistant
through Cantabile's connection to help you, signed in as a user of its
own, "Cantabile support" (an administrator, so that it can look at your
integrations, logs and repairs; never the owner, and never with your
password, which it cannot change either). The add-on makes that user and
gives it a new password for each session that nobody sees; afterwards the
user is disabled again and has no password. A session lasts at most an
hour, ends after 15 minutes without use, and every request is recorded.
You see the user in Settings → People while it exists, and while a
session is open the add-on's own pages (below) say so at the top, with
End now: it ends the session at once and disables the user again.
Turning the option off and restarting the add-on ends it too. On these
pages the user "Cantabile support" cannot switch reading or control on,
change a protection or make the other choices that are yours. Home
Assistant must answer plain HTTP on its own port for this (with an
ssl_certificatein itshttp:configuration support is told it cannot open it).
Pages
The add-on's own pages are not in the sidebar: open them from Cantabile's dashboard ("Devices" under the status, "Building"), or from Settings → Add-ons → Cantabile Edge Agent → Open web UI. "Show in sidebar" on that page puts it there if you want it. Only an administrator of Home Assistant can use them.
- Devices: Home Assistant's devices that a Cantabile device profile knows, and what Cantabile would read from each and could control. See "Using a device with Cantabile" below.
- Building or community: joining a building or an energy community.
Your devices in Cantabile (the mapping)
At its first start the agent proposes which of Home Assistant's devices
Cantabile uses (the mapping, /data/mapping.yaml in the add-on's folder):
Cantabile's own devices first (their device profiles say what each value
is), then devices Cantabile knows, then solar, grid, battery and room
sensors by their names. New devices are added while the proposal is
unchanged. The proposal only shows your home in Cantabile's dashboard;
nothing is read for Cantabile or sent until you agree.
Using a device with Cantabile
On the add-on's Devices page each device Home Assistant has and a Cantabile device profile knows is listed with what Cantabile would read from it (for example solar power, the battery's charge, a room's temperature) and what it could control (heating, cooling, charging, the battery). A thermostat that no specific profile knows gets the generic one (any device with a climate entity). Use with Cantabile confirms the device:
- Cantabile takes the device's values as its profile describes them, instead of the proposal's guesses, and keeps the proposal away from that device from then on. Stop using it on the same page and the proposal takes it back.
- The device appears on Cantabile's dashboard, and in the area "Cantabile" if it has no area of its own (a thermostat in its room keeps its room).
- Reading and control start off. Switch them on for the device on the same page ("Cantabile may read these values", "Cantabile may control it"): this needs your consent in the Configuration tab first (above; control needs its own). The agent starts again for a few seconds to apply it. The dashboard here shows the device either way: that stays in your home.
- Controls that must not be switched off are protected as their profile says (a thermostat, an inverter's output): Cantabile never switches them off. You can lift or set protection on the page. A device sealed by its custodian (a grid or metering operator) is shown locked.
- A thermostat that heats and cools: choose heating, cooling, by season (the default: heating October to April) or by outdoor temperature. Cantabile uses one at a time.
Nothing is installed or set up in Home Assistant here: the page uses the devices Home Assistant already has. Values your own mapping (written by hand) already reads stay there, and a control on an entity another control already writes is left out: one writer per device.
Moving from an earlier install
A mapping an installer confirmed for an earlier install of Cantabile (for
example the agent's container, /root/cantabile-agent/mapping.yaml) is
taken over once:
- Copy it to Home Assistant's share folder as
cantabile/mapping.yaml(/share/cantabile/mapping.yaml, e.g. with the Samba or SSH add-on). - Restart the add-on. Its log says "an earlier install's mapping … imports it once".
Its entries keep their names; consent is not taken over (you decide again). An entry whose sensor has no value here is replaced by the same value from Cantabile's own devices, and the file lists what changed. The copy in the share folder can stay; it is not taken again unless it changes.
What it reads, and what leaves your home
- Nothing leaves until you agreed to share data (the Configuration tab) and switched reading on for the devices Cantabile may read (the Devices page).
- At start the add-on reads Home Assistant's instance id once (in
/homeassistant/.storage), as the identity of your home in Cantabile. Then it runs as its own user without any special rights; it never reads yoursecrets.yaml, passwords or tokens. - Everything goes to Cantabile over one encrypted connection that the agent opens; nothing in your network is opened for it.
Backups
Home Assistant's backups include the add-on's data: its identity with Cantabile, the mapping, your consent. Restored on a new machine, the home keeps its history with Cantabile.
Help
Cantabile's support, from your Cantabile account.
© 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved.