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.
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 — 3,937 tests, 8 languages, full config entry migration chain, CI/CD.
- What you get
- Feature status
- Supported hardware & capability matrix
- Known limitations
- Installation
- Getting started
- 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) |
| Curated notification blueprints, incl. demand-clean alert, vacuum-then-mop, smart-start-on-away (v3.4.2/v3.4.3) | ✅ 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 → |
| 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 |
What works on your robot — the fast answer to the most common setup question:
| Capability | 600 | 900 (EPHEMERAL) | i / s / j-series (SMART) | Braava m6 |
|---|---|---|---|---|
| Live cleaning map & path | ❌ | ✅ | ✅ | ✅ |
| Clean by room name | ❌ | ✅ auto-detected zones | ✅ named rooms | ✅ named rooms |
| Cloud room names, favourites, history | ❌ | ✅ optional | ✅ optional | |
| 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) | ✅ | ✅ | ✅ | ✅ |
| Mop control (pad wetness, tank status) | — | — | — | ✅ |
| 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) | ❌ | ❌ | ✅ | ✅ |
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.
- 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 →.
Requirements: Home Assistant 2025.5 or newer · HACS installed (for recommended install)
- HACS → Integrations → ⋮ → Custom repositories
- URL:
https://github.com/johnnyh1975/ha_roomba_plus· Category: Integration - Install Roomba+ → restart HA
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
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.
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
- Keep roomba_rest980 installed for now — don't remove it yet
- Add Roomba+ — 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 roomba_rest980 and stop the rest980 Docker container
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 |
| 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+). Thank you all.
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.