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.
$ git clone https://github.com/koalazak/rest980.git
$ cd rest980
$ npm installCheck your robot firmware version! and set your firmware version in firmwareVersion rest980 configuration!
The service can be configured by editing config/default.json or by setting environment variables.
Config File (config/default.json) |
Environment | Description |
|---|---|---|
| port | PORT | (default:3000) The HTTP port to listen on. |
| blid | BLID | (required) The Roomba blid. * |
| password | PASSWORD | (required) The Roomba password. * |
| robotIP | ROBOT_IP | (optional) Set if you know your robot IP to skip discovery and speed up startup. |
| firmwareVersion | FIRMWARE_VERSION | (optional) Set to 1 or 2 depends of your robot firmware version. Use 2 for any firmware >=2 (yes, use 2 if you have firmware version 3). Default to 1 for firmware 1.6.6 |
| enableLocal | ENABLE_LOCAL | (optional) Set to 'no' if you want to disable local API. Default 'yes'. |
| enableCloud | ENABLE_CLOUD | (optional) Set to 'no' if you want to disable cloud API. Default 'yes'. |
| keepAlive | KEEP_ALIVE | (optional) Set to 'no' if you want to connect and disconnect to the robot in each request (slow but leave the connection free for the official mobile app). |
| basicAuthUser | BASIC_AUTH_USER | (optional) Set to enable basic auth. Both user and pass must be set. |
| basicAuthPass | BASIC_AUTH_PASS | (optional) Set to enable basic auth. Both user and pass must be set. |
| sslKeyFile | SSL_KEY_FILE | (optional) Set path to key file to enable HTTPS. Both key and cert must be set. (how to create self signed cert) |
| sslCertFile | SSL_CERT_FILE | (optional) Set path to cert file to enable HTTPS. Both key and cert must be set. (how to create self signed cert) |
See dorita980 for more information and instructions for obtaining your robot blid and password
$ cd rest980
$ DEBUG=rest980:* npm start
rest980:server Listening on port 3000
omit DEBUG=rest980:* if you want. You can just run with npm start
You can use koalazak/rest980 docker image to run this server in a docker container. Usefull to run on Synology for example.
Pull Docker image:
docker pull koalazak/rest980Run Docker image:
docker run -e BLID=myuser -e PASSWORD=mypass -e ROBOT_IP=myrobotIP koalazak/rest980
Also you can local build and test in Docker from this Dockerfile
docker build . -t koalazak/rest980
Now you can make request to this server on port 3000.
There are 2 main endpoints: local and cloud, mapped to dorita980 local and cloud methods as well.
HTTP status 500 and response:
{"message":"human message","error":{}}
All cleaning actions are under /api/local/action/[action] endpoint using GET method without query params:
Available actions:
- start
- stop
- pause
- dock
- resume
- cleanRoom
Example: start to clean
GET http://192.168.1.110:3000/api/local/action/startSuccess Response:
{"ok":null,"id":23}
Example: clean a specific room
Some roomba types support "room specificic cleaning" - at the time of writing, at least the s9 and the i7 support this featrue. Assuming you have this model, and have a "Smart Map" for the floor you're trying to clean, you can send room specific cleaning commands. The easiest way to find out the values for this is to start a room specific clean via the app, and then look at the state endpoint (documented below) and find the lastCommand entry. Using this, you can find the room ids. These seem to be stable over time, unless a re-training or new smart map is saved.
The pmap_id and user_pmapv_id are also derived from the same lastCommand trick. These also seem to be stable - unless a new training run or edit to the smart map happens. It's important to get these correct, else your roomba won't clean.
curl -X POST http://192.168.1.110:3000/api/local/action/cleanRoom -H 'Content-Type: application/json' -d '{"ordered": 0, "pmap_id": "123456", "regions": [{"region_id":"5", "region_name":"Hallway","region_type":"hallway"}], "user_pmapv_id": "987654"}'Note that this is a
POSTbecuase it has a body, unlike the other relatedactionmethods.
All info endpoints are under /api/local/info/[record] using GET method without query params:
Available records:
- mission
- wireless
- lastwireless
- sys
- sku
- state (only in firmware 2)
Example: get current mission variables
GET http://192.168.1.110:3000/api/local/info/missionSuccess Response:
{ "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 }
All configuration endpoints are under /api/local/config/[configName] using GET method to get current configuration and POST method to set a new configuration.
Available configName:
- ptime (only GET in firmware 1)
- bbrun (only GET)
- cloud (only GET)
- langs (only GET. Use
preferencesto set lang) - week
- time (POST Y GET in firmware 1. Only GET in Firmware 2)
- preferences
- carpetBoost/auto (only POST. Use
preferencesto get current config) - carpetBoost/performance (only POST. Use
preferencesto get current config) - carpetBoost/eco (only POST. Use
preferencesto get current config) - edgeClean/on (only POST. Use
preferencesto get current config) - edgeClean/off (only POST. Use
preferencesto get current config) - cleaningPasses/auto (only POST. Use
preferencesto get current config) - cleaningPasses/one (only POST. Use
preferencesto get current config) - cleaningPasses/two (only POST. Use
preferencesto get current config) - alwaysFinish/on (only POST. Use
preferencesto get current config) - alwaysFinish/off (only POST. Use
preferencesto get current config)
See dorita980 documentation for responses and body params for each method and version firmware.
GET http://192.168.1.110:3000/api/local/config/preferencesSuccess Response:
{ ok:
{ flags: 1024, // See Cleaning Preferences table in dorita980 documentation.
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 }See dorita980 documentation for preferences in firmware 2.
POST http://192.168.1.110:3000/api/local/config/preferencesBody:
{
"flags": 1107, // See Cleaning Preferences table in dorita980 documentation.
"lang": 2,
"timezone": "America/Buenos_Aires",
"name": "myRobotName"
}
Success Response:
{"ok":null,"id":293}
See dorita980 documentation for preferences in firmware 2.
POST http://192.168.1.110:3000/api/local/config/cleaningPasses/twoBody:
{}
Success Response:
{"ok":null,"id":293}
Use GET in all info endpoints without query params:
- /api/cloud/info/status
- /api/cloud/info/history
- /api/cloud/info/missionHistory
Use GET in all action endpoints without query params:
- /api/cloud/action/clean
- /api/cloud/action/quick
- /api/cloud/action/spot
- /api/cloud/action/dock
- /api/cloud/action/start
- /api/cloud/action/stop
- /api/cloud/action/pause
- /api/cloud/action/resume
- /api/cloud/action/wake
- /api/cloud/action/reset
- /api/cloud/action/find
- /api/cloud/action/wipe
- /api/cloud/action/sleep
- /api/cloud/action/off
- /api/cloud/action/fbeep
Example:
GET http://192.168.1.110:3000/api/cloud/action/cleanSuccess Response:
{"status":"OK","method":"multipleFieldSet"}
You can add images or files to public/ folder to serve static files.
Visiting http://serverIP:3000/map with your browser you can play with this cool experiment
Video: Realtime cleaning map
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent