cantabile_edge 0.1.389

This commit is contained in:
Setti Solutions S.R.L committed 2026-10-30 02:48:00 +02:00
1 parent c71ddf37ca
commit 343331d234
9 files changed
+383 -25

No files matched your search

+105 -6
View File
@@ -14,21 +14,120 @@ runs those devices through Home Assistant: heating, charging, the battery.
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:** Cantabile's dashboards (Cantabile, Electricity, Solar &
battery, Heating & cooling, Total energy), and Home Assistant's Energy
dashboard while you have none of your own. Your own dashboards are never
changed.
- **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.
## 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 an installer has confirmed, with you, which devices
Cantabile may read (the mapping) and you agreed to share data.
- 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