Contributing and Development

Contributing and development

The repository's CLAUDE.md is the developer guide: architecture, the test suite, the CI gate, the release process, and the conventions. It is written for an AI assistant, which makes it unusually explicit, and everything in it applies to a human contributor as well. This page only says where to start for the common kinds of contribution.

Reporting hardware

The most valuable contribution, and it needs no code. Hardware reports says what to include.

Fixing a vendor note

Vendor notes is a wiki page. Edit it if your account can, or open an issue with the correction.

Running the tests

The suite runs in Docker, because Home Assistant imports fcntl and Windows Python has none, and because the container installs exactly what CI installs. tests/docker/README.md has the commands; the short form is:

docker compose -f tests/docker/compose.yml run --rm tests

Lint and types are ruff and mypy --strict, configured in pyproject.toml. All five CI jobs (ruff, mypy, hassfest, HACS validation, pytest) are required checks on main, for everyone.

Adding a discovery OUI

Network scan and DHCP discovery share one list of manufacturer MAC prefixes, kept in two places that must match: SUNSPEC_VENDOR_OUIS in discovery.py and the dhcp array in manifest.json. A PR that adds a prefix should say which device it was read from.

Adding a write control

Every writable point is one entry in write_controls.py. The module docstring explains why it is a curated list rather than "everything SunSpec marks writable", and which blocks are off limits because they hold grid protection settings. A new entry needs a translation key in translations/en.json and de.json, and a test in tests/test_write.py.

The model definitions

The JSON files under pysunspec2/models/json/ are pulled from sunspec/models by a scheduled workflow that opens a PR when they changed. Do not edit them by hand; a fix belongs upstream.

The embedded pysunspec2

Transport fixes go into custom_components/sunspec2/pysunspec2/, not into workarounds in api.py. Its __init__.py records every change against upstream; add yours to that list. The upstream unit tests live in tests/pysunspec2/ and run with the rest of the suite.