Developer Guide¶

Setup¶

git clone https://github.com/mikemccllstr/voltkeeper
cd voltkeeper
uv sync --group dev
mise run setup

Installs dependencies, then sets up pre-commit hooks (lint, format, typecheck) that run automatically on every commit. The CI will catch it if you skip this step, but you’ll save yourself a round-trip.

Architecture¶

voltkeeper is organized into three main packages under src/voltkeeper/:

Package	Purpose
`bluetooth/`	BLE client, scan, device factory, encryption, handshake
`core/`	Modbus commands, field struct definitions, device model hierarchy
`core/devices/`	Per-model device classes (V1 and V2 protocol)

Top-level modules handle CLI commands (cli.py), device polling (device_handler.py), MQTT integration (mqtt_client.py), load testing (load_test.py), probe and annotation (probe.py, annotate.py), and validation (validate.py).

Development workflow¶

All work follows test-driven development. The full quality gate is:

mise run check

This runs lint, typecheck, and tests. Individual checks:

Task	What it runs
`mise run lint`	Ruff linter
`mise run typecheck`	Mypy type checker
`mise run test`	Pytest with branch coverage
`mise run test-fast`	Pytest without coverage overhead
`mise run format`	Ruff formatter (applies changes)
`mise run setup`	Install pre-commit hooks (run once after cloning)
`mise run format-check`	Ruff formatter (check only)

Building documentation¶

mise run docs

Builds both HTML and man page output from the Sphinx source tree.

Commit style¶

Lowercase imperative, single line, no period:

add cipher module: aes-128-cbc with chained iv per FINDINGS §15.8

Adding a new device¶

See Contributing Devices for the contributor guide and Maintainer Guide for merging submissions.