Files
cantabile-ha-addons/README.md
T

84 lines
4.2 KiB
Markdown

# Cantabile add-ons for Home Assistant
Copyright © 2026 Setti Solutions S.R.L, www.setti.md. All rights reserved. This notice covers every file in this
repository, including those that cannot carry a comment (the device
profiles' JSON, `go.sum`, images): see `LICENSE` and `NOTICE`.
Cantabile plans a home's energy (solar, battery, heating, charging) and,
with the owner's consent, runs the devices the owner chooses. These add-ons
bring it to any Home Assistant (HA OS or Supervised).
| Add-on | What it does |
|---|---|
| `cantabile_edge`: **Cantabile Edge Agent** | Connects this Home Assistant to Cantabile: reads the devices the owner chose (only with the owner's consent), plans, and with consent to control runs them through Home Assistant. Python agent and a Go link (the site's key and its connection to the platform). |
| `cantabile_modbus`: **Cantabile Modbus bridge** | Reads inverters, meters, relays and circuits by Cantabile's device profiles (Modbus TCP, or Home Assistant's own entities) and shows them in Home Assistant, each control with its protection. |
| `cantabile_eebus`: **Cantabile EEBUS** | Pairs with EEBUS devices (the grid operator's control box, heat pumps, wallboxes, inverters), shows them in Home Assistant and hands the grid operator's §14a limit to the agent. Go, on enbility's eebus-go. |
Each add-on's `DOCS.md` is what the owner reads in Home Assistant.
## Install
Settings → Add-ons → Add-on store → ⋮ → Repositories, add
`https://git.setti.solutions/Daniel/cantabile-ha-addons`, then install the
add-on. The Supervisor pulls the prebuilt images
(`git.setti.solutions/daniel/cantabile-ha-<edge|modbus|eebus>-<arch>:<version>`,
named by `image:` in each `config.yaml`); this version: `0.1.676`, arch amd64.
## Layout
| Path | What |
|---|---|
| `repository.yaml` | The add-on repository (HA reads it here). |
| `cantabile_edge/`, `cantabile_modbus/`, `cantabile_eebus/` | The add-ons: manifest (`config.yaml`), `Dockerfile`, start scripts, owner's documentation, translations, icons. |
| `src/edge/` | The Edge Agent image: `cantabile_edge/` (Python), `link/` (Go: `cantabile-link`), `run.sh`, `Dockerfile`, `tests/`. |
| `src/modbus-bridge/` | The Modbus bridge (`bridge.py`) and its Modbus TCP code (`cantabile_modbus.py`). |
| `src/eebus-bridge/` | The EEBUS bridge (Go) and its third-party notices. |
| `src/profiles/` | Cantabile's device profiles (JSON; `README.md` describes the format). |
| `tests/` | The add-ons' tests (manifests, `addon-run`, the Modbus add-on, the EEBUS add-on). |
## Build the images
From the repository's root, with Docker (BuildKit). `VERSION` is the
add-on's version (`config.yaml`); `ARCH` is HA's arch name (`amd64`,
`aarch64`; add `--platform linux/arm64` for aarch64).
```
# Cantabile Edge Agent: the agent image first, then the add-on on top.
# The platform's files go to cantabile_edge/platform/ first (README.md there).
docker build -t cantabile-edge:local --build-arg VERSION=$VERSION src/edge
docker build -f cantabile_edge/Dockerfile --build-arg EDGE_IMAGE=cantabile-edge:local \
--build-arg VERSION=$VERSION -t cantabile-ha-edge-amd64:$VERSION .
# Cantabile Modbus bridge
docker build -f cantabile_modbus/Dockerfile --build-arg VERSION=$VERSION -t cantabile-ha-modbus-amd64:$VERSION .
# Cantabile EEBUS
docker build -f cantabile_eebus/Dockerfile --build-arg VERSION=$VERSION -t cantabile-ha-eebus-amd64:$VERSION .
```
To run an image you built instead of the published one, push it to a
registry you control and point `image:` in the add-on's `config.yaml` at it,
in a fork of this repository. (The Supervisor's own local build uses an
add-on's folder alone as build context; these images need `src/`, so they
are built as above.)
## Tests
```
# the add-ons (Python 3.12+, pytest, PyYAML, paho-mqtt, websocket-client)
python -m pytest tests
# the Edge Agent (from src/edge: pip install '.[test]')
cd src/edge && python -m pytest tests
# the link and the EEBUS bridge (Go 1.26)
(cd src/edge/link && go test ./...) && (cd src/eebus-bridge && go test ./...)
```
## Licence
Proprietary: see `LICENSE`. Third-party components and their licences:
`THIRD-PARTY-NOTICES.md`.
---
Copyright © 2026 Setti Solutions S.R.L, www.setti.md, [www.setti.md](https://www.setti.md). All rights reserved.