ebus-evidence

ebus-evidence turns existing ebusd message-mode raw logs into small, reproducible evidence for cross-installation eBUS research.

It is deliberately passive:

• no direct eBUS adapter access;
• no eBUS writes or telegram injection;
• no active probing just to create evidence;
• no MQTT publishing;
• no cloud upload;
• no automatic semantic naming or confidence scores.

The normal data path is:

eBUS adapter -> normal ebusd -> message-mode raw log -> ebus-evidence

Current research scope: the parser works on normal ebusd message-mode raw logs. Before a telegram can become a normal Frame or Evidence event, the parser validates the eBUS master CRC, response CRC, ACK/NAK state and complete transaction framing. Message-mode logs are an ebusd-generated representation, not a lossless wire capture; one known ebusd echo-logging artefact is handled only when the remaining response CRC and final ACK independently prove the transaction. The bundled hw5103-open-evidence profile and current real-world validation are focused on Vaillant-family systems, especially HW5103/HMU/VWZIO research paths. See Parser and validation status for the independent multi-million-line cross-installation results.

Beginner workflow

For the normal Linux/Docker or native ebusd path, the intended workflow is:

install -> doctor -> collect -> export

Requirements: Linux, Python 3.11+, Git, and a readable normal ebusd message-mode raw log.

1. Install

Choose any directory where your user can write. The home directory below is only a simple example; ebus-evidence does not need to live next to ebusd, Docker or under a specific system path.

cd ~   # example only
git clone https://github.com/MarcelT87/ebus-evidence.git
cd ebus-evidence
bash install.sh

You can also clone directly to another writable location, for example:

git clone https://github.com/MarcelT87/ebus-evidence.git /path/to/ebus-evidence
cd /path/to/ebus-evidence
bash install.sh

The installer creates a local .venv, installs the checkout and enables the local ./evidence launcher. Runtime data such as data/evidence-state.json and data/evidence.zip are kept relative to that checkout. It does not configure or access the eBUS adapter. For users who already use uv, an optional checkout-free path is also supported. Pin a release or exact commit and run all commands from the same working directory because the normal data/ files are relative to that directory:

mkdir ebus-evidence-run
cd ebus-evidence-run

uvx --from 'git+https://github.com/MarcelT87/ebus-evidence.git@v0.1.0rc2' \
  ebus-evidence doctor --raw /path/to/ebusd.raw --profile hw5103-open-evidence

uvx --from 'git+https://github.com/MarcelT87/ebus-evidence.git@v0.1.0rc2' \
  ebus-evidence import --raw /path/to/ebusd.raw --profile hw5103-open-evidence

uvx --from 'git+https://github.com/MarcelT87/ebus-evidence.git@v0.1.0rc2' \
  ebus-evidence export

This is an optional convenience path, not a replacement for the beginner installer. A VCS-installed uvx run may report Source commit: unavailable because the installed package need not retain a Git checkout; runtime and profile SHA-256 provenance are still recorded and verified.

2. Check

./evidence doctor

If doctor cannot auto-discover your setup, use an explicit file:

./evidence doctor --raw /path/to/ebusd.raw --profile hw5103-open-evidence

Do not use ebusd byte-mode logging (--lograwdata=bytes). The supported common input is normal message-mode raw logging.

3. Collect

./evidence collect

Collection is passive and read-only. There is no normal collection timer; it keeps following new raw-log records until you stop it with Ctrl-C.

The beginner command automatically uses:

profile:   hw5103-open-evidence
state:     data/evidence-state.json
contexts:  data/contexts

A later ./evidence collect resumes from the saved checkpoint when continuity can be proven. It does not silently discard a gap.

Check progress at any time with:

./evidence status

Existing/static raw-log file

If you already have a static copy of an ebusd message-mode raw log, do not use live collection just to replay history. Import the existing file from beginning to end:

