roombapy-prime

KO | EN

gitlite — search

#ruby #mysql #github #tailwindcss #json #api #gemini #anthropic #golang #nlp

(★ 9)

Python library to control iRobot’s cloud-connected ‘Prime’/V4-generation robots

File Explorer

ZIP Download

- - ci.yml
  - codeql.yml
  - release.yml
- dependabot.yml
- - ADER_UPDATE_DRAFT_2026-07-11.md
  - FINDINGS_2026-07-11.md
  - HA_ROOMBA_PLUS_CROSSREF.md
- - APK_3_0_0_FINDINGS.md
  - base_roomba_config_REFERENCE.json
  - DEVELOPMENT_NOTES.md
  - EVIDENCE_TRAIL.md
  - PRIME_APP_GAP_ANALYSIS_2026-07-11.md
  - ROOMBAPY_COMPARISON.md
  - SETTING_VALUE_SETS.md
  - vendor_class_triage.json
  - vendor_enum_triage.json
  - vendor_schemas_ruby_0_7_12.json
  - WRITE_PATH_TEST_STATUS.md
- API_REFERENCE.md
- DATA_PRIVACY.md
- basic_usage.py
- clean_regions.py
- do_not_disturb.py
- error_handling.py
- favorites_and_history.py
- maintenance.py
- maps.py
- mission_control.py
- schedules.py
- settings.py
- watching.py
- v0.1.11a.md
- v0.1.11a1.md
- v0.1.11a10.md
- v0.1.11a11.md
- v0.1.11a12.md
- v0.1.11a13.md
- v0.1.11a14.md
- v0.1.11a15.md
- v0.1.11a16.md
- v0.1.11a17.md
- v0.1.11a18.md
- v0.1.11a19.md
- v0.1.11a2.md
- v0.1.11a20.md
- v0.1.11a21.md
- v0.1.11a22.md
- v0.1.11a23.md
- v0.1.11a24.md
- v0.1.11a25.md
- v0.1.11a26.md
- v0.1.11a27.md
- v0.1.11a28.md
- v0.1.11a29.md
- v0.1.11a3.md
- v0.1.11a30.md
- v0.1.11a31.md
- v0.1.11a4.md
- v0.1.11a5.md
- v0.1.11a6.md
- v0.1.11a7.md
- v0.1.11a8.md
- v0.1.11a9.md
- v0.2.0b1.md
- v0.2.0b10.md
- v0.2.0b11.md
- v0.2.0b12.md
- v0.2.0b13.md
- v0.2.0b14.md
- v0.2.0b15.md
- v0.2.0b16.md
- v0.2.0b2.md
- v0.2.0b3.md
- v0.2.0b4.md
- v0.2.0b5.md
- v0.2.0b6.md
- v0.2.0b7.md
- v0.2.0b8.md
- v0.2.0b9.md
- v0.3.0.md
- v0.3.0b1.md
- v0.3.0b10.md
- v0.3.0b11.md
- v0.3.0b12.md
- v0.3.0b13.md
- v0.3.0b14.md
- v0.3.0b15.md
- v0.3.0b16.md
- v0.3.0b17.md
- v0.3.0b18.md
- v0.3.0b2.md
- v0.3.0b3.md
- v0.3.0b4.md
- v0.3.0b5.md
- v0.3.0b6.md
- v0.3.0b7.md
- v0.3.0b8.md
- v0.3.0b9.md
- v0.3.1.md
- v0.3.2.md
- v0.3.3.md
- v0.3.4.md
- - __init__.py
  - enums_common.py
  - favorites.py
  - geometry.py
  - livemap.py
  - map_bundle.py
  - map_editing.py
  - mission_control.py
  - mission_history.py
  - robot_info.py
  - schedules_dnd.py
  - time_estimates.py
- - conftest.py
  - test_auth.py
  - test_auth_lockout.py
  - test_aws_sigv4.py
  - test_command_polygon_metadata.py
  - test_diagnostics.py
  - test_documentation_is_reachable.py
  - test_favorites.py
  - test_ids.py
  - test_init.py
  - test_livemap.py
  - test_map_bundle.py
  - test_map_editing.py
  - test_models.py
  - test_mqtt_client.py
  - test_prime_factory.py
  - test_prime_robot.py
  - test_rest_client.py
  - test_schedules_dnd.py
  - test_time_estimates.py
  - test_tools_boundary.py
- __init__.py
- auth.py
- aws_sigv4.py
- diagnostics.py
- ids.py
- mqtt_client.py
- prime_factory.py
- prime_robot.py
- py.typed
- rest_client.py
- vendor_errors.py
- vendor_reference.json
- vendor_reference.py
- check_stale_files.py
- check_vendor_schema_enums.py
- check_vendor_value_sets.py
- check_version_badge.py
- check_version_pin.py
- vendor_gap_report.py
- - __init__.py
  - _cli.py
  - name_clean_zone.py
  - verify_favorite_write.py
  - verify_local_channel.py
  - verify_map_edit.py
  - verify_mission_commands.py
  - verify_mission_timeline.py
  - verify_named_shadows.py
  - verify_region_commands.py
  - verify_region_commands_session.py
  - verify_schedule_write.py
  - verify_settings_write.py
  - verify_virtual_wall_write.py
  - verify_writes.py
- - __init__.py
  - conftest.py
  - test_flow_control_all.py
  - test_main_safety_gates.py
  - test_mqtt_connection_required.py
  - test_name_clean_zone.py
  - test_no_getattr_on_wire_data.py
  - test_tools_cli.py
  - test_verify_favorite_write.py
  - test_verify_local_channel.py
  - test_verify_map_edit.py
  - test_verify_map_edit_pickers.py
  - test_verify_mission_commands.py
  - test_verify_mission_timeline.py
  - test_verify_named_shadows.py
  - test_verify_region_commands.py
  - test_verify_region_commands_session.py
  - test_verify_schedule_write.py
  - test_verify_settings_write.py
  - test_verify_virtual_wall_write.py
  - test_verify_writes.py
- LICENSE
- pyproject.toml
- README.md
CHANGELOG.md
LICENSE
pyproject.toml
README.md
SECURITY.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

PyPI Visit
Python Visit
Downloads Visit
CI Visit
License Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

An independent, async Python client library for iRobot's cloud-connected
**"Prime"/V4-generation** robots — the successor line to the Classic
protocol devices supported by [roombapy](https://github.com/pschmitt/roombapy).

> **Status: v0.3.4.** Reading and writing both work
> against real hardware, confirmed across a dozen field testers' accounts:
> login, MQTT, mission control, schedules, map edits, favorites, robot
> settings, and **region-based cleaning** — sending a robot to specific
> rooms, from a saved favorite, built from scratch, and with the *scope*
> confirmed rather than merely the delivery: a single-room command on a
> Combo 105 covered 234 sq ft against two whole-house runs at 644.
>
> **Splitting and merging rooms** are confirmed on hardware too. The
> merge command's wire name is `arrange_room`, not `merge_rooms` — a
> discriminator that contradicts its own class name, attested now in app
> bytecode, on a live robot, and in the robot's own firmware.
>
> Virtual wall and keep-out zone writes **work**, on two independent
> accounts, including the write / re-read / write round trip that
> separates "accepted" from "stored". The HTTP 500 this section used to
> describe was solved: `virwall` starts with a COUNT of the walls.
>
> One thing has still never been tried: a write carrying a **modified**
> list. Every confirmed write resent zones unchanged. See
> [Confidence & known gaps](#confidence--known-gaps).
>
> The diagnostic scripts live in a **separate distribution**
> ([`tools/`](tools/README.md)) so that installing this library never puts
> robot-moving commands on your PATH.

## Contents

- [Features](#features)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Testing](#testing)
- [Contributing](#contributing)
- [Confidence & known gaps](#confidence--known-gaps)
- [What the vendor's own app told us](#what-the-vendors-own-app-told-us)
- [Data privacy & security](#data-privacy--security)
- [Why not just extend roombapy?](#why-not-just-extend-roombapy)
- [Documentation](#documentation)
- [Credits](#credits)
- [License](#license)

## Features

- **Login & session** — account login (Gigya + AWS Custom Authorizer), automatic MQTT token refresh
- **Live state** — current robot status, one-shot (`get_state()`) or continuous (`watch_state()`); battery percentage and charging/dock state are confirmed live via the named shadow `ro-currentstate` (`CurrentStateShadow`) — a separate, older `RobotStatusV2` parser also exists but is unconfirmed to appear anywhere (see the confidence table)
- **Mission control** — start/stop/pause/resume/dock via `send_simple_command()`, confirmed working live against a real robot; the richer, region-aware `send_mission_command()` remains available but is now believed incorrect for basic use
- **Favorites** — list, create, update, delete, reorder saved cleaning routines
- **Maps** — read map metadata and active versions, edit rooms/zones/furniture/virtual walls, watch the live map while cleaning, download+unpack the full map bundle
- **Schedules** — recurring cleaning schedules per household (list, create, update, delete)
- **Mission history** — past cleaning runs with duration, coverage, and end reason
- **Parts & device info** — consumable part status, reset after replacement, serial number data, time estimates, notification feed. Find-my-robot: **confirmed working** via `send_simple_command("find")` (jayjay) — a genuine, audible chime with no robot movement; two other mechanisms (a REST endpoint, a shadow write) were tried first and confirmed **not working** — see the docstrings on `poll_echo_value()`/`trigger_echo_via_shadow()`/`send_simple_command()`
- **Settings** — Do Not Disturb windows, cleaning profiles, per-map default routine suggestions
- **Diagnostics** — a companion distribution, [`roombapy-prime-tools`](tools/README.md), validates all of the above against a real account and reports what works. Deliberately separate: several of its commands move a real robot, and they have no business on the PATH of a Home Assistant installation that only consumes this library.

## Installation

```bash
pip install roombapy-prime
```

This gives you the **library only** — no console scripts at all. That is
deliberate.

**If you want the diagnostic tools** (to test your own robot, or to help
with the open questions below), install those instead — they pull this
library in as a dependency, so it stays one command:

```bash
pip install roombapy-prime-tools
```

### Upgrading, if you have the tools

**Upgrade the tools, not the library.** They are two distributions, and
upgrading the library on its own leaves the tools where they were:

```bash
# right -- brings the matching library with it
pip install --upgrade roombapy-prime-tools

# wrong, if you have the tools -- upgrades half of the pair
pip install --upgrade roombapy-prime
```

This is not theoretical. @chairstacker upgraded the library to b6, ran
`verify-writes custom_initiator`, and was asked for a cleaning-history
entry — an instruction b6 had removed, because `find` creates no history
entry. He reported the missing entry as a finding. The tool was still b5.

`verify-writes` now says so at startup when the two disagree, and names
the command above. That is a backstop rather than a fix: the reason the
two can drift is that the tools are deliberately a separate
distribution, so several commands that move a real robot stay off the
PATH of a Home Assistant installation that only consumes the library.

See [`tools/README.md`](tools/README.md) for what they do and how to use
them safely.

Requires Python 3.11+. Dependencies: `aiohttp`, `paho-mqtt`, `certifi`.

## Quick start

```python
import asyncio
import aiohttp
from roombapy_prime import PrimeFactory

async def main():
    async with aiohttp.ClientSession() as session:
        robot = await PrimeFactory.create_prime_robot(
            session=session,
            username="you@example.com",
            password="hunter2",
            country_code="US",
            # blid="BLID123",  # optional — first robot on the account is used otherwise
        )
        await robot.connect()

state = await robot.get_state()
        print(state.payload)

async for delta in robot.watch_state():  # runs until cancelled
            print(delta.payload)

asyncio.run(main())
```

A few other things you can do with the same `robot` object, once connected:

```python
favorites = await robot.get_favorites()
history = await robot.get_mission_history(robot.blid, max_reports=10)
maps = await robot.get_active_map_versions()

# Sends a real command to the robot — confirmed working live (see the
# status note above), but it still moves your actual robot.
await robot.send_simple_command("start")  # or "stop"/"pause"/"resume"/"dock"
```

There's more — schedules, DND settings, map editing, live map streaming.
See [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) for every method
and model organized by feature area, with confidence markers per item —
or the module docstrings in `roombapy_prime/` directly for the full
evidence behind each one.

Eleven runnable examples are in [`examples/`](examples/). Each reads
credentials from environment variables; none hardcode a password, and
every one that writes anything puts it behind a flag.

| Example | Covers |
|---|---|
| `basic_usage.py` | Log in, connect, read state, watch for updates |
| `clean_regions.py` | Send the robot to named rooms and zones |
| `mission_control.py` | Start, pause, resume, dock |
| `schedules.py` | Reading and writing cleaning schedules |
| `favorites_and_history.py` | Saved favourites and past missions |
| `settings.py` | Robot settings |
| `maps.py` | Map versions, region names, downloading the bundle |
| `maintenance.py` | Consumable part counters, and resetting them |
| `do_not_disturb.py` | Quiet hours — two mutually exclusive shapes |
| `watching.py` | Live position and dock streams instead of polling |
| `error_handling.py` | Which failures are worth retrying, and which are not |

If you are writing anything that logs in unattended, start with
`error_handling.py`: an `AuthCredentialsError` will never succeed on
retry, and a naive retry loop turns it into `AuthRateLimitedError`.

## Testing

```bash
pip install -e ".[test]"
pytest roombapy_prime/tests/
```

1079+ tests for the library, plus 499 for the command-line tools —
structural checks against decompiled source,
a byte-for-byte regression pin for the SigV4 signer, genuine
multi-threading tests for the connection lock, and more. This validates
internal consistency (the library builds the requests it claims to
build); it does **not** validate that a real server accepts them — only
the diagnostics script below can do that. See
[`docs/internal/DEVELOPMENT_NOTES.md`](docs/internal/DEVELOPMENT_NOTES.md) for the
detailed breakdown (German; all code, comments, and this README are in
English per project convention).

## Contributing

If you own a Prime/V4 robot, running the diagnostics against your own
account is by far the most useful thing you can do. Every "confirmed"
entry above exists because somebody did exactly that.

Three findings that shaped this library came from testers pasting their
**full** terminal output rather than summarising it as "didn't work":
the live map turning out to be zlib-compressed (visible in the first two
bytes of a diagnostic line), `initiator` being mandatory for region
commands, and a robot's own capability list revealing five fields this
library was silently discarding. None of those would have surfaced from
a description of the symptom.

The most useful things right now:

- **Virtual wall writes with a CHANGED list** — never attempted. Writes
  themselves are confirmed on two accounts (@chairstacker resent four
  zones of two types; @jayjay13011 wrote, re-read the new map version
  and wrote again), but every one of them resent the existing zones
  unchanged. Adding, moving or removing a zone is untested, and
  `set_virtual_wall` **replaces the whole shared list** — a partial list
  deletes everything omitted.
- **Robot settings other than child lock** — they write and read back
  cleanly; whether they change anything is untested.
- **Anything at all on hardware not listed above.** The capability set
  genuinely differs between models, and each new device has so far
  turned up something.

The tools are a **separate distribution** — one command, and it pulls
this library in with it:

```bash
pip install roombapy-prime-tools
```

Start with `roombapy-prime-validate`: read-only, sends nothing, and its
output alone answers several open questions.

> If `roombapy-prime-validate` is not found, you have the library
> installed but not the tools — the two commands above are different
> packages. `python -m roombapy_prime.diagnostics` runs the same thing
> from the library alone. Full setup, the staged
safety model, and what each script does:
**[`tools/README.md`](tools/README.md)**.

Bug reports and findings are welcome even without a robot — the
[evidence trail](docs/internal/EVIDENCE_TRAIL.md) documents how each
conclusion was reached, including the ones that turned out wrong, and a
second pair of eyes on that reasoning is genuinely useful.

## Confidence & known gaps

The honest version. "Confirmed" below means a real person watched a real
robot and reported back — not that a request returned without an error.

**Summary:** reading works. Writing works, with one exception noted
below. Three independent accounts have exercised this, on a Roomba Plus
505 Combo, a Roomba Combo (G18-series) and a Y41-series machine.

### Confirmed on real hardware

| Area | How it was confirmed |
|---|---|
| Login (Gigya + AWS Custom Authorizer), token refresh | multiple accounts |
| MQTT connection, named-shadow reads | multiple accounts |
| Reading state, favorites, mission history, maps, schedules, parts | multiple accounts |
| Mission control — `start`/`stop`/`pause`/`resume`/`dock` | robot visibly reacted |
| `find` (audible locate, no movement) | robot chimed |
| **Region cleaning from a saved favorite** | robot cleaned the named rooms |
| **Region cleaning built from scratch** | robot travelled to room 12 and cleaned it |
| Schedule writes — unchanged resend and a real disable | change took effect |
| **Map editing (`edit_map`, room rename)** | renamed and reverted, both confirmed in the app |
| Zone names in the map bundle | **not established.** The reading code had a typo that made it return nothing on every bundle, so the earlier "confirmed" here rested on a search that never ran. Fixed in b15 and now genuinely untested. |
| Map editing — room rename, with revert | twice, name changed in the app |
| Favorite writes — resend, colour change, delete | change visible in the app |
| Robot settings — child lock | appeared in the app, robot announced it audibly |
| Keep-out zone / no-mop zone **reads** | two real zones, both types correctly identified |
| **Splitting and merging rooms** | both accepted on a Combo 105, map re-rendered (response level; geometry not audited) |
| **Region cleaning on an x05** | 234 sq ft against two whole-house runs at 644 — the area is the proof, not the acknowledgement |
| Firmware catalogue (`get_firmware`) | a real response, parsed |
| **Dock report topics** | `dock/paddry/report` received live; firmware confirms the family is exactly {evac, refill, padwash, paddry} |
| **The local channel still answers** | the APP dropped local networking in 3.0.0; the robots did not |

### Independently reconstructed

`samm-git/irobot-explore` rebuilt the same protocol from a different app
version (1.6.0) on different hardware, with no knowledge of this
project. Where two independent derivations agree, a thing is confirmed
rather than one derivation deep.

Agreeing without contradiction: service discovery, Gigya login,
`/v2/login`, the four IoT session attributes, the custom-authorizer
flow, shadow topics and envelope, the `cmd` topic with `p2map_id` and
`regions`, `rid`/`zid`/`tid`, settings under `desired`, SigV4 for map
data.

Where we differed, that reconstruction was right twice — see the
0.3.0 changelog entry.

### Region cleaning: what it took, and what it needs

This was the project's central unknown for months. Two things were
required, and neither is obvious:

- **`initiator` is mandatory.** A stored favorite does not carry one —
  the app adds it at send time. Resending a favorite unchanged is
  accepted, acknowledged, and silently ignored.
- **The wire keys are `start` and `region_id`**, not `clean` and `id`.
  The latter pair was an assumption recorded in this project's own code
  and never checked.

A map version is **not** required. The robot re-versions its map every
few seconds while cleaning (five values inside 37 seconds in one real
capture), so a stored favorite is stale within a minute of being saved —
and commands carrying versions hours out of date started missions
regardless.

### Known broken

- **A virtual wall write carrying a CHANGED list** — never attempted.
  The HTTP 500 that used to sit here was solved: `virwall` starts with a
  COUNT of the walls. Writes are confirmed on two accounts, including
  the write / re-read / write round trip that separates "accepted" from
  "stored" (#28, closed 30 July).
  But every confirmed write **resent the existing zones unchanged**.
  Adding, moving or removing one is untested, and `set_virtual_wall`
  replaces the whole shared list — a partial list deletes everything
  omitted. That hazard is guarded by a test, not by the server.

- **`schedHold`** writes succeed and read back correctly, and the
  schedule stays active in the app. Writing it to `rw-settings` is
  evidently not the mechanism the app uses.

Worth knowing how that surfaced: this project's cross-check against the
  classic shadow flagged the divergence *before* the tester looked in the
  app. Two sources disagreeing turned out to mean "the write did not
  take", which makes that check a real signal.

### Untested

- **Robot settings other than child lock** — `ecoCharge`, `noAutoPasses`
  and `vacHigh` all write and read back cleanly; none has an easily
  observable effect, so their real-world behaviour is unknown.
- **Multi-robot household and teaming** concepts beyond basic settings
  scoping.
- The discriminator value inside a map-edit command's `edit_cmd`
  envelope. The envelope shape and 8 of 9 commands' fields are confirmed;
  `SetRoomMetadata` and `VirtualWall` use custom serializers whose
  internals are not.
- **Whole-house cleaning through the region command path** (`clean_all` /
  `select_all`). Deliberately untested rather than assumed: a wrong guess
  cleans the whole house. Reading firmware 3.8.126 narrowed it — there is
  no `clean_all` field at all, and scope comes from whether `regions` is
  present — but that is architecture-consistent inference, not a proven
  branch condition. The safe rule is unchanged: send a global command
  only when whole-house is positively intended, and never rely on
  `command_type=START` to limit scope. START is the operating mode, not a
  scope limiter.
- **Uploading a p2map** back to the robot, and the services write path.
  Both are marked at their call sites too.

### A warning if you search for help

Every public example of Roomba region cleaning you will find is for the
**Classic** protocol: `pmap_id`, `user_pmapv_id`, a flat payload, local
MQTT. Prime/V4 uses `p2map_id` and a different command structure
entirely. The names are close enough to look applicable and are not.

The full reasoning behind every entry above — including the conclusions
that turned out wrong and why — is in
[`docs/internal/EVIDENCE_TRAIL.md`](docs/internal/EVIDENCE_TRAIL.md).

## What the vendor's own app told us

`com.irobot.home.prime` 3.0.0 is a Flutter rewrite, and its data layer
ships as plain Kotlin serialisers rather than compiled constants. A
systematic comparison against it — 223 serialiser classes, 87 enums, 71
request classes, 25 locale files — corrected this library in places no
amount of field testing would have found, because **nothing was
failing**:

| Found | Why it mattered |
|---|---|
| `dirt`, `map_id`, `covStrat` | read here as `numberOfDirtDetects`, `staticMapId`, `coverageStrategy` — plausible names no robot has ever sent, so all three read `None` on every mission ever recorded |
| `cmd`, `disc`, `poly`, `tentativeLoc` | four timeline event types dropped from every real timeline, because this library read the long forms |
| `coverage` | per-room mission progress, declared beside fields already read. `RoomEvent`'s docstring spent fourteen lines reasoning about what `area` and `total_area` mean; the field that answers it was in the same object |
| 112 error codes | with iRobot's own title and explanation in 25 languages. Of 126 labels written here, **two** matched the vendor's |
| `schedule_id` inside options | 3.0.0 moved it; a schedule whose id cannot be found is one nobody can edit, and that reads as an empty calendar rather than an error |
| 24 writable settings | `audio.volume` with a dot, not `audio`; `padWetness.padPlate` addressed directly, retiring a read-modify-write recommendation |

The full comparison — what was checked, what was corrected, what was deliberately left alone, and
what the APK cannot answer — is in
**[docs/internal/APK_3_0_0_FINDINGS.md](docs/internal/APK_3_0_0_FINDINGS.md)**.

**And one thing it did not settle.** The app spells four commands in
camelCase (`washPad`, `dryPad`) where this library uses lowercase. The
lowercase forms are what a real robot recorded in its own shadow, with a
pad-wash counter to match, so they stay. A confirmed shape outranks a
plausible one — a rule this comparison had cause to apply three times.

## Does your robot still answer locally?

**Yes — confirmed on current firmware.**

App 2.2.4 carried a complete local API — 46 local-socket serializers,
`irobotmcs` discovery, port 5678. App 3.0.0 has none of it. This
library previously concluded from that the local path had been
*removed*, which was wrong: the **app** stopped using it, the robots
did not. An app dropping a path says nothing about the firmware behind
it.

Two independent confirmations on `p25-705+9.3.6+I3.8.149`, current as
of August 2026: a field tester's discovery run (SKU W155020) and the
author of `samm-git/irobot-explore`, who speaks the channel live.

```
roombapy-prime-verify-local-channel
```

Four stages — UDP discovery, TCP connect, TLS handshake, and
deliberately **no** MQTT CONNECT. No credentials, no cloud, nothing sent
to the robot beyond the nine-byte discovery broadcast.

### Where it stands

| stage | on current firmware |
|---|---|
| UDP discovery | **answers** |
| TCP :8883 | **open** |
| TLS handshake | **fails**, `BAD_SIGNATURE` |

The TLS failure is the interesting part. The robot signs with a key
that does not match the certificate it presents. TLS 1.3 carries that
signature in `CertificateVerify`; TLS 1.2 with an ECDHE suite carries
it in `ServerKeyExchange`. Capping the version changes *which message*
holds the bad signature, not whether one is sent — a hypothesis this
project held and a field run disproved.

One case remains untested: a **static RSA** suite has no server
signature at all. If the robot's legacy stack offers one, nothing is
signed for a client to reject. The tool now tries it as a third
attempt.

So a native helper with a patched TLS library is the only route anyone
has **got working** — not, as this README previously implied, the only
route that could exist. Nobody has yet demonstrated that pure Python
cannot do it.

### Two caveats worth stating plainly

**The channel is closed until something opens it.** It comes up as part
of the BLE provisioning flow and closes again on reboot, so a silent
run means "nobody has provisioned this robot recently", not "the
firmware dropped it".

**A local transport removes the round trip, not the dependency.** The
reference implementation that speaks this channel still logs in to the
cloud once, to fetch the robot's local password.

## Data privacy & security

**In one sentence:** everything goes directly to iRobot's own cloud
infrastructure, nothing is sent to any third party, and nothing is
written to disk by this library unless you explicitly ask for it.

- [`docs/DATA_PRIVACY.md`](docs/DATA_PRIVACY.md) — what data goes
  where, and what this library does and doesn't store, verified
  directly against the code
- [`SECURITY.md`](SECURITY.md) — credential handling, TLS
  verification, and what's still unverified from a security standpoint

## Why not just extend roombapy?

Classic-protocol robots talk local MQTT with `ssl.CERT_NONE` and a
blid/password pair — no account, no internet round-trip. Prime/V4 robots
are cloud-only: AWS IoT Custom Authorizer sessions, request/response
"shadow" state instead of a local firehose, and a REST API for map
management that Classic doesn't have at all. Different trust model,
different protocol shape, not just a missing feature — see
[`docs/internal/ROOMBAPY_COMPARISON.md`](docs/internal/ROOMBAPY_COMPARISON.md) for the
full comparison (including a size/structure breakdown of both libraries).

## Documentation

**Start here:** [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) (every
method and model) and [`CHANGELOG.md`](CHANGELOG.md) (what's changed,
release by release).

Everything else — the session-by-session reverse-engineering trail
(`docs/internal/`) and a handful of superseded early drafts
(`docs/archive/`) — is background material, not needed to use the
library. See the comment at the top of each folder's files for what's
there and why.
- [Setting value sets](docs/internal/SETTING_VALUE_SETS.md) — why four of the six writable settings cannot have a picker
- [APK 3.0.0 findings](docs/internal/APK_3_0_0_FINDINGS.md) — what iRobot's own app corrected, and what was deliberately left alone

## Credits

- **[roombapy](https://github.com/pschmitt/roombapy)** (pschmitt and
  contributors) — the Classic-protocol client this project doesn't
  extend (see [above](#why-not-just-extend-roombapy)), but whose
  design this project learned from throughout: `prime_robot.py`
  mirrors its public-class pattern, `prime_factory.py` mirrors its
  factory pattern, and the TLS-verification discussion in
  [`SECURITY.md`](SECURITY.md) directly contrasts with its
  local-network `ssl.CERT_NONE` approach (correct for its use case,
  not for this one).
- **[Ader](https://github.com/lvigilantecorreo-commits)** —
  maintainer of
  **[roomba-v4](https://github.com/lvigilantecorreo-commits/roomba-v4)**,
  the first public reverse-engineering work on the V4/Prime command
  path, and the project that triggered this library's development in
  the first place. Since then, an ongoing two-way exchange of
  cross-verification findings between the two independent projects —
  including confirming that room/zone-targeting is real, found
  directly in the app's own binary under the internal name `p2maps`,
  now the central concept this entire library is organized around.
- **chairstacker** — this project's primary field tester. Confirmed
  mission control working live against a real robot (the single
  biggest open question this library had for most of its life), and
  a detailed `--dump-config` capture from a real account surfaced
  three genuine crash bugs and a write-side bug that static analysis
  alone had missed. Most of what this library can say "confirmed
  live" about, it can say because of this testing.
- **jadestar1864** — a second, independent Prime account (same
  robot model as chairstacker's, different household) — the first
  confirmation that this library's behavior is consistent across
  more than one real account, not just one lucky match.

## License

MIT — see [`LICENSE`](LICENSE).

roombapy-prime

Owner Repos

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

roombapy-prime

Owner Repos

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README