Roomba+ is a Gold-quality Home Assistant custom integration for iRobot Roomba and Braava robots. It connects directly over local Wi-Fi MQTT — no cloud account required, no polling, no subscription — and exposes far more sensors, intelligence, and controls than the built-in HA integration.
| Your robot | Install | Why |
|---|---|---|
| Any supported robot | v4.0.0 (stable) — the default in HACS | One line for both generations. No beta channel needed any more. |
| Roomba Max · Combo/Plus 400-series and other newer cloud robots | v4.0.0 | Earlier stable lines cannot connect to your robot at all |
| Not sure | Check your model number against the supported hardware table below |
⚠️ If HACS shows you onlymainand downloading it hangs, see Troubleshooting → Installing. Nothing is wrong with your setup.
🔬 V4/Prime is a separate path. These robots don't speak the local MQTT protocol everything below is built on — no local control, and a handful of Classic features have no counterpart. See V4/Prime support → before assuming everything on this page applies to your robot.
Why Roomba+?
- No prerequisites — local MQTT push, no Docker container, no polling. Cloud credentials are optional and used only for map sync and analytics.
- Full automation support — replace
vacuum.startwithsmart_start: it waits if a blocking sensor fires (a door contact, a baby monitor), skips rooms that aren't actually dirty, and can pause and resume around your presence — all from automations you already have, no new workarounds needed. - Comprehensive monitoring — 100+ entities covering maintenance life, wear rates, 365-entry mission history, performance trends, and error detail with recommended actions.
- Self-calibrating — maintenance thresholds, navigation health, battery degradation, and per-room cleaning rhythms all adapt to your robot's own usage history rather than fixed thresholds or manual configuration.
- Gold quality scale — 5,590+ tests, 8 languages, full config entry migration chain, CI/CD.
- What you get
- Feature status
- Supported hardware & capability matrix
- V4/Prime support
- Known limitations
- Installation
- Getting started
- Companion Lovelace card
- Migration
- Documentation
- Data privacy & data flow
- Replacing or selling your robot
- Translations
- Contributing
- Credits
- Status & control — phase/error detail beyond the standard HA vacuum states, blocking-sensor gate, room-targeted cleaning
- Maintenance & health — self-calibrating filter/brush/battery countdowns, a composite 0–100 health score, wear-rate anomaly detection
- Mission intelligence — 365-entry history, per-mission coordinate replay maps, anomaly explanations in plain language
- Room intelligence (SMART + cloud) — per-room cleaning rhythms, overdue-room catch-up cleaning, dirt ↔ sensor correlation
- Scheduling & presence — presence-aware auto-scheduling, demand cleaning, your cleaning schedule as a native HA calendar
- Automation-ready — 8+ copy-paste recipes in Automations & dashboards →, a REST API, device triggers, HA Long-Term Statistics
Full reference, tagged by which robots support what: Feature reference →
At a glance — what's shipped, what's next, and what was evaluated and deliberately not built:
| Feature | Status |
|---|---|
| Live map, room targeting, blocking sensors, maintenance tracking | ✅ Shipped |
| Presence-aware scheduling, demand cleaning, self-calibrating thresholds | ✅ Shipped |
| Mission history, health scoring, anomaly detection | ✅ Shipped |
| Room rhythms, overdue-room cleaning, mission cleaning maps (SMART + cloud) | ✅ Shipped |
| Cleaning schedule as HA calendar, maintenance as HA to-do list | ✅ Shipped (v3.4.0) |
| Coverage analytics for pose-less lewis-firmware robots | ✅ Shipped (v3.4.0) |
| Six blueprints: curated notifications, demand-clean alert, vacuum-then-mop, smart-start-on-away, robot-went-silent, exception notifications (v3.4.2 onwards) | ✅ Shipped — see Automations |
| Multi-robot fleet health rollup (v3.4.3) | ✅ Shipped — see API → GET /household |
| Gentle mode switch (v3.4.3) | ✅ Shipped |
| Braava mop-pad wear & water-level sensors | ✅ Shipped (pre-existing — pad_days_until_due, tank_level; no separate water-consumption field exists, tank_level already covers it, see Release notes →) |
Full backup & restore (create_backup/restore_backup actions) (v3.5.0) |
✅ Shipped — see Release notes → |
| Repairs redesign — 20 of 29 Repair Issues removed, converted to events, or merged (v3.5.0) | ✅ Shipped — see Release notes → |
| Device tracker — which room the robot is in, and the matching Home Assistant area (v2.9.0, areas in v4.0.0a14) | ✅ Shipped — see Device tracker |
| V4/Prime support — cloud-only robots (400-series) (v4.0.0) | ✅ Shipped — see V4/Prime support |
| Furniture-change detection from cloud map deltas | 🔲 Backlog, not yet scheduled |
| Room shape / door-position export | 🔲 Backlog, not yet scheduled |
| Voice commands ("clean the kitchen", etc.) | ❌ Evaluated, not pursued — see Known limitations |
Full version-by-version history: GitHub Releases →
| Series | Examples | Tested |
|---|---|---|
| 600 (Bump & run) | Roomba 694, 692 | |
| 900 (VSLAM) | Roomba 980, 985 | ✅ Roomba 980 |
| i-series | i3, i7, i7+ | ✅ i7+ |
| s-series | s9+ | ✅ S9+ |
| j-series | j7, j7+ | ✅ j-series |
| Braava | m6 | ✅ Braava jet m6 |
| V4/Prime (v4.0.0) | Combo/Plus 400-series; Roomba Max 705 Vac (W155042) | ✅ multiple field testers — see below |
What works on your robot — the fast answer to the most common setup question:
| Capability | 600 | 900 EPHEMERAL |
i / s / j SMART |
Braava m6 | Prime |
|---|---|---|---|---|---|
| Live cleaning map & path | ❌ | ✅ | ✅ | ✅ | ✅ |
| Clean by room name | ❌ | ✅ auto-detected zones | ✅ named rooms | ✅ named rooms | ✅ named rooms |
| Cloud room names, favourites, history | ❌ | ✅ optional | ✅ optional | ✅ always — cloud is the only path | |
| Presence-aware scheduling & demand cleaning | ❌ | ✅ | ✅ | ✅ | ✅ |
| Room rhythms, overdue-room cleaning, mission maps (v3.3.0) | ❌ | ❌ — needs cloud room data | ✅ requires cloud | ✅ requires cloud | ✅ |
| Dirt ↔ sensor correlation (v3.3.0) | ❌ | ❌ | ✅ requires cloud | ✅ requires cloud | ✅ |
| Maintenance reminders (filter/brush/battery) | ✅ | ✅ | ✅ | ✅ | ✅ real part names |
| Mop control (pad wetness, tank status) | — | — | — | ✅ | ✅ plus AutoWash dock controls |
| Cleaning schedule as HA calendar (v3.4.0) | ✅ | ✅ | ✅ | ✅ | ✅ |
| Maintenance tasks as HA to-do list (v3.4.0) | ✅ | ✅ | ✅ | ✅ | ✅ |
| — incl. "unnamed zones" reminder (v3.4.0, SMART only) | ❌ | ❌ | ✅ | ✅ | ✅ |
| Do Not Disturb, start-blocked reasons | ❌ | ❌ | ❌ | ❌ | ✅ |
| Local connection (works without internet) | ✅ | ✅ | ✅ | ✅ | ❌ cloud only |
EPHEMERAL and SMART are the two capability tiers among Classic robots: an EPHEMERAL robot builds a fresh map each run, a SMART robot keeps a persistent one it can name rooms on. Prime is a different generation entirely — newer robots that talk to iRobot's cloud protocol and have no local connection at all.
Cloud features require your iRobot app email and password and are entirely optional — all local MQTT functionality works without them.
Capability tiers, in plain terms: 600-series = bump-and-run (no map, no room targeting). 900-series = VSLAM ephemeral map with automatic zone detection and cloud history. i/s/j-series and Braava = persistent Smart Map with named rooms, favourites, and the full room-intelligence feature set.
V4/Prime robots are architecturally different enough (cloud-only, no local MQTT at all) that they're not part of the table above — see the next section for what they actually support today.
A device_tracker entity reporting which room the robot is currently in. Present since v2.9.0 and
never documented here, which is why you may not have noticed it.
It exposes two attributes worth automating on:
| Attribute | What it is |
|---|---|
room |
The robot's own name for the room — whatever you typed in the iRobot app |
area_id |
The matching Home Assistant area, resolved through the segment-to-area mapping you configured for Clean Area, falling back to a name match |
area_id is the better target: it survives renaming a room in the iRobot app, and it is the same
regardless of your Home Assistant language. Home Assistant areas are rooms — not to be confused
with zones, which are geographic and meant for presence detection.
Works for Classic and V4/Prime robots. For Prime, the room comes from the mission timeline, so it is reported whether Home Assistant started the mission or the robot ran on its own schedule.
One deprecation to be aware of. The entity's state also shows the room name, and Home Assistant stops supporting that mechanism in Core 2027.7. Nothing breaks today, and there is about a year — but if you have an automation matching on the state rather than the attributes, that is the one to move:
# before
condition: state
entity_id: device_tracker.roomba
state: "Kitchen"
# after
condition: template
value_template: "{{ state_attr('device_tracker.roomba', 'area_id') == 'kitchen' }}"The property will be removed a release before the deadline rather than on it, with a repair notification rather than only a release note.
iRobot's newer-generation robots (Combo/Plus 400-series and similar, on the "Prime" cloud protocol) don't speak the local MQTT protocol every other feature on this page is built on — they're cloud-only. Support for them was added in v4.0.0a0 as a genuinely separate code path, not an extension of the existing one, using the companion roombapy-prime library.
Stable since v4.0.0, after five betas and two dozen field testers. It has been tested against multiple real robots on separate accounts — but the feature set is deliberately narrower than everything described above, and three things remain unverified: whether the robot obeys Do Not Disturb, the upper pad-wash range on some docks, and uploading a modified map (which is not built at all). See the 4.0.0 release notes for what that means in practice.
Room cleaning now works (July 2026). This paragraph used to say it was the one thing Prime could not do — that was accurate for months and is not any more. Sending a robot to named rooms is confirmed on real hardware, from a saved favorite and from a command built from scratch, and Prime robots additionally support per-room suction level, which Classic has no equivalent for.
Virtual walls can be read and written; what has never been tried is a write that CHANGES the list — every confirmed write resent the existing zones unchanged, and the command replaces the whole list, so a partial one deletes what it omits.
Error messages now come from iRobot (August 2026). This integration wrote its own 126 error labels over the years; a comparison against the vendor's app found that two of them matched. The rest were not merely worded differently — "Charging error" where iRobot says "Charging Issue: contacts need to be cleaned". The second tells you what to do. The catalogue now uses the vendor's own titles and explanations, in all eight supported languages, and falls back to ours for the 75 codes iRobot does not document. Part names and maintenance units follow the same rule, so the words beside your robot match the words in the app. Everything else listed below works.
What works right now:
- Room cleaning by name —
roomba_plus.clean_roomand the services built on it. Accent- tolerant matching ("kuche" finds "Küche"), two-pass and suction level per room, and rooms from every saved map so an automation works whether or not the robot is parked on that floor - Zone cleaning on demand —
roomba_plus.clean_zone, by zone name or numeric id. The iRobot app stopped allowing zone favourites; this is how you send the robot to a zone from Home Assistant instead - Consumable parts — filter, brushes, mop pads and dirt disposal bag, with the app's own units: hours, routines, evacuations
- Setup via a third onboarding option (sign in with your iRobot cloud account) — Classic robots on the same account are set up automatically alongside any Prime ones
- Start, pause, stop, dock
- Locate ("find my robot") — confirmed working, produces a genuine, audible chime with no robot movement. Two earlier mechanisms were tried against real devices and confirmed not working before this one was found to be the correct one
- Live activity (cleaning/paused/docked/returning/idle), derived from the robot's real-time mission stream — plus current room, area, and pass-count as attributes when available
- Live cleaning map — an occupancy-grid image, updated as the robot cleans (no pose trail or room-outline overlay yet, unlike the Classic map entity)
- Battery percentage, bin present, mop tank present, detected pad, lifetime runtime hours, firmware version, and the robot's own reported connectivity to AWS IoT — real, live-confirmed values, not placeholders (see the latest release notes for the evidence trail). Live-updating via a push subscription that itself isn't confirmed live-tested yet — seeded with a real value at startup either way, so this works even if the push side turns out not to (see PrimeStatusCoordinator's own docstring)
- Dock, pad-wash, and pad-dry status — human-readable labels from a fully confirmed, 86-value enum (mostly error states; not translated into all 8 languages given how rarely most of them actually appear). Configured suction level (a genuine device_class=ENUM sensor, 5 confirmed values, translated)
- Carpet boost switch — reads and writes the account's real "boost suction when carpet is detected" setting. The write mechanism itself is confirmed to work (the same one already confirmed for other shadow writes), but whether toggling it actually changes the robot's real behavior isn't confirmed yet the way start/stop/dock/find are
- Schedule calendar — read-only, same
calendar.roomba_*_schedulepattern as Classic robots, showing each schedule's own room/zone (resolved to a real name via the account's map data, falling back to "Zone {id}" if unnamed). Only weekly-recurring schedules are shown; bi-weekly/ monthly/one-time schedules are deliberately skipped rather than shown with a guessed date — verifying any of those needs a real device test that waits days/weeks to see whether the robot actually fires as expected, a materially higher-risk test than anything else in this project - Error sensor — the robot's own error code, translated, with the same stale-error suppression Classic uses (the firmware does not reset the code when it docks after a failure, so a naive sensor would show a long-finished error forever). Also exposes the robot's readiness state as attributes, for the case where a mission is refused without an error code being set
- Capability-gated entities — sensors your robot cannot support (a mop pad on a vacuum-only model, a pad-wash dock it does not have) are not created at all, rather than sitting permanently unavailable. If you are wondering why a particular entity is missing, the integration's diagnostics download now names the flag responsible
- Two diagnostic sensors: current mission event, and connection health
- The device page itself (Settings → Devices) now shows the robot's real name, model, serial number, and firmware version — previously always blank/generic for every Prime robot despite individual sensors already showing the same data correctly (a separate code path that had never been fixed for Prime at all)
Added in v4.0.0a14:
- A room map with room outlines and room names, plus xiaomi-vacuum-map-card calibration. Ready immediately rather than after the first mission, because the cloud hands over finished polygons. The existing map (iRobot's own rendered image, showing where the robot actually cleaned) stays alongside it.
- Mission history sensors — last mission, result, duration, clean streak, anomaly count — plus maintenance dates, mission progress and long-term statistics backfilled into Home Assistant's own statistics.
- Schedule switches, one per schedule on the robot, so an automation can disable just the weekday routine.
- Setting switches — child lock, eco charging, two-pass cleaning, extra suction.
- A device tracker reporting which room the robot is in, and which Home Assistant area that maps to.
- Saved favorites, three ways: a button each, a
favoritesattribute on the vacuum entity, and arun_favoriteaction keyed on the favorite's ID rather than its name (a name changes when you rename it in the iRobot app; an automation keyed on it breaks silently). - Suction level as a select, using the profile names the app shows.
- Room preferences — profile, suction, two-pass, carpet boost per room, as set in the iRobot app — exposed as a map attribute so automations can honour them instead of overriding them.
What's not there yet:
- Pad wetness.
padPlatehas its own value table, separate from the other pad types, so a control writing one level across all three would be wrong for at least one — silently, since the robot accepts it. Waiting on a capture from a robot whoseppWetLvlcapability is nonzero. - Evacuate, power off, spot clean, map training. No Prime command has been identified for any of them. Absent rather than non-functional.
- Maintenance to-do items, which depend on the Classic consumable model.
- Repair issues. All nine of Classic's are tied to the local MQTT stream, pose maps or zone naming; none has a Prime equivalent. Checked rather than assumed.
- Everything else on this page that depends on local MQTT or pose data. Classic robots use — room intelligence, mission history, maintenance tracking, and more are simply a different, not-yet-built facade for V4/Prime robots specifically
Full detail, architecture, and the evidence trail behind every confirmed piece of the protocol: Release notes →
- Room shapes on 900-series follow coverage, not walls — a room is built from where the robot drove, so furniture leaves holes, edges stop about one robot radius short of the wall, and boundaries land at narrow points in the coverage rather than at doorways. More missions settle the room count; they do not change the shape, because the furniture is in the same place every time. Wall-accurate outlines would need obstacle data these robots do not report. Rooms are not derived at all until three missions have completed — see Troubleshooting →.
- 600-series is untested — should work (same local MQTT protocol), but no field confirmation yet. See the capability matrix above for what it does and doesn't support by design.
- i-series (lewis firmware) mission cleaning maps confirmed (July 2026, field-confirmed by Thonno on an i7) — previously confirmed on Braava jet m6 (sapphire firmware) only. See Upgrade notes →.
- Stuck-hotspot detection on lewis firmware is structurally wired up but not field-confirmed — the coverage heatmap and layout-change detection this same release adds for lewis firmware do work; whether the cloud data actually populates for a genuine stuck incident on this specific firmware is still an open question. See Release notes →.
- No voice commands ("clean the kitchen", etc.) — evaluated for this release and dropped, not delayed: there's currently no supported way for a third-party integration to ship Assist voice sentences that work without you creating a file yourself. See Release notes →.
- No "time to retrain your Smart Map" reminder — considered for the new to-do list, dropped: no existing signal was reliable enough at the right granularity (the closest one fires per-furniture-item, not map-wide). See Release notes →.
- V4/Prime room cleaning is confirmed working (July 2026) — an earlier version of this note said it was the one thing that did not work on Prime. It took three field sessions to establish why:
initiatoris a mandatory field a stored favorite does not carry, and the wire keys arestart/region_idrather thanclean/id. Two of those sessions appeared to disprove the explanation and were confounded by commands that never reached the broker. Prime robots also support per-room suction level, which Classic has no equivalent for. - V4/Prime robot settings are exposed as switches (v4.0.0a14) — child lock, eco charging, two-pass cleaning and extra suction. Child lock is verified end to end on real hardware: it appears in the iRobot app and the robot announces it audibly. The other three write and read back cleanly, meaning the robot echoes the new value, though their physical effect is harder to observe. Schedule hold is deliberately not offered: the write succeeds, the read-back confirms it, and the schedule stays active regardless — a switch the robot accepts and ignores would make the UI state something false.
- V4/Prime virtual walls can be read and written (confirmed 30 July 2026) — the cause of months of HTTP 500 responses was that the
virwallarray starts with a count of the walls before the walls themselves. Confirmed working on four zones of two different types in one command. Worth recording how it was found: three testers between them ruled out list length, zone type mixing, map count, account, map version and every request-envelope variant — none of which mattered, because the payload failed at element zero. It took an unfiltered bytecode dump of the app's serializer, after several filtered passes had missed the four relevant lines. - V4/Prime + Classic robots on the same Home Assistant instance simultaneously — each is independently confirmed working, but running both types at once hasn't been specifically tested.
Requirements: Home Assistant 2025.5 or newer · HACS installed (for recommended install)
- HACS → search for Roomba+
- Download the newest release → restart HA
Roomba+ is in the HACS default store, so there is no custom repository to add. If an older guide told you to add one, that step is obsolete — it does no harm, but it is not needed.
ℹ️ No beta channel needed since v4.0.0. Earlier v4 releases were pre-releases and required Show beta versions; 4.0.0 is a normal release and HACS offers it by default. If you enabled beta versions for the v4 betas, you can leave the setting on or turn it off — either way you get 4.0.0.
If HACS offers you only
mainand downloading it hangs, you are on a checkout from before v3.5.2 was tagged. Selectingmainfails with a 404:Download failed - Got status code 404 when trying to download .../releases/download/main/ha_roomba_plus.zipThat is HACS looking for a release asset on a tag called
main, which does not exist. Nothing is wrong with your setup.(Found by @pk-1966, who worked it out unaided.)
Copy custom_components/roomba_plus/ into your HA config/ directory, then restart HA.
- Settings → Devices & Services → Add integration → Roomba+
- Roomba is discovered automatically via DHCP/Zeroconf — or enter the IP manually
- Hold the HOME button on the robot for ~2 seconds until it plays tones
- (Smart Map robots, optional) Enter your iRobot app email and password to enable cloud features
V4/Prime robots (Combo/Plus 400-series — see above): pick "sign in with your iRobot cloud account" instead of the discovery flow above — there's nothing to discover locally for these, they're cloud-only. Classic robots on the same account are set up automatically alongside any Prime ones found.
Note: Roomba+ and the built-in Core Roomba integration cannot run simultaneously — they share the same local MQTT connection. Remove the Core integration first.
Settings → Devices & Services → Roomba+ → Configure → iRobot cloud credentials
Enter email and password, or clear both fields to disable cloud. A connection test runs before saving.
Settings → Devices → Roomba+ → ⋮ → Reconfigure — no need to remove and re-add.
ha_roomba_plus_card — a dashboard card built for this integration: the map, room buttons and mission history in one place.
Install it through HACS as a custom repository of type Dashboard (older HACS versions call it Lovelace). It is a separate project with its own releases, which is why it is not part of this download — keeping a card and an integration in step across two release schedules would be work for no benefit.
You may not need it. Home Assistant's own vacuum card already carries start, stop, return, locate and suction level, and any other control this integration provides is an entity you can place beside it with a plain Entities card:
type: entities
entities:
- vacuum.your_robot
- select.your_robot_prime_cleaning_modeThe companion card earns its place when you want the map and the room buttons together, not for one or two controls.
After installation, five steps to get the most out of Roomba+:
- Check the map — open the device page.
image.{name}_cleaning_maprenders automatically for 900-series and Smart Map robots. No configuration required. - Smart Map robots: add cloud credentials — Settings → Devices → Roomba+ → Configure → iRobot cloud credentials. Room names, favorites, and history appear immediately.
- Replace
vacuum.startwithroomba_plus.smart_startin all automations — it respects blocking sensors and optionally targets specific rooms. See Automations & dashboards → for copy-paste examples. - Set a blocking sensor (optional) — Settings → Configure → Blocking sensors. Pick any binary sensor (door contact, occupancy, person home). The robot will queue or abort rather than starting when it fires.
- Reset consumables after replacing them — Settings → device → press the Filter / Brush / Battery reset button, or mark the matching to-do item done. The remaining-life countdown restarts either way.
Two things also appear automatically, no setup needed: your cleaning schedule as calendar.{name}_schedule, and filter/brush maintenance as todo.{name}_maintenance.
- Settings → Devices & Services → iRobot Roomba and Braava → Delete
- Restart Home Assistant
- Install and set up Roomba+ via HACS
⚠️ "rest980" means two things here, and they need opposite treatment. The integration stays installed — that is where your room names come from. The server container (oftenrest980_j7) has to be stopped before you set Roomba+ up, because a robot accepts exactly one local connection at a time and the server holds it on port 8883. Roomba+ then cannot connect at all, and nothing in the error says why.
Assumed at the start: roomba_rest980 is working, with its room entities present in Home Assistant. That is the normal state if you are migrating — it is what you are migrating from — and it matters for one reason: those entities exist because the container was running the last time Home Assistant started. Keeping them alive through the steps below is what the second note is about.
- Install Roomba+ through HACS and restart Home Assistant — but don't set it up yet
- Stop the rest980 server container. Leave the integration installed
- Set Roomba+ up — it connects directly to the robot without middleware
- Enter your iRobot credentials in the setup flow to restore cloud zone names and favorites
- Settings → Devices → Roomba+ → Configure → Import rooms from roomba_rest980 (only shown when an existing roomba_rest980 installation is detected on a Smart Map robot) — reads room names straight from its
select.*entities and fills in any of your Roomba+ room labels that aren't set yet. Never overwrites a name you've already assigned through Roomba+'s own naming workflow. - Once you're happy with the result, remove the roomba_rest980 integration and delete the container
⚠️ Do not restart Home Assistant between steps 2 and 5.roomba_rest980 builds its room entities during setup, from data it fetches off the server. With the container stopped, its config entry fails to load and those entities never appear — so the import in step 5 would find nothing to import.
Once they exist they are safe: the room data sits on the entity itself and does not go away when the server stops. It is only the next start that cannot recreate them. That is why the HACS restart comes first, while the container is still running.
If you restart by accident, start the container again, restart Home Assistant, and pick up from step 2.
Each robot is a separate integration entry with its own device, entities, and storage. Repeat the Add Integration flow for each robot. Cloud credentials are stored per robot.
| Feature reference → | Every entity, service, and configuration option — organized by what you're trying to do, tagged by which robots support it |
| Automations & dashboards → | Copy-paste automation recipes and a starter dashboard |
| REST API → | Full endpoint reference with response shapes and examples |
| Feature comparison → | Roomba+ vs HA Core vs roomba_rest980 |
| xiaomi-vacuum-map-card → | Interactive room map card integration guide |
| Upgrade notes → | Per-version migration steps and learning-period notes |
| Troubleshooting → | Common problems grouped by topic |
| Data privacy → | Where your data goes, what stays on your disk, and what is in a diagnostics download |
| GitHub Releases → | Changelogs and release notes |
Questions or issues? → GitHub Issues · HA Community Forum
Roomba+ is a local-first integration. Here's exactly what talks to what.
Local MQTT (always on). Base functionality — live status, cleaning map, room targeting, blocking sensors, maintenance tracking — runs entirely over a local MQTT connection between Home Assistant and the robot (BLID + local password). No internet connection or cloud account is required.
iRobot cloud (optional). If you enter your iRobot app email and password (Settings → Devices → Roomba+ → Configure → iRobot cloud credentials), Roomba+ additionally talks to iRobot's own cloud API — the same servers and the same account the official iRobot app itself uses. Nothing is proxied through a third party or a Roomba+-specific server. This unlocks Smart Map room names, favorites, mission history enrichment, and the room-intelligence features marked "requires cloud" in the capability matrix above. It's entirely optional — everything else works without it, and you can add or remove cloud credentials at any time (see Adding or updating cloud credentials).
How often cloud data refreshes. Right after a mission ends, Roomba+ tries to pull the fresh cloud data almost immediately (within ~90 seconds, retrying once 10 minutes later if iRobot's own cloud hasn't caught up yet). Outside of that, cloud data refreshes on its own about once every 24 hours — so a change made only in the iRobot app (a renamed room, a new favorite) can take up to a day to appear here, not instantly.
What's stored, and where. Mission history, coverage/stuck-hotspot data, door markers, robot profile, and maintenance timers are all stored in Home Assistant's own .storage/ directory, on your instance. This data never leaves your Home Assistant instance on its own, and is deleted along with everything else when you remove the integration (v3.4.0+) — see Replacing or selling your robot if you want to export it first.
No phone-home. Roomba+ has no analytics, telemetry, or crash-reporting server of any kind — nothing is sent to the developer or anyone else automatically. The REST API (see REST API →) is served by your own Home Assistant instance and requires your own long-lived access token; it's not a hosted service.
Diagnostics downloads. Settings → Devices → Roomba+ → Download diagnostics redacts your BLID, local password, and iRobot credentials automatically before the file is generated — and is only ever created when you click the button, never automatically or on a schedule.
Filing a bug report? GitHub issues and the diagnostics download above are the only ways any data leaves your instance for troubleshooting purposes — both are things you explicitly initiate.
Roomba+ stores learned data (mission history, coverage baselines, maintenance timers, health trends) inside HA — not on the robot. Before removing a robot, export your history so you can restore it later:
curl -H "Authorization: Bearer <token>" \
"https://<ha>/api/roomba_plus/<entry_id>/mission_history?format=export" \
-o roomba_backup.jsonThen remove the integration via Settings → Devices & Services → Roomba+ → Delete — this permanently deletes the exported data above from your HA instance too (v3.4.0+), so export first if you want to keep it.
Factory reset (if selling) is done through the iRobot app, not this integration: app → robot → Settings → Factory Reset.
For a replacement robot, add a new config entry and optionally restore history via the import endpoint. Full steps: Troubleshooting → Replacing or selling your robot
| Language | Status |
|---|---|
| English | ✅ Complete |
| German | ✅ Complete |
| French | ✅ Complete |
| Italian | ✅ Complete — native speaker review welcome |
| Spanish | ✅ Complete — native speaker review welcome |
| Portuguese | ✅ Complete (European) — native speaker review welcome |
| Dutch | ✅ Complete — native speaker review welcome |
| Polish | ✅ Complete — community contribution by mdarocha, native speaker review welcome |
To contribute or report an incorrect phrase: open an issue or PR with the corrected translations/<lang>.json.
Roomba+ is maintained by one person — field-tester reports and pull requests are genuinely how this project moves faster:
- Found a bug, or a robot/firmware combination that doesn't work as documented? → GitHub Issues — a
diagnosticsdownload (Settings → Devices → Roomba+ → Download diagnostics, auto-redacted) attached to the report saves a lot of back-and-forth. - Own hardware nobody's field-tested yet (600-series, s9+, newer firmware)? A short raw-state capture is often more useful than a bug report — see the Credits section below for the kind of field testing that has directly shaped past releases.
- Translations — see just above; a native-speaker pass on any non-English language is always welcome, even a one-line correction.
- Code contributions — welcome via PR, though given the single-maintainer reality, please open an issue to discuss scope first for anything beyond a small, self-contained fix. The version plan (linked from GitHub Releases →) shows what's already planned, to avoid duplicate effort.
Field testing — real-device reports from these community members have directly driven bug fixes, cancelled features that didn't hold up, and shaped the version plan: Thonno (i7+), veronoicc (i7+, i8+), boutXIII (Braava jet m6), ronluna (S9+), KingAntDesigns (Braava jet m6, j7+), mdarocha (i3+), chairstacker, jayjay13011, DaRealGuGu, arielgr, utkjmitch, jadestar1864 (V4/Prime). Thank you all.
Some findings were only possible because two people reported the same thing differently: a mode number that meant "normal" on one robot and "smart" on another, or a room name the app showed and the API did not. Neither would have been caught from a single account.
Code — @jouwdan found that the V4/Prime map stream carries a second URL alongside the raw occupancy grid, and that room outlines live in the map bundle rather than in the metadata endpoint — which fixed a rooms map that was unavailable on three separate models. Also brought the Roomba Max 705 (W155042) into the tested set.
Translation — mdarocha contributed the Polish (pl) translation, boutXIII contributed the French (fr) translation.
roombapy — Python library for local MQTT/TLS communication with Roomba robots.
dorita980 by Facu Decena — Pioneering work documenting the local MQTT protocol, cloud auth flows, and Smart Map commands.
rest980 by Facu Decena — REST interface and cloud API analysis, including the Gigya → AWS Cognito auth flow.
roomba_rest980 — Reverse-engineered iRobot cloud API client whose auth implementation the cloud layer is based on.
Roomba980-Python by Nick Waterton — Comprehensive Python implementation with detailed Roomba protocol documentation.
Home Assistant Core Roomba Integration — Architecture foundation for Roomba+.
Roomba+ is an independent community project with no affiliation to iRobot or Picea Robotics.
MIT License — use at your own risk.