roombapy
Unofficial iRobot Roomba python library (SDK).
Fork of NickWaterton/Roomba980-Python
This library was created for the Home Assistant Roomba integration.
Installation
pip install roombapy[cli]
Notes
This library is only for firmware 2.x.x Check your robot version!
Only local connections are supported.
How to discover your robots and obtain credentials
roombapy discover <optional ip address>
This will find your Roomba in local network, and obtain credentials automagically whether possible.
Event stream
To get event stream from iRobot, use:
roombapy connect <ip> -p <password>
Output is suitable for piping into tools like jq.
Library usage
import asyncio
from roombapy import RoombaClient
async def main() -> None:
async with RoombaClient("192.168.1.50", blid, password) as robot:
robot.register_on_message_callback(print)
await robot.send_command("start")
await asyncio.sleep(60)
asyncio.run(main())
connect() either establishes a session or raises. Losing it afterwards is
the library's problem, not yours: a supervised reconnect with exponential
backoff runs until disconnect(). Register with
register_on_connection_state_callback to reflect availability.
A rejected credential is the exception — RoombaAuthError stops the
supervisor, because a wrong password does not become right by retrying.
Typed state, if you want it
master_state stays dict[str, Any], exactly as before. Alongside it,
reported is a typed view of the same dictionary — no parsing, no copy:
robot.reported.get("cleanMissionStatus", {}).get("phase") # checked by mypy
robot.master_state["state"]["reported"] # unchanged, still Any
reported is empty until the robot's first MQTT message arrives, so index
it with .get() rather than [] right after connect() — the fields
themselves are typed, but their presence is not guaranteed until a message
has been received. Coverage is also deliberately partial beyond that: a key
that is not declared is simply not typed, which is the right outcome for
firmware-specific fields.
Upgrading from 1.x
Version 2 is asynchronous throughout, and breaking.
| 1.x | 2.0 |
|---|---|
RoombaFactory.create_roomba(...) |
RoombaClient(address, blid, password) |
Roomba(remote_client, continuous=…, delay=…) |
RoombaClient(...); continuous/delay are gone |
RoombaRemoteClient |
internal; construct RoombaClient directly |
roomba.connect() / .disconnect() |
await them |
.send_command() / .set_preference() |
await them |
roomba.roomba_connected |
robot.connected |
RoombaDiscovery().get_all() |
await it; takes a timeout |
RoombaPassword(ip).get_password() |
await it; takes a timeout |
periodic_connection(), stop_connection |
removed with the thread |
master_state, the state machine and every constant table are unchanged.
Two behaviour changes worth knowing before you upgrade:
- Authentication failures raise. In 1.x a rejected password arrived via
on_connectand merely leftroomba_connectedFalse, so callers polled a flag.connect()now raisesRoombaAuthError. - Room-scoped commands are checked.
send_command("start", {"regions": []})raisesRoombaScopeError. An empty list does not mean "no rooms" to the robot — it means the key is omitted and the whole house is cleaned. Omitregionsentirely if that is what you want.
Development
This project uses uv for dependency management and packaging.
If you have Nix with flakes enabled, the quickest way to get a full dev environment (uv, a matching Python interpreter, and mosquitto for the integration tests) is:
nix develop
Otherwise, install uv yourself and run:
uv sync --all-extras --dev
To improve your development experience, you can install pre-commit hooks via the following command. With every commit it will run a set of checks, making sure it meets the quality standards.
uv run pre-commit install
Run the test suite with:
uv run pytest
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file roombapy-2.0.0.tar.gz.
File metadata
- Download URL: roombapy-2.0.0.tar.gz
- Upload date:
- Size: 73.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a2b47136d1950f25ceab5d25924eead1678bc70cb6455cc5fbd25270182666f0
|
|
| MD5 |
99dc6740e105bd3361c6ae079b872951
|
|
| BLAKE2b-256 |
2e12903bfa67b91afc2bf87751658a9fd5f4288802664fa4f0da4453c8384bea
|
File details
Details for the file roombapy-2.0.0-py3-none-any.whl.
File metadata
- Download URL: roombapy-2.0.0-py3-none-any.whl
- Upload date:
- Size: 77.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
14a7c798b1ecb0b1c20cb8c18dc54ea4147669b8031d8981fbfaeefa3bb6c87f
|
|
| MD5 |
8578044589ebf32936582cea9fc23692
|
|
| BLAKE2b-256 |
34e33a6843146463528258ee63410eb7877bc22fb106a22eb69fca5a6f62eb51
|
