dorita980-node18 – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 # dorita980
2 [![Build Status](https://travis-ci.org/koalazak/dorita980.svg?branch=master)](https://travis-ci.org/koalazak/dorita980)
3 [![dependencies Status](https://david-dm.org/koalazak/dorita980/status.svg)](https://david-dm.org/koalazak/dorita980)
4 [![npm version](https://badge.fury.io/js/dorita980.svg)](http://badge.fury.io/js/dorita980)
5  
6 Unofficial iRobot Roomba 980 node.js library (SDK)
7  
8 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.
9  
10 See [rest980](https://github.com/koalazak/rest980) if you need a HTTP REST API interface.
11  
12 # Firmware 1.6.6 documentation
13  
14 All this document is only for firmware 1.6.6. [Check your robot version!](http://homesupport.irobot.com/app/answers/detail/a_id/529)
15  
16 If you have firmware version 2.0 [click here](https://github.com/koalazak/dorita980) to see the new documentation.
17  
18 There are some breaking changes between 1.6.6 and 2.0.0.
19  
20 # Features
21  
22 - Get your username/password easily
23 - Auto discovery robot IP (optional)
24 - Cloud API control (from inside or outside your home)
25 - Local API control (from your LAN)
26 - Simplified Cleaning Preferences settings.
27 - Firmware 1.6.6 compatible. If you have firmware 2.0 [go here](https://github.com/koalazak/dorita980).
28 - See [rest980](https://github.com/koalazak/rest980) if you need a HTTP REST API interface to use dorita980 throw.
29  
30  
31 [![iRobot Roomba 980 cleaning map using dorita980 lib](https://img.youtube.com/vi/XILvHFEX7TM/0.jpg)](https://www.youtube.com/watch?v=XILvHFEX7TM)
32  
33 Video: Realtime cleaning map using dorita980 lib in [rest980](https://github.com/koalazak/rest980).
34  
35 # Install
36  
37 First you need node.js installed and then:
38  
39 ```bash
40 $ npm install dorita980 --save
41 ```
42  
43 # Quick start via Local request on your LAN
44 You can control the robot from your local network.
45  
46 Create `myapp.js` file with this content:
47  
48 ```javascript
49 var dorita980 = require('dorita980');
50  
51 var myRobotViaLocal = new dorita980.Local('MyUsernameBlid', 'MyPassword', '192.168.1.104', 1); // robot IP address. Firmware major version.
52  
53 // start to clean!
54 myRobotViaLocal.start().then((response) => {
55 console.log(response);
56 }).catch((err) => {
57 console.log(err);
58 });
59  
60 ```
61  
62 Then install `dorita980` using `npm` and run your program:
63  
64 ```bash
65 $ npm install dorita980 --save
66 $ node myapp.js
67 ```
68  
69 # Quick start via Cloud request
70 You can control the robot from inside or outside your home.
71  
72 Create `myapp.js` file with this content:
73  
74 ```javascript
75 var dorita980 = require('dorita980');
76  
77 var myRobotViaCloud = new dorita980.Cloud('MyUsernameBlid', 'MyPassword', 1); // No need robot IP. Firmware major version.
78  
79 // start to clean!
80 myRobotViaCloud.start().then((response) => {
81 console.log(response);
82 }).catch((err) => {
83 console.log(err);
84 });
85  
86 ```
87  
88 Then install `dorita980` using `npm` and run your program:
89  
90 ```bash
91 $ npm install dorita980 --save
92 $ node myapp.js
93 ```
94  
95 ## Examples
96  
97 Get robot status via Cloud request:
98  
99 ```javascript
100 var dorita980 = require('dorita980');
101  
102 var myRobotViaCloud = new dorita980.Cloud('MyUsernameBlid', 'MyPassword', 1); // No need robot IP. Firmware major version.
103  
104 myRobotViaCloud.getStatus().then(function(data){
105 console.log(data);
106 }).catch(function(err){
107 console.error(err);
108 });
109 ```
110  
111 Pause the robot via Cloud request:
112  
113 ```javascript
114 var dorita980 = require('dorita980');
115  
116 var myRobotViaCloud = new dorita980.Cloud('MyUsernameBlid', 'MyPassword', 1); // No need robot IP. Firmware major version.
117  
118 // Pause!
119 myRobotViaCloud.pause().then((response) => {
120 console.log(response);
121 }).catch((err) => {
122 console.log(err);
123 });
124  
125 ```
126  
127 Pause the robot via Local request:
128  
129 ```javascript
130 var dorita980 = require('dorita980');
131  
132 var myRobotViaLocal = new dorita980.Local('MyUsernameBlid', 'MyPassword', '192.168.1.104', 1); // robot IP address. Firmware major version.
133  
134 // Pause!
135 myRobotViaLocal.pause().then((response) => {
136 console.log(response);
137 }).catch((err) => {
138 console.log(err);
139 });
140 ```
141  
142 # How to get your username/blid and password
143 (Needed for Cloud and Local requests)
144  
145 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.
146  
147 ```bash
148 $ git clone https://github.com/koalazak/dorita980.git
149 $ cd dorita980
150 $ npm install
151 $ npm run getpassword <robotIP> <firmwareversion>
152 ```
153  
154 Example Output:
155  
156 ```
157 $ cd dorita980
158 $ npm install
159 $ npm run getpassword 192.168.1.103 1
160 > node ./bin/getpassword.js "192.168.1.103" 1
161  
162 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...
163 ========>
164 Good job!
165 Password: xxxxxxxxxxxxx
166 Username/blid: yyyyyyyyyyyy
167 Use this credentials in dorita980 lib :)
168  
169 ```
170  
171 ## Auto discover IP address for local request:
172  
173 If you dont known the robot IP address to use in `dorita980.Local()` you can use `dorita980.getRobotIP()` to find it.
174 This process takes 1 or 2 seconds, so if you known the IP just use it explicity.
175  
176 ```javascript
177 var dorita980 = require('dorita980');
178  
179 dorita980.getRobotIP(function (ierr, ip) {
180 if (!ierr) {
181 var myRobotViaLocal = new dorita980.Local('MyUsernameBlid', 'MyPassword', ip);
182  
183 myRobotViaLocal.getMission().then((response) => {
184 console.log(response);
185 }).catch((err) => {
186 console.log(err);
187 });
188 } else {
189 console.log('error looking for robot IP');
190 }
191 });
192 ```
193  
194 # Local API Firmware 1.6.6
195  
196 The library send commands direclty over wifi to your robot. You dont need internet connection.
197  
198 ## Succesfull response
199  
200 A successfull response return an object with `ok` property and the internal request id:
201  
202 ```javascript
203 { ok: null, id: 2 }
204 ```
205  
206 ## Error response
207 An error response return an object with `err` property and error number:
208  
209 ```javascript
210 { err: -32600 }
211 ```
212  
213 ## Methods
214  
215 #### `getTime()`
216 ```javascript
217 {"ok":{"d":"sat","h":13,"m":8},"id":8}
218 ```
219  
220 #### `setTime({"d":6,"h":13,"m":9})`
221  
222 ```javascript
223 {"ok":null,"id":23}
224 ```
225  
226 #### `setPtime({"time":1474128577})`
227  
228 ```javascript
229 {"ok":null,"id":23}
230 ```
231  
232 #### `getBbrun()`
233 ```javascript
234 {"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}
235 ```
236  
237 #### `getLangs()`
238 ```javascript
239 { ok: { total: 5, iterIndex: 2, iterName: 'en-US' }, id: 2 }
240 ```
241  
242 #### `getSys()`
243  
244 ```javascript
245 { ok:
246 { umi: 2,
247 pid: 2,
248 blid: 1,2,3,4,5,6,6,8],
249 sw: 'v1.6.6',
250 cfg: 0,
251 boot: 3580,
252 main: 4313,
253 wifi: 517,
254 nav: '01.09.08',
255 ui: 2996,
256 audio: 31,
257 bat: 'lith' },
258 id: 2 }
259 ```
260  
261 #### `getWirelessLastStat()`
262 ```javascript
263 { ok: { softap: 0, station: 1, cloud: 3, strssi: 47, diagflags: 0 }, id: 2 }
264 ```
265  
266 #### `getWeek()`
267 Monday disable and every day start at 10:30am
268 ```javascript
269 { ok:
270 { cycle: [ 'start', 'none', 'start', 'start', 'start', 'start', 'start' ],
271 h: [ 10, 10, 10, 10, 10, 10, 10 ],
272 m: [ 30, 30, 30, 30, 30, 30, 30 ] },
273 id: 2 }
274 ```
275  
276 #### `setWeek(newWeek)`
277  
278 Disable Sunday and set every day at 10:30am
279 ```javascript
280 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]}
281 myRobotViaLocal.setWeek(newWeek)
282 ```
283  
284 Response:
285  
286 ```javascript
287 {"ok":null,"id":218}
288 ```
289  
290 #### `getPreferences(autoDecodeFlags)`
291  
292 If `autoDecodeFlags` is `false` the returned object not include `cleaningPreferences` property. Default is `true` so always decode flags.
293  
294 ```javascript
295 { ok:
296 { flags: 1024, // See Cleaning Preferences table.
297 lang: 2,
298 timezone: 'America/Buenos_Aires',
299 name: 'myRobotName',
300 cleaningPreferences: {
301 carpetBoost: 'auto', // 'auto', 'performance', 'eco'
302 edgeClean: true,
303 cleaningPasses: '1', // '1', '2', 'auto'
304 alwaysFinish: true
305 }
306 },
307 id: 2 }
308 ```
309  
310 #### `setPreferences(newPreferences)`
311  
312 ```javascript
313 var newPreferences = {
314 flags: 1107, // See Cleaning Preferences table.
315 lang: 2,
316 timezone: 'America/Buenos_Aires',
317 name: 'myRobotName'
318 };
319  
320 myRobotViaLocal.setPreferences(newPreferences)
321 ```
322  
323 Response:
324  
325 ```javascript
326 {"ok":null,"id":293}
327 ```
328  
329  
330 #### `getMission(autoDecodeFlags)`
331 With this you can draw a map :)
332  
333 If `autoDecodeFlags` is `false` the returned object not include `missionFlags` and `notReadyMsg` properties. Default is `true` so always decode flags.
334  
335 ```javascript
336 { ok:
337 { flags: 0,
338 cycle: 'none',
339 phase: 'charge',
340 pos: { theta: 179, point: {x: 102, y: -13} },
341 batPct: 99,
342 expireM: 0,
343 rechrgM: 0,
344 error: 0,
345 notReady: 0,
346 mssnM: 0,
347 sqft: 0,
348 missionFlags: { idle: true, binFull: false, binRemoved: false, beeping: false },
349 notReadyMsg: 'Ready'
350 },
351 id: 2 }
352 ```
353  
354 #### `getWirelessStatus()`
355 ```javascript
356 { ok:
357 { softap: 0,
358 station: 1,
359 strssi: 45,
360 dhcp: 1,
361 addr: 1744939200,
362 mask: 16777215,
363 gtwy: 16885952,
364 dns1: 16885952,
365 dns2: 0,
366 bssid: [ 123, 23, 23, 123, 23, 123 ],
367 sec: 4 },
368 id: 2 }
369 ```
370  
371 #### `getCloudConfig()`
372 ```javascript
373 { ok: { cloudconfig: 'https://irobot-connect.axeda.com/ammp/' },
374 id: 2 }
375 ```
376  
377 #### `start()`
378 ```javascript
379 {"ok":null,"id":293}
380 ```
381  
382 #### `pause()`
383 ```javascript
384 {"ok":null,"id":293}
385 ```
386  
387 #### `stop()`
388 ```javascript
389 {"ok":null,"id":293}
390 ```
391  
392 #### `resume()`
393 ```javascript
394 {"ok":null,"id":293}
395 ```
396  
397 #### `dock()`
398 Note: before dock you need to pause() or stop() your robot.
399 ```javascript
400 {"ok":null,"id":293}
401 ```
402  
403 #### `decodeCleaningPreferences(flags)`
404 (this is not a promise)
405  
406 Example for `1024` value flags, return:
407  
408 ```javascript
409 {
410 carpetBoost: 'auto',
411 edgeClean: true,
412 cleaningPasses: '1',
413 alwaysFinish: true
414 }
415 ```
416  
417 ## Simplifications to set Cleaning Preferences:
418 This methods use setPreferences() with the correct `flags` for each setting.
419  
420 #### `setCarpetBoostAuto()`
421 ```javascript
422 {"ok":null,"id":293}
423 ```
424  
425 #### `setCarpetBoostPerformance()`
426 ```javascript
427 {"ok":null,"id":293}
428 ```
429  
430 #### `setCarpetBoostEco()`
431 ```javascript
432 {"ok":null,"id":293}
433 ```
434  
435 #### `setEdgeCleanOn()`
436 ```javascript
437 {"ok":null,"id":293}
438 ```
439  
440 #### `setEdgeCleanOff()`
441 ```javascript
442 {"ok":null,"id":293}
443 ```
444  
445 #### `setCleaningPassesAuto()`
446 ```javascript
447 {"ok":null,"id":293}
448 ```
449  
450 #### `setCleaningPassesOne()`
451 ```javascript
452 {"ok":null,"id":293}
453 ```
454  
455 #### `setCleaningPassesTwo()`
456 ```javascript
457 {"ok":null,"id":293}
458 ```
459  
460 #### `setAlwaysFinishOn()`
461 ```javascript
462 {"ok":null,"id":293}
463 ```
464  
465 #### `setAlwaysFinishOff()`
466 ```javascript
467 {"ok":null,"id":293}
468 ```
469  
470 ## Cleaning Preferences Flags table (firmware 1.6.6)
471 See `decodeCleaningPreferences(flags)` mehod.
472  
473 | Carpet Boost | Cleaning Passes | Finish Cleaning when bin is full | Edge Clean | Flags DEC |
474 |--------------|-----------------|----------------------------------|------------|------------|
475 | auto | auto | on | on | 0 |
476 | auto | auto | on | off | 2 |
477 | auto | auto | off | on | 32 |
478 | auto | auto | off | off | 24 |
479 | auto | one | on | on | 1024 |
480 | auto | one | on | off | 1026 |
481 | auto | one | off | on | 1056 |
482 | auto | one | off | off | 1058 |
483 | auto | two | on | on | 1025 |
484 | auto | two | on | off | 1027 |
485 | auto | two | off | on | 1057 |
486 | auto | two | off | off | 1059 |
487 | Performance | auto | on | on | 80 |
488 | Performance | auto | on | off | 82 |
489 | Performance | auto | off | on | 112 |
490 | Performance | auto | off | off | 114 |
491 | Performance | one | on | on | 1104 |
492 | Performance | one | on | off | 1106 |
493 | Performance | one | off | on | 1136 |
494 | Performance | one | off | off | 1138 |
495 | Performance | two | on | on | 1105 |
496 | Performance | two | on | off | 1107 |
497 | Performance | two | off | on | 1137 |
498 | Performance | two | off | off | 1139 |
499 | Eco | auto | on | on | 16 |
500 | Eco | auto | on | off | 18 |
501 | Eco | auto | off | on | 48 |
502 | Eco | auto | off | off | 50 |
503 | Eco | one | on | on | 1040 |
504 | Eco | one | on | off | 1042 |
505 | Eco | one | off | on | 1072 |
506 | Eco | one | off | off | 1074 |
507 | Eco | two | on | on | 1041 |
508 | Eco | two | on | off | 1043 |
509 | Eco | two | off | on | 1073 |
510 | Eco | two | off | off | 1075 |
511  
512  
513  
514 # Cloud API Firmware 1.6.6
515  
516 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.
517 iRobot Cloud Service has a public HTTP API to send commands to your robot if you known your user and password.
518  
519 - `myRobotViaCloud.getStatus()`
520 - `myRobotViaCloud.accumulatedHistorical()`
521 - `myRobotViaCloud.missionHistory()`
522 - `myRobotViaCloud.clean()`
523 - `myRobotViaCloud.quick()`
524 - `myRobotViaCloud.spot()`
525 - `myRobotViaCloud.dock()`
526 - `myRobotViaCloud.start()`
527 - `myRobotViaCloud.pause()`
528 - `myRobotViaCloud.resume()`
529 - `myRobotViaCloud.stop()`
530 - `myRobotViaCloud.wake()`
531 - `myRobotViaCloud.reset()`
532 - `myRobotViaCloud.find()`
533 - `myRobotViaCloud.wipe()` (untested)
534 - `myRobotViaCloud.patch()` (untested)
535 - `myRobotViaCloud.dlpkg()` (untested)
536 - `myRobotViaCloud.rechrg()` (untested)
537 - `myRobotViaCloud.wlapon()` (untested)
538 - `myRobotViaCloud.wlapoff()` (untested)
539 - `myRobotViaCloud.wlston()` (untested)
540 - `myRobotViaCloud.wlstoff()` (untested)
541 - `myRobotViaCloud.wifiscan()` (untested)
542 - `myRobotViaCloud.ipdone()` (untested)
543 - `myRobotViaCloud.provdone()` (untested)
544 - `myRobotViaCloud.bye()` (untested)
545 - `myRobotViaCloud.wllogflush()` (untested)
546 - `myRobotViaCloud.sleep()`
547 - `myRobotViaCloud.off()`
548 - `myRobotViaCloud.fbeep()`
549  
550 ## Note for node.js v0.10 users
551  
552 dorita980 is compatible with node.js > 4.0 But you can use the [getpassword](https://github.com/koalazak/dorita980#how-to-get-your-usernameblid-and-password) feature in node.js < 4.0 using `--harmony` flag like that:
553  
554 ```bash
555 $ node --harmony ./bin/getpassword.js "192.168.1.104"
556 ```
557  
558  
559 ## Author
560  
561 - [Facu ZAK](https://github.com/koalazak)