Litter-Robot smart home integration, free and open source
Whisker Litter-Robot 3 and 4, Feeder-Robot: drawer, litter, cat visits, cleaning.
Published by guim31
- Devices
- Version 1.0.1
- Requires Gladys >=5.1.0
- ★ 0
Follow your Whisker self-cleaning litter boxes and feeder from Gladys: the Litter-Robot 3 Connect, the Litter-Robot 4 and the Feeder-Robot. See when the waste drawer must be emptied, when the cat last went (and what it weighs, on a Litter-Robot 4), be warned of a fault, and start a cleaning or dispense a portion from the dashboard or a scene.
The integration uses the Whisker cloud, with the account of the Whisker app, like the app itself and like the Home Assistant integration. It is not affiliated with Whisker: Litter-Robot, Feeder-Robot and Whisker are trademarks of their owner.
Developed without the hardware: feedback welcome. This integration was built and tested against the real answers of the Whisker cloud published by the pylitterbot library and by Home Assistant, not against a real robot. If something does not work as described, please say so on the Gladys forum or in the issues.
What you need
- Gladys Assistant 5.1.0 or later, with access to the internet.
- A Litter-Robot 3 Connect (the Wi-Fi model), a Litter-Robot 4 and/or a Feeder-Robot, already set up in the Whisker app.
- The e-mail and password of that Whisker account. An account that asks for a second factor at sign-in is not supported: sign in once in the app first.
The Litter-Robot 5 and the Litter-Robot 3 without Wi-Fi are not supported.
Set up
- Install the integration from the Gladys catalog.
- In Configuration, enter the E-mail and the Password of your Whisker account, then save.
- Click Test the connection: the message under the button lists the robots found on the account, with their state.
- Open the Discover tab: one device per robot. Click Add, pick a room, save.
Options:
- Refresh interval: how often the robots are read from the Whisker cloud, 2, 5 (default), 10 or 15 minutes. A Litter-Robot 4 and a Feeder-Robot also send their changes live; a Litter-Robot 3 is only read at this interval.
- Weight unit: kilograms or pounds, for the cat weight in the widget.
- Feeder-Robot: portions per day: the most portions Gladys may dispense over 24 hours (4 by default, a minute apart at least). See Actions.
- Language of the feature names: English, French (default), German or Spanish. The names are given when a device is added; the robot states and the messages of the scenes follow this language too.
The password is sent only to Whisker's sign-in service (Amazon Cognito). The integration keeps the session tokens it receives in its private storage, so that a restart does not sign in again with the password.
The devices
Litter-Robot 3 Connect
| Feature | What it is |
|---|---|
| Status | The state in words: Ready, Cleaning in progress, Drawer full… |
| Waste drawer | How full the drawer is, in %, from the cycles counted since emptied |
| Cycles since emptied | Cleaning cycles since the drawer counter was last reset |
| Start cleaning | Button: starts a cleaning cycle now |
| Reset drawer gauge | Button: tells the robot the drawer was emptied (counter to zero) |
| Cleaning delay | Minutes between the cat leaving and the cleaning: 3, 7 or 15 |
| Night light | Switch: the night light on or off |
| Panel lock | Switch: locks the buttons of the robot |
| Sleep mode | Whether a sleep period is set (read only) |
| Last visit | Date and time of the last cat visit seen by the integration |
Litter-Robot 4
| Feature | What it is |
|---|---|
| Status | The state in words |
| Waste drawer | How full the drawer is, in %, as the robot measures it |
| Litter level | The litter level in the globe, in % |
| Cat weight (g) | The last weight the robot recorded, in grams (SmartWeight) |
| Cleaning cycles (total) | Every cleaning cycle since the robot was set up |
| Start cleaning | Button: starts a cleaning cycle now |
| Cleaning delay | 3, 7, 15, 25 or 30 minutes |
| Night light mode | Off, On or Automatic |
| Panel lock | Switch: locks the buttons of the robot |
| Sleep mode | Whether a sleep period is set on at least one day (read only) |
| Last visit | Date and time of the last cat visit seen by the integration |
Gladys has no unit of mass: the weight is a number of grams, the unit is in its name. Its history and the scenes ("weight below 3500") work as usual.
Feeder-Robot
| Feature | What it is |
|---|---|
| Status | Ready, Motor jammed, Chute full, On battery, Offline |
| Food level | The food left in the hopper, in % (by steps of the sensor) |
| Portions today | Portions dispensed since midnight, meals and extra portions |
| Last meal | Date, name and portions of the last meal or extra portion |
| Dispense a portion | Button: one portion now, within the daily limit |
| Automatic night light | Switch |
| Panel lock | Switch |
A robot that the Whisker cloud reports offline shows an "unreachable" badge in Gladys.
Dashboard
The Litter-Robot widget shows one litter box (the one chosen in its settings, else the first): the Drawer and Litter levels, the Visits today, its state, its Last visit and Last weight, and the buttons:
- Clean: starts a cleaning cycle (Gladys asks for confirmation first);
- Drawer emptied (Litter-Robot 3): sets the drawer counter back to zero.
Scenes
Triggers
- Cat visit: a cat used the Litter-Robot. The integration sees it when the robot starts its countdown before cleaning, or, if that moment fell between two readings, when the cycle counter moves (a cleaning started by Gladys does not count). Filter: the robot. Information for the scene: Robot name, Last weight recorded (kg) and (lb) (Litter-Robot 4), Visits today.
- Waste drawer full: the robot reports its drawer full, once per filling. Information: Robot name, Drawer level (%).
- Robot error: a robot reports a fault or goes offline. Filters: the robot and the kind of error (globe motor fault, pinch detected, cat sensor fault, bonnet removed, robot offline, feeder motor jammed). Information: Robot name, Kind of error (code), Error, in words.
Actions
- Start a Litter-Robot cleaning: starts a cycle now. Refused while the robot detects a cat.
- Dispense a Feeder-Robot portion: one portion now. To protect your cat from a scene that loops, Gladys dispenses at most the number of portions set in the configuration over 24 hours, and never two within a minute. Beyond that, the action does nothing and says so: its result Portion dispensed is then "no", and Portions left (24 h) tells how many remain. The meals planned in the Whisker app are not counted.
Scene ideas
- Empty the drawer: trigger Waste drawer full → send a message "The litter box drawer is full, it's your turn!".
- Watch the cat's health: trigger Cat visit → condition Visits today greater than 8 → notify, an unusual number of visits can mean a urinary problem. Or a scene on the Cat weight (g) feature: below 3500 → notify.
- Clean while nobody is home: trigger "everyone left" → action Start a Litter-Robot cleaning.
- Fault alert: trigger Robot error with kind Globe motor fault or Pinch detected → message with Error, in words.
Refresh, quotas and privacy
- The robots are read every few minutes (the Refresh interval), plus one reading a few seconds after a command; every robot family is listed again once an hour to find a robot added to the account. A Litter-Robot 4 and a Feeder-Robot are followed live through the subscription the Whisker app uses.
- Whisker publishes no quota nor terms for this API, which is the one of its app; the integration stays at the pace of the Home Assistant integration (5 minutes by default) and stops trying after a refused password or when Whisker throttles the account (15 minutes).
- Stored in the integration's private storage: the session tokens, a hash of the e-mail, the visits of the day and the portions dispensed by Gladys. Never the password; the logs never contain the password, the e-mail nor a token.
Troubleshooting
- "E-mail or password refused by Whisker": check them in the Whisker app, then save the configuration again. After a refusal, the integration does not try again by itself: save the configuration or click Test the connection.
- "Your Whisker account asks for an extra step": sign in once in the Whisker app (new password, verification code), then test the connection.
- "The Whisker cloud does not answer": an internet or Whisker outage; the integration tries again at the next refresh.
- No device in the Discover tab: click Test the connection; the account must be the one where the robots are set up (not a shared account).
- A visit or a state comes late: a Litter-Robot 3 is only read at the refresh interval; lower it to 2 minutes.
- More details: set
LOG_LEVEL=debugon the integration and read its logs.
Limits
- Developed without the hardware: the commands follow pylitterbot and the Whisker app, but were not tried on a real robot.
- Only the Litter-Robot 3 Connect, the Litter-Robot 4 and the Feeder-Robot; no Litter-Robot 5, no pet profiles (the weight is the robot's last reading, not a weight per cat: with several cats, it is the last one in).
- The visits are the ones the integration saw since it was installed; it does not read the history of the Whisker app.
- The Litter-Robot 3 has no live updates here: it is read at the refresh interval.
- No sleep schedule nor meal schedule editing: use the Whisker app.
- The cloud is required: without internet, nothing can be read or controlled.
Configuration settings
These are the settings Litter-Robot asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your Whisker account | section | No | The account of the Whisker app, where your Litter-Robot 3 Connect, Litter-Robot 4 or Feeder-Robot is set up. The integration reads them through the Whisker cloud, like the app. Not affiliated with Whisker. |
string | Yes | The e-mail you sign in to the Whisker app with. | |
| Password | secret | Yes | The password of the Whisker app. Sent only to Whisker's sign-in service, never written to the logs. |
| Options | section | No | A Litter-Robot 4 and a Feeder-Robot send their changes live; every robot is also read again at the interval below. |
| Refresh interval | select | No | How often the robots are read from the Whisker cloud. The only source for a Litter-Robot 3. |
| Weight unit | select | No | For the cat weight in the widget (Litter-Robot 4). The device feature is in grams. |
| Feeder-Robot: portions per day | select | No | At most this many portions dispensed by Gladys over 24 hours, a minute apart, so a scene that loops cannot empty the hopper. The meals of the Whisker app are not counted. |
| Language of the feature names | select | No | Names given to the features when a device is added, and language of the robot states and of the scene messages. |
How to install Litter-Robot in Gladys
- In Gladys, open Integrations: Litter-Robot appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/guim31/gladys-litter-robot:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/guim31/gladys-litter-robot.
Litter-Robot requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Litter-Robot is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation