search

Zefau / ioBroker.roomba

Connect your iRobot Roomba to ioBroker
MIT License
13 stars 6 forks source link
iobroker irobot roomba

readme

:heavy_exclamation_mark: DEVELOPMENT HAS BEEN MOVED TO COMMUNITY.

Logo

ioBroker.roomba

Connect your iRobot Roomba to ioBroker.

Based on the dorita980 library https://github.com/koalazak/dorita980#readme

Paypal Donation

Number of Installations Stable Version NPM Version Travis CI Downloads

NPM

Table of contents

  1. Features
  2. Installation
  3. Setup instructions
  4. Supported Roomba's / Firmware versions
  5. Channels & States
  6. Description of Preferences (incomplete)
  7. Smart Home / Alexa integration using ioBroker.javascript
  8. Changelog
  9. Credits
  10. Licence

Features

The following features come with this adapter:

Installation

ioBroker.roomba needs canvas in order to draw maps of the Roomba missions. ioBroker will try to install this dependency with ioBroker.roomba installation.

Though, you probably have to install package dependencies of canvas (and canvas itself) with the following command:

Linux

sudo apt-get install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev

Furthermore, run the following command in the ioBroker.roomba directory (/opt/iobroker/node_modules/iobroker.roomba):

sudo npm install canvas --unsafe-perm=true

Windows

  1. Make sure you have node-gyp installed via

    npm install -g node-gyp

  2. Make sure you have build essentials installed via

    npm install --global --production windows-build-tools

  3. Download GTK 2 (for Win32 or Win64) and unzip it (e.g. to C:\path\to\GTK2)

  4. Run 

    node-gyp rebuild --GTK_Root=C:\path\to\GTK2

  5. Install canvas from within the iobroker.roomba folder

    cd C:\path\to\iobroker\node_modules\iobroker.roomba
npm install canvas

For details, see https://github.com/Automattic/node-canvas/wiki/Installation:-Windows.

Setup instructions

Automated setup

To automatically setup ioBroker.roomba following the instructions in the admin panel of ioBroker.roomba.

ATTENTION: The authentication credentials are not the same as you are using in the smartphone app!

  1. Make sure the ioBroker.roomba adapter is started.
  2. Make sure your robot is on the Home Base and powered on (green lights on).
  3. Then press and hold the HOME button on your robot until it plays a series of tones (about 2 seconds).
  4. Release the button and your robot will flash WIFI light.
  5. Then come back here press the button to retrieve IP and credentials.

If the automated process fails retrieving your credentials, please use the manual setup.

Manual setup

For manual setup see https://github.com/koalazak/dorita980#how-to-get-your-usernameblid-and-password.

Supported Roomba's / Firmware versions

Supported Firmware versions

Software-Version Firmware Info Supported
v1.4 Release Notes #c5f015 supported (#c5f015 incl. map)
v2.4.6-x Release Notes #c5f015 supported (#c5f015 incl. map)
v3.2.xx Release Notes #c5f015 supported (#f03c15 NO map)

Supported Roomba's

Serie Models (incomplete) Software-Version Firmware Info Supported
Roomba® 6xx 605, 606, 612, 616, 671, 676, 680, 696 v3.2.40 Release Notes (most likely)
Roomba® 6xx 675, 690 v3.2.40 Release Notes #c5f015 supported (#f03c15 NO map)
Roomba® 7xx 774, 785, - #f03c15 Model does not offer Wifi connectivity, thus no support
Roomba® 8xx 880, 886, 891, 896 - Release Notes (most likely)
Roomba® 8xx 895 v3.2.10 / 40 / 69 Release Notes #c5f015 supported (#f03c15 NO map)
Roomba® 9xx 965, 981 - Release Notes (most likely)
Roomba® 9xx 960, 966, 980 v2.4.6-3 Release Notes #c5f015 supported (incl. map)
Roomba® i i7 (7150), i7+ (7550) v1.4 Release Notes #c5f015 supported (incl. map)
Roomba® e5 e5 v3.4.42 Release Notes #c5f015 supported (#f03c15 NO map)
Roomba® s S9+ v3.2.4 Release Notes #c5f015 supported (incl. map)

