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

7.2 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.

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.

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. All rights reserved.