169 lines
8.4 KiB
Markdown
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.
|