cantabile_edge 0.1.307 (cantabile eae23e0d6ffb)

This commit is contained in:
Setti Solutions S.R.L committed 2026-10-29 18:29:59 +02:00
commit c71ddf37ca
12 files changed
+326

No files matched your search

+15
View File
@@ -0,0 +1,15 @@
# Changelog
Versions are `0.1.<n>`: 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.
+51
View File
@@ -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.
+18
View File
@@ -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 []
+9
View File
@@ -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.
+148
View File
@@ -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)
+40
View File
@@ -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
Binary file not shown.

After

Width:  |  Height:  |  Size: 7.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.8 KiB

+17
View File
@@ -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.
+17
View File
@@ -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.