homebridge-roborock-map-camera

Shows your Roborock vacuum's live cleaning map as a camera accessory in Apple Home — no Home Assistant required. Works by calling the official python-roborock CLI directly.

Requirements

On the same machine as Homebridge:

• Python 3 with python-roborock[cli] installed
• ffmpeg installed and on PATH
• One-time login: roborock login --email "[email protected]"
• Your vacuum's device ID: roborock list-devices

Installation

Install via Homebridge UI X (search "Robot Vacuum Map") or npm install -g homebridge-roborock-map-camera

Configuration

Configure through Homebridge UI X, or add to config.json:

{
  "platform": "RoborockMapCamera",
  "name": "Robot Vacuum Map",
  "deviceId": "your-device-id",
  "roborockBinPath": "/home/homebridge/.local/bin/roborock",
  "refreshSeconds": 20
}

Fields: deviceId (required), roborockBinPath, refreshSeconds (default 20), ffmpegPath.

How it works

A background process periodically runs roborock session map-image to save the current map as a PNG. Snapshots are read straight from that file, and the "live" video feed is ffmpeg looping the same still image.

License

MIT { "platform": "RoborockMapCamera", "name": "Robot Vacuum Map", "deviceId": "your-device-id", "roborockBinPath": "/home/homebridge/.local/bin/roborock", "refreshSeconds": 20 }

Fields: deviceId (required), roborockBinPath, refreshSeconds (default 20), ffmpegPath.

How it works

A background process periodically runs roborock session map-image to save the current map as a PNG. Snapshots are read straight from that file, and the "live" video feed is ffmpeg looping the same still image.

License

MIT

Tested devices

Tested on a Roborock S8. It calls the roborock CLI generically (no model-specific logic), so it likely works on other Roborock models supported by python-roborock, but only the S8 has been verified.

Changelog

• 1.0.3: Map fetcher now backs off exponentially on repeated failures (instead of retrying every interval forever) and logs a clear hint when the Roborock login has expired.

Self-contained setup (v1.1.0+)

Installing or updating this plugin now automatically creates an isolated Python virtual environment (at ~/.roborock-venv, for whichever user runs Homebridge) with pinned, compatible dependencies - so a system-wide pip/apt upgrade elsewhere on the machine can't break it, and reinstalling the plugin (e.g. after restoring Homebridge from a config-only backup) sets this back up automatically.

The one thing that still can't be automated is logging into your Roborock account, since it requires a code emailed to you at that moment:

~/.roborock-venv/bin/roborock login --email "[email protected]"

If you're restoring onto a fresh machine, back up ~/.roborock-venv (or just re-run the login command above) alongside your Homebridge config.

Fully self-contained storage (v1.2.0+)

The isolated Python venv AND the Roborock login session now live inside Homebridge's own storage path (<storage>/roborock-map-camera/), instead of the home directory of the user running Homebridge. That means a normal Homebridge backup (the built-in "Backup" button in Homebridge UI X, or any backup that includes the storage path) now restores everything this plugin needs - map image, Python environment, and login - with nothing left to redo manually, as long as you're restoring onto the same OS/architecture.

Required system packages

This plugin needs these installed on the Homebridge machine itself - they are OS-level packages, so no Homebridge backup can ever include or restore them. On a fresh Raspberry Pi OS / Debian install, run once:

sudo apt install -y ffmpeg python3-venv python3-pip

If either is missing, the plugin now logs a clear error naming exactly this command every time it starts, so it won't fail silently.