Integrating your Roombas in Home Assistant and setting up room-specific cleaning

May 17, 2026  ·  6 min read

This guide shows how to integrate your Roomba in Home assistant, trigger room-specific cleaning, and add some nice buttons to the GUI. To trigger room-specific cleaning from a Home Assistant dashboard button you need two values that iRobot never exposes in the UI: pmap_id and user_pmapv_id. This guide shows how to extract them directly from your robot using a small Python script.

Step 1 — Create a Python virtual environment in VS Code

Open your project folder in VS Code, then open a terminal (Terminal → New Terminal) and run:

python -m venv .venv

Activate it:

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

Step 2 — Install roombapy and retrieve your credentials

roombapy is a Python library that speaks the Roomba's local MQTT protocol. It also ships a CLI command, get-roomba-password-cloud, that fetches your robot's local password from the iRobot cloud — no network sniffing needed.

1. Install the package:

pip install roombapy

2. Retrieve the BLID and local password for each robot:

get-roomba-password-cloud your@email.com yourPassword

The output lists every robot on your account with its IP address, BLID, and password. Note these down — you will need them in Step 5.

Step 3 — Install the iRobot Roomba and Braava integration in Home Assistant

1. Go to Settings → Devices & Services.
2. If your robot is already on the local network, it may appear automatically under Discovered — click it to proceed. Otherwise click + Add Integration and search for iRobot Roomba.
3. HA will ask for the robot's local password. Enter the password you retrieved in Step 2 with get-roomba-password-cloud.
4. Repeat for each robot on your account.

Step 4 — Temporarily disable the Roomba integration in Home Assistant

The Roomba only accepts one MQTT connection at a time. As long as HA's Roomba integration is running it holds that slot, and any direct connection attempt from your script will be refused with ConnectionRefusedError.

1. Go to Settings → Devices & Services.
2. Find the Roomba integration and click ⋮ → Disable.
3. Confirm. HA will disconnect from the robot within a few seconds.

Step 5 — Run the pmap script

Save the script below as get_pmap.py in your project folder:

"""Connect to a Roomba and print its full state, including pmaps and region IDs."""

import argparse
import json
import time

from roombapy import RoombaFactory

parser = argparse.ArgumentParser(description="Fetch Roomba state and pmap info")
parser.add_argument("-ip",       required=True, help="Roomba IP address")
parser.add_argument("-blid",     required=True, help="Roomba BLID")
parser.add_argument("-password", required=True, help="Roomba password")
args = parser.parse_args()

roomba = RoombaFactory.create_roomba(args.ip, args.blid, args.password)
roomba.connect()

print("Waiting for state data...", flush=True)
time.sleep(8)

state = roomba.master_state
roomba.disconnect()

# Print full state
print(json.dumps(state, indent=2))

# Extract and summarise pmap info
# Format is a list of single-key dicts: [{pmap_id: user_pmapv_id}, ...]
pmaps = state.get("state", {}).get("reported", {}).get("pmaps", [])
if pmaps:
    print("\n--- PMAP SUMMARY ---")
    for pmap in pmaps:
        for pmap_id, user_pmapv_id in pmap.items():
            print(f"pmap_id       : {pmap_id}")
            print(f"user_pmapv_id : {user_pmapv_id}")
        print()
else:
    print("\nNo pmaps found in state. Try increasing the sleep time.")

Run it, passing the values from Step 2:

python get_pmap.py -ip 192.168.1.X -blid YOUR_BLID -password YOUR_PASSWORD

After 8 seconds the full robot state is printed, followed by a clean summary:

--- PMAP SUMMARY ---
pmap_id       : miffpx5AQKGI5O0Ak3kE4g
user_pmapv_id : 260516T101837

Use these values in your HA dashboard button to start room-specific cleaning:

type: custom:button-card
name: Vacuum Living Room
icon: mdi:play
color_type: card
color: rgb(0, 0, 100)
tap_action:
  action: call-service
  service: vacuum.send_command
  service_data:
    entity_id: vacuum.your_robot
    command: start
    params:
      pmap_id: miffpx5AQKGI5O0Ak3kE4g
      user_pmapv_id: 260516T101837
      regions:
        - region_id: "1"
          type: rid

Once you have all values, re-enable the Roomba integration in HA (Settings → Devices & Services → Roomba → Enable) and your new button is ready to use.

Step 6 — Add a status glance card to the dashboard

Before adding control buttons, add a glance card so you can always see the robot's current state, battery level, and whether the bin is full — all at a glance. In the HA dashboard editor add a Manual card and paste:

show_name: true
show_icon: true
show_state: true
type: glance
entities:
  - entity: vacuum.consuela
  - entity: sensor.consuela_battery
  - entity: binary_sensor.consuela_bin_full
title: Consuela

Repeat for each robot, swapping the entity names accordingly.

Step 7 — Add start, pause, and send-home buttons

This grid card places three custom:button-card buttons side by side. Install button-card from HACS first if you haven't already.

type: grid
columns: 3
square: false
cards:
  - type: custom:button-card
    name: Vacuum Living Room
    icon: mdi:play
    color_type: card
    color: rgb(0, 0, 100)
    tap_action:
      action: call-service
      service: vacuum.send_command
      service_data:
        entity_id: vacuum.consuela
        command: start
        params:
          pmap_id: 69_uii6sQ_qHrccv_FINAg
          regions:
            - region_id: "1"
              type: rid
            - region_id: "2"
              type: rid
          user_pmapv_id: 250326T071933

  - type: custom:button-card
    name: Pause
    icon: mdi:pause
    color_type: card
    color: rgb(100, 60, 0)
    tap_action:
      action: call-service
      service: vacuum.pause
      service_data:
        entity_id: vacuum.consuela

  - type: custom:button-card
    name: Send Home
    icon: mdi:home
    color_type: card
    color: rgb(0, 80, 0)
    tap_action:
      action: call-service
      service: vacuum.return_to_base
      service_data:
        entity_id: vacuum.consuela

Step 8 — Add a "Commence!" button that starts all robots at once

If you have multiple robots, this single button starts them all simultaneously. HA's vacuum.start service accepts a list of entity IDs in one call.

type: custom:button-card
name: Commence!
icon: mdi:sword
color_type: card
color: rgb(120, 0, 0)
aspect_ratio: 3/1.5
styles:
  name:
    - font-size: 1.4rem
    - font-weight: bold
    - letter-spacing: 0.05em
tap_action:
  action: call-service
  service: vacuum.start
  target:
    entity_id:
      - vacuum.consuela
      - vacuum.ambrosio
      - vacuum.albert

Each robot starts its last-used mission. Place this card above the per-robot glance cards for a satisfying one-tap whole-house clean.