./evidence doctor --raw /path/to/ebusd.raw --profile hw5103-open-evidence
./evidence import --raw /path/to/ebusd.raw
./evidence export

import is read-only, does not require ebusd to be running locally and refuses to mix the imported history with an existing evidence state.

4. Export a verified ZIP

./evidence export

This creates:

data/evidence.zip

and immediately verifies the bundle and the normal public-submission policy.

If data/system.json exists and is valid, it is included automatically. Raw context payloads remain excluded by default.

The successful result ends with:

Status .............. VALID
Deterministic ....... yes
Public submission ... PASS

Ready to share.

5. Submit the evidence

For community review, submit the generated:

data/evidence.zip

through the repository's Evidence submission issue form.

The form has one required .zip upload field plus a small environment/privacy checklist. A normal default export should report Public submission ... PASS before you upload it. You do not need to copy verifier output into the issue: export already performs the local structural and public-submission checks, and maintainers should independently verify every submitted ZIP before trusting it.

Do not attach the complete ebusd.raw file. The normal ZIP intentionally keeps the contribution small and excludes raw context by default.

See Submit evidence for the exact sharing and privacy workflow.

Optional system identity

For cross-installation hardware/firmware comparison, an existing ebusctl scan result can be converted into a privacy-minimized data/system.json.

No scan is initiated by ebus-evidence.

See System identity.

Advanced / explicit commands

The beginner commands are convenience wrappers around the same implementation. The explicit expert interface remains available:

ebus-evidence doctor
ebus-evidence import
ebus-evidence analyze
ebus-evidence watch
ebus-evidence system
ebus-evidence bundle
ebus-evidence verify

Use the explicit commands when you need custom profiles, paths, timezone handling, JSON analysis output, checkpoint controls or explicit bundle options.

For example:

source .venv/bin/activate

ebus-evidence watch \
  --profile hw5103-open-evidence \
  --state data/evidence-state.json \
  --context-dir data/contexts

analyze inspects existing raw-log history. It does not create the persistent evidence state used by collect or import before export.

Privacy

The normal export:

• excludes raw context payloads;
• excludes absolute host paths;
• excludes resume checkpoint/device/inode details;
• excludes host metadata and credentials;
• retains absolute observation/evidence timestamps because timing is part of reproducible evidence;
• explicitly discloses timestamp retention in the bundle/verifier output.

Only use --include-context-raw when you deliberately want reviewed raw context payloads in the ZIP.

Supported setups

Setup	Current status
normal ebusd in Docker + readable message-mode raw log	supported and real-world validated
normal ebusd via native/systemd + readable message-mode raw log	supported; more independent validation wanted
copied/static message-mode raw log	supported through import
read-only mounted growing message-mode raw log	supported through collect
Home Assistant OS eBUSd App/Add-on	file-based workflow
direct adapter access	intentionally unsupported
ebusd byte-mode raw log	unsupported

The adapter transport used by ebusd is outside the evidence boundary.

Documentation

• Installation and first run — beginner and advanced paths
• ebusd setup matrix — Docker/native/remote layouts
• System identity — privacy-minimized hardware/firmware identity
• Community test — cross-installation contribution workflow
• Parser and validation status — CRC/framing guarantees, known ebusd logging caveat and independent full-dataset validation
• Submit evidence — upload a generated evidence ZIP through the structured public form
• Bundle format v1 — public ZIP/data contract for independent consumers
• Home Assistant — special file-based route for Home Assistant users
• Troubleshooting — symptom-based help
• Project boundaries — what this repository owns and what stays outside it

Development

source .venv/bin/activate
python -m pip install -e '.[dev]'
pytest -q

Tests use synthetic fixtures and do not require a heating system.

Relationship to ebusd

ebusd is a separate project maintained by John30 and contributors.

ebus-evidence is an independent community project. It is not part of ebusd and does not bundle or redistribute ebusd.

License

MIT. See LICENSE.