@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

npm install @wizardry.steamworks/node-red-contrib-roomba980-local

@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:

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 dorita980 library 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:

  1. 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.
  2. In Node-RED, add any Roomba node and open its Connection dropdown, then press the pencil button to create or edit a connection.
  3. Press Discover Roombas. Available robots are listed with their BLID and IP address.
  4. 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-password command-line tool from the dorita980 project and enter the result in the dialog. Firmware 1.x connections also need the optional request-promise package; install it once in the Node-RED user directory with npm install request-promise (it is not installed by default because it pulls in the deprecated request chain).
  • 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.

Node Info

Version: 1.1.1
Updated 5 days ago
License: Apache-2.0
Rating: not yet rated

Categories

Actions

Rate:

Downloads

0 in the last week

Nodes

  • dorita980Config
  • get
  • set
  • basic
  • getstatus

Keywords

  • node-red
  • node-red-contrib
  • roomba
  • roomba980
  • irobot
  • dorita980
  • vacuum
  • local

Maintainers

Contributors

  • Dennis Henning
  • Facu ZAK