TL;DR
The README tells users that rain settings, schedules, multi-area, and PIN changes are not supported, but the library already implements and exports those operations. Users cannot tell which APIs are production-ready, experimental, or unsafe to use.
Problem
The README currently lists these items under “Not yet supported”:
- settings writes for rain;
- schedules;
- multi-area;
- PIN change.
Relevant code and documentation:
The Home Assistant integration also exposes these methods as user-facing services and entities.
Why it happens
Protocol features were added after the original README status section, but the public capability matrix was not updated with the implementation. The project now has several different confidence levels:
- hardware-captured and tested behavior;
- implemented but still experimental behavior;
- APK-derived research helpers;
- unknown or unsupported behavior.
A binary supported/unsupported list no longer describes the actual state accurately.
Current behavior
- Developers may avoid valid APIs because the README says they do not exist.
- Other developers may discover methods in code and assume they are fully supported despite unresolved timing, verification, and partial-write risks.
- Home Assistant exposes functions that the underlying library documentation calls unsupported.
- Release notes and support expectations are inconsistent between the two projects.
Expected behavior
The README should contain a capability matrix with explicit maturity and evidence, for example:
| Feature |
Read |
Write |
Evidence |
Stability |
| Status |
Yes |
N/A |
Hardware capture |
Supported |
| Start/pause/dock |
N/A |
Yes |
Hardware capture |
Experimental until confirmation is fixed |
| Multi-area |
Yes |
Yes |
Hardware capture |
Experimental |
| Mower settings |
Yes |
Yes |
Partial capture |
Experimental |
| Work times |
Yes |
Yes |
Hardware capture |
Experimental |
| PIN change |
Yes |
Yes |
Hardware capture |
Experimental |
| Firmware update |
No |
No |
Unknown |
Unsupported |
The public API documentation should also state important semantics such as authentication, confirmation guarantees, complete-vs-partial writes, and possible indeterminate outcomes.
Impact
Incorrect documentation makes it harder to assess whether command failures are implementation bugs, unsupported protocol areas, or expected experimental limitations. It also increases the chance that downstream projects depend on unstable behavior without realizing it.
Suggested direction
Update the README alongside each feature implementation and add a test or release checklist that compares documented capabilities against exported public methods. Link each experimental feature to its protocol evidence and known limitations.
Acceptance criteria
- The README no longer labels implemented operations as absent.
- Every public high-level operation has an explicit support/stability status.
- Experimental and hardware-confirmed behavior are clearly distinguished.
- The Home Assistant integration does not expose a feature as stable when pyGrouw documents it as experimental.
- Release changes that add or remove public operations include a documentation update.
TL;DR
The README tells users that rain settings, schedules, multi-area, and PIN changes are not supported, but the library already implements and exports those operations. Users cannot tell which APIs are production-ready, experimental, or unsafe to use.
Problem
The README currently lists these items under “Not yet supported”:
Relevant code and documentation:
The Home Assistant integration also exposes these methods as user-facing services and entities.
Why it happens
Protocol features were added after the original README status section, but the public capability matrix was not updated with the implementation. The project now has several different confidence levels:
A binary supported/unsupported list no longer describes the actual state accurately.
Current behavior
Expected behavior
The README should contain a capability matrix with explicit maturity and evidence, for example:
The public API documentation should also state important semantics such as authentication, confirmation guarantees, complete-vs-partial writes, and possible indeterminate outcomes.
Impact
Incorrect documentation makes it harder to assess whether command failures are implementation bugs, unsupported protocol areas, or expected experimental limitations. It also increases the chance that downstream projects depend on unstable behavior without realizing it.
Suggested direction
Update the README alongside each feature implementation and add a test or release checklist that compares documented capabilities against exported public methods. Link each experimental feature to its protocol evidence and known limitations.
Acceptance criteria