Features

• Roomba start on demand
• Roomba stop and dock on demand
• Roomba charging status
• Roomba battery level (with low battery warning)
• Roomba docked notifcation
• Roomba running notification
• Roomba bin full notification

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

Installation

Automatic Installation

1. Install Homebridge: sudo npm i -g homebridge --unsafe-perm
2. Download this plugin: sudo npm i -g homebridge-roomba2
3. Follow Setup to get Roomba credentials
4. Add an Accessory for your Roomba and configure it using Config-Ui-X
5. Restart Homebridge

Manual Installation

1. Install Homebridge: sudo npm i -g homebridge --unsafe-perm
2. Download this plugin: sudo npm i -g homebridge-roomba2
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-roomba2
4. Type sudo npm run getrobotpwd <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 Config-Ui-X. You can alsoconfigure your accessory using JSON:

{
  "accessory": "Roomba2",
  "name": "Roomba",
  "model": "960",
  "blid": "1234567890",
  "robotpwd": "aPassword",
  "ipaddress": "192.168.x.xxx",
  "dockContactSensor": true,
  "runningContactSensor": true,
  "binContactSensor": true,
  "dockOnStop": true
}

Deprecated configuration

The homebridge-roomba2 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 soas 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.

Building

The homebridge-roomba2 plugin uses TypeScript, pnpm andnvm.

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

Use nvm to select the required node version:

nvm use

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

nvm install

Install pnpm, if you haven't already:

npm -g install pnpm

Prepare the project:

pnpm install

Build the project:

pnpm build

or

pnpm watch

Contributing

The homebridge-roomba2 plugin uses Changesets to maintain the CHANGELOG.md and to bump the package's version number according to semer.

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:

pnpm 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.

Credits

STVMallen - Original plugin

ncovercash - Dock status