Custom Home Assistant integration for PETLIBRO pet devices (feeders, fountains, litter boxes). Hub-based integration using the PETLIBRO cloud API, with real-time push over the vendor's MQTT broker and polling as a fallback.
Based on jjjonesjr33/petlibro — this is a maintained fork with additional features, bug fixes, and audit improvements. It is kept in sync with upstream (currently through upstream v1.3, September 2026). Original credit goes to @jjjonesjr33, @C4-Dimitri, and @FeliGoblin for the foundational work.
- Granary Smart Feeder (PLAF103) — V1 & V2, including the dual-tray model's left/right food level
- Space Smart Feeder (PLAF107)
- Air Smart Feeder (PLAF108)
- Polar Wet Food Feeder (PLAF109)
- Granary Smart Camera Feeder (PLAF203)
- One RFID Smart Feeder (PLAF301)
- Dockstream Smart Fountain (PLWF105)
- Dockstream RFID Smart Fountain (PLWF305)
- Dockstream 2 Smart Fountain — Plug-In (PLWF106)
- Dockstream 2 Smart Fountain — Cordless (PLWF116)
- Luma Smart Litter Box (PLLB001)
- Open HACS in Home Assistant
- Go to Integrations
- Click the three-dot menu → Custom repositories
- Add
https://github.com/dn5qMDW3/petlibroas an Integration - Install PETLIBRO from HACS
- Restart Home Assistant
- Go to Settings → Devices & Services → Add Integration and search for PETLIBRO
- Download the latest release
.zip - Extract
custom_components/petlibro/into your Home Assistantconfig/custom_components/directory - Restart Home Assistant
- Add the integration via Settings → Devices & Services
When adding the integration, enter:
- Region —
USorCN(server region for your account) - Email — your PETLIBRO account email
- Password — your PETLIBRO account password
To change the email or password later, use Reconfigure in the integration's three-dot menu, or Configure → Change login credentials. There is no need to remove and re-add the integration.
Note: PETLIBRO only allows one active session per account, and signing in elsewhere invalidates the others. If you keep the mobile app logged in, create a separate account for Home Assistant and share your devices to it — you can accept the invitation with the
petlibro.accept_shareservice.
- Real-time push — state changes arrive within about a second over PETLIBRO's MQTT broker, instead of waiting for the next poll. Polling continues in the background as a safety net (every 5 minutes while push is healthy, 60 seconds if it drops). No setup: no broker to configure and nothing to do with Home Assistant's own MQTT integration.
- Sensor entities for battery, water level, food level, weights, drinking statistics, etc.
- Switches for sound, light, child lock, deodorization, and other device toggles
- Notification switches — per-device alert toggles (offline, low battery, low water, filter and cleaning reminders, drinking trends, cleaning success/failure, motion and sound detection, and more), mirroring the mobile app's notification settings
- Buttons for manual feed, manual clean, lid open, timer resets, etc.
- Number inputs for volume, schedules, thresholds
- Selects for modes (clean mode, water dispensing mode, etc.)
- Device sharing — see pending invitations, and accept or decline them from Home Assistant
- Litter box cleaning schedules — view them, and add or remove them via services
- Litter box operation — an Operation sensor that says what the Luma is doing right now (idle, cleaning, leveling, emptying, paused, ending), with the raw action, state and progress as attributes
- Litter box air purifier and coverage settings — coverage assist, the fan speed of a manual purifier run, and whether and when a manual run turns itself off
- Litter box use per pet — today's visits, pee count and poop count on each pet, alongside the box-wide totals, plus the Luma's litter level
- Feeding schedule control — enable, disable, skip or delete individual feeding plans, and switch the whole schedule on or off, via services
- Firmware update notifications
- Multi-language support (14 languages)
- Account-level unit preferences (feed, water, weight)
Each entity uses a standard Home Assistant icon; the device's product picture appears on its firmware update entity.
See docs/API_REFERENCE.md for the full PETLIBRO Cloud API reference, and docs/MQTT_RESEARCH.md for how the push channel works (broker, certificates, topics and payloads). Both were last checked against PETLIBRO app 1.9.40 (October 2026); the reference lists what the app offers that the integration does not use yet.
| Service | What it does |
|---|---|
petlibro.add_feeding_plan |
Add a scheduled feed to a dry food feeder |
petlibro.edit_feeding_plan |
Change an existing feeding plan |
petlibro.toggle_feeding_plan |
Enable or disable one feeding plan |
petlibro.skip_feeding_plan |
Skip, or un-skip, one feeding plan for today |
petlibro.delete_feeding_plan |
Permanently remove a feeding plan |
petlibro.toggle_feeding_schedule |
Enable or disable a feeder's whole schedule |
petlibro.toggle_today_feeding_schedule |
Enable or disable all of today's feeds |
petlibro.accept_share |
Accept a pending device-share invitation |
petlibro.decline_share |
Decline a pending device-share invitation |
petlibro.share_device |
Invite another PETLIBRO account to a device you own |
petlibro.add_clean_plan |
Add a cleaning schedule to a litter box |
petlibro.delete_clean_plan |
Remove a cleaning schedule from a litter box |
Pending share invitations appear on the Pending share invitations binary sensor, with the invitation IDs in its attributes. When only one invitation is waiting, accept_share and decline_share can be called without arguments.
- Live camera feed — Granary Smart Camera Feeder (PLAF203) and Luma Smart Litter Box (PLLB001) use TUTK/Kalay P2P video which isn't currently feasible to integrate directly into HA. Help welcome.
Add to configuration.yaml:
logger:
default: warning
logs:
custom_components.petlibro: debugSettings → Devices & Services → PETLIBRO → ⋮ → Download diagnostics produces a file with the raw data PETLIBRO returns for each device and pet. Serial numbers, MAC addresses, Wi-Fi names, account details, tokens and image URLs are redacted, so it is suitable for attaching to an issue — and it is the quickest way to get a missing field or a new device supported.
After adding the integration, allow 1–5 minutes for all entities to populate. If entities are missing, restart Home Assistant.
- Login fails — Verify credentials and region. Code
1009means the token expired (auto-handled). Code1025means a force logout (someone else logged in to the same account). - Devices missing — Check your account on the PETLIBRO mobile app to confirm devices are bound. Shared devices appear with limited control.
- Empty values — Some devices return empty strings/null for unused fields. The integration filters these where possible.
- Luma "Device Error" turns on for a few seconds — The sensor mirrors PETLIBRO's
deviceStoppedWorkingflag, which the cloud sets briefly while the box is idle. The PETLIBRO app only uses it to grey out its Clean / Empty / Level buttons and shows no error, so a short blip is not a hardware fault. Until the cause is known (#1), have automations wait for the sensor to stay on — 15 minutes has been enough to avoid false alarms — instead of triggering on the first change. With debug logging enabled, the integration logs the raw device payloads each time the flag changes — those log lines are what the issue needs. - Real-time push not connecting — Check the Real-time push diagnostic sensor. Its attributes show the broker, the subscribed devices, the time of the last event, and the last error. Push is an optimisation: when it is unavailable the integration keeps polling, so devices still work, just less promptly.
For a richer dashboard experience, check out dn5qMDW3/petlibro-cards — custom Lovelace cards designed for this integration.
GPL-3.0 — same as upstream.
This integration is built on the work of:
- @jjjonesjr33 — original integration
- @C4-Dimitri — co-developer
- @FeliGoblin — co-developer
Original repo: https://github.com/jjjonesjr33/petlibro