Files

169 lines
8.4 KiB
Markdown

# 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. `off` only
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_certificate` in its `http:` 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:
1. 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).
2. 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 your
`secrets.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](https://www.setti.md). All rights reserved.