Skip to content

Commit 90b8459

Browse files
authored
Merge branch 'main' into fix/b01-q10-dp-codes-112-113
2 parents ee93f4d + 4411412 commit 90b8459

59 files changed

Lines changed: 1828 additions & 193 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/review/SKILL.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
name: review
3+
description: Conduct authoritative code review on python-roborock changes against repository architectural hierarchy, typing standards, and maintainer conventions.
4+
---
5+
6+
# Code Review Skill
7+
8+
Use this skill when reviewing pull requests, inspecting code changes, or verifying new device traits in `python-roborock`.
9+
10+
All reviews are evaluated against the engineering conventions defined in [AGENTS.md](../../../AGENTS.md).
11+
12+
---
13+
14+
## Review Workflow
15+
16+
1. **Classify Changed Files by Layer**:
17+
Group changed files according to the 3-tier architectural hierarchy:
18+
- **Priority 1: Public Trait APIs & Consumer Contracts** (`roborock/devices/traits/`, `roborock/data/containers.py`)
19+
- **Priority 2: Data Lifecycle & State Management** (trait state, callbacks, `RoborockDevice.close()`)
20+
- **Priority 3: Wire Protocols, Codecs & Cryptography** (`roborock/protocols/`, `roborock/devices/transport/`, `roborock/devices/rpc/`)
21+
22+
2. **Evaluate Layer 1: Public Trait APIs & Consumer Contracts**:
23+
- Are trait models subclassing `RoborockBase` with `@dataclass`?
24+
- Is `TypedDict` completely avoided for domain data models?
25+
- Is `Any` strictly prohibited on public trait boundaries?
26+
- Are forward references (`"ClassName"`) and `typing.TYPE_CHECKING` guards avoided? (Needing them usually indicates circular dependencies or coupling that should be refactored).
27+
- Are non-universal traits gated by device feature flags (`device.features`) and supported categories?
28+
- Are trait abstractions consumer-agnostic (not hardcoded exclusively to Home Assistant entities)?
29+
- Are transport details (keys, tokens, sockets) cleanly isolated from traits?
30+
31+
3. **Evaluate Layer 2: Lifecycle, State & Simplification**:
32+
- **Value-Returning Helpers**: Do helper functions return values instead of modifying `self` via hidden side effects?
33+
- **Direct Flow**: Is the execution path straightforward and direct, avoiding unnecessary indirection or ping-ponging between methods?
34+
- **Concurrency**: Does 1:1 async command-response matching use `asyncio.Future` correlated by protocol request/sequence ID (`request_id` or `msg_id`)?
35+
- **Teardown**: Are all tasks, event listeners, and channels cleanly unhooked in `RoborockDevice.close()`?
36+
- **Capability Gating**: Is capability gating checking protocol version, category (appropriate for device family), and device feature flags?
37+
38+
4. **Evaluate Layer 3: Wire Protocols, Codecs & Resilient Enums**:
39+
- Do status and error code enums subclass `RoborockEnum` (with lowercase `unknown = -1` member) or `RoborockModeEnum` (with `from_code_optional()`)?
40+
- Are unexpected wire codes prevented from crashing via unhandled `ValueError`?
41+
- Is wire-contained `Any` properly scoped to genuine protocol polymorphism (e.g. Tuya DPS maps)?
42+
43+
5. **Evaluate Tests & Fixtures**:
44+
- **Test Mirroring & Colocation**: Are tests colocated in the matching mirror path under `tests/` for the module being tested (e.g., tests for `roborock/devices/traits/v1/status.py` in `tests/devices/traits/v1/test_status.py`; new modules have corresponding new test suites under the mirror directory)?
45+
- **No One-Off Bugfix Test Files**: Flag any fragmented single-bug or single-PR test files (e.g., `tests/test_battery_low_voltage_fix.py`). Tests must be integrated into the module's corresponding test suite.
46+
- Are tests using `fake_channel` and `@pytest.mark.parametrize` rather than hand-rolled mocks or duplicate methods?
47+
- Do assertions verify public behavior rather than private `_state` variables?
48+
49+
6. **Format Review Output**:
50+
Structure review comments with clear rationale and actionable code recommendations:
51+
- **Priority Level & File Reference**
52+
- **Issue / Anti-Pattern Identified**
53+
- **Grounded Rationale** (citing protocol resilience, consumer stability, or maintainability)
54+
- **Concrete Before / After Diff or Suggested Fix**

