commit c71ddf37ca49e2209f9806f559f2e38c3eeb552a Author: Setti Solutions S.R.L Date: Thu Oct 29 18:29:59 2026 +0200 cantabile_edge 0.1.307 (cantabile eae23e0d6ffb) diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4dc0147 --- /dev/null +++ b/LICENSE @@ -0,0 +1,7 @@ +Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. + +The Cantabile Edge Agent add-on and its images are proprietary software of +Setti Solutions S.R.L. You may install and run them on your own Home Assistant +to use the Cantabile service. Copying, modifying, redistributing or +publishing them, in whole or in part, needs the written permission of +Setti Solutions S.R.L. diff --git a/cantabile_edge/CHANGELOG.md b/cantabile_edge/CHANGELOG.md new file mode 100644 index 0000000..32f7f32 --- /dev/null +++ b/cantabile_edge/CHANGELOG.md @@ -0,0 +1,15 @@ +# Changelog + +Versions are `0.1.`: n counts the commits of the Cantabile repository the +add-on was built from. The image's label `org.opencontainers.image.revision` +names the commit; the agent inside is the Edge Agent image of that commit. + +## 0.1.x + +- First packaging as a Home Assistant add-on: the agent and its link to + Cantabile, the MQTT broker from the Mosquitto add-on, Cantabile's area, + device and dashboards in Home Assistant. + +--- + +© 2026 Setti Solutions S.R.L, [www.setti.md](https://www.setti.md). All rights reserved. diff --git a/cantabile_edge/DOCS.md b/cantabile_edge/DOCS.md new file mode 100644 index 0000000..e93c546 --- /dev/null +++ b/cantabile_edge/DOCS.md @@ -0,0 +1,51 @@ +# 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. + +## 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. + +## 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. +- 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. diff --git a/cantabile_edge/Dockerfile b/cantabile_edge/Dockerfile new file mode 100644 index 0000000..f2ac70b --- /dev/null +++ b/cantabile_edge/Dockerfile @@ -0,0 +1,18 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +# The add-on's image: the Edge Agent image of the same commit (edge/build.sh) +# with addon-run in front, and the platform it belongs to (the devices URL, +# the command and bundle certificates), as a Hub build bakes them in. +# Built by ha-addon/build.sh, one image per arch; the Supervisor pulls it. +ARG EDGE_IMAGE +FROM ${EDGE_IMAGE} +ARG VERSION ARCH REVISION +LABEL io.hass.version="${VERSION}" io.hass.type="addon" io.hass.arch="${ARCH}" \ + org.opencontainers.image.revision="${REVISION}" +# bundles.pem is optional (no bundle key: the agent plans with its flat price). +COPY addon.env commands.pem bundles.pem* /etc/cantabile/ +COPY addon-run /usr/local/bin/addon-run +# addon-run starts as root (it reads Home Assistant's instance id) and runs +# the agent as uid 10001. +USER root +ENTRYPOINT ["addon-run"] +CMD [] diff --git a/cantabile_edge/README.md b/cantabile_edge/README.md new file mode 100644 index 0000000..40950ba --- /dev/null +++ b/cantabile_edge/README.md @@ -0,0 +1,9 @@ +# Cantabile Edge Agent + +Plans your home's energy with Cantabile (prices, weather, your devices) and, +with your consent, runs the devices you choose: heating, charging, the +battery. See the Documentation tab. + +--- + +© 2026 Setti Solutions S.R.L, [www.setti.md](https://www.setti.md). All rights reserved. diff --git a/cantabile_edge/addon-run b/cantabile_edge/addon-run new file mode 100755 index 0000000..667f353 --- /dev/null +++ b/cantabile_edge/addon-run @@ -0,0 +1,148 @@ +#!/usr/bin/env python3 +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +"""The Edge Agent's start as a Home Assistant add-on (runs as root). + +- Home Assistant's instance id: .storage/core.uuid is root-only; a copy in + /data for the link (the site id comes from it, as on the Hub and THR-Home). +- The add-on's options (/data/options.json): mode, claim code, dashboards. +- MQTT: the broker the Supervisor offers (the Mosquitto add-on), with the + login it made for this add-on; without one, no discovery in HA. +- First start: config.yaml and an empty mapping, as the Hub's edge-prepare + (nothing is sent until an installer confirms the mapping). +Then the link and the agent (cantabile-run) as uid 10001, without root's +capabilities: /homeassistant stays mapped, but only what is readable for +everyone is readable for them. +ADDON_DATA, ADDON_HA_CONFIG, ADDON_ETC, SUPERVISOR_URL and ADDON_DRY_RUN=1 +(print the environment instead of starting) are for tests. +""" +import json +import os +import pwd +import sys +import urllib.request + +DATA = os.environ.get("ADDON_DATA", "/data") +HA_CONFIG = os.environ.get("ADDON_HA_CONFIG", "/homeassistant") +ETC = os.environ.get("ADDON_ETC", "/etc/cantabile") +SUPERVISOR = os.environ.get("SUPERVISOR_URL", "http://supervisor") +DRY = os.environ.get("ADDON_DRY_RUN") == "1" +USER = "cantabile" # edge/Dockerfile: uid 10001 + +CONFIG = """# The Edge Agent as a Home Assistant add-on (written once by addon-run). +mode: shadow +mapping: /data/mapping.yaml +state_dir: /data/state +sink: {kind: link, path: /run/cantabile/link.sock} +""" +MAPPING = """# Which HA entities Cantabile may read (edge/cantabile_edge/mapping.py). +# None yet: an installer confirms the mapping. +version: 1 +assets: [] +""" + + +def log(msg): + print(f"addon-run: {msg}", flush=True) + + +def owner(): + if DRY or os.geteuid() != 0: + return None + pw = pwd.getpwnam(USER) + return pw.pw_uid, pw.pw_gid + + +def put(path, text, mode=0o600, own=None, keep=False): + """Write a file the agent's user owns; keep=True: only if missing.""" + if keep and os.path.exists(path): + return + os.makedirs(os.path.dirname(path), exist_ok=True) + tmp = path + ".tmp" + with open(tmp, "w") as f: + f.write(text) + os.chmod(tmp, mode) + if own: + os.chown(tmp, *own) + os.replace(tmp, path) + + +def chown_tree(path, own): + """The agent's files in /data (options.json stays the Supervisor's).""" + for root, dirs, files in os.walk(path): + for n in dirs + files: + p = os.path.join(root, n) + if p != os.path.join(DATA, "options.json") and not os.path.islink(p): + os.chown(p, *own) + os.chown(path, *own) + + +def mqtt(env, own): + token = os.environ.get("SUPERVISOR_TOKEN", "") + req = urllib.request.Request(f"{SUPERVISOR}/services/mqtt", headers={"Authorization": f"Bearer {token}"}) + try: + with urllib.request.urlopen(req, timeout=10) as r: + d = json.load(r)["data"] + except Exception as e: # no broker add-on: the agent runs without HA discovery + log(f"no MQTT broker from the Supervisor ({e}): no Cantabile device in Home Assistant") + return + if d.get("ssl"): + log("the MQTT broker wants TLS, which the agent does not speak yet: no Cantabile device in Home Assistant") + return + env["CANTABILE_MQTT_HOST"] = str(d["host"]) + env["CANTABILE_MQTT_PORT"] = str(d.get("port", 1883)) + if d.get("username"): + env["CANTABILE_MQTT_USER"] = d["username"] + put(f"{DATA}/mqtt-password", d.get("password", ""), own=own) + env["CANTABILE_MQTT_PASSWORD_FILE"] = f"{DATA}/mqtt-password" + log(f"MQTT broker {d['host']}:{env['CANTABILE_MQTT_PORT']}") + + +def main(): + own = owner() + with open(f"{DATA}/options.json") as f: + opts = json.load(f) + env = dict(os.environ) + # The platform this build belongs to (ha-addon/build.sh: addon.env). + with open(f"{ETC}/addon.env") as f: + for line in f: + k, sep, v = line.strip().partition("=") + if sep and not k.startswith("#"): + env.setdefault(k, v) + env["CANTABILE_COMMAND_CERT"] = f"{ETC}/commands.pem" + if os.path.exists(f"{ETC}/bundles.pem"): + env["CANTABILE_BUNDLE_CERT"] = f"{ETC}/bundles.pem" + + with open(f"{HA_CONFIG}/.storage/core.uuid") as f: + put(f"{DATA}/ha-core.uuid", f.read(), own=own) + env["CANTABILE_HA_UUID_FILE"] = f"{DATA}/ha-core.uuid" + + code = (opts.get("claim_code") or "").strip() + if code: + put(f"{DATA}/claim-code", code + "\n", own=own) + env["CANTABILE_MODE"] = opts.get("mode", "shadow") + env["CANTABILE_DASHBOARDS"] = "1" if opts.get("dashboards", True) else "0" + mqtt(env, own) + + put(f"{DATA}/config.yaml", CONFIG, 0o644, own, keep=True) + put(f"{DATA}/mapping.yaml", MAPPING, 0o644, own, keep=True) + os.makedirs(f"{DATA}/state", exist_ok=True) + if own: + chown_tree(DATA, own) + + cmd = ["cantabile-run", "--config", f"{DATA}/config.yaml", "run"] + if DRY: + print(json.dumps({"cmd": cmd, "env": {k: v for k, v in env.items() if k.startswith(("CANTABILE_", "HA_"))}})) + return + if own: + # Drop to the agent's user and every capability; no way back. + cmd = ["setpriv", f"--reuid={own[0]}", f"--regid={own[1]}", "--init-groups", + "--inh-caps=-all", "--bounding-set=-all", "--no-new-privs"] + cmd + os.execvpe(cmd[0], cmd, env) + + +if __name__ == "__main__": + try: + main() + except FileNotFoundError as e: + log(f"missing {e.filename}") + sys.exit(1) diff --git a/cantabile_edge/config.yaml b/cantabile_edge/config.yaml new file mode 100644 index 0000000..16eee62 --- /dev/null +++ b/cantabile_edge/config.yaml @@ -0,0 +1,40 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +# The Edge Agent as a Home Assistant add-on (HANDOVER 3e): the same image as +# the Hub's, wrapped by addon-run (Dockerfile). ha-addon/build.sh sets +# version and arch for each build; the image is prebuilt, per arch. +name: Cantabile Edge Agent +version: "0.1.307" +slug: cantabile_edge +description: Plans your home's energy with Cantabile and, with your consent, runs the devices you choose. +url: https://cantabile.cloud +arch: [amd64] +image: git.setti.solutions/daniel/cantabile-ha-edge-{arch} +stage: experimental +startup: application +boot: auto +# Core's API through the Supervisor (SUPERVISOR_TOKEN): states, registries, +# areas, dashboards, service calls. hassio_api only for the MQTT service. +homeassistant_api: true +hassio_api: true +services: + - mqtt:want +# The Building page (joining a building from home): only through HA's +# ingress, in the sidebar for administrators. +ingress: true +ingress_port: 8099 +panel_icon: mdi:office-building +panel_title: Cantabile +panel_admin: true +# Read once at start, as root, for the site id: .storage/core.uuid (root +# only); the agent then runs as its own user (addon-run). +map: + - type: homeassistant_config + read_only: true +options: + mode: shadow + claim_code: "" + dashboards: true +schema: + mode: list(off|shadow) + claim_code: password? + dashboards: bool diff --git a/cantabile_edge/icon.png b/cantabile_edge/icon.png new file mode 100644 index 0000000..1d1cc93 Binary files /dev/null and b/cantabile_edge/icon.png differ diff --git a/cantabile_edge/logo.png b/cantabile_edge/logo.png new file mode 100644 index 0000000..248eddc Binary files /dev/null and b/cantabile_edge/logo.png differ diff --git a/cantabile_edge/translations/de.yaml b/cantabile_edge/translations/de.yaml new file mode 100644 index 0000000..465090f --- /dev/null +++ b/cantabile_edge/translations/de.yaml @@ -0,0 +1,17 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +configuration: + mode: + name: Modus + description: >- + shadow: Der Agent liest Ihre Geräte und plant, steuert aber nichts. + off: Er hält nur die Verbindung zu Cantabile. Empfehlen und Steuern + werden in Cantabile eingeschaltet, mit Ihrer Zustimmung. + claim_code: + name: Aktivierungscode + description: Der Code auf Ihrer Cantabile-Karte (XXXX-XXXX-XXXX). Er verbindet dieses Zuhause mit Ihrem Cantabile-Konto. + dashboards: + name: Dashboards + description: >- + Die Dashboards von Cantabile in Home Assistant (Cantabile, Strom, + Solar & Batterie, Heizen & Kühlen, Energie gesamt) und das + Energie-Dashboard, solange Sie kein eigenes haben. diff --git a/cantabile_edge/translations/en.yaml b/cantabile_edge/translations/en.yaml new file mode 100644 index 0000000..8ea5ac7 --- /dev/null +++ b/cantabile_edge/translations/en.yaml @@ -0,0 +1,17 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +configuration: + mode: + name: Mode + description: >- + shadow: the agent reads your devices and plans, and controls nothing. + off: it only keeps the connection to Cantabile. Advising and running + devices are turned on from Cantabile, with your consent. + claim_code: + name: Claim code + description: The code on your Cantabile card (XXXX-XXXX-XXXX). It ties this home to your Cantabile account. + dashboards: + name: Dashboards + description: >- + Cantabile's dashboards in Home Assistant (Cantabile, Electricity, Solar + & battery, Heating & cooling, Total energy), and the Energy dashboard + while you have none of your own. diff --git a/repository.yaml b/repository.yaml new file mode 100644 index 0000000..6acd409 --- /dev/null +++ b/repository.yaml @@ -0,0 +1,4 @@ +# Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. +name: Cantabile +url: https://cantabile.cloud +maintainer: Setti Solutions S.R.L (www.setti.md)