@wizardry.steamworks/node-red-contrib-roomba980-local 1.1.1
Local-only Node-RED nodes for iRobot Roomba vacuums, built on dorita980. Setup and documentation: https://grimore.org/node-red/redesigning_a_local_wifi_controller_for_roomba_robots
@wizardry.steamworks/node-red-contrib-roomba980-local
Local-only Node-RED nodes for iRobot Roomba robot vacuums, built on the
maintained dorita980 library. All
communication happens directly with the robot on your LAN over MQTT/TLS. No
iRobot cloud account and no internet access are required.
Full setup guide and project documentation: https://grimore.org/node-red/redesigning_a_local_wifi_controller_for_roomba_robots
Credits and project history
This package was cleaned up and is maintained in 2026 by Wizardry and Steamworks.
It is a fork of two earlier projects, and their authors are credited here and in NOTICE:
node-red-contrib-roomba980by Dennis Henning — the original Node-RED Roomba 980 node.dorita980by Facu ZAK (koalazak) — the Node.js Roomba local API library.
The 2026 cleanup keeps the Node-RED integration working entirely locally and removes its dependence on the discontinued iRobot cloud:
- One shared MQTT/TLS connection per robot, reused by every flow node.
- Automatic TLS cipher detection with retry, so firmware 2.x robots connect without manual cipher configuration.
- Connection and pairing failures are reported through node status/warnings instead of crashing the Node-RED process.
- Discovery and password extraction in the config dialog work with modern Node-RED and Node.js without the old cloud endpoints.
- The patched
dorita980library is vendored inside this package, so no separate download or private registry is needed. - Cloud-only nodes (
accumulatedHistorical,missionHistory) were removed because they have no local equivalent.
The package is published as
@wizardry.steamworks/node-red-contrib-roomba980-local. The scoped name is
required because the package was first published on the public npm registry
after Node-RED's 31 January 2022 naming change. It was briefly published under
the temporary names node-red-contrib-roomba980-local and
node-red-contrib-dorita980-local; both are unpublished. Existing flows
continue to work: the node types (dorita980Config, basic, get, set,
getstatus) did not change.
The plugin is licensed under Apache-2.0 (see LICENSE). The vendored
dorita980 library remains MIT licensed; its license is included in
vendor/dorita980/LICENSE.
Requirements
- Node.js 18 or newer (Node.js 20 and 22 are supported).
- Node-RED 3.0 or newer.
- A Wi-Fi enabled Roomba from the 900 series or another model supported by
dorita980(i7/i7+, 980, 960, 900, e5, 690, 675, …). - The robot and Node-RED on the same network. Discovery and the local MQTT connection do not work across VLANs or through NAT without extra routing.
Install
From the Node-RED user directory (usually ~/.node-red):
npm install @wizardry.steamworks/node-red-contrib-roomba980-local
Or use Manage palette → Install in the Node-RED editor and search for
@wizardry.steamworks/node-red-contrib-roomba980-local.
After installation, the nodes appear in the palette under the dorita980 category.
Upgrading from an earlier package name
The package was previously published as the unscoped
node-red-contrib-roomba980-local and, briefly, as the temporary
node-red-contrib-dorita980-local. Both names are now unpublished and must not
be installed alongside the scoped package: they register the same node types
(dorita980Config, basic, get, set, getstatus). Remove them first:
cd ~/.node-red
npm uninstall node-red-contrib-roomba980-local node-red-contrib-dorita980-local
npm install @wizardry.steamworks/node-red-contrib-roomba980-local
Existing flows keep working because the node types did not change. The plugin also logs a warning at startup if it detects either older package still installed.
Getting the BLID and password
The robot's username (BLID) and password are needed once per robot. The
dorita980Config dialog can discover the robot and extract the password:
- Put the robot in Wi-Fi pairing mode: press and hold HOME until it plays a short series of tones (about two seconds), then release. The Wi-Fi light flashes.
- In Node-RED, add any Roomba node and open its Connection dropdown, then press the pencil button to create or edit a connection.
- Press Discover Roombas. Available robots are listed with their BLID and IP address.
- Select the robot and press Get password. The dialog shows the pairing progress and fills in the password.
Notes:
- Discovery sends a UDP broadcast to port 5678. If Node-RED runs in Docker, use host networking (or a broadcast-capable network) or discovery will not see the robot. The MQTT connection itself only needs normal TCP access to the robot on port 8883.
- Password extraction connects to TCP port 8883 while the robot is in pairing
mode and supports firmware 2.x. For firmware 1.x, use the
get-roomba-passwordcommand-line tool from thedorita980project and enter the result in the dialog. Firmware 1.x connections also need the optionalrequest-promisepackage; install it once in the Node-RED user directory withnpm install request-promise(it is not installed by default because it pulls in the deprecatedrequestchain). - The password is stored in the flow configuration in plain text (this node
does not use Node-RED's credential encryption). Protect access to the
Node-RED editor and to
flows_*.json.
Configuration
Each robot is represented by one dorita980Config node:
| Field | Description |
|---|---|
| Name | Optional label shown in the editor. |
| IP | Address of the robot on the local network, for example 192.168.1.50. |
| Username | The robot's BLID, for example 3192C22470628800. |
| Password | The password returned by the pairing process. |
| Firmware | 2.x (default) or 1.x. |
Every flow node that references the same configuration shares a single local MQTT connection. Different configuration nodes stay independent.
Multiple Roombas
Add one dorita980Config per robot. To create a second one, open a Roomba node
and choose Add new dorita980Config from the Connection dropdown. Run
discovery and password extraction for each robot separately. Connections are
labelled with the robot's BLID and IP so they can be told apart.
Removing a connection
Open any Roomba node and press the pencil next to the Connection dropdown (or open the connection from the configuration sidebar). The dialog lists every stored connection with the number of nodes that use it. Press Remove and confirm:
- The robot's MQTT session is closed.
- The configuration node is deleted.
- Nodes that referenced it have their Connection cleared and report an error until they are given another connection.
The removal can be undone with Ctrl+Z before deploying.
Nodes
dorita980Config (configuration node)
Holds the address and credentials of one robot and owns its shared connection. It reports connection state in the editor (connecting, connected, disconnected, error).
basic
Sends one of the basic commands. msg.payload must be one of:
start, pause, stop, resume, dock, clean, find
find makes a docked robot play its locate chime; a robot that is already
cleaning normally ignores it.
get
Calls a read-only dorita980 method when a message arrives. The method is
chosen in the node editor. The response is returned in msg.payload.
Available methods:
getTime, getBbrun, getLangs, getSys, getWirelessLastStatus, getWeek,
getPreferences, getMission, getBasicMission, getWirelessStatus,
getWirelessConfig, getCloudConfig, getSKU
For firmware 1.x responses the { ok, id } wrapper is unwrapped and the ok
value is returned.
set
Calls a preference setter when a message arrives. The method is chosen in the
node editor. The response is returned in msg.payload.
Available methods:
setCarpetBoostAuto, setCarpetBoostPerformance, setCarpetBoostEco,
setEdgeCleanOn, setEdgeCleanOff, setCleaningPassesAuto, setCleaningPassesOne,
setCleaningPassesTwo, setAlwaysFinishOn, setAlwaysFinishOff
getstatus
Returns a local status snapshot from the robot, without the cloud. The payload contains the state collected over the local connection: battery percentage, name, cleaning mission status and preferences.
This replaces the cloud-only accumulatedHistorical and missionHistory nodes.
Use getBbrun for lifetime run counters, or getMission /
getPreferences for the current mission and state.
There is no note, tone or song command in the 900-series local API. The only
sound command exposed to local clients is the fixed find chime.
Example flow
examples/roomba-local.json contains a small
flow with an Inject node, the basic and getstatus nodes, and Debug nodes.
After importing it, open the connection and set the robot's IP, BLID and
password.
Troubleshooting
The node says "not configured". Open the connection and fill in IP, username and password.
Discovery finds nothing. Make sure the robot is on the same L2 network, the firewall allows UDP 5678, and Node-RED is not running in a container without host networking.
The robot is in pairing mode but no password appears.
Keep the robot in pairing mode and retry. The editor shows a live log. A
connection refused error means the robot is not listening on port 8883; press
HOME again to re-enter pairing mode. Only one pairing session can be active.
The status stays "connecting" or "connection error".
The robot only accepts one local client per BLID. Make sure the iRobot app or
another integration is not connected, and that only this Node-RED package uses
that BLID. Check that the robot is awake and reachable with ping. Firmware 2.x
uses TLS on port 8883; firmware 1.x uses the older local protocol. If the robot
was recently updated, verify the dorita980 fork supports the new firmware.
A flow node reports "no robot connection". The connection was removed or never configured. Open the node and select a connection. Saving the configuration reconnects running nodes without a redeploy.
The process logged a Roomba connection error. Expected when the robot is asleep, off the network or in pairing mode. The nodes recover automatically when the robot becomes reachable again; saving the connection forces a reconnect.
Vendored dorita980
The patched library lives in vendor/dorita980. It is a
private copy of the maintained fork, included in the npm tarball so the package
works without a private registry. It is not a separate published package. See
vendor/dorita980/README.md and
NOTICE.
Maintainers can refresh the copy after updating the fork:
DORITA980_SRC=/path/to/dorita980 npm run sync:vendor
Development
npm test
npm pack
Tests use the built-in node:test runner and a fake dorita980 module, so they
do not need a robot or network access. See RELEASING.md for the
SVN, Verdaccio and npm release process.
License
- Node-RED integration and 2026 cleanup: Apache-2.0, Copyright 2026 Wizardry and Steamworks.
- Original Node-RED node: Copyright Dennis Henning.
- Vendored
dorita980: MIT, Copyright (c) 2016 Facu ZAK and Copyright (c) 2026 Wizardry and Steamworks.
See LICENSE, NOTICE and
vendor/dorita980/LICENSE.