homebridge-roomba

@homebridge-plugins/homebridge-roomba">@homebridge-plugins/homebridge-roomba" >
@homebridge-plugins/homebridge-roomba">@homebridge-plugins/homebridge-roomba?label=downloads" >

Features

• Roomba start on demand
• Roomba stop and dock on demand
• Roomba charging status
• Roomba battery level (with low battery warning)
• Roomba docked notification
• Roomba running notification
• Roomba bin full notification
• Find Roomba (Identify Function, supported in 3rd Party HomeKit apps)

The homebridge-roomba plugin polls Roomba for its status when requested by HomeKit, so when you first open
the Home app you may see an old status, or no status, until Roomba has had time to respond (which may take
a few seconds).

Installation

1. Use the Homebridge UI’s Plugins screen to search for and install “homebridge-roomba”
2. Follow Setup to get Roomba credentials and to configure your Roomba
3. Restart Homebridge

Manual Installation

1. Install Homebridge: sudo npm i -g homebridge --unsafe-perm
2. Download this plugin: sudo npm i -g @homebridge-plugins/homebridge-roomba
3. Follow Setup to get Roomba credentials
4. Enter Roomba’s credentials in your config.json file.
5. Restart Homebridge

Setup

1. Find your Roomba’s IP address (for help see the troubleshooting section); it will look like 192.168.X.XXX or 10.X.X.XXX, or similar.
2. Open a terminal on your Homebridge system, either using ssh or by using the Homebridge Terminal located in the ⋮ menu, top-right in the Homebridge UI.
3. Change into the directory where the plugin is installed: cd $(npm root -g)/homebridge-roomba
4. Type npm run roomba:getpassword <IP ADDRESS> (replacing <IP ADDRESS> with the IP address you discovered above).
5. Follow the instructions on screen to obtain your Roomba’s blid and password. NB: Read the instructions carefully and ensure that you’re pressing and holding the correct button on your Roomba.
6. Proceed to Configuration.

Configuration

This plugin supports GUI-based configuration using Homebridge UI, which is the recommended
approach for configuring your Roomba.

Manual configuration

Here is example JSON for configuring a Roomba accessory:

{
  "accessory": "Roomba",
  "name": "Roomba",
  "model": "960",
  "blid": "1234567890",
  "robotpwd": "aPassword",
  "ipaddress": "192.168.x.xxx",
  "dockContactSensor": true,
  "runningContactSensor": true,
  "binContactSensor": true,
  "cleanBehaviour": "rooms",
  "mission": {
    "ordered": 1,
    "pmap_id": "ab1cd_eFGhiJklMN2PqRsT",
    "regions": [
      {
        "region_id": "1",
        "type": "rid",
        "params": {
          "noAutoPasses": true,
          "twoPasses": true
        }
      }
    ],
    "user_pmapv_id": "220101T120101"
  },
  "stopBehaviour": "home"
}

Cleaning Mission configuration

This plugin can instruct the Roomba to clean everywhere or go on a specific cleaning job when started. Follow these steps to get the mission configuration values from the iRobot app.

1. Select the rooms you want to clean in the iRobot app, start the cleaning job, then close the iRobot app.
2. Open a terminal on your Homebridge system, either using ssh or by using the Homebridge Terminal located in the ⋮ menu, top-right in the Homebridge UI.
3. Change into the directory where the plugin is installed: cd $(npm root -g)/homebridge-roomba
4. Type npm run roomba:getlastcommand <BLID> <PASSWORD> <IP ADDRESS> (replacing <BLID> <PASSWORD> <IP ADDRESS> with the values for your robot).

Note: Modifying the map (Room Dividers, Names or Zones) in the iRobot app will result in a new user_pmapv_id value and may result in new region_id values that will cause an error if not updated in mission configuration.

Deprecated configuration

The homebridge-roomba plugin used to support keep-alive and auto refresh modes for obtaining Roomba’s status.
Both of these modes required more resources from Homebridge and Roomba than were necessary.

Now the plugin efficiently queries Roomba’s status on demand so as not to slow down Homebridge and so
as to provide HomeKit with Roomba’s status only when it requests it.

Troubleshooting

Click on any of the items below to expand the corresponding answer.

Finding my Roomba’s IP address

> You can find your Roomba’s IP Address in the iRobot app. Open the app and choose your Robot. Scroll down to the bottom and find Robot Settings. Click Wi-Fi Settings and then Robot Wi-FI Details. You will find your IP address and various other network goodies here.



> Alternatively you can open up your Router Admin Panel and look for a list of devices. Once you identify the Roomba, you should see an associated IP address, however, this process will be different for each type of router.

> While identifying your Roomba’s IP address, we strongly recommend assigning your Roomba a Static IP Address (See Roomba cannot be found after router restart OR Roomba’s IP Address changed below).

Building

The homebridge-roomba plugin uses TypeScript and
nvm.

nvm is used to control the version of node used. You can skip the nvm step if you manage your own
node versions.

Use nvm to select the required node version:

nvm use

or, if you don’t have the required node version installed:

nvm install

Prepare the project:

npm install

Build the project:

npm run build

or

npm run watch

Testing

The fastest way to test changes is to copy the built product directly to your Homebridge, and then to restart Homebridge.

If your Homebridge is running on your local machine, you can build (as above) and then copy the config.schema.json file and dist
folder to the homebridge-roomba folder in your Homebridge’s node_modules folder.

If your Homebridge is running on another machine, you can use a remote copy tool such as scp to copy the files:

npm run build && scp -r config.schema.json package.json dist user@host.local:/usr/lib/node_modules/homebridge-roomba/

Note: the destination path above is an example of what the path to node_modules on your Homebridge server might be.

If you see “Permission denied” errors from scp you will need to adjust the permissions on the files in that folder
on your Homebridge machine.

Contributing

The homebridge-roomba plugin uses Changesets to maintain the CHANGELOG.md and to bump the package’s version number according to semver.

If you are preparing a PR, please consider using Changesets to include a summary of your change for the CHANGELOG.md, following the example of existing changelog entries (but feel free to provide more detail).

To create a new changeset:

npm exec changeset

That will prompt you to indicate whether your change is a patch (a bug fix) or a minor or major change. If you are adding a feature it is a minor change, not a patch.

Changesets will create a new file in the .changeset directory that you can commit as part of your PR.

.git-blame-ignore-revs

Some revisions in the git history are spurious in a git blame, such as linting the code base.
These revisions are listed in .git-blame-ignore-revs. You can configure your local git repository
to use this file to skip these revisions in a blame:

git config blame.ignoreRevsFile .git-blame-ignore-revs

config.schema.json

Useful references for the config.schema.json:

• https://github.com/oznu/homebridge-config-ui-x/wiki/Developers:-Plugin-Settings-GUI
• https://github.com/hamzahamidi/ajsf
• https://github.com/json-schema-form/angular-schema-form/blob/master/docs/index.md

Releasing

The maintainer will run these steps to update the plugin version and publish to npmjs.com:

npm exec changeset version

Review the additions to CHANGELOG.md and package.json, commit with the comment “vX.X”, and then publish:

npm exec changeset publish

Credits

STVMallen - Original plugin

ncovercash - Dock status