Please help me regarding the supported devices and let me know via an issue, whether your Roomba model is supported!

Channels & States

After sucessful setup the following channels and states will be created:

Channel Folder State Description
cleaning - - Commands and information regarding cleaning process
cleaning last - Last commands sent to robot
cleaning last command Last command sent to robot
cleaning last timestamp Timestamp last command was sent
cleaning last datetime DateTime last command was sent
cleaning last initiator Initiator of last command
cleaning last cycle Cycle
cleaning last phase Phase
cleaning last error Indicates an error during last mission
cleaning schedule - Schedule information
cleaning schedule cycle Schedule cycle (Sunday to Saturday)
cleaning schedule hours Hour to start cycle (Sunday to Saturday)
cleaning schedule minutes Minute to start cycle (Sunday to Saturday)
cleaning - dock Send the robot to the docking station
cleaning - pause Pause the current cleaning process
cleaning - resume Resume the current cleaning process
cleaning - start Start a cleaning process
cleaning - stop Stop the current cleaning process
device - - Device information
device network - Network information
device network dhcp State whether DHCP is activated
device network router Mac address of router
device network ip IP address
device network subnet Subnet adress
device network gateway Gateway address
device network dns1 Primary DNS address
device network dns2 Secondary DNS address
device preferences - Set preferences
device preferences binPause UNKNOWN
device preferences carpetBoostAuto Automatic: Roomba will automatically boost its vacuum power to deep clean carpets.
device preferences carpetBoostHigh Performance Mode: Roomba will always boost its vacuum to maximise cleaning performance on all floor surfaces.
device preferences ecoCharge UNKNOWN
device preferences noAutoPasses One Pass: Roomba will cover all areas with a single cleaning pass.
device preferences noPP UNKNOWN
device preferences openOnly UNKNOWN
device preferences schedHold UNKNOWN
device preferences twoPass Roomba will cover all areas a second time. This may be helpful in homes with pets or for occasional deep cleaning.
device versions - Version information
device versions hardwareRev Hardware Revision
device versions batteryType Battery Type
device versions soundVer UNKNOWN
device versions uiSwVer UNKNOWN
device versions navSwVer UNKNOWN
device versions wifiSwVer UNKNOWN
device versions mobilityVer UNKNOWN
device versions bootloaderVer Bootloader Version
device versions umiVer UNKNOWN
device versions softwareVer Software Version
device - _rawData Raw preferences data as json
device - mac Mac address of the robot
device - name Name of the robot
device - type Type of the robot
states - - Status information
states - _connected Connection state
states - battery Battery level of the robot
states - binFull State whether bin status is full
states - binInserted State whether bin is inserted
states - docked State whether robot is docked
states - signal Signal strength
states - status Current status of the robot
statistics - - Statistic Information
statistics missions - Mission Statistics
statistics missions failed Number of failed cleaning jobs
statistics missions succeed Number of successful cleaning jobs
statistics missions total Number of cleaning jobs
statistics time - Time Statistics
statistics time avgMin UNKNOWN
statistics time hOnDock UNKNOWN
statistics time nAvail UNKNOWN
statistics time estCap UNKNOWN
statistics time nLithChrg UNKNOWN
statistics time nNimhChrg UNKNOWN
statistics time nDocks UNKNOWN
- - refreshedDateTime DateTime of last update
- - refreshedTimestamp Timestamp of last update

Description of Preferences (incomplete)

The following payload will be received when calling getPreferences() (see https://github.com/koalazak/dorita980#getpreferences):

Object Index Type Description ioBroker State
netinfo - object Network Information of the Roomba connection -
netinfo .dhcp boolean State whether DHCP is activated device.network.dhcp
netinfo .addr ip IP address device.network.ip
netinfo .mask ip Subnet adress device.network.subnet
netinfo .gw ip Gateway address device.network.gateway
netinfo .dns1 ip Primary DNS address device.network.dns1
netinfo .dns2 ip Secondary DNS address device.network.dns2
netinfo .bssid mac Mac address of router device.network.router
netinfo .sec integer Unknown (not mapped)
wifistat - object Unknown -
wifistat .wifi integer Unknown (not mapped)
wifistat .uap boolean Unknown (not mapped)
wifistat .cloud integer Unknown (not mapped)
wlcfg - object Unknown -
wlcfg .sec integer Unknown (not mapped)
wlcfg .ssid string Unknown (not mapped)
mac - mac Mac address of Roomba -
country - string Unknown -
cloudEnv - string Unknown -
svcEndpoints .svcDeplId string Unknown -
mapUploadAllowed - boolean Unknown -
localtimeoffset - integer Unknown -
... - ... ... -

Please help me regarding the description of the preferences. If you know the meaning of preferences stated as unknown in the table, let me know their meaning via an issue!

Smart Home / Alexa integration using ioBroker.javascript

Send Map via Telegram when mission is finished

This requires the ioBroker adapter ioBroker.telegram to be installed (https://github.com/ioBroker/ioBroker.telegram).

Create a script in the "common" folder of ioBroker.javascript and add the following listener to it:

var _fs = require('fs');

/*
 * MISSION END: Send map
 * 
 */
var message = "%device.name% finished at %missions.current.endedDateTime% cleaning %missions.current.sqm% sqm in %missions.current.runtime% seconds (%missions.current.error% errors).";
var ns = 'roomba.0';
var imagePath = 'tmp/';

on({id: ns + '.missions.current.ended', change: 'any'}, function(obj)
{
    if (!obj.state || !obj.state.val) return;

    // replace variables with state values
    var pos, variable, state, value;
    while (message.indexOf('%') > -1)
    {
        pos = message.indexOf('%');
        variable = message.substring(pos, message.indexOf('%', pos+1)+1);
        state = getState(ns + '.' + variable.replace(/%/g, ''));

        if (state !== null && state.val !== null)
            value = state.val
        else
        {
            log('State ' + variable.replace(/%/g, '') + ' not found!', 'warn');
            value =  '';
        }

        if (typeof value === "boolean") value = value === true ? 'with' : 'no';
        message = message.replace(RegExp(variable, 'gi'), value);
    }

    // console
    log(message);

    // get image
    var img = getState(ns + '.missions.current.mapImage').val;

    if (img !== null && img.indexOf('data:image/png;base64,') > -1)
    {
        _fs.writeFile(imagePath + 'image.png', img.replace(/^data:image\/png;base64,/, ''), 'base64', function(err)
        {
            if (err !== null)
                log(err.message, 'warn');
            else
                sendTo('telegram', {text: imagePath + 'image.png', message: message});
        });
    }
});

2019-05-04 fixed error that prevented sending the map

You may edit the variable message to any notification you would like to receive with the map. You may use %name-of-state% to retrieve the value of a state within the ioBroker.roomba object tree.

Changelog

1.1.0 (2020-02-06)

1.1.0 (2020-02-06)

1.0.7 (2019-09-03)

1.0.6 (2019-08-19)

1.0.5 (2019-08-18)

1.0.4 (2019-08-15)

1.0.3 (2019-07-23)

1.0.2 (2019-07-20)

1.0.1 (2019-05-15)

1.0.0 (2019-05-04)

0.5.0 (2019-04-21)

0.4.5 (2019-03-20)

0.4.4 (2019-03-15)

0.4.3 (2019-02-10)

0.4.2 (2019-02-09)

0.4.1 (2019-02-03)

0.4.0 (2019-01-08)

0.3.x (2019-01-06)

0.3.0 (2019-01-06)

0.2.3 (2018-12-03)

0.2.2 (2018-12-02)

Note: If you are coming from an earlier version, you have to (1) empty your settings, (2) save, (3) restart the adapter and (4) enter / fetch credentials again (duo to the fact that password will be stored encrypted now)

0.2.1 (2018-11-25)

0.2.0 (2018-11-18)

0.1.0 (2018-11-04)

Credits

unofficial API

Thanks to @koalazak for the unofficial iRobot Roomba 980 node.js library (SDK).

Icons

Icons made by Iconnice from www.flaticon.com is licensed by CC 3.0 BY

License

The MIT License (MIT)

Copyright (c) 2018-2019 Zefau zefau@mailbox.org

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.