‎.claude/skills‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../.agents/skills

‎AGENTS.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Repository Engineering Guidelines: python-roborock
2+
3+
## Overview & Scope
4+
`python-roborock` is an asynchronous (`asyncio`) device integration library supporting multi-protocol Roborock vacuum and home appliances (V1 JSON-RPC over AES, B01 Tuya DPS for Q7/Q10, and A01 Tuya DPS for Dyad/Zeo). While Home Assistant Core is a primary downstream consumer, `python-roborock` is an independent client library whose public abstractions must remain general-purpose and consumer-agnostic.
5+
6+
This document serves as the authoritative, single source of truth for engineering conventions, architectural standards, and automated code reviews across all contributors and coding agents.
7+
8+
---
9+
10+
## Environment & Tooling Standards
11+
- **Target**: Python 3.11+, Hatchling build backend, `uv` package manager.
12+
- **Linters & Formatters**: Ruff (line length 120), Mypy (`check_untyped_defs = true`), Codespell.
13+
- **Testing**: pytest (`pytest-asyncio`).
14+
15+
### Key Developer Commands
16+
```bash
17+
# Environment setup
18+
uv venv && uv sync
19+
20+
# Run tests
21+
uv run pytest
22+
uv run pytest tests/devices/traits/v1/test_status.py
23+
uv run pytest tests/protocols/test_v1_protocol.py
24+
25+
# Lint and typecheck
26+
uv run pre-commit run --all-files
27+
# or directly:
28+
uv run ruff check roborock tests
29+
uv run mypy roborock tests
30+
```
31+
32+
---
33+
34+
## Core Architectural Hierarchy & Review Priorities
35+
Evaluate every change against the repository's three core layers in strict priority order:
36+
37+
1. **Priority 1: Public Trait APIs & Consumer Contracts** (Highest Priority)
38+
- Clean, stable user-facing abstractions decoupled from wire protocol details, Tuya DPS keys, encryption keys, or transport sockets.
39+
- Strongly typed with concrete models subclassing `RoborockBase`; never expose raw protocol dictionaries or `Any` on public boundaries.
40+
41+
2. **Priority 2: Data Lifecycle & State Management**
42+
- Simple, linear data flow. Keep side effects visible: helper functions MUST be pure transformations that compute and return values rather than mutating object state as a side effect.
43+
- Exhaustive lifecycle teardown: all listeners, background tasks, and channels cleanly unhooked in `RoborockDevice.close()`.
44+
- Concurrency: 1:1 request/response matching across async push channels uses `asyncio.Future` correlated by protocol request/sequence ID (`request_id` for V1 RPC, `msg_id` for B01/Tuya).
45+
- Transform data in render pipelines; never mutate cached telemetry state or raw packets for presentation effects.
46+
47+
3. **Priority 3: Wire Protocol Parsers, Codecs & Cryptography**
48+
- Encapsulate cryptography (AES, MD5), protocol framing, and raw sockets to `roborock.protocols` and `roborock.devices.transport` / `roborock.devices.rpc`.
49+
- Keep protocol families (V1 JSON-RPC, B01 Tuya DPS, A01 Tuya DPS) strictly isolated; never conflate schemas across families.
50+
- Enforce enum fallback resilience (`RoborockEnum` with lowercase `unknown = -1` or `RoborockModeEnum.from_code_optional()`); never crash on unexpected firmware codes.
51+
52+
---
53+
54+
## Detailed Engineering Conventions
55+
56+
### 1. Typing & Data Models
57+
- **Subclass `RoborockBase`**: Define structured domain and wire data models as `@dataclass` subclassing `RoborockBase` (`from_dict`, `as_dict`). Avoid `TypedDict` or loose dicts. (Binary protocol packets, transport message envelopes, and map layers are exempt).
58+
- **Enum Fallback Resilience**: All enums representing device status, firmware modes, error codes, and wire protocol integer codes MUST inherit from `RoborockEnum` (defining a lowercase `unknown = -1` or `0` member) or `RoborockModeEnum` (using `from_code_optional()`). Internal enums not decoding unknown firmware codes remain standard `Enum`/`StrEnum`.
59+
- **Strongly Type What You Know; Contain `Any` to the Wire**: Public trait APIs, method signatures, properties, and domain models MUST declare concrete types. `Any` is accepted only where the underlying wire protocol is dynamic or polymorphic (Tuya DPS maps, low-level RPC dispatch, serialization helpers, evolving cloud schemas).
60+
- **Avoid Forward References & `TYPE_CHECKING`**: Avoid stringified forward references (`"ClassName"`) and `if typing.TYPE_CHECKING:` guards wherever possible. They typically indicate circular dependencies or coupling that should be refactored by extracting shared models.
61+
- **Explicit Parameters**: Do not mark arguments or dataclass fields as `Optional[...]` or default them to `None` if they are always required by the protocol or caller.
62+
- **Trust Type Annotations**: Prohibit defensive runtime `isinstance` checks on statically typed parameters in business and trait logic. (Dynamic wire payload unpacking and type narrowing in `from_dict` or RPC deserializers is legitimate and expected).
63+
64+
### 2. Protocol & Device Communications
65+
- **Channel Trait Boundary**: Traits receive only an abstract communication channel (e.g., `Channel`, `RpcChannel`). Never pass device local keys, security tokens, IP addresses, or transport sockets into `Trait` instances.
66+
- **Version Isolation**: Keep V1, B01, and A01 parser pipelines strictly isolated. Do not bleed Tuya DPS decoding logic into V1 or vice versa.
67+
68+
### 3. Trait Design & Client Integration
69+
- **Compound Capability & Feature Gating**: Capability and trait availability MUST be gated by protocol version (`device.pv == "1.0"` or `DeviceVersion.V1`), appropriate category (`RoborockCategory.VACUUM`, `WET_DRY_VAC`, or `WASHING_MACHINE`), and device feature flags (`device.features`).
70+
- **Linear State Flow**: Methods that parse responses or transform telemetry must return values to make state assignments explicit at the call site. Avoid multi-layered helper cascades.
71+
- **Consumer Agnosticism**: Design traits around cohesive, general-purpose consumer concepts (`CleanHistoryTrait`, `DockTrait`, `ConsumableTrait`), not low-level firmware registers or raw Tuya DPS numbers.
72+
- **Diagnostic Safety & Privacy**: Exclude sensitive user information (Wi-Fi SSIDs, passwords, cloud tokens, encryption keys) from device diagnostics and logs.
73+
74+
### 4. Error Handling & Exceptions
75+
- **Hierarchy Rooting**: All custom exceptions MUST inherit from `roborock.exceptions.RoborockException`.
76+
- **Specific Exception Narrowing**: Catch only specific, expected exception classes (`RoborockTimeout`, `RoborockConnectionException`, `json.JSONDecodeError`). Catching broad `Exception` is permitted only in teardown/cleanup handlers (e.g. `device.py`) to guarantee resources are unsubscribed before re-raising or logging.
77+
- **Context-Rich Parsing Exceptions**: Wrap deserialization, decoding, and schema mapping errors into `RoborockParsingException` with rich context (`trait_name`, `command`, `payload`, `inner_error`).
78+
- **Guard Clauses**: Flatten nested conditional branches with early exit guard clauses (`if not condition: return`).
79+
80+
### 5. Test Patterns & Fixtures
81+
- **Test Mirroring & Colocation**: Place and maintain unit tests in the matching mirror path under `tests/` (e.g. `tests/devices/traits/v1/test_status.py` for `roborock/devices/traits/v1/status.py`; `tests/map/test_b01_q10_map_parser.py` for `roborock/map/b01_q10_map_parser.py`).
82+
- **Avoid One-Off Test Files**: Do not create fragmented, single-bug test files (such as `tests/test_battery_low_voltage_fix.py`). Integrate test cases into the module's corresponding test suite.
83+
- **Fixture Reuse & Parametrization**: Reuse shared fixtures (`fake_channel`, `message_builder`, `device_fixture`) in `tests/` and use table-driven `@pytest.mark.parametrize`.
84+
- **Behavior-Driven Assertions**: Assert on public trait methods, return values, and emitted channel commands—never on private object attributes (`_state`).
85+
86+
### 6. PR Hygiene & Sizing
87+
- **Scoping & Sizing**: Keep pull requests focused on a single logical change or subsystem where possible (e.g. parser module with tests in one PR, traits consuming it in a follow-up PR). Large PRs (>500–1,000 LOC) take longer to review and block releases.
88+
- **CI Requirements**: PRs must pass automated CI (`.github/workflows/ci.yml`):
89+
- **Commitlint**: Commit messages and PR titles MUST follow Conventional Commits (`feat:`, `fix:`, `refactor:`, `chore:`, `docs:`).
90+
- **Pre-commit**: Ruff, Mypy (`check_untyped_defs = true`), and Codespell must pass (`uv run pre-commit run --all-files`).
91+
- **Pytest**: All unit tests must pass (`uv run pytest`).
92+
- **Logical Placement**: Place domain constants and enums in the module where they are consumed or in `roborock.data.code_mappings`. Do not duplicate definitions across files.
93+
94+
---
95+
96+
## Available Agent Skills
97+
98+
Portable agent skills following the [Agent Skills specification](https://agentskills.io/specification) are located under `.agents/skills/`:
99+
100+
- **Code Review Skill** (`.agents/skills/review/SKILL.md`):
101+
A structured, interactive review workflow for evaluating pull requests and diffs against the repository's architectural hierarchy, typing rules, and testing standards. To invoke during interactive sessions, refer to [.agents/skills/review/SKILL.md](.agents/skills/review/SKILL.md).

‎CHANGELOG.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,97 @@
22

33
<!-- version list -->
44

5+
## v7.6.0 (2026-09-13)
6+
7+
### Features
8+
9+
- Add dust collection settings to the B01 Q7 api
10+
([#919](https://github.com/Python-roborock/python-roborock/pull/919),
11+
[`b8b2409`](https://github.com/Python-roborock/python-roborock/commit/b8b2409404438478f36f3ef343f4828423caaffb))
12+
13+
14+
## v7.5.0 (2026-09-12)
15+
16+
### Bug Fixes
17+
18+
- Resolve Q7 map mypy errors ([#911](https://github.com/Python-roborock/python-roborock/pull/911),
19+
[`09c9a5b`](https://github.com/Python-roborock/python-roborock/commit/09c9a5b1bd3d2f7e5c635b70d10948fbaf7b8b66))
20+
21+
### Features
22+
23+
- Align Q7 map colors with V1 ([#911](https://github.com/Python-roborock/python-roborock/pull/911),
24+
[`09c9a5b`](https://github.com/Python-roborock/python-roborock/commit/09c9a5b1bd3d2f7e5c635b70d10948fbaf7b8b66))
25+
26+
- Color and label Q7 rooms in the rendered map
27+
([#911](https://github.com/Python-roborock/python-roborock/pull/911),
28+
[`09c9a5b`](https://github.com/Python-roborock/python-roborock/commit/09c9a5b1bd3d2f7e5c635b70d10948fbaf7b8b66))
29+
30+
- Decode and render Q7 carpets ([#911](https://github.com/Python-roborock/python-roborock/pull/911),
31+
[`09c9a5b`](https://github.com/Python-roborock/python-roborock/commit/09c9a5b1bd3d2f7e5c635b70d10948fbaf7b8b66))
32+
33+
- Decode Q7 (B01) map geometry — dock, robot pose, path and rooms
34+
([#911](https://github.com/Python-roborock/python-roborock/pull/911),
35+
[`09c9a5b`](https://github.com/Python-roborock/python-roborock/commit/09c9a5b1bd3d2f7e5c635b70d10948fbaf7b8b66))
36+
37+
- Render Q7 restricted areas ([#911](https://github.com/Python-roborock/python-roborock/pull/911),
38+
[`09c9a5b`](https://github.com/Python-roborock/python-roborock/commit/09c9a5b1bd3d2f7e5c635b70d10948fbaf7b8b66))
39+
40+
41+
## v7.4.3 (2026-09-12)
42+
43+
### Bug Fixes
44+
45+
- Name B01 Q7 code 2103 and document dock dust-collection state fields
46+
([#921](https://github.com/Python-roborock/python-roborock/pull/921),
47+
[`65f592b`](https://github.com/Python-roborock/python-roborock/commit/65f592b43036dbd3e8c08cc333202c2259430c62))
48+
49+
### Chores
50+
51+
- Reflow F_2103 comment ([#921](https://github.com/Python-roborock/python-roborock/pull/921),
52+
[`65f592b`](https://github.com/Python-roborock/python-roborock/commit/65f592b43036dbd3e8c08cc333202c2259430c62))
53+
54+
### Documentation
55+
56+
- Add .claude/skills symlink for Claude Code discovery
57+
([#954](https://github.com/Python-roborock/python-roborock/pull/954),
58+
[`7d65d27`](https://github.com/Python-roborock/python-roborock/commit/7d65d270e3efeafb95e38bdec251d0fdf11889d0))
59+
60+
- Add repository engineering guidelines, review skill, and contributor standards
61+
([#954](https://github.com/Python-roborock/python-roborock/pull/954),
62+
[`7d65d27`](https://github.com/Python-roborock/python-roborock/commit/7d65d270e3efeafb95e38bdec251d0fdf11889d0))
63+
64+
- Add repository engineering guidelines, review skill, and contributor standards (#953)
65+
([#954](https://github.com/Python-roborock/python-roborock/pull/954),
66+
[`7d65d27`](https://github.com/Python-roborock/python-roborock/commit/7d65d270e3efeafb95e38bdec251d0fdf11889d0))
67+
68+
- Address review feedback on feature gating, forward refs, and test paths
69+
([#954](https://github.com/Python-roborock/python-roborock/pull/954),
70+
[`7d65d27`](https://github.com/Python-roborock/python-roborock/commit/7d65d270e3efeafb95e38bdec251d0fdf11889d0))
71+
72+
- Streamline AGENTS.md by removing redundancies
73+
([#954](https://github.com/Python-roborock/python-roborock/pull/954),
74+
[`7d65d27`](https://github.com/Python-roborock/python-roborock/commit/7d65d270e3efeafb95e38bdec251d0fdf11889d0))
75+
76+
- **q7**: Document live map pushes and cover them in tests
77+
([#927](https://github.com/Python-roborock/python-roborock/pull/927),
78+
[`af8a4d1`](https://github.com/Python-roborock/python-roborock/commit/af8a4d1dba01ebfe3f5c05f3c53d80c2b73d28fe))
79+
80+
### Refactoring
81+
82+
- Enable stricter ruff lints and broad exception checking
83+
([#956](https://github.com/Python-roborock/python-roborock/pull/956),
84+
[`28a6edc`](https://github.com/Python-roborock/python-roborock/commit/28a6edcc790d48ddffa214c77216133dfe12e5f6))
85+
86+
87+
## v7.4.2 (2026-09-10)
88+
89+
### Bug Fixes
90+
91+
- Remove v1 image parser monkey patch
92+
([#949](https://github.com/Python-roborock/python-roborock/pull/949),
93+
[`dfd93fc`](https://github.com/Python-roborock/python-roborock/commit/dfd93fcc4edd2cdf350515f3a23a38202cc9c8ca))
94+
95+
596
## v7.4.1 (2026-09-07)
697

798
### Bug Fixes

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,9 @@ and you certify that you have the right to submit it under that license.
3434

3535
## Development Workflow
3636

37-
### Code Style
37+
### Code Style & Architecture
38+
39+
Before writing code or opening pull requests, please review our [Repository Engineering Guidelines](AGENTS.md) for our standards on typing (`RoborockBase` dataclasses), value-returning state helpers, protocol isolation, and test suite consolidation.
3840

3941
We use several tools to enforce code quality and consistency. These are configured via `pre-commit` and generally run automatically.
4042

‎docs/DEVICES.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ Cloud and Network.
2121
* Use `device.b01_q10_properties.vacuum` to access vacuum commands (start, pause, stop, dock, empty dustbin, set clean mode, set fan level).
2222
* Use `device.b01_q10_properties.command.send()` for raw DP commands.
2323
* **Vacuums (B01 Q7)**: Use `device.b01_q7_properties` for Q7 series devices.
24+
* The device streams full map frames on its own while cleaning, so the rendered map stays current without polling or a heartbeat. Register `device.b01_q7_properties.map_content.add_update_listener(cb)` and read `image_content` / `map_data` when notified.
2425

2526
## Background: Understanding Device Protocols
2627

‎pyproject.toml‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "python-roborock"
3-
version = "7.4.1"
3+
version = "7.6.0"
44
description = "A package to control Roborock vacuums."
55
authors = [{ name = "humbertogontijo", email = "humbertogontijo@users.noreply.github.com" }, {name="Lash-L"}, {name="allenporter"}]
66
requires-python = ">=3.11, <4"
@@ -106,14 +106,40 @@ allowed_tags = [
106106
major_tags= ["refactor"]
107107

108108
[tool.ruff]
109-
lint.ignore = ["F403", "E741"]
110-
lint.select=["E", "F", "UP", "I"]
109+
lint.ignore = []
110+
# TODO: Enable ASYNC (flake8-async) in a dedicated follow-up PR once async open() and timeout parameters are refactored.
111+
lint.select = [
112+
"A",
113+
"B",
114+
"BLE",
115+
"C4",
116+
"E",
117+
"F",
118+
"FA",
119+
"I",
120+
"ICN",
121+
"ISC",
122+
"PGH",
123+
"PIE",
124+
"UP",
125+
"W",
126+
"YTT",
127+
]
111128
line-length = 120
112129
extend-exclude = ["roborock/map/proto/*_pb2.py"]
113130

114131
[tool.ruff.lint.per-file-ignores]
115132
"*/__init__.py" = ["F401"]
133+
"roborock/__init__.py" = ["F403"]
134+
"roborock/data/__init__.py" = ["F403"]
135+
"roborock/data/b01_q7/__init__.py" = ["F403"]
136+
"roborock/data/b01_q10/__init__.py" = ["F403"]
137+
"roborock/data/dyad/__init__.py" = ["F403"]
138+
"roborock/data/mower/__init__.py" = ["F403"]
139+
"roborock/data/v1/__init__.py" = ["F403"]
140+
"roborock/data/zeo/__init__.py" = ["F403"]
116141
"roborock/map/proto/*_pb2.py" = ["E501", "I001", "UP009"]
142+
"tests/*" = ["B010"]
117143

118144
[[tool.mypy.overrides]]
119145
module = ["roborock.map.proto.*"]

0 commit comments

Comments
 (0)