{"id":13583412,"url":"https://github.com/koalazak/rest980","last_synced_at":"2025-04-05T22:07:07.498Z","repository":{"id":45062983,"uuid":"72160493","full_name":"koalazak/rest980","owner":"koalazak","description":"REST interface to control your iRobot Roomba 980 via local server on your lan.","archived":false,"fork":false,"pushed_at":"2024-03-11T11:41:09.000Z","size":55,"stargazers_count":309,"open_issues_count":9,"forks_count":62,"subscribers_count":38,"default_branch":"master","last_synced_at":"2025-03-29T21:06:44.287Z","etag":null,"topics":["api","cloud","docker-image","dockerfile","dorita980","iot","irobot","rest","robot","roomba","roomba980"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/koalazak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":null,"open_collective":"dorita980","ko_fi":null,"tidelift":null,"custom":null}},"created_at":"2016-10-28T00:50:43.000Z","updated_at":"2025-03-21T20:06:19.000Z","dependencies_parsed_at":"2022-08-26T10:51:27.631Z","dependency_job_id":"db69cf40-9ff4-4cc3-9056-191ccffb1d3d","html_url":"https://github.com/koalazak/rest980","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koalazak%2Frest980","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koalazak%2Frest980/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koalazak%2Frest980/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koalazak%2Frest980/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koalazak","download_url":"https://codeload.github.com/koalazak/rest980/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247406089,"owners_count":20933803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","cloud","docker-image","dockerfile","dorita980","iot","irobot","rest","robot","roomba","roomba980"],"created_at":"2024-08-01T15:03:27.898Z","updated_at":"2025-04-05T22:07:07.467Z","avatar_url":"https://github.com/koalazak.png","language":"JavaScript","funding_links":["https://opencollective.com/dorita980"],"categories":["JavaScript"],"sub_categories":[],"readme":"# rest980\n\nrest980 create a http server to map all [dorita980](https://github.com/koalazak/dorita980) methods in a REST API to control your iRobot Roomba 900 series 980 / i7 / i7+ via HTTP requests.\n\n## Install\n```bash\n$ git clone https://github.com/koalazak/rest980.git\n$ cd rest980\n$ npm install\n```\n\n## Fimrware version\n\n[Check your robot firmware version!](http://homesupport.irobot.com/app/answers/detail/a_id/529) and set your firmware version in `firmwareVersion` rest980 configuration!\n\n## Configuration\nThe service can be configured by editing `config/default.json` or by setting environment variables.\n\n|Config File (`config/default.json`)|Environment|Description|\n|:---|:---|:---|\n|port|PORT|*(default:3000)* The HTTP port to listen on.|\n|blid|BLID|*(required)* The Roomba blid. *|\n|password|PASSWORD|*(required)* The Roomba password. *|\n|robotIP|ROBOT_IP|*(optional)* Set if you know your robot IP to skip discovery and speed up startup.|\n|firmwareVersion|FIRMWARE_VERSION|*(optional)* Set to 1 or 2 depends of your robot firmware version. Use `2` for any firmware \u003e=2 (yes, use 2 if you have firmware version 3). Default to 1 for firmware 1.6.6|\n|enableLocal|ENABLE_LOCAL|*(optional)* Set to 'no' if you want to disable local API. Default 'yes'.|\n|enableCloud|ENABLE_CLOUD|*(optional)* Set to 'no' if you want to disable cloud API. Default 'yes'.|\n|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).|\n|basicAuthUser|BASIC_AUTH_USER|*(optional)* Set to enable basic auth. Both user and pass must be set.|\n|basicAuthPass|BASIC_AUTH_PASS|*(optional)* Set to enable basic auth. Both user and pass must be set.|\n|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)](http://www.akadia.com/services/ssh_test_certificate.html)|\n|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)](http://www.akadia.com/services/ssh_test_certificate.html)|\n\n*See [dorita980](https://github.com/koalazak/dorita980) for more information and instructions for obtaining your robot blid and password*\n\n\n\n## Start API Server\n```\n$ cd rest980\n$ DEBUG=rest980:* npm start\nrest980:server Listening on port 3000\n```\n\nomit `DEBUG=rest980:*` if you want. You can just run with `npm start`\n\n## Or use Docker Image\n\nYou can use [koalazak/rest980](https://hub.docker.com/r/koalazak/rest980/) docker image to run this server in a docker container. Usefull to run on [Synology](https://www.synology.com/en-global/) for example.\n\nPull Docker image:\n```bash\ndocker pull koalazak/rest980\n```\n\nRun Docker image:\n```\ndocker run -e BLID=myuser -e PASSWORD=mypass -e ROBOT_IP=myrobotIP koalazak/rest980\n```\n\n## Dockerfile\n\nAlso you can local build and test in Docker from this [Dockerfile](https://github.com/koalazak/rest980/blob/master/Dockerfile)\n\n```\ndocker build . -t koalazak/rest980 \n```\n\n## API documentation\n\nNow you can make request to this server on port 3000.\nThere are 2 main endpoints: `local` and `cloud`, mapped to [dorita980](https://github.com/koalazak/dorita980) local and cloud methods as well.\n\n## Error responses:\nHTTP status 500 and response:\n```\n{\"message\":\"human message\",\"error\":{}}\n```\n\n## Local\n\n### Actions\n\nAll cleaning actions are under `/api/local/action/[action]` endpoint using GET method  without query params:\n\nAvailable actions:\n\n- start\n- stop\n- pause\n- dock\n- resume\n- cleanRoom\n\nExample: start to clean\n\n```http\nGET http://192.168.1.110:3000/api/local/action/start\n```\nSuccess Response:\n```\n{\"ok\":null,\"id\":23}\n```\n\nExample: clean a specific room\n\nSome 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.\n\nThe `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.\n\n\n```sh\ncurl -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\"}'\n```\n\n\u003e Note that this is a `POST` becuase it has a body, unlike the other related `action` methods.\n\n\n### Info\n\nAll info endpoints are under `/api/local/info/[record]` using GET method without query params:\n\nAvailable records:\n\n- mission\n- wireless\n- lastwireless\n- sys\n- sku\n- state (only in firmware 2)\n\nExample: get current mission variables\n```http\nGET http://192.168.1.110:3000/api/local/info/mission\n```\nSuccess Response:\n```\n{ \"ok\":\n   { \"flags\": 0,\n     \"cycle\": \"none\",\n     \"phase\": \"charge\",\n     \"pos\": { \"theta\": 179, \"point\": {\"x\": 102, \"y\": -13} },\n     \"batPct\": 99,\n     \"expireM\": 0,\n     \"rechrgM\": 0,\n     \"error\": 0,\n     \"notReady\": 0,\n     \"mssnM\": 0,\n     \"sqft\": 0 },\n  \"id\": 2 }\n```\n\n### Configurations\n\nAll configuration endpoints are under `/api/local/config/[configName]` using `GET` method to get current configuration and `POST` method to set a new configuration.\n\nAvailable configName:\n\n- ptime (only GET in firmware 1)\n- bbrun (only GET)\n- cloud (only GET)\n- langs (only GET. Use `preferences` to set lang)\n- week\n- time (POST Y GET in firmware 1. Only GET in Firmware 2)\n- preferences\n- carpetBoost/auto (only POST. Use `preferences` to get current config)\n- carpetBoost/performance (only POST. Use `preferences` to get current config)\n- carpetBoost/eco (only POST. Use `preferences` to get current config)\n- edgeClean/on (only POST. Use `preferences` to get current config)\n- edgeClean/off (only POST. Use `preferences` to get current config)\n- cleaningPasses/auto (only POST. Use `preferences` to get current config)\n- cleaningPasses/one (only POST. Use `preferences` to get current config)\n- cleaningPasses/two (only POST. Use `preferences` to get current config)\n- alwaysFinish/on (only POST. Use `preferences` to get current config)\n- alwaysFinish/off (only POST. Use `preferences` to get current config)\n\nSee [dorita980](https://github.com/koalazak/dorita980) documentation for responses and body params for each method and version firmware.\n\n### Examples:\n\n#### Get preferences in firmware 1:\n```http\nGET http://192.168.1.110:3000/api/local/config/preferences\n```\nSuccess Response:\n```javascript\n{ ok:\n   { flags: 1024, // See Cleaning Preferences table in dorita980 documentation.\n     lang: 2,\n     timezone: 'America/Buenos_Aires',\n     name: 'myRobotName',\n     cleaningPreferences: {\n        carpetBoost: 'auto', // 'auto', 'performance', 'eco'\n        edgeClean: true,\n        cleaningPasses: '1', // '1', '2', 'auto'\n        alwaysFinish: true \n      }\n    },\n id: 2 }\n```\n\nSee [dorita980](https://github.com/koalazak/dorita980) documentation for preferences in firmware 2.\n\n#### Set preferences in firmware 1:\n```http\nPOST http://192.168.1.110:3000/api/local/config/preferences\n```\nBody:\n```\n{ \n  \"flags\": 1107, // See Cleaning Preferences table in dorita980 documentation.\n  \"lang\": 2,\n  \"timezone\": \"America/Buenos_Aires\",\n  \"name\": \"myRobotName\"\n}\n```\n\nSuccess Response:\n```\n{\"ok\":null,\"id\":293}\n```\n\nSee [dorita980](https://github.com/koalazak/dorita980) documentation for preferences in firmware 2.\n\n#### Set cleaning passes to two:\n```http\nPOST http://192.168.1.110:3000/api/local/config/cleaningPasses/two\n```\nBody:\n```\n{}\n```\n\nSuccess Response:\n```\n{\"ok\":null,\"id\":293}\n```\n\n## Cloud (only for firmware 1.6.x)\n\nUse `GET` in all `info` endpoints without query params:\n\n- /api/cloud/info/status\n- /api/cloud/info/history\n- /api/cloud/info/missionHistory\n\nUse `GET ` in all `action` endpoints without query params:\n\n- /api/cloud/action/clean\n- /api/cloud/action/quick\n- /api/cloud/action/spot\n- /api/cloud/action/dock\n- /api/cloud/action/start\n- /api/cloud/action/stop\n- /api/cloud/action/pause\n- /api/cloud/action/resume\n- /api/cloud/action/wake\n- /api/cloud/action/reset\n- /api/cloud/action/find\n- /api/cloud/action/wipe\n- /api/cloud/action/sleep\n- /api/cloud/action/off\n- /api/cloud/action/fbeep\n\nExample:\n\n```http\nGET http://192.168.1.110:3000/api/cloud/action/clean\n```\nSuccess Response:\n```\n{\"status\":\"OK\",\"method\":\"multipleFieldSet\"}\n```\n## Host images or files\n\nYou can add images or files to `public/` folder to serve static files.\n\n## Realtime Map (experimental)\n\nVisiting  `http://serverIP:3000/map` with your browser you can play with this cool experiment\n\n![/map](https://cloud.githubusercontent.com/assets/8185092/20685415/23e2ed58-b593-11e6-8492-280cc381abda.png)\n\n[![iRobot Roomba 980 cleaning map using dorita980 lib](https://img.youtube.com/vi/XILvHFEX7TM/0.jpg)](https://www.youtube.com/watch?v=XILvHFEX7TM)\n\nVideo: Realtime cleaning map\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoalazak%2Frest980","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoalazak%2Frest980","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoalazak%2Frest980/lists"}