Looking for iRobot "Prime" / V4-generation owners to test a new Python library (roombapy-prime)

Share your Projects!
1

Looking for iRobot “Prime” / V4-generation owners to test a new Python library (roombapy-prime)

Hi all,

I maintain ha_roomba_plus, a HACS integration for Classic-protocol Roomba/Braava robots (the ones roombapy already supports — local MQTT, blid + password). It’s been stable and Gold-tier for a while now.

What it doesn’t support is iRobot’s newer “Prime”/V4-generation robots — the ones that only talk to iRobot’s cloud (AWS IoT), not your local network. Different auth model, different protocol, no local blid/password to grab. roombapy can’t be extended to cover them without basically becoming a different library.

So I built one: roombapy-prime — a from-scratch async Python client for Prime/V4 robots.

The catch — and why I’m posting this here

Everything in this library comes from reverse-engineering the Prime Android app (decompilation, native library analysis, and — this part actually mattered — the app’s own bundled JSON configuration file, which turned out to be a far better source of truth than guessing from bytecode). Field names, endpoints, wire formats: all confirmed against real source, not guessed.

What it has never done is talk to a real account. I don’t own a Prime/V4 robot, so I have no way to close that last gap myself.

If you have one of these robots, this is where you come in.

What I’m asking

Run the library’s built-in read-only diagnostics script against your account and send me the result. It:

  • Logs in, reads your robot’s current state, favorites, mission history, map info, schedules, DND settings
  • Never sends a command to your robot and never edits anything, by default — no cleaning starts, no maps get touched
  • Prints (and can open) a pre-filled GitHub issue with the full report, so sharing results is one click
  • Redacts your credentials from that report before building the link
pip install git+https://github.com/johnnyh1975/roombapy-prime.git
roombapy-prime-validate --username [email protected] --country-code US

That’s genuinely it. Whatever comes back — all green, all red, somewhere in between — is useful information I don’t currently have.

If you’re up for going further, there’s an opt-in --allow-writes flag that does one reversible thing: creates a test favorite, checks it shows up, deletes it again. Nothing else. Full details, including exactly what the library does and doesn’t touch, are in the README and SECURITY.md.

Where this goes

If this actually works against real accounts, the plan is to fold Prime/V4 support into ha_roomba_plus itself, so both generations are covered by one integration. Right now that’s blocked entirely on “does this library work,” which only real accounts can answer.

Repo: GitHub - johnnyh1975/roombapy-prime: Python library to control iRobot’s cloud-connected ‘Prime’/V4-generation robots · GitHub
Issues / results: Issues · johnnyh1975/roombapy-prime · GitHub

Thanks in advance to anyone willing to point this at their robot — even a single “here’s what broke” is genuinely useful.

2

Hi @johnnyh1975 - thanks for all your work.
Here’s the link to the Github issue:
Live-Validierung: 7 OK, 1 fehlgeschlagen, 4 uebersprungen · Issue #1 · johnnyh1975/roombapy-prime

3

Long time listener, first time caller haha.

Ran the validator against a Roomba 104 Combo (Y351020, fw 9.3.6) — 28 OK / 0 failed / 3 skipped (the intentionally-off writes). Everything worked first try: full auth chain, AWS IoT MQTT, all four named shadows, favorites, mission history, schedules, and the complete map pipeline (bundle download + parse).

Full report here, along with what we found probing the robot on the LAN: Field report: Roomba 104 Combo (Y351020) — full validator pass (28 OK / 0 failed) + LAN probing · Issue #37 · johnnyh1975/roombapy-prime · GitHub — short version, discovery on UDP 5678 answers and reports ver:"4", but a full TCP sweep found nothing open. Caveat we’re careful about: that’s one state only (docked, awake, normal mode, already provisioned), TCP only, and on UDP just the known discovery string. So it’s “we couldn’t find a local path,” not “none exists” — corrections very welcome.

One gotcha for anyone else scanning Roombas: classic robots seem to allow only one local MQTT client. Our m6 and 960 showed 8883 open until we connected them to HA, after which scans said closed. Briefly fooled us into thinking our scanner was broken.

Two small things for @johnnyh1975: the roombapy-prime-validate console script isn’t in the v0.1.11a31 wheel (used python -m roombapy_prime.diagnostics instead), and your tier-guess caveat reproduced — rw-settings answered but the report flags it unstable.

Robot’s docked and I can iterate quickly — happy to run anything you want tested. Excited to help push this forward; these robots deserve better than being welded to one app.

(Worked alongside Claude for the LAN sweeps and writeup — hardware and validator run are mine.)

4

@utkjmitch Welcome — and that is a better first post than most people’s tenth.

The 104 Combo is a model nobody had run anything against, so a clean pass on it is genuinely new information rather than a confirmation. I’ve replied to the detail over on the issue so it stays with the report, but three things are worth saying here where more people will see them.

The missing roombapy-prime-validate command is my fault, not yours. It lives in the tools package rather than the library, and the README mentions that a few lines above the install command — clearly not clearly enough. I’ve moved the note to where you were actually looking, with the python -m fallback you worked out on your own.

Your one-MQTT-client observation is the most useful thing in the post. Classic Roombas only accept a single local connection, so scanning one that Home Assistant already holds shows the port closed. Anyone poking at their robot with a port scanner will hit that and conclude the wrong thing — and you only spot it if you happen to have both an integrated and a non-integrated robot to compare. That’s going in the docs.

And the LAN conclusion is stated more carefully than I would have asked for. “We couldn’t find a local path in the state we tested” rather than “there isn’t one” is the correct claim, and I wouldn’t spend more evenings chasing it. The cloud path works and the UDP beacon still gives you presence and identification on the LAN.

For anyone else reading along and wondering whether it’s worth joining in: this is what actually moves the project. Complete terminal output instead of “it didn’t work”, an explicit list of what wasn’t tested, and a warning about a wrong conclusion the next person would have drawn.

Every real breakthrough here has come from someone with hardware and patience — the compressed map stream, a mandatory field nobody knew about, five capability flags being silently dropped, and most recently the virtual-wall bug that had been unsolved for months. None of it was found by reading code.

If you own a V4/Prime robot and can spare twenty minutes, the read-only validator sends nothing and changes nothing. That alone answers open questions.

5

roombapy-prime v0.2.0b1 — first beta

The Python library for iRobot’s V4/Prime generation — the cloud-only Roomba Combo and Plus models — has reached beta.

These robots have no local interface at all. Everything runs through iRobot’s cloud, which is why the existing integrations do not cover them. This library talks that protocol, and Roomba+ builds a Home Assistant integration on top of it.

What works today

Reading, comprehensively. Live state, battery, dock and bin status, mission progress room by room, the full map pipeline including room outlines and names, schedules, favourites, consumable parts with the app’s own units, mission history, quiet hours.

Writing, confirmed on real hardware. Starting and stopping missions, cleaning specific rooms by name, running saved favourites, enabling and disabling schedules, robot settings including child lock, suction level and two-pass cleaning — and, most recently, virtual walls: keep-out and no-mop zones, confirmed on two independent accounts.

A live map stream. Position updates arrive continuously during a mission — around 900 points in a single run — which is enough to draw where the robot has actually been.

What beta means here

Not that everything works. That what works is known, and what is uncertain is written down.

Every wire format in this library is marked as one of three things: confirmed against a real robot, inferred from the app’s own code, or a guess nobody should build on. That distinction is in the source, not in someone’s head.

The practical effect is that features get left out on purpose. One example: there is no pad-wetness control, because one of the three pad types turns out to use a separate value table — a control writing one level across all three would be wrong for at least one of them, and the robot would accept it without complaint. That waits on one capture from the right robot rather than on a plausible guess.

What is not yet confirmed

Twelve write operations have never been sent to a robot. They are modelled from the app’s own code and look complete — map renaming, quiet hours, favourite ordering, schedule creation. “Looks complete” has been wrong before, so they are offered as clearly-labelled experiments with a note on what to check in the app afterwards, rather than as features.

One endpoint’s response has never been seen. Its request format was worked out; nobody has run it.

Robots outside the Combo and Plus families. Almost all confirmation so far comes from a handful of models. A run on something untested is worth more than another run on something known.

What is missing

No local control. Careful probing of a V4 robot on the LAN found the discovery beacon answering but nothing to connect to — in the one state that was tested. Cloud is the working path, and likely the only one.

A few commands have no known equivalent. Evacuating the bin, powering off, spot cleaning, map training. These are absent rather than broken: no command has been identified, and a control that silently does nothing is worse than one that is not there.

Mixed households — a classic and a V4 robot on one account — have never been tested. Not expected to be a problem, but untested is untested.

Trying it

The validator is read-only. It sends nothing and changes nothing:

pip install "roombapy-prime-tools@git+https://github.com/johnnyh1975/[email protected]#subdirectory=tools"
roombapy-prime-validate

That is the tools package; the library alone ships no commands.

For Home Assistant, the integration is Roomba+, installable through HACS.

Every significant finding in this project came from someone with a robot and some patience — including the last one, which had been open for months and took three people to close. If you own one of these machines, twenty minutes of read-only output is genuinely the most useful thing anyone can contribute.