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

+182 -5
View File
@@ -4,25 +4,47 @@
- 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.
- The add-on's options (/data/options.json): the owner's consent, mode,
claim code, dashboards.
- Consent (HANDOVER 0, the owner's decision of 2026-10-30): given when the
add-on is installed from Cantabile's repository, in its configuration:
sharing the energy data of the devices chosen for Cantabile (needed: until
it is given the add-on does not enrol or connect, and its page says why)
and, separately, control. The same texts and version as the Hub's setup
wizard and panel; recorded in the agent's consent file
(/data/state/consent.json: share, control, when, the texts' version, the
source), which the link sends to Cantabile with its heartbeat. Taken
back in the configuration: nothing more is collected or sent.
- The hardware fingerprint (hashed ids: the DMI ones are root-only): written
once per start for the link, which recognises a reinstall with it.
- 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).
- First start: config.yaml and an empty mapping, as the Hub's edge-prepare;
the agent then proposes one from Home Assistant's devices (propose.py),
consent off: nothing is read for Cantabile until the owner agrees.
- An earlier install's mapping (/share/cantabile/mapping.yaml, the owner or
support puts it there): copied to /data/mapping-import.yaml for the agent,
which imports it once per content, consent off.
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 html
import json
import os
import pwd
import re
import signal
import subprocess
import sys
import time
import urllib.request
DATA = os.environ.get("ADDON_DATA", "/data")
HA_CONFIG = os.environ.get("ADDON_HA_CONFIG", "/homeassistant")
SHARE = os.environ.get("ADDON_SHARE", "/share")
ETC = os.environ.get("ADDON_ETC", "/etc/cantabile")
SUPERVISOR = os.environ.get("SUPERVISOR_URL", "http://supervisor")
DRY = os.environ.get("ADDON_DRY_RUN") == "1"
@@ -35,10 +57,32 @@ 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.
# None yet: the agent proposes them from Home Assistant's devices, or imports
# an earlier install's mapping (/share/cantabile/mapping.yaml), consent off.
version: 1
assets: []
"""
IMPORT = "cantabile/mapping.yaml"
INGRESS_PORT = 8099
RESTART = 75
# The consent's texts: the Hub's (hub/.../cantabile/web CONSENT_TEXT,
# CONTROL_TEXT and CONSENT_VERSION), working texts until the legal team's.
CONSENT_TEXT = "Cantabile may receive the energy data of the devices chosen for it."
CONTROL_TEXT = ("Allow Cantabile to control the devices you choose (heating, charging, battery, shades) "
"within the limits you set.")
CONSENT_VERSION = "working-2026-10-29"
CONSENT_SOURCE = "given at installation in the add-on's configuration"
WAITING = {
"en": ("Cantabile is not connected",
"Cantabile connects only with your consent. In the add-on's Configuration (Settings, Apps or Add-ons, "
"Cantabile Edge Agent), turn on \"Share energy data with Cantabile\" (and, if you want, \"Cantabile may "
"control devices\"), save and restart the add-on.", "Open the configuration"),
"de": ("Cantabile ist nicht verbunden",
"Cantabile verbindet sich nur mit Ihrer Einwilligung. Schalten Sie in der Konfiguration des Add-ons "
"(Einstellungen, Apps bzw. Add-ons, Cantabile Edge Agent) „Energiedaten mit Cantabile teilen“ ein (und, "
"wenn Sie möchten, „Cantabile darf Geräte steuern“), speichern Sie und starten Sie das Add-on neu.",
"Konfiguration öffnen"),
}
def log(msg):
@@ -76,6 +120,88 @@ def chown_tree(path, own):
os.chown(path, *own)
def consent(opts, own, now=None):
"""The owner's consent from the configuration into the agent's consent
file; True when sharing is given. Kept as it was (and when it was given)
while unchanged; the operators' consents (the add-on's page) stay."""
path = f"{DATA}/state/consent.json"
try:
with open(path) as f:
d = json.load(f)
d = d if isinstance(d, dict) else {}
except (OSError, ValueError):
d = {}
share = opts.get("consent_data") is True
control = share and opts.get("consent_control") is True
if (d.get("share"), d.get("control"), d.get("text_version"), d.get("by")) != \
(share, control, CONSENT_VERSION, "ha-addon-config") or not os.path.exists(path):
d.update(share=share, control=control, at=int(now or time.time()), by="ha-addon-config",
source=CONSENT_SOURCE, text_version=CONSENT_VERSION,
texts={"share": CONSENT_TEXT, "control": CONTROL_TEXT})
os.makedirs(os.path.dirname(path), exist_ok=True)
put(path, json.dumps(d, ensure_ascii=False), 0o600, own)
log(f"consent from the configuration: sharing {'given' if share else 'not given'}, "
f"control {'given' if control else 'not given'} (texts {CONSENT_VERSION})")
return share
def own_slug():
"""This add-on's slug from the Supervisor (for the link to its
configuration); "" when it can't be asked."""
token = os.environ.get("SUPERVISOR_TOKEN", "")
req = urllib.request.Request(f"{SUPERVISOR}/addons/self/info", headers={"Authorization": f"Bearer {token}"})
try:
with urllib.request.urlopen(req, timeout=10) as r:
return str((json.load(r).get("data") or {}).get("slug") or "")
except (OSError, ValueError):
return ""
def waiting_html(accept_language, slug=""):
"""The page while there is no consent, in German or English, in HA's
light or dark look, with a button to the add-on's configuration."""
lang = "de" if (accept_language or "").strip().lower().startswith("de") else "en"
title, text, button = WAITING[lang]
link = (f'<p><a class="b" target="_top" href="/hassio/addon/{html.escape(slug)}/config">{html.escape(button)}</a></p>'
if re.fullmatch(r"[a-z0-9_]+", slug or "") else "")
return (f'<!doctype html><html lang="{lang}"><head><meta charset="utf-8"><meta name="viewport" '
f'content="width=device-width,initial-scale=1"><title>{html.escape(title)}</title><style>'
"body{font-family:system-ui,sans-serif;margin:16px;max-width:46rem;background:#fff;color:#1c1c1c}"
"a.b{display:inline-block;padding:.6rem 1rem;border-radius:8px;background:#03a9f4;color:#fff;"
"text-decoration:none}"
"@media (prefers-color-scheme:dark){body{background:#111;color:#e1e1e1}}</style></head><body>"
f"<h2>{html.escape(title)}</h2><p>{html.escape(text)}</p>{link}</body></html>")
def waiting_page(own):
"""No consent: the add-on's page (HA's ingress) says why Cantabile is not
connected and where to give it; nothing is enrolled or sent."""
from http.server import BaseHTTPRequestHandler, HTTPServer
slug = own_slug()
class Page(BaseHTTPRequestHandler):
def do_GET(self):
body = waiting_html(self.headers.get("Accept-Language"), slug).encode()
ok = self.client_address[0] in ("172.30.32.2", "127.0.0.1", "::1")
self.send_response(200 if ok else 403)
self.send_header("Content-Type", "text/html; charset=utf-8" if ok else "text/plain")
self.send_header("Cache-Control", "no-store")
self.end_headers()
self.wfile.write(body if ok else b"Open this page from Home Assistant.")
do_POST = do_GET
def log_message(self, *a):
pass
server = HTTPServer(("0.0.0.0", INGRESS_PORT), Page)
if own:
os.setgroups([])
os.setgid(own[1])
os.setuid(own[0])
server.serve_forever()
def mqtt(env, own):
token = os.environ.get("SUPERVISOR_TOKEN", "")
req = urllib.request.Request(f"{SUPERVISOR}/services/mqtt", headers={"Authorization": f"Bearer {token}"})
@@ -97,6 +223,21 @@ def mqtt(env, own):
log(f"MQTT broker {d['host']}:{env['CANTABILE_MQTT_PORT']}")
def fingerprint(env, own):
"""The box's hardware ids, hashed by the link itself (`cantabile-link
fingerprint`, as root); no raw serial is written."""
if DRY:
return
try:
out = subprocess.run(["cantabile-link", "fingerprint"], capture_output=True, text=True, timeout=30).stdout
json.loads(out)
except (OSError, ValueError, subprocess.TimeoutExpired) as e:
log(f"no hardware fingerprint: {e}")
return
put(f"{DATA}/fingerprint.json", out, own=own)
env["CANTABILE_FINGERPRINT_FILE"] = f"{DATA}/fingerprint.json"
def main():
own = owner()
with open(f"{DATA}/options.json") as f:
@@ -111,11 +252,24 @@ def main():
env["CANTABILE_COMMAND_CERT"] = f"{ETC}/commands.pem"
if os.path.exists(f"{ETC}/bundles.pem"):
env["CANTABILE_BUNDLE_CERT"] = f"{ETC}/bundles.pem"
if os.path.exists(f"{ETC}/devices-ca.pem"): # the direct path's CA (docs/direct-link.md)
env["CANTABILE_DEVICES_CA"] = f"{ETC}/devices-ca.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"
if not consent(opts, own):
log("no consent to share energy data (the add-on's configuration): not connecting to Cantabile. "
"Turn on \"Share energy data with Cantabile\" in the Configuration tab and restart the add-on.")
if DRY:
print(json.dumps({"consent": False}))
return
waiting_page(own)
return
fingerprint(env, own)
code = (opts.get("claim_code") or "").strip()
if code:
put(f"{DATA}/claim-code", code + "\n", own=own)
@@ -125,6 +279,15 @@ def main():
put(f"{DATA}/config.yaml", CONFIG, 0o644, own, keep=True)
put(f"{DATA}/mapping.yaml", MAPPING, 0o644, own, keep=True)
env["CANTABILE_PROPOSE"] = "1"
try:
with open(f"{SHARE}/{IMPORT}") as f:
put(f"{DATA}/mapping-import.yaml", f.read(), 0o600, own)
log(f"an earlier install's mapping in /share/{IMPORT}: the agent imports it once, consent off")
except FileNotFoundError:
pass
except (OSError, UnicodeDecodeError) as e:
log(f"/share/{IMPORT} not read: {e}")
os.makedirs(f"{DATA}/state", exist_ok=True)
if own:
chown_tree(DATA, own)
@@ -137,7 +300,21 @@ def main():
# 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)
# 75: the agent asks to start again (a device's consent or controls
# changed on its page, as the Hub's devices tool restarts it)
child = None
def forward(sig, _frame):
if child is not None:
child.send_signal(sig)
for sig in (signal.SIGTERM, signal.SIGINT):
signal.signal(sig, forward)
while True:
child = subprocess.Popen(cmd, env=env)
rc = child.wait()
if rc != RESTART:
sys.exit(rc)
log("the agent starts again")
if __name__ == "__main__":