Tapo Robot Vacuum for Home Assistant

Local-only control of TP-Link Tapo robot vacuums (RV20, RV30 Max Plus, RV30C, RV50 and relatives), with a live map card bundled in. No cloud, no extra downloads. The tapo_rv30 domain name is historical; it is one integration for the range.

If it does the job for you, a star on the repo is what sorts the HACS store results, so it is how the next person with a Tapo finds it.

Mock-ups with a made-up house, rendered through the integration's own map code.

1. Click the badge above, or in HACS add https://github.com/epg-pers/tapo-rv30-ha as a custom repository of type Integration. Download it and restart Home Assistant.
2. Home Assistant finds the robot on its own (it watches for its network address) and offers "Tapo robot vacuum found": enter your Tapo account email and password. If it is not offered, Settings, Devices and services, Add integration, Tapo Robot Vacuum, and type the robot's IP address. If the robot's IP changes later, the entry follows it. The robot must be on firmware 1.2 or newer (TPAP); the older AES models (RV30C) are detected automatically, best effort.
3. Open Tapo Vacuum in the sidebar: the map, schedules, history, rooms, maintenance and settings are all there. For your own dashboards, add a card and pick Tapo Vacuum. Nothing else to install.

Needs Home Assistant 2026.3 or newer (HACS enforces it). Coming from a fork of this project? Same domain, so your config entry and entities carry over; see switching from a fork.

• Bundled map card: tap-to-clean rooms through a lossless room mask (no calibration), zone drawing, saved zones, floors, presets, controls, theme-aware, visual editor
• Live cleaning path on the map, and a Last Clean Map of where the robot actually went
• Clean map history: every run's map kept in Home Assistant (no extra robot calls), viewable and downloadable from the History tab even while the robot is cleaning, with retention you choose
• Per-room "last cleaned": worked out from the robot's own run maps, shown when you hold a room, and available to automations
• Sidebar page: map, a schedules editor for the robot's own schedules, history and statistics, rooms with freshness, maintenance and settings, no dashboard needed (switch it off in the integration options if you prefer)
• Smart cleaning planner: keeps each room within a target like "every 2 days" and cleans the due rooms when nobody is home, inside your time window, leaving out rooms whose motion sensors say they are in use; starts in preview mode
• Map editor on the sidebar page: draw no-go zones and virtual walls and place furniture straight onto the live map and save them to the robot, with undo, no app
• Map backup and recovery: a Backups tab that shows every backup as a thumbnail and restores one to the robot in a press; restore a whole map backup to the robot locally (Home Assistant serves it on the LAN and the robot applies it, no cloud); save a map's no-go zones, virtual walls, carpets and room names and re-apply them after the robot re-maps the floor; plus local copies of your cloud map backups so they survive even if TP-Link's are lost
• Remote drive: take control from the sidebar page and steer the robot with arrows or keys, like the Tapo app
• Go to a point from the card: tap the map, press Go
• Do Not Disturb aware: a schedule inside the robot's Do Not Disturb window never runs; the sidebar page and the services flag it before you save, instead of leaving a dead schedule on the robot
• One-click dashboard: a dashboard strategy that builds the whole thing for every robot
• Schedules from Home Assistant: add, change, enable / disable and remove the robot's own
• Matter: pairing state, a button that opens the pairing window, and the setup code from an admin-only action
• Furniture drawn as little illustrations on the map, from the app's own type table
• Voice: "vacuum the kitchen and the lounge" works in Assist with nothing to configure
• Discovery: the robot is found on the network and its entry follows IP changes
• Device triggers and blueprints for the automation editor; the vacuum wears its own state-coloured robot picture instead of a generic icon
• Presets from Home Assistant: create, edit and delete the robot's presets with per-room suction, water and passes, the same way the Tapo app does; each also gets a button
• Robot notices (dust bag full, area unreachable, water tank empty and the rest) as events and a device trigger
• Go to point, per-run suction / water / passes, native vacuum.clean_area with Home Assistant areas, events for start / finish / error
• Adaptive polling, hardened TPAP login, a repair issue when the robot stops answering, diagnostics, reconfigure and reauth from the integration page

This is the upstream project: new features, fixes and protocol work land here first, and the forks of this integration build on its code. If you use it in any form, starring the repo, reporting issues and contributing here is what keeps it moving.

Coming from a fork? Same domain, so your entities and dashboards carry over; see switching from a fork.

Assist understands the robot out of the box, no sentences to write:

• "vacuum the kitchen", "clean the lounge and the hallway", "hoover the dining room"
• "clean everywhere", "start the vacuum"
• "send the robot home", "tell the vacuum to dock"
• "stop the vacuum", "pause the robot"

Room names are matched against the robot's current map (partial matches work), and the reply says what it did or which room it did not recognise. With more than one robot, say its name ("tell Jarvis to clean the kitchen", "send Jarvis home"); see automations.

Our events show up as device triggers in the automation editor ("Finished cleaning", "Reported an error", "Started cleaning", "Gave a notice", under the robot's device), no raw event trigger needed. Two ready-made blueprints:

Blueprint	What it does
Notify with the last clean map	Phone notification with area, minutes and the Last Clean Map image when a run finishes
Clean when everyone has left	Start the house or chosen rooms once everyone has been away for a while, within a time window, only if docked

Sensors, switches, selects, numbers, buttons and the update entity adapt to what your model reports. Everything is documented at epg-pers.github.io/tapo-rv30-ha: getting started, the card and dashboards, voice and automations, entities, services and events, Matter, troubleshooting, the planner, the protocol notes and the changelog.

examples/dashboard.yaml is a ready-made view (controls, status chips, the live map, presets, one-tap rooms, settings, maintenance; the chip rows use Mushroom) and examples/automations.yaml covers notifications from the events and a local weekday schedule. tapo_vacuum.py is a standalone CLI that needs no Home Assistant.

Mock-up with a made-up house. Map, a schedules editor, history and statistics, rooms with freshness, maintenance and settings in one page. Details in docs/panel.md. Turn it off under the integration's Configure button if you only want the card.

type: custom:tapo-rv30-card
entity: vacuum.robot

Options: name, show_presets, show_controls, rotate (0 / 90 / 180 / 270 for maps the robot scanned sideways). The history button on the map opens the status panel: the last clean map, the recent runs and consumable life bars. Hold a room to see when it was last cleaned and how much of it the robot covered, and to start it with chosen levels.

Mock-ups with a made-up house.

Create a dashboard (Settings, Dashboards, Add dashboard, New dashboard from scratch), open its raw configuration editor and replace the contents with:

strategy:
  type: custom:tapo-rv30

It builds a view per robot: the card, one-tap room buttons, presets, the last clean map, status, maintenance, settings, schedules and totals, all from the entities the integration created, so it follows renames and models. Taps resolve through a room mask the integration serves, so odd-shaped rooms work; a floor switcher appears when the robot has several maps; the header shows status, current room, battery and progress, with a banner when the robot reports a problem.

Other Tapo RoboVac models should work with the features they report. Please open an issue with your model and firmware either way; the bug and feature templates ask for what helps.

Firmware updates can break local access. Several users report that an RV30 Max (Plus) firmware update silently breaks local access on port 4433 (connection refused or TLS handshake failure) until the robot is power-cycled; TP-Link's forum reply is that third-party local access is unsupported. If polling stops after an update on an unchanged network, reboot the vacuum and consider turning off automatic firmware updates in the Tapo app. Thanks to @jan-tdy for documenting this.

Do not probe a robot while it is working. On 2026-10-21 an RV30 Max Plus was sent a batch of read-only setup and backup queries mid-run and, within seconds, aborted the run and lost its saved maps, clean history and cloud backups. The cause is not proven, but tapo_rv30.send_raw now refuses anything outside the integration's own methods while the robot is working, and the details are in docs/protocol.md. Probe docked.

Bug reports and pull requests are welcome; see CONTRIBUTING.md. Security problems go through SECURITY.md, not the issue tracker.

The TPAP / SPAKE2+ transport code (custom_components/tapo_rv30/tpap.py and tapo_vacuum.py) is derived from the python-kasa project (PR #1592), which is licensed under GPL-3.0-or-later.

Thanks to the people whose forks and PRs fed back in: @cheesyturkey (command fixes, settings and dock entities), @jan-tdy (batching, retries, room geometry, schedules), @peggleg (AES transport, schedules), @danieyal (TPAP hardening, charging sensor), @Charles226 (security review), @cavefire (presets, capability discovery), @ckarlof (map-card calibration), @G0LDENWASTAKEN (HA 2026.8 fix).

This project is licensed under the GNU General Public License v3.0 or later. See LICENSE for the full text.