66 lines
2.3 KiB
Markdown
66 lines
2.3 KiB
Markdown
|
# Contributing
|
||
|
|
|
||
|
|
## Before opening an issue
|
||
|
|
|
||
|
|
Run `solixauto doctor` and include its output. It reports platform, Python
|
||
|
|
version, dependencies, whether credentials resolve, detected subnets, and
|
||
|
|
notification status.
|
||
|
|
|
||
|
|
**Do not paste secrets.** Never include:
|
||
|
|
|
||
|
|
- `notifications.yaml` or any part of it
|
||
|
|
- your `.env` file, Anker email, or password
|
||
|
|
- your ntfy topic (anyone with it can read your alerts)
|
||
|
|
|
||
|
|
Device profiles contain serial numbers. Redact them if that matters to you.
|
||
|
|
|
||
|
|
## Reporting a device that does not work
|
||
|
|
|
||
|
|
Include:
|
||
|
|
|
||
|
|
- model and part number, e.g. `A1782`
|
||
|
|
- what `solixauto discover-anker` printed
|
||
|
|
- whether the device shows as online in the Anker app at the time
|
||
|
|
- for Shelly devices, generation and model, plus `solixauto conflicts <plug>`
|
||
|
|
|
||
|
|
Devices that pair over Bluetooth only cannot be supported here. They publish
|
||
|
|
nothing to Anker's cloud MQTT broker. That is a hardware limitation, not a bug.
|
||
|
|
|
||
|
|
## Field mappings
|
||
|
|
|
||
|
|
Telemetry field names come from the upstream
|
||
|
|
[anker-solix-api](https://github.com/thomluther/anker-solix-api) project.
|
||
|
|
Corrections to field meanings belong there, not here.
|
||
|
|
|
||
|
|
If a field is wrong or missing for your model, that is the right place to
|
||
|
|
report it. This project only adds derived fields computed from what upstream
|
||
|
|
already decodes.
|
||
|
|
|
||
|
|
## Code changes
|
||
|
|
|
||
|
|
- No comments in code; the project is written without them
|
||
|
|
- Match the existing style rather than introducing a formatter
|
||
|
|
- Anything touching the engine needs a matching check in `--test` output. If
|
||
|
|
a behaviour cannot be observed with `--test`, it is very hard for a user to
|
||
|
|
trust it.
|
||
|
|
- Safety-relevant changes (the battery floor, stale handling, rate limits)
|
||
|
|
should come with a description of the failure mode they address
|
||
|
|
|
||
|
|
## Testing
|
||
|
|
|
||
|
|
There is no unit test suite yet. Contributions that add one are welcome.
|
||
|
|
|
||
|
|
At minimum, exercise the paths you touched:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
solixauto run <profile> --test --offline
|
||
|
|
solixauto run <profile> --test --simulate battery_soc=12
|
||
|
|
solixauto run <profile> --dry-run --cycles 6
|
||
|
|
```
|
||
|
|
|
||
|
|
A fake Shelly is easy to stand up with aiohttp if you need to test the control
|
||
|
|
path without hardware; the RPC surface used is small: `/shelly`,
|
||
|
|
`/rpc/Shelly.GetStatus`, `/rpc/Shelly.GetConfig`, `/rpc/Switch.Set`,
|
||
|
|
`/rpc/Switch.SetConfig`, `/rpc/Schedule.List`, `/rpc/Schedule.Delete`,
|
||
|
|
`/rpc/Webhook.List`.
|