Controlling iRobot Roomba from the Command Line

If you’re a heavy command line (cli) user in Macos, Linux or WSL, you may it convenient to easily start or stop your robot from it’s cleaning cycle. In this post I’ll you fellow keyboard jockeys how to control and even view your robot as is cleans.

Utilities, Tools, Apps and Endpoints

There are a few tools I use to communicate with the Roomba. They’re like yin and yang. One is a library called dorita980. It provides a lower level of communication to the Roomba on your LAN (local network). The other, rest980 provides an API layer.

Rest 980

rest980 create a http server to map all dorita980 methods in a REST API to control your iRobot Roomba 900 series 980 / i7 / i7+ via HTTP requests.

https://github.com/koalazak/rest980

Again, this is from my notes. Please refer to the official README at the repo link above for proper documentation and examples.

Start the Server

If you have node (nodeJS) installed you can just clone the repo and start the server:

cbergeron@cb-mbp rest980 (master) $ DEBUG=rest980:* npm start

> rest980@2.1.0 start
> node ./bin/www

  rest980:server Listening on port 3000 +0ms

This will start the node/Express server on localhost port 3000: localhost:3000 or 127.0.0.1:3000 / 127.0.1.1:3000

Verify the Server (API Endpoint) is running

You can now check to see the API endpoint is running by connecting to port 3000. You can do this in a browser or using a tool like httpie or curl:

cbergeron@cb-mbp dorita980 (master) $ http http://localhost:3000

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 89
Content-Type: application/json; charset=utf-8
Date: Sun, 15 Aug 2021 00:30:25 GMT
ETag: W/"59-pSgrD/pK10leEJPjrIwFdVOiqIE"
X-Powered-By: Express

{
    "documentation": "https://github.com/koalazak/rest980",
    "pong": "2021-08-15T00:30:25.000Z"
}

This is the json object we received from the endpoint:

{
    "documentation": "https://github.com/koalazak/rest980",
    "pong": "2021-08-15T00:28:25.844Z"
}

You should also see a GET request to the server in the output if you ran it in DEBUG mode like I did here.

GET / 200 0.546 ms - 89

Once you have the REST API connected to your robot on your local network, you can start interacting with it. Here’s the output from the /api/local/config/preferences API route:

curl "http://localhost:3000/api/local/config/preferences" | jq .

{
  "netinfo": {
    "dhcp": true,
    "addr": 167772192,
    "mask": 4294967040,
    "gw": 167772161,
    "dns1": 167772161,
    "dns2": 0,
    "bssid": "9c:3d:cf:cf:6c:1a",
    "sec": 4
  },
# ... TRUNCATED BY CB ...

Another simple way to do this is with a simple app that will start a roomba cleaning cycle.

Create a Simple Test App

Create a basic myapp.js file with these contents:

var dorita980 = require('dorita980');

var myRobotViaLocal = new dorita980.Local('`31E8442031030170`', ':1:1608793068:UUyR5cdy7e4k3Jae', '10.0.0.129'); // robot IP address

myRobotViaLocal.on('connect', init);

function init () {
  myRobotViaLocal.clean()
  .then(() => myRobotViaLocal.end()) // disconnect to leave free the channel for the mobile app.
  .catch(console.log);
}

On line 3, we’re connecting to the robot on the IP: 10.0.0.129 which is the last argument. The first two are the BID and password, respectively.

Run the Test App

cbergeron@cb-mbp dorita980 (master) $ node myapp.js
cbergeron@cb-mbp dorita980 (master) $ echo $?
0

# Your Roomba should start to run 

Now that you can talk to your Roomba using the API, we can use Dorita 980 for mapping

Dorita 980

dorita980 is an unofficial iRobot Roomba node.js library (SDK).

With this library you can send commands to your wifi enabled Roomba through the iRobot cloud API or directly from your LAN and integrate your roboot with your own Home Automation or IoT project.

https://github.com/koalazak/dorita980

The information below is from my notes. Please refer to the official README at the repo link above for proper documentation.

Configuration

To run Dorita, you need to get the BID (Bot ID) and password from your Roomba. The BID is encoded as a string in a format like this: 31E8442031030170 and the password: :1:1608793068:UUyR5cdy7e4k3Jae. To get these you can run the included

MagicMirror Module

There’s also a MagicMirror Module that uses this API for displaying the robot’s status. Different robots will have varying degress of support ranging from Charge Level, Charge State and Bin Full Status.

The code for this module can be found over on github.

Other

The second Roomba I had got scratched up quite easily from normal usage. If you’re interested in protecting yours, there are quite a quite a few Roomba protective and decorative skins available.