wazp / dorita980

unofficial iRobot Roomba 980 library / SDK

dorita980

Unofficial iRobot Roomba 980 library (SDK).

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

Features

• Get your username/password easily
• Auto discovery robot IP (optional)
• Cloud API control (from inside or outside your home)
• Local API control (from your LAN)
• Simplified Cleaning Preferences settings.
• Firmware 1.6.6 compatible.
• See rest980 if you need a HTTP REST API interface to use dorita980 throw.

Video: Realtime cleaning map using dorita980 lib

Install

First you need node.js installed and then:

$ npm install dorita980 --save

Quick start via Local request on your LAN

You can control the robot from your local network.

Create myapp.js file with this content:

var dorita980 = require('dorita980');

var myRobotViaLocal = new dorita980.Local('MyUsernameBlid', 'MyPassword', '192.168.1.104'); // robot IP address

// start to clean!
myRobotViaLocal.start().then((response) => {
  console.log(response);
}).catch((err) => {
  console.log(err);
});

Then install dorita980 using npm and run your program:

$ npm install dorita980 --save
$ node myapp.js

Quick start via Cloud request

You can control the robot from inside or outside your home.

Create myapp.js file with this content:

var dorita980 = require('dorita980');

var myRobotViaCloud = new dorita980.Cloud('MyUsernameBlid', 'MyPassword'); // No need robot IP

// start to clean!
myRobotViaCloud.start().then((response) => {
  console.log(response);
}).catch((err) => {
  console.log(err);
});

Then install dorita980 using npm and run your program:

$ npm install dorita980 --save
$ node myapp.js

Examples

Get robot status via Cloud request:

var dorita980 = require('dorita980');

var myRobotViaCloud = new dorita980.Cloud('MyUsernameBlid', 'MyPassword'); // No need robot IP

myRobotViaCloud.getStatus().then(function(data){
  console.log(data);  
}).catch(function(err){
  console.error(err);
});

Pause the robot via Cloud request:

var dorita980 = require('dorita980');

var myRobotViaCloud = new dorita980.Cloud('MyUsernameBlid', 'MyPassword'); // No need robot IP

// Pause!
myRobotViaCloud.pause().then((response) => {
  console.log(response);
}).catch((err) => {
  console.log(err);
});

Pause the robot via Local request:

var dorita980 = require('dorita980');

var myRobotViaLocal = new dorita980.Local('MyUsernameBlid', 'MyPassword', '192.168.1.104'); // robot IP address 

// Pause!
myRobotViaLocal.pause().then((response) => {
  console.log(response);
}).catch((err) => {
  console.log(err);
});

How to get your username/blid and password

(Needed for Cloud and Local requests)

Download or clone this repo then install, then run npm run getpassword. You need to know your robot IP address (look in your router or scan your LAN network with nmap to find it). Or use dorita980.getRobotIP() method.

$ git clone https://github.com/koalazak/dorita980.git
$ cd dorita980
$ npm install
$ npm run getpassword

Example Output:

$ cd dorita980
$ npm install
$ npm run getpassword 192.168.1.103
> node ./bin/getpassword.js "192.168.1.103"

Make sure your robot is on the Home Base and powered on. Then press and hold the HOME button on your robot until it plays a series of tones (about 2 seconds). Release the button and your robot will flash WIFI light. Then wait...
========>
Good job!
Password: xxxxxxxxxxxxx
Username/blid: yyyyyyyyyyyy
Use this credentials in dorita980 lib :)

Auto discover IP address for local request:

If you dont known the robot IP address to use in dorita980.Local() you can use dorita980.getRobotIP() to find it. This process takes 1 or 2 seconds, so if you known the IP just use it explicity.

var dorita980 = require('dorita980');

dorita980.getRobotIP(function (ierr, ip) {
  if (!ierr) {
    var myRobotViaLocal = new dorita980.Local('MyUsernameBlid', 'MyPassword', ip);

    myRobotViaLocal.getMission().then((response) => {
      console.log(response);
    }).catch((err) => {
      console.log(err);
    });
  } else {
    console.log('error looking for robot IP');
  }
});

Local API

The library send commands direclty over wifi to your robot. You dont need internet connection.

Succesfull response

A successfull response return an object with ok property and the internal request id:

{ ok: null, id: 2 }

Error response

An error response return an object with err property and error number:

{ err: -32600 }

Methods

getTime()

{"ok":{"d":"sat","h":13,"m":8},"id":8}

setTime({"d":6,"h":13,"m":9})

{"ok":null,"id":23}

setPtime({"time":1474128577})

{"ok":null,"id":23}

getBbrun()

{"ok":{"hr":103,"min":10,"sqft":251,"nStuck":8,"nScrubs":62,"nPicks":280,"nPanics":97,"nCliffsF":518,"nCliffsR":1005,"nMBStll":0,"nWStll":1,"nCBump":0},"id":9}

getLangs()

{ ok: { total: 5, iterIndex: 2, iterName: 'en-US' }, id: 2 }

getSys()

{ ok:
   { umi: 2,
     pid: 2,
     blid: 1,2,3,4,5,6,6,8],
     sw: 'v1.6.6',
     cfg: 0,
     boot: 3580,
     main: 4313,
     wifi: 517,
     nav: '01.09.08',
     ui: 2996,
     audio: 31,
     bat: 'lith' },
  id: 2 }

getWirelessLastStat()

{ ok: { softap: 0, station: 1, cloud: 3, strssi: 47, diagflags: 0 }, id: 2 }

getWeek()

Monday disable and every day start at 10:30am

{ ok:
   { cycle: [ 'start', 'none', 'start', 'start', 'start', 'start', 'start' ],
     h: [ 10, 10, 10, 10, 10, 10, 10 ],
     m: [ 30, 30, 30, 30, 30, 30, 30 ] },
  id: 2 }

setWeek(newWeek)

Disable Sunday and set every day at 10:30am

var newWeek = {"cycle":["none","start","start","start","start","start","start"],"h":[10,10,10,10,10,10,10],"m":[30,30,30,30,30,30,30]}
myRobotViaLocal.setWeek(newWeek)

Response:

{"ok":null,"id":218}

getPreferences(autoDecodeFlags)

If autoDecodeFlags is false the returned object not include cleaningPreferences property. Default is true so always decode flags.

{ ok:
   { flags: 1024, // See Cleaning Preferences table.
     lang: 2,
     timezone: 'America/Buenos_Aires',
     name: 'myRobotName',
     cleaningPreferences: {
        carpetBoost: 'auto', // 'auto', 'performance', 'eco'
        edgeClean: true,
        cleaningPasses: '1', // '1', '2', 'auto'
        alwaysFinish: true 
      }
    },
 id: 2 }

setPreferences(newPreferences)

var newPreferences = { 
  flags: 1107, // See Cleaning Preferences table.
  lang: 2,
  timezone: 'America/Buenos_Aires',
  name: 'myRobotName'
};

myRobotViaLocal.setPreferences(newPreferences)

Response:

{"ok":null,"id":293}

getMission()

With this you can draw a map :)

{ ok:
   { flags: 0,
     cycle: 'none',
     phase: 'charge',
     pos: { theta: 179, point: {x: 102, y: -13} },
     batPct: 99,
     expireM: 0,
     rechrgM: 0,
     error: 0,
     notReady: 0,
     mssnM: 0,
     sqft: 0 },
  id: 2 }

getWirelessStatus()

{ ok:
   { softap: 0,
     station: 1,
     strssi: 45,
     dhcp: 1,
     addr: 1744939200,
     mask: 16777215,
     gtwy: 16885952,
     dns1: 16885952,
     dns2: 0,
     bssid: [ 123, 23, 23, 123, 23, 123 ],
     sec: 4 },
  id: 2 }

getCloudConfig()

{ ok: { cloudconfig: 'https://irobot-connect.axeda.com/ammp/' },
  id: 2 }

start()

{"ok":null,"id":293}

pause()

{"ok":null,"id":293}

stop()

{"ok":null,"id":293}

resume()

{"ok":null,"id":293}

