No module Published on Offcanvas position

Integrating iRobot Roomba with Domoticz

Category: Domoticz

I'm a firm believer of keeping all your stuff as centralized as possible. One portal to manage all your things instead of having a huge amount of apps and web portal links to manage everything.
Because I'm too lazy to do chores, I've been looking  for robot vacuums that integrate with Domoticz well. I've started with LG Hombots, i found they were cheaper compared to Roomba's back then.
And let me tell you... LG Hombots SUCK. To make a long story short, the WiFI hack works, but the interface for it crashes everyday and Domoticz won't be able to send commands when that happens forcing you to reboot the vacuum every single day.
And this is how I ended up with the better solution: Roomba, money well spent!

Much like the LG Hombot WIFI hack, someone took a lot of effort to create one for the Roomba's too! So all credits goes to them ofcourse for creating something this wonderfull. I'm just here to to summarize how to integrate it into your Domoticz system.
To use the integration you need three things installed:

  1. rest980 by Koalazak https://github.com/koalazak/rest980
  2. rest980-domoticz by damsma https://github.com/damsma/rest980-domoticz
  3. dorita980 by koalazak https://github.com/koalazak/dorita980

You'll be using nr. 3 mostly to get the BLID (which is like a username) and Password for your vacuum, afterwards you won't need it anymore unless you are planning to replace or get more vacuums in the future.
I personally created a seperate VM just to install it and turn it off once I have the information I need

The instructions for the installation are very easy to follow on each of the Github pages, but i'll sum it all up here for easier reading.

  1. Install dorita980 in either your own Domoticz machine or a seperate Linux VM.
    apt-get install npm nodejs
    npm install dorita980 --save
  2. For the next part, you need to know the IP address that is assigned to your Roomba.
    You can find the IP address in your router, the Roomba app under Robot Settings > Wi-Fi Settings or you memorized it because you set the IP to static during configuration
    Use the next command to get your BLID and Password
    npm install -g dorita980
    get-roomba-password <robotIP>

    According to the instructions you can also use dorita980.getRobotIP() to get the information if you do not know the IP, but I haven't used it myself so I couldn't really discribe the process. 

  3. On your Domoticz device itself, install rest980.
    git clone https://github.com/koalazak/rest980.git
    cd rest980
    npm install

  4. Open up the default.json file with your favorite text editor in config/default.json.
    There are 4 values that need to be changed in that file:
    - BLID
    - Password
    You should have gotten both from step 2
    - RobotIP, it's the IP address assigned to your Roomba. You should know it by know considering it was needed in Step 2
    - FirmwareVersion, in most cases it should be a 2. If you are unsure which version your Roomba is running on, you can check it in the app under Robot Settings > About Roomba
    even if you are running version 3, enter 2 here.

  5. To make sure rest980 always starts up when you reboot Domoticz, you are going to need PM2.
    If you don't have it yet, you can install it using:
    npm i -g pm2

    Once installed, use the following command to make sure it starts up on boot
    pm2 startup
pm2 start npm --name "rest980-roomba" -- start
pm2 save
  6. To test if the connection works between domoticz and your Roomba, use the following command:
    wget http://127.0.0.1:3000/api/local/action/start > /dev/null

    If it works, you should hear your Roomba starting up ready to clean.
    To return it back to it's charging station use the following command:

    wget http://127.0.0.1:3000/api/local/action/dock > /dev/null

    The 127.0.0.1 serveradress always refers to the server that has rest980 installed, it's not the roomba itself.

  7. Once you confirm it working, it's time to install the plugin in Domoticz and then restart the domoticz service to make it appear in the hardware list.

    cd domoticz/plugins
    git clone "https://github.com/damsma/rest980-domoticz.git
    systemctl restart domoticz

  8. Go to your Domoticz interface and go to Setup > Hardware. Create a new device and you'll notice you can now select iRobot Roomba (rest980-domoticz).
    All the settings are already prefilled correctly assuming rest980 is installed on the same device domoticz is installed, otherwise you need to change the IP address.

As far as I can see, the plugin only allows you to start cleaning and make it return to it's dock or just turn it off if you selected it in the hardware options.
Considering all the options that exist in rest980, I believe it's very doable to get the status of your Roomba and report it back into domoticz by leveraging the Domoticz API and writing the status back into variables.
I might have to do this myself one of these days so Domoticz can send me push notification to empty the dust bin.

Having more than one iRobot device

If you have multiple roomba's like me to clean other floors, then you'll find out soon enough that simply installing the REST980 on a machine or domoticz won't allow you add any other device.
To bypass this problem, you will have to use Dockers and create containers for each device you own. It's a bit more work, but not that much.

I'm not going to describe how to install Docker, there are tons of guides for that already online that you can find with some google-fu.
Once you have Docker installed you need to pull the docker image, you can do that with the following command:

docker pull koalazak/rest980

For each device you want to add, you'll need a different port, it starts at 3000 for the first device. Logic sense would dictate you would choose 3001, 3002 and so on, but that's completely up to you.
To make sure the container runs the moment you reboot the server and provide it with the correct settings, use the following command:

sudo docker run --name (name for your container) --restart always -e BLID=(BLID HERE)-e PASSWORD=(ROOMBA PASS HERE) -e ROBOT_IP=(IP HERE) -e PORT=(CUSTOM PORT) -e FIRMWARE_VERSION=2 -p (CUSTOM PORT):(CUSTOM PORT) koalazak/rest980:latest

Run this command as many times as you want for all your devices.
To test if your devices can be reached, use the following commands:

Start the roomba:

wget http://(docker server IP):(custom port)/api/local/action/start > /dev/null 

Dock the roomba:

wget http://(docker server IP):(custom port)/api/local/action/dock > /dev/null

From this point on you can go to Domoticz and add all your devices using the plugin. For server address you fill in the server that hosts your containers and the port number you have assigned to each device.