ha-rest980-roomba
Home Assistant - iRobot Roomba i7+ Configuration using rest980
This repository provides configuration to get an iRobot Roomba i7+ robot vacuum cleaner integrated with Home Assistant using the rest980 Docker Image!
Example Lovelace UI View
Setup Instructions
The instructions included below don't specifically contain testing/confirmation per step. Please complete all the steps before performing any validation testing.
NOTE: These instructions are written for the Roomba, but the same steps can be following for adding a Braava m6.
I have included example multi-map configuration for the Braava (as this is how my setup works in my apartment given the Braava does not traverse carpet), please refer the FAQ for more info on my Multi-Floor setup.
Step 1: Prerequisites
Before completing any of the below steps, you need to first configure your rooms/zones using the iRobot App!
The following custom components are used in this deployment - these can be installed from HACS
If you plan to leverage multiple maps, the following additional components are used
A working MQTT Server with discovery is also needed (in conjunction with the check-button-card for Maintenance items) https://www.home-assistant.io/integrations/sensor.mqtt/
Step 2: Get Robot Login Details
NOTE Do not have iRobot App running on your phone when doing this !!!
DOCKER
docker run -it node sh -c "npm install -g dorita980 && get-roomba-password <robotIP>"
HA ADDON
- Add the following Github Repository to your HA Add-on Store https://github.com/jeremywillans/hass-addons
- Locate and install the roombapw Add-on, following the included instructions.
OTHER If you dont have direct access to Docker you can clone and install the dorita980 package locally (requires git and node to be installed) - refer here for instructions
Step 3: Configure Vacuum Map Directory
To allow the map to be correctly produced, you will need to create a new vacuum directory. I have chosen to put this inside the HA configuration directory, but you can choose to put this elsewhere and update the configuration accordingly (if you are using HASS and referencing my hass-addons repo, please leave this at the default!)
Copy the contents of the Vacuum directory from Github into this folder.
Note: The image.php file will need updating, but this will be done after the setup is complete.
Step 4: Configure Docker / HA Add-on
I use docker compose for all my HA related images, but have also listed the docker run command (copied from the rest980 github page) I have also included an example PHP Docker Image which i use to host the map.
To allow this to work on Hass.io - I have created a custom github repository which can be added to Hass.io allowing the installation of the rest980 and nginx-php Docker Images (support arm and amd64 platforms)
Note: Docker Hub only hosts a amd64 version of rest980, I have configured the HA Addon (formerly HASS) to build the image locally so it works on RPi (armv7). If you don't use HA and want to run rest980 on a non-arm64 platform, you will need to build the image manually.
DOCKER-COMPOSE
Note: I use a separate docker bridged network which can be created with:
docker network create docker
DOCKER RUN
docker run -name rest980 -e BLID=myuser -e PASSWORD=mypass -e ROBOT_IP=myrobotIP -e FIRMWARE_VERSION=2 -p 3000:3000 koalazak/rest980:latest
docker run -name php-nginx -p 3001:8080 -v /<HA_CONFIG>/roomba:/app -e NGINX_WEBROOT=/app webhippie/php-nginx:latest
PORTAINER-IN-HASSIO
Confirm you can access the WebUI
http://<ip or fqdn of docker host>:<port>/api/local/info/state
HA ADDON
-
Add the following Github Repository to your HA Add-on Store https://github.com/jeremywillans/hass-addons
-
Install the rest980 addon, then update and save the configuration options
NOTE Rest980 Firmware option 2 implies 2+ (inclusive of 3.x)
-
Install and configure the php-nginx addon.
-
Start rest980 and php-nginx
Note There are two copies of each addon listed, these allow you to run a second robot (or braava), you do not need these if you only have 1 unit!
Alternative: You can also run these locally by creating a rest980 (or similar) folder within "addons/local" and then copying the contents from each folder on my hass-addons repository.
This will create a new local addon which you can install
Step 5: Get Room Details
- Initiate a Clean Rooms clean from the iRobot App, ensuring you note the order in which you select the rooms (room names are no longer shown in the api)
- Navigate to
http://<ip or fqdn of docker host>:<rest980port>/api/local/info/state - Look for the "lastCommand" section and copy down the following info, noting the order as this references what you selected in the app.
- regions (type "rid" is Room, type "zid" is Zone)
Note: If you recreate your map, you will need to repeat this process as the region_id's will most likely change!
Step 6: Configure Home Assistant Package and Secrets
The below are my configuration YAML files which uses the Packages feature in HA to keep all the separate components together.
I split off the regions into the secrets file to make it easier to manage for future updates (these will change if you update your floor plan from the iRobot app)
I have tried to map as many of the reported statuses, however I occasionally get an "Unknown" in the logs, if you work out another state, please post it up!
I have included notification options (with optional inclusion of the map for IOS users), these can be deleted from vacuum.yaml if not needed
Notes:
- Make sure you remove any trailing commas from the regions when copying them into the secrets file!
- The input_booleans and input_text entries all start with vacuum as this is used in the templates for correct mapping in lovelace
You will NEED to update the following items to match the rooms you have used
- Secret, Input Boolean and Input Text per room/zone
- Group "Vacuum_Rooms"
- Automation "Vacuum Add Rooms for Cleaning" Trigger entities
- Automation "Vacuum Remove Rooms for Cleaning" trigger entities
I have also included a sample copy of the Braava m6 Configuration, and an additional file that has extra items for multi-floor. Refer FAQ for more details on multi-floor setups.
Step 7: Configure Map Options
You will need separate map file for each robot and/or floor. For each map, please update the variables at the top of the image.php to align with your environment.
Specifically the log, rest980, token and timezone ones should be done now - the rest are best to update once a full clean has run (to populate the map)
You can create the long-lived HA Token from your HA Account Profile page.
Step 8: Configure Lovelace
I have used the below lovelace configuration, ensure the relevant custom components are installed, as listed in the prerequisites section
Note: This config is shown as the two cards uses
- Vertical Stack
- Picture Glance
The following file provides an example setup for the Braava m6 configured for multiple floors, more info on this can be found in the FAQ Document.
Note: This multi-floor card uses the custom add-ons state-switch and select-list-card as listed in the prerequisites.
You will NEED to update the following items to match the rooms you have used
- Input Boolean per room/zone
Step 9: Update Map Options
After you have run a clean cycle, the map should be populating however it is likely not quite sized correctly.
In the Vacuum directory (in HA Configuration), you will need to update the height, width, offset and flip options in the image.php file to correctly reflect your layout.
I have moved these as variables at the top of the file making it easier to update.
You will also need to replace the included floor.png file with an floor plan or similar file which is used as the background for the robot map.
Note: Once the vacuum has completed is clean, the image.php file references the latest.png file in the local vacuum directory so your changes wont be reflected upon refresh. Simply delete the "latest.png" file in the vacuum directory to force map regeneration each time (or run http://:/image.phpclear=true```)
Step 10: Create Vacuum Maintenance Sensors
You will need to create the Maintenance Sensors - simply expand the Maintenance dropdown in Lovelace and click the green check next to each item to create these. You might need to click on them twice to reset the time to zero.
Note: check-button-card is assuming you have MQTT Discovery enabled using the default discovery prefix of "homeassistant" If you have a different discovery prefix defined - such as "smartthings" - please add the following to each of the Maintenance Tasks in Lovelace
- entity: sensor.vacuum_maint_clean_brushes
severity:
- hue: '140'
value: 8 days
- hue: '55'
value: 10 days
- hue: '345'
value: 14 days
title: Brushes
type: 'custom:check-button-card'
discovery_prefix: smartthings <--------------- THIS
visibility_timeout: 10 days
Step 12: Update Recorder
To prevent the database from storing unessential data, the below provides an example of suggested exclusions you can add to your recorder component within your configuration.yaml file
recorder:
<existing code here, if any>
exclude:
entity_globs:
- sensor.vacuum_*
- automation.vacuum_*
entities:
- sensor.rest980
- camera.roomba
Step 13: Enjoy!
Support
Check the FAQ here!
Got questions? Please post them here.
In case you've found a bug, please open an issue on GitHub.
Disclaimer
This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with the iRobot Corporation, or any of its subsidiaries or its affiliates. The official iRobot website can be found at https://www.irobot.com
Credits
- Facu ZAK for creating dorita980 and rest980 !
- gotschi for creating the original Roomba Map PHP file !
- Ben Tomlin for creating the xiaomi-vacuum-card from which my roomba-vacuum-card is shamelessly derived from!
My Repos
ha-rest980-roomba | roomba-vacuum-card | hass-addons | event-emitter
