homebridge-litter-robot-5

A Homebridge plugin that exposes the Whisker Litter-Robot 5 (standard model) to HomeKit.

Heads up: This plugin talks to Whisker's unofficial, reverse-engineered cloud API (via the nodelitterbot library). There is no public Whisker API — so this can break if Whisker changes their backend. It is not affiliated with or endorsed by Whisker.

What it exposes

Each Litter-Robot 5 becomes one HomeKit accessory; all of the controls below are services grouped under that one accessory.

| Control | HomeKit type | Notes | | --- | --- | --- | | Litter Drawer | Filter Maintenance | Waste-drawer level as a "filter life" %. | | Drawer Fullness / Litter Level | Humidity Sensor | 0–100% glanceable tiles with history graphs. | | Waste Drawer Full | Occupancy Sensor | Trips when the drawer is full. Notifiable. | | Needs Attention | Occupancy Sensor | Trips on a fault / stuck cycle. Notifiable. Driven by an external monitor if alertStatePath is set, else by the plugin's own detection. | | Cat Occupancy | Occupancy Sensor | Cat present / cycle in progress (weight-based — see note). Has a short decay to avoid flicker. | | <Pet> Weight | Humidity Sensor | One accessory per pet on the account, showing its weight (HAP has no weight type). Read-only. | | Night Light | Lightbulb (color) | On/off + a color wheel that maps to the globe's color. (No brightness slider — see note.) | | Night Light Auto | Switch | Globe light-sensor mode; on = Auto, off = Always On. | | Display | Lightbulb | Front-screen brightness, snapping to Low / Medium / High. (No off — the screen is always on.) | | Keypad Lock | Switch | Locks the buttons on the unit (a child-/cat-lock); on = locked. | | Clean Cycle | Switch (momentary) | Starts a clean cycle, then resets. | | Power | Switch | Powers the unit on/off. Off by default. | | Sleep Mode | Switch | Toggles sleep mode. Off by default. |

About the standard Litter-Robot 5

This targets the standard LR5, not the Pro:

• No camera accessory — the standard LR5 exposes no stream.
• Cat detection is weight-based (SmartScale), not camera-AI (a Pro/Whisker+ feature).
• The Night Light has no brightness control: on this hardware the brightness value shifts the apparent color, not luminance, so only the color wheel is exposed.
• The front screen's color isn't separately controllable (the device exposes only one color field) — just its brightness.

Requirements

• Node.js ≥ 24 — required by the nodelitterbot dependency.
• Homebridge v1.8+ or v2.

Installation

Search for Litter-Robot 5 in the Homebridge UI, or:

npm install -g homebridge-litter-robot-5

Configuration

Use the Homebridge UI (recommended), or add a platform block to config.json:

{
  "platforms": [
    {
      "platform": "LitterRobot5",
      "name": "Litter-Robot 5",
      "email": "[email protected]",
      "password": "your-whisker-password",
      "pollingInterval": 30,
      "occupancyDecay": 30
    }
  ]
}

| Option | Default | Notes | | --- | --- | --- | | email / password | — | Whisker account credentials. Required. | | pollingInterval | 30 | Seconds between cloud polls per robot (min 15). | | occupancyDecay | 30 | Seconds occupancy stays "detected" after activity clears. 0 disables. | | enable… toggles | mostly on | Show/hide each control. Power and Sleep default off. | | excludedSerials | [] | Serials to hide from HomeKit. | | robots | [] | Per-unit overrides — see below. |

Per-unit overrides

The enable… toggles are global defaults. To customize a single unit, add an entry under Per-Unit Overrides (robots) identifying it by serial or name, and set only the toggles you want to differ — anything left unset inherits the global default.

"robots": [
  { "name": "Attic Litterbox", "enablePowerSwitch": true, "enableSleepSwitch": false }
]

The name match uses the Whisker account nickname, not a name you've changed in the Home app. Serial is the unambiguous identifier.

Recommended: run as a child bridge

Run this plugin as a child bridge (toggle in the Homebridge UI) so a cloud hiccup is isolated from the rest of Homebridge.

How it works

• One shared Whisker session; each robot is polled on its own loop (default 30s) with backoff.
• HomeKit reads are served from the last poll — characteristic reads never hit the network, so HomeKit polling can't rate-limit your account.
• The Cognito token is cached under the Homebridge storage path (litter-robot-5-tokens.json, mode 0600) so restarts refresh rather than re-login. Credentials and tokens are never logged.
• Settings writes (night light, keypad lock, screen) are sent as direct PATCHes because the API returns an empty-bodied success response that the library otherwise mishandles, and because the night-light mode must be title-cased.

External monitor (advanced, optional)

The plugin's Needs Attention and Waste Drawer Full sensors can be driven by an external process instead of the plugin's own detection. Set alertStatePath to a JSON file of the form:

{ "<robot-serial>": { "drawerFull": false, "needsAttention": false, "stuckCycle": false, "updatedAt": 1717700000000 } }

If the file exists and the entry is fresh (updatedAt within 5 minutes), the plugin uses those determinations; otherwise it falls back to its own. The file must be readable by the user Homebridge runs as. This is how a richer, safety-aware monitor (which can also auto-recover faults — something the plugin deliberately won't do) feeds HomeKit.

On running two pollers (by design). With such a monitor you have two independent pollers on one Whisker account. This is intentional: the published plugin must self-poll to work standalone, the monitor owns all safety-critical auto-recovery, and user commands write directly from the plugin for responsiveness — so neither side can be a pure reader of the other. To keep the combined load polite, the plugin's default poll is a relaxed 45s, and if the monitor adds a top-level "__cloud": { "degraded": true, "updatedAt": … } to the alert file (e.g. when it sees the cloud throttling), the plugin honors it and widens to degradedPollingInterval until it clears (disable via cloudHealthHint: false). Full state-snapshot consolidation was evaluated and deliberately rejected — it would re-derive every device-field mapping in a second place, multiplying drift risk for no meaningful load reduction.

Local extensions (advanced, optional)

The plugin does not ship any control that clears faults (that affects a safety feature). If you want to add install-specific services — e.g. a manual fault-reset switch — set enableLocalExtensions: true and drop a file named litter-robot-5-extensions.cjs in your Homebridge storage path. On startup the plugin loads it (only when the flag is on) and calls its hook for each accessory. Because it lives in the storage path (not node_modules), it survives plugin updates.

// <storage path>/litter-robot-5-extensions.cjs  — local only, not part of the package
module.exports.applyAccessory = function ({ api, accessory, robot, log }) {
  const { Service, Characteristic } = api.hap;
  const svc = accessory.getServiceById(Service.Switch, 'remote-reset')
    || accessory.addService(Service.Switch, 'Reset Errors', 'remote-reset');
  const on = svc.getCharacteristic(Characteristic.On);
  on.onGet(() => false);
  on.onSet(async (v) => {
    if (!v) return;
    try { await robot.reset(); } catch (e) { log.warn('reset failed: ' + e.message); }
    finally { setTimeout(() => svc.updateCharacteristic(Characteristic.On, false), 800); }
  });
};

Only place a file here that you wrote/trust — it is executed as part of Homebridge.

Known limitations

• Built on an unaudited, reverse-engineered library; the underlying API can change without notice.
• nodelitterbot logs some errors directly to the console (unprefixed) on a failed write or unexpected value.
• "Stuck" detection is conservative: the fault sensor uses live signals and ignores the device's latched fault register, which is prone to false positives.

Credits

Built on nodelitterbot. Litter-Robot and Whisker are trademarks of their respective owners.

License

MIT