dock()

Note: before dock you need to pause() or stop() your robot.

{"ok":null,"id":293}

decodeCleaningPreferences(flags)

(this is not a promise)

Example for 1024 value flags, return:

{ 
  carpetBoost: 'auto',
  edgeClean: true,
  cleaningPasses: '1',
  alwaysFinish: true 
}

Simplifications to set Cleaning Preferences:

This methods use setPreferences() with the correct flags for each setting.

setCarpetBoostAuto()

{"ok":null,"id":293}

setCarpetBoostPerformance()

{"ok":null,"id":293}

setCarpetBoostEco()

{"ok":null,"id":293}

setEdgeCleanOn()

{"ok":null,"id":293}

setEdgeCleanOff()

{"ok":null,"id":293}

setCleaningPassesAuto()

{"ok":null,"id":293}

setCleaningPassesOne()

{"ok":null,"id":293}

setCleaningPassesTwo()

{"ok":null,"id":293}

setAlwaysFinishOn()

{"ok":null,"id":293}

setAlwaysFinishOff()

{"ok":null,"id":293}

Cleaning Preferences Flags table (firmware 1.6.6)

See decodeCleaningPreferences(flags) mehod.

Carpet Boost	Cleaning Passes	Finish Cleaning when bin is full	Edge Clean	Flags DEC
auto	auto	on	on	0
auto	auto	on	off	2
auto	auto	off	on	32
auto	auto	off	off	24
auto	one	on	on	1024
auto	one	on	off	1026
auto	one	off	on	1056
auto	one	off	off	1058
auto	two	on	on	1025
auto	two	on	off	1027
auto	two	off	on	1057
auto	two	off	off	1059
Performance	auto	on	on	80
Performance	auto	on	off	82
Performance	auto	off	on	112
Performance	auto	off	off	114
Performance	one	on	on	1104
Performance	one	on	off	1106
Performance	one	off	on	1136
Performance	one	off	off	1138
Performance	two	on	on	1105
Performance	two	on	off	1107
Performance	two	off	on	1137
Performance	two	off	off	1139
Eco	auto	on	on	16
Eco	auto	on	off	18
Eco	auto	off	on	48
Eco	auto	off	off	50
Eco	one	on	on	1040
Eco	one	on	off	1042
Eco	one	off	on	1072
Eco	one	off	off	1074
Eco	two	on	on	1041
Eco	two	on	off	1043
Eco	two	off	on	1073
Eco	two	off	off	1075

Cloud API

When you connect your robot to your wifi network, the robot starting to receive remote commands from the iRobot Cloud Service and from the mobile app. iRobot Cloud Service has a public HTTP API to send commands to your robot if you known your user and password.

• myRobotViaCloud.getStatus()
• myRobotViaCloud.accumulatedHistorical()
• myRobotViaCloud.missionHistory()
• myRobotViaCloud.clean()
• myRobotViaCloud.quick()
• myRobotViaCloud.spot()
• myRobotViaCloud.dock()
• myRobotViaCloud.start()
• myRobotViaCloud.pause()
• myRobotViaCloud.resume()
• myRobotViaCloud.stop()
• myRobotViaCloud.wake()
• myRobotViaCloud.reset()
• myRobotViaCloud.find()
• myRobotViaCloud.wipe() (untested)
• myRobotViaCloud.patch() (untested)
• myRobotViaCloud.dlpkg() (untested)
• myRobotViaCloud.rechrg() (untested)
• myRobotViaCloud.wlapon() (untested)
• myRobotViaCloud.wlapoff() (untested)
• myRobotViaCloud.wlston() (untested)
• myRobotViaCloud.wlstoff() (untested)
• myRobotViaCloud.wifiscan() (untested)
• myRobotViaCloud.ipdone() (untested)
• myRobotViaCloud.provdone() (untested)
• myRobotViaCloud.bye() (untested)
• myRobotViaCloud.wllogflush() (untested)
• myRobotViaCloud.sleep()
• myRobotViaCloud.off()
• myRobotViaCloud.fbeep()

Author

• Facu ZAK