ebus-tools

Consumer-side tooling for eBus / Homie 5 deployments, built on ebus-sdk. A collection of small, standalone command-line tools that discover, visualize, snapshot, diff, and inspect a live eBus site over MQTT.

These tools use the SDK's consumer surface (Controller, SiteTopology); they are applications, not library mechanism. Keeping them here holds the SDK a pure library and gives operator/developer tooling one home instead of scattering it across adapter and simulator repos.

Status

Scaffold (0.1.0). The umbrella ebus-tools command reports the roster; each tool ships as its own console script as it lands. Track progress in the TOOLS-* backlog.

Tool	What it does	Status
ebus-topology	Discover the site and render its connection graph as Graphviz dot / Mermaid	planned
ebus-snapshot	Capture a live device tree (structure + values) to a file, and diff two snapshots	planned
ebus-inspect	Discover devices; print / get / set a device's nodes, properties, and values	planned

Install

pip install ebus-tools            # from PyPI (once released)
pip install -e .                  # from a checkout (editable, for development)
pip install -e ".[mdns]"          # + mDNS broker discovery (_secure-mqtt._tcp)

Requires Python 3.10+ and ebus-sdk>=0.14.

Usage

ebus-tools            # print the version and the tool roster
ebus-tools --version

Per-tool usage is documented as each tool lands.

Development

pip install -e ".[dev]"
pytest tests/ -v
ruff check .
ruff format --check .

CI runs ruff check + ruff format --check on every push/PR (lint.yml), and a v* tag triggers a test-gated PyPI publish via Trusted Publishing (publish.yml). The version is single-sourced in src/ebus_tools/__init__.py; the publish workflow refuses to release if the git tag disagrees.

First release also needs a one-time PyPI Trusted Publisher: on pypi.org, add a GitHub publisher for owner electrification-bus, repo tools, workflow publish.yml, environment pypi.

Layout

tools/
├── src/ebus_tools/         # package (PyPI: ebus-tools, import: ebus_tools)
│   ├── __init__.py         # __version__ (single source of truth)
│   └── cli.py              # umbrella `ebus-tools` entry point
├── tests/                  # smoke tests (import + CLI)
├── pyproject.toml          # package config + console_scripts + ruff/pytest
├── .ebus-spec.json         # spec application lockfile (role=controller)
└── .github/workflows/      # lint.yml, publish.yml

License

MIT (c) 2026 Clark Communications Corporation.