roombapy-prime-tools 0.3.1__tar.gz

roombapy_prime_tools-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jean-Christoph (@johnnyh1975)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

roombapy_prime_tools-0.3.1/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: roombapy-prime-tools
+Version: 0.3.1
+Summary: Diagnostic and field-test tooling for roombapy-prime (moves real robots -- read the safety notes)
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/johnnyh1975/roombapy-prime
+Project-URL: Issues, https://github.com/johnnyh1975/roombapy-prime/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: roombapy-prime==0.3.1
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Dynamic: license-file
+
+# roombapy-prime-tools
+
+Diagnostic and field-test tooling for
+[roombapy-prime](https://github.com/johnnyh1975/roombapy-prime).
+
+> **These scripts move a real robot.** That is why they are a separate
+> distribution: the library itself is installed into Home Assistant setups via
+> `ha_roomba_plus`, and robot-moving commands have no business on the PATH of
+> every one of those installations. Installing the library alone gives you
+> **no** console scripts at all.
+
+## What this is for
+
+Almost everything this project knows about the Prime/V4 protocol came from
+someone running one of these against their own robot and reporting back. If you
+own a Prime robot, that is by far the most useful thing you can do — and the
+read-only stages cannot change anything, so it costs you nothing but a few
+minutes.
+
+## Install
+
+One command; it pulls the library in as a dependency:
+
+```bash
+python3 -m venv ~/roombapy-test-venv
+source ~/roombapy-test-venv/bin/activate
+
+pip install "roombapy-prime-tools@git+https://github.com/johnnyh1975/roombapy-prime.git@v0.3.0b10#subdirectory=tools"
+```
+
+Requires Python 3.11+. You will need to re-run the `source` line each time you
+open a new terminal.
+
+**These are not part of Home Assistant.** They run on your own computer,
+outside HA entirely. HACS does not install them and does not need to.
+
+## Account details
+
+Set these once per terminal rather than retyping a 32-character BLID on every
+command — every script reads them:
+
+```bash
+export ROOMBAPY_PRIME_USERNAME="you@example.com"
+export ROOMBAPY_PRIME_BLID="YOUR_ROBOT_BLID"
+export ROOMBAPY_PRIME_COUNTRY="US"      # your own: DE, FR, IT, ES ...
+```
+
+The country code matters — it selects which regional endpoint you authenticate
+against, and the default is `US`.
+
+The password is deliberately **not** a command-line argument: it would end up
+in your shell history and in any terminal output you paste into an issue. Set
+`ROOMBAPY_PRIME_PASSWORD` for unattended runs, or let it prompt.
+
+Any of these can be overridden per-run with `--username`/`--blid`/
+`--country-code`.
+
+## Start here
+
+```bash
+roombapy-prime-validate
+```
+
+Read-only. Logs in, reads state, shadows, favorites, maps and mission history,
+then prints a report. Sends nothing to the robot. Its output alone answers
+several currently open questions.
+
+Add `--dump-config diagnose.json` to save the raw responses. **Review that file
+before sharing it** — redaction catches the known cases, but cannot guarantee
+every surprise in an unfamiliar response shape.
+
+## The staged safety model
+
+Every script that can change something follows the same pattern:
+
+1. **Stage 0** — reconnaissance. Reads only, sends nothing, needs no flag.
+2. **Stage 1+** — each requires an explicit `--i-understand-this-...` flag
+   **and** an interactive confirmation showing the exact payload before
+   anything is sent.
+
+Start at stage 0. A stage-0 result is a genuinely useful contribution on its
+own — several findings in this project came from nothing more.
+
+Everything validates *before* asking for your password, so an incomplete
+command tells you what is missing without making you type credentials first.
+
+## The scripts
+
+| Command | What it does |
+|---|---|
+| `roombapy-prime-validate` | Full read-only validation run. **Start here.** |
+| `…-verify-named-shadows` | Dumps all nine device shadows. The single richest source of protocol data. |
+| `…-verify-commands` | Basic mission commands (start/stop/dock/…) with before/after state. |
+| `…-verify-mission-timeline` | Watches the live mission/event topics. Read-only unless `--start-mission`. |
+| `…-verify-region-commands` | Room-specific cleaning, staged. **Confirmed working** — see below. `--list-rooms` shows rooms *and* zones, with the source of each name. |
+| `…-verify-region-commands-session` | The above as one guided session — one login, prompts between stages. |
+| `…-verify-map-edit` | Renames one room and reverts it. |
+| `…-verify-favorite-write` | Create/update/delete saved routines. |
+| `…-verify-schedule-write` | Resend and disable schedules. |
+| `…-verify-virtual-wall-write` | Keep-out zones and virtual walls. **Writes work** — the HTTP 500 was solved before 0.2.0b1. Untested: a write carrying a *changed* list. |
+| `…-name-clean-zone` | Names a clean zone. **Full-list rewrite** — anything omitted is deleted. Dry run by default. |
+| `…-verify-settings-write` | Child lock, eco charge, schedule hold, … Writes confirmed; most effects untested. |
+
+Every script has `--help`, and it is worth reading before a first run.
+
+The last two are the easiest way to contribute something genuinely new — both
+start read-only.
+
+## Region commands: solved, and worth re-running
+
+Room-specific cleaning works. It took three rounds to establish, and two
+things were required that are not obvious:
+
+- **`initiator` is mandatory.** A stored favorite does not carry one, so
+  resending one unchanged is accepted, acknowledged and silently ignored.
+- **The wire keys are `start` and `region_id`**, not `clean` and `id`.
+
+```bash
+roombapy-prime-verify-region-commands-session \
+    --i-understand-this-will-move-my-robot \
+    --i-understand-this-is-experimental-and-unconfirmed
+```
+
+It lists your eligible favorites and you pick one by number. **Watch the
+robot while it runs.** The fastest stop is the real iRobot app or the
+button on the robot.
+
+Two notes from the sessions that got this working:
+
+- A favorite made from **specific rooms** tells you far more than a
+  whole-home one. If the robot cleans everything, you have only learned
+  that the command arrived.
+- Check the delivery confirmation in the output. Every stage that
+  received one started a mission; every stage that did not got nothing.
+  A "nothing happened" without a confirmation says nothing about the
+  payload.
+
+## Virtual walls: reads work, writes do not
+
+Stage 0 (`--list-maps`, then `--list-walls`) works and is read-only.
+It is how the zone types were confirmed against real data.
+
+`--update-unchanged` **works.** The HTTP 500 this paragraph described
+was solved before 0.2.0b1 — `virwall` starts with a COUNT of the walls —
+and confirmed on two accounts, including the write / re-read / write
+round trip that separates "accepted" from "stored".
+
+**What is still untested: a write carrying a CHANGED list.** Every
+confirmed write resent its zones unchanged, and `set_virtual_wall`
+replaces the whole shared list — anything omitted is deleted.
+
+## Developing from an unreleased checkout
+
+The pin above names a git tag, which does not exist yet while a version is
+still in development. From a checkout, install the core editable first and skip
+dependency resolution here:
+
+```bash
+pip install -e .                     # from the repository root
+pip install -e ./tools --no-deps
+```
+
+Without `--no-deps`, pip fetches a second, unrelated copy of the core from
+GitHub and shadows your editable one — which then fails in ways that look like
+a code bug rather than an install problem. The CI does exactly this, for
+exactly this reason.
+
+## Versioning
+
+This distribution pins an exact core version. The scripts reach deep into the
+library, so a mismatched pair fails confusingly rather than cleanly —
+`scripts/check_version_pin.py` in the repository root enforces that the two
+stay in step.

roombapy_prime_tools-0.3.1/README.md

@@ -0,0 +1,173 @@
+# roombapy-prime-tools
+
+Diagnostic and field-test tooling for
+[roombapy-prime](https://github.com/johnnyh1975/roombapy-prime).
+
+> **These scripts move a real robot.** That is why they are a separate
+> distribution: the library itself is installed into Home Assistant setups via
+> `ha_roomba_plus`, and robot-moving commands have no business on the PATH of
+> every one of those installations. Installing the library alone gives you
+> **no** console scripts at all.
+
+## What this is for
+
+Almost everything this project knows about the Prime/V4 protocol came from
+someone running one of these against their own robot and reporting back. If you
+own a Prime robot, that is by far the most useful thing you can do — and the
+read-only stages cannot change anything, so it costs you nothing but a few
+minutes.
+
+## Install
+
+One command; it pulls the library in as a dependency:
+
+```bash
+python3 -m venv ~/roombapy-test-venv
+source ~/roombapy-test-venv/bin/activate
+
+pip install "roombapy-prime-tools@git+https://github.com/johnnyh1975/roombapy-prime.git@v0.3.0b10#subdirectory=tools"
+```
+
+Requires Python 3.11+. You will need to re-run the `source` line each time you
+open a new terminal.
+
+**These are not part of Home Assistant.** They run on your own computer,
+outside HA entirely. HACS does not install them and does not need to.
+
+## Account details
+
+Set these once per terminal rather than retyping a 32-character BLID on every
+command — every script reads them:
+
+```bash
+export ROOMBAPY_PRIME_USERNAME="you@example.com"
+export ROOMBAPY_PRIME_BLID="YOUR_ROBOT_BLID"
+export ROOMBAPY_PRIME_COUNTRY="US"      # your own: DE, FR, IT, ES ...
+```
+
+The country code matters — it selects which regional endpoint you authenticate
+against, and the default is `US`.
+
+The password is deliberately **not** a command-line argument: it would end up
+in your shell history and in any terminal output you paste into an issue. Set
+`ROOMBAPY_PRIME_PASSWORD` for unattended runs, or let it prompt.
+
+Any of these can be overridden per-run with `--username`/`--blid`/
+`--country-code`.
+
+## Start here
+
+```bash
+roombapy-prime-validate
+```
+
+Read-only. Logs in, reads state, shadows, favorites, maps and mission history,
+then prints a report. Sends nothing to the robot. Its output alone answers
+several currently open questions.
+
+Add `--dump-config diagnose.json` to save the raw responses. **Review that file
+before sharing it** — redaction catches the known cases, but cannot guarantee
+every surprise in an unfamiliar response shape.
+
+## The staged safety model
+
+Every script that can change something follows the same pattern:
+
+1. **Stage 0** — reconnaissance. Reads only, sends nothing, needs no flag.
+2. **Stage 1+** — each requires an explicit `--i-understand-this-...` flag
+   **and** an interactive confirmation showing the exact payload before
+   anything is sent.
+
+Start at stage 0. A stage-0 result is a genuinely useful contribution on its
+own — several findings in this project came from nothing more.
+
+Everything validates *before* asking for your password, so an incomplete
+command tells you what is missing without making you type credentials first.
+
+## The scripts
+
+| Command | What it does |
+|---|---|
+| `roombapy-prime-validate` | Full read-only validation run. **Start here.** |
+| `…-verify-named-shadows` | Dumps all nine device shadows. The single richest source of protocol data. |
+| `…-verify-commands` | Basic mission commands (start/stop/dock/…) with before/after state. |
+| `…-verify-mission-timeline` | Watches the live mission/event topics. Read-only unless `--start-mission`. |
+| `…-verify-region-commands` | Room-specific cleaning, staged. **Confirmed working** — see below. `--list-rooms` shows rooms *and* zones, with the source of each name. |
+| `…-verify-region-commands-session` | The above as one guided session — one login, prompts between stages. |
+| `…-verify-map-edit` | Renames one room and reverts it. |
+| `…-verify-favorite-write` | Create/update/delete saved routines. |
+| `…-verify-schedule-write` | Resend and disable schedules. |
+| `…-verify-virtual-wall-write` | Keep-out zones and virtual walls. **Writes work** — the HTTP 500 was solved before 0.2.0b1. Untested: a write carrying a *changed* list. |
+| `…-name-clean-zone` | Names a clean zone. **Full-list rewrite** — anything omitted is deleted. Dry run by default. |
+| `…-verify-settings-write` | Child lock, eco charge, schedule hold, … Writes confirmed; most effects untested. |
+
+Every script has `--help`, and it is worth reading before a first run.
+
+The last two are the easiest way to contribute something genuinely new — both
+start read-only.
+
+## Region commands: solved, and worth re-running
+
+Room-specific cleaning works. It took three rounds to establish, and two
+things were required that are not obvious:
+
+- **`initiator` is mandatory.** A stored favorite does not carry one, so
+  resending one unchanged is accepted, acknowledged and silently ignored.
+- **The wire keys are `start` and `region_id`**, not `clean` and `id`.
+
+```bash
+roombapy-prime-verify-region-commands-session \
+    --i-understand-this-will-move-my-robot \
+    --i-understand-this-is-experimental-and-unconfirmed
+```
+
+It lists your eligible favorites and you pick one by number. **Watch the
+robot while it runs.** The fastest stop is the real iRobot app or the
+button on the robot.
+
+Two notes from the sessions that got this working:
+
+- A favorite made from **specific rooms** tells you far more than a
+  whole-home one. If the robot cleans everything, you have only learned
+  that the command arrived.
+- Check the delivery confirmation in the output. Every stage that
+  received one started a mission; every stage that did not got nothing.
+  A "nothing happened" without a confirmation says nothing about the
+  payload.
+
+## Virtual walls: reads work, writes do not
+
+Stage 0 (`--list-maps`, then `--list-walls`) works and is read-only.
+It is how the zone types were confirmed against real data.
+
+`--update-unchanged` **works.** The HTTP 500 this paragraph described
+was solved before 0.2.0b1 — `virwall` starts with a COUNT of the walls —
+and confirmed on two accounts, including the write / re-read / write
+round trip that separates "accepted" from "stored".
+
+**What is still untested: a write carrying a CHANGED list.** Every
+confirmed write resent its zones unchanged, and `set_virtual_wall`
+replaces the whole shared list — anything omitted is deleted.
+
+## Developing from an unreleased checkout
+
+The pin above names a git tag, which does not exist yet while a version is
+still in development. From a checkout, install the core editable first and skip
+dependency resolution here:
+
+```bash
+pip install -e .                     # from the repository root
+pip install -e ./tools --no-deps
+```
+
+Without `--no-deps`, pip fetches a second, unrelated copy of the core from
+GitHub and shadows your editable one — which then fails in ways that look like
+a code bug rather than an install problem. The CI does exactly this, for
+exactly this reason.
+
+## Versioning
+
+This distribution pins an exact core version. The scripts reach deep into the
+library, so a mismatched pair fails confusingly rather than cleanly —
+`scripts/check_version_pin.py` in the repository root enforces that the two
+stay in step.

roombapy_prime_tools-0.3.1/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "roombapy-prime-tools"
+version = "0.3.1"
+description = "Diagnostic and field-test tooling for roombapy-prime (moves real robots -- read the safety notes)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Home Automation",
+]
+
+# Pinned to an exact core version on purpose. These scripts reach deep
+# into the library (shadow models, wire-format helpers, private-ish
+# report plumbing), so a mismatched pair fails in confusing ways rather
+# than cleanly. scripts/check_version_pin.py enforces that this pin and
+# the core's own version stay in step.
+dependencies = [
+    # A BARE PIN, not a git URL. PyPI rejects any distribution carrying
+    # a direct-URL dependency and rejects the whole upload with it, so
+    # the git pointer that was right while this lived only on GitHub
+    # made the package unpublishable.
+    "roombapy-prime==0.3.1",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/johnnyh1975/roombapy-prime"
+Issues = "https://github.com/johnnyh1975/roombapy-prime/issues"
+
+# EVERY console script this project ships lives here, and nowhere else.
+# The core distribution deliberately registers none at all -- several of
+# these move a real robot, and they have no business on the PATH of a
+# Home Assistant installation that merely consumes the library.
+#
+# roombapy-prime-validate points into the CORE package (its Report class
+# is shared with the library), which is fine: entry points may reference
+# any importable module, and installing this distribution installs the
+# core as a dependency.
+[project.scripts]
+roombapy-prime-validate = "roombapy_prime.diagnostics:main"
+roombapy-prime-verify-commands = "roombapy_prime_tools.verify_mission_commands:main"
+roombapy-prime-verify-map-edit = "roombapy_prime_tools.verify_map_edit:main"
+roombapy-prime-verify-mission-timeline = "roombapy_prime_tools.verify_mission_timeline:main"
+roombapy-prime-verify-named-shadows = "roombapy_prime_tools.verify_named_shadows:main"
+roombapy-prime-verify-region-commands = "roombapy_prime_tools.verify_region_commands:main"
+roombapy-prime-name-clean-zone = "roombapy_prime_tools.name_clean_zone:main"
+roombapy-prime-verify-local-channel = "roombapy_prime_tools.verify_local_channel:main"
+roombapy-prime-verify-region-commands-session = "roombapy_prime_tools.verify_region_commands_session:main"
+roombapy-prime-verify-schedule-write = "roombapy_prime_tools.verify_schedule_write:main"
+roombapy-prime-verify-favorite-write = "roombapy_prime_tools.verify_favorite_write:main"
+roombapy-prime-verify-virtual-wall-write = "roombapy_prime_tools.verify_virtual_wall_write:main"
+roombapy-prime-verify-writes = "roombapy_prime_tools.verify_writes:main"
+roombapy-prime-verify-settings-write = "roombapy_prime_tools.verify_settings_write:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["roombapy_prime_tools*"]
+
+[tool.pytest.ini_options]
+# A genuinely un-awaited coroutine in production code is a real bug that
+# produces exactly this warning. Ten sloppy test mocks were emitting it
+# routinely, which would have buried a real one in the noise -- the same
+# way a silently swallowed exception went unnoticed for months. Promoted
+# to an error so the noise cannot come back.
+filterwarnings = [
+    "error::RuntimeWarning:.*never awaited.*",
+]
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "B", "C4", "UP"]
+ignore = ["E501"]

roombapy_prime_tools-0.3.1/roombapy_prime_tools/__init__.py

@@ -0,0 +1,15 @@
+"""Diagnostic and field-test tooling for roombapy-prime.
+
+DELIBERATE ONE-WAY BOUNDARY: everything in here may import from the
+library core (roombapy_prime.auth, .prime_robot, .models, ...), but the
+core must NEVER import from here. That direction was already respected
+before this package existed -- moving these modules into their own
+subpackage makes it structural rather than a matter of discipline, and
+test_tools_boundary.py enforces it mechanically.
+
+Why the separation matters beyond tidiness: these modules register 11
+console scripts, several of which MOVE A REAL ROBOT. Keeping them
+distinct from the library is what makes it possible to ship the library
+to consumers (Home Assistant installations, via ha_roomba_plus) without
+putting robot-moving commands on their PATH.
+"""