Homebridge PetLibro 2

A Homebridge plugin that integrates PetLibro smart feeders and water fountains with Apple HomeKit, allowing you to trigger manual feeding sessions and monitor water levels directly from your iOS Home app. This is a fork from the original homebridge-petlibro plugin, updated to support multiple PetLibro devices.

Original repository: HomebridgeLibro

Features

• 🍽️ Manual Feeding: Trigger feeding sessions from your Home app
• 📱 HomeKit Integration: Works seamlessly with Apple's Home ecosystem
• 🔄 Momentary Switch: Switch automatically resets after feeding
• 🛡️ Robust Error Handling: Graceful failures that won't break Homebridge
• 🔐 Secure Authentication: Uses the same API as the official PetLibro app
• 🐾 Multi-Device Support: Automatically discovers and adds all feeders and fountains linked to your account
• 💧 Water Fountain Support: View water level of compatible water fountains in HomeKit
• 📶 Offline Detection: Apple Home shows "Not Responding" when PetLibro reports the device offline
• 🔒 Token Persistence: Auth token is cached across Homebridge restarts to reduce login traffic and avoid kicking the PetLibro mobile app out (single-session-per-account constraint)

Supported Devices

This plugin works with PetLibro devices that use the main PetLibro app (not PetLibro Lite):

Smart Feeders

• Granary Smart Feeder (PLAF103)
• Space Smart Feeder (PLAF107)
• Air Smart Feeder (PLAF108)
• Polar Wet Food Feeder (PLAF109)
• Granary Smart Camera Feeder (PLAF203)
• One RFID Smart Feeder (PLAF301)

Water Fountains

• Dockstream Smart Fountain (PLWF105)
• Dockstream RFID Smart Fountain (PLWF305)
• Dockstream 2 Smart Fountain - Plug-In Model (PLWF106)
• Dockstream 2 Smart Fountain - Cordless Model (PLWF116)

Installation

Option 1: Homebridge Config UI X (Recommended)

1. Search for "PetLibro" in the Homebridge Config UI X plugin store
2. Install the plugin
3. Configure using the web interface

Option 2: Command Line

npm install -g homebridge-petlibro-2

Configuration

Using Homebridge Config UI X

After installation, configure the plugin through the Homebridge web interface. You'll need:

• Your PetLibro account email
• Your PetLibro account password
• Number of portions to dispense (optional, defaults to 1)

Manual Configuration

Add the following to your Homebridge config.json in the platforms section:

{
  "platforms": [
    {
      "platform": "PetLibroPlatform",
      "email": "[email protected]",
      "password": "your-petlibro-password",
      "portions": 1,
      "timezone": "America/New_York",
      "country": "US"
    }
  ]
}

Configuration Options

| Option | Required | Default | Description | |--------|----------|---------|-------------| | platform | Yes | | Must be "PetLibroPlatform" | | email | Yes | | Your PetLibro account email | | password | Yes | | Your PetLibro account password | | portions | No | 1 | Number of portions per feeding (1-10) | | timezone | No | "America/New_York" | Your timezone | | country | No | "US" | Your country code — sent to PetLibro for login regional metadata; does not change which API endpoint is used | | fountainPollingInterval | No | 300 | Seconds between water level updates for fountains | | apiEndpoint | No | https://api.us.petlibro.com | Advanced: full base-URL override. PetLibro currently runs a single global endpoint; the mobile app uses it from every region |

Multi-Device Support

The plugin automatically discovers all PetLibro devices linked to your account:

• Feeders appear as switches in HomeKit - tap to trigger manual feeding
• Water Fountains appear as humidity sensors showing water level percentage
• Devices use their names from the PetLibro app
• New devices are added automatically on Homebridge restart
• Removed devices are automatically cleaned up

Water Fountain Notes

Apple Home has no native "fill level" characteristic. Water fountains are exposed as a HumiditySensor, which is the only sensor service Apple Home renders as a visible tile with a live percentage value.

• The percentage shown represents how full the water reservoir is (0-100%)
• Apple Home labels the tile as "Humidity" — the value displayed is the water level, regardless of label
• Third-party HomeKit apps (Eve, Controller for HomeKit) show the same value and can graph history
• Water level is updated periodically (default: every 5 minutes)
• You can adjust the polling interval with the fountainPollingInterval option

Migrating from earlier plugin versions that used a Battery service? Restart Homebridge once — the plugin strips the old Battery service from cached accessories and replaces it with a HumiditySensor automatically.

Important Setup Notes

Account Limitations

⚠️ PetLibro only allows one device to be logged into an account at a time.

Recommended Setup:

1. Create a second PetLibro account with a different email
2. In your main PetLibro app, share your feeder to the new account
3. Use the new account credentials in this Homebridge plugin

This allows both your mobile app and Homebridge to work simultaneously.

Verification Steps

Before configuring the plugin:

1. ✅ Verify your credentials work in the official PetLibro mobile app
2. ✅ Ensure you're using the main "PetLibro" app (not "PetLibro Lite")
3. ✅ Confirm your feeder is connected to WiFi and working normally

Usage

1. After configuration, your feeder will appear as a switch in the Home app
2. Tap the switch to trigger a manual feeding
3. The switch automatically turns off after 1 second (momentary behavior)
4. Check Homebridge logs to confirm feeding was successful

Troubleshooting

Authentication Issues

Problem: Plugin fails to authenticate

• ✅ Verify email/password work in the PetLibro mobile app
• ✅ Ensure only one device is logged into your PetLibro account
• ✅ Try creating a dedicated account for Homebridge (recommended)

Device Not Found

Problem: Plugin authenticates but can't find your feeder

• ✅ Confirm your feeder appears in the PetLibro mobile app
• ✅ Check that device sharing is set up correctly (if using separate account)
• ✅ Look at Homebridge logs for device discovery details

Feeding Not Working

Problem: Switch appears but feeding doesn't work

• ✅ Ensure feeder has food and is powered on
• ✅ Verify feeder connectivity in the PetLibro app
• ✅ Check Homebridge logs for API error messages
• ✅ Try manual feeding through the official app first

Common Error Messages

"Invalid account or password"

• Check credentials are correct
• Ensure no other device is logged into the account

"Device ID not found"

• Verify device sharing is configured properly
• Check that the feeder appears in your account

"Authentication failed: SYSTEM_ERROR"

• Usually indicates incorrect API credentials
• Verify you're using the main PetLibro app (not Lite)

Technical Details

This plugin uses the same API endpoints as the official PetLibro mobile application, reverse-engineered from the open-source HomeAssistant PetLibro integration.

API Endpoints Used

• Authentication: POST /member/auth/login
• Device Discovery: POST /device/device/list
• Manual Feeding: POST /device/device/manualFeeding
• Device Real Info: POST /device/device/realInfo (for water level)

Testing

Tests use Node's built-in node:test runner — no extra dependencies. Requires Node.js 18 or newer.

npm install
npm test

What's covered

• test/device-type.test.js — getDeviceType() classification: PLWF* serials and product names containing Dockstream/Fountain (case-insensitive) classify as fountains; everything else defaults to feeder. Includes coverage for alias field names (product_name, model, device_id, deviceId) returned by different firmware versions.
• test/region.test.js — resolveBaseUrl() precedence: apiEndpoint override > region > country-to-region mapping > US default. Verifies EU country codes (DE, FR, GB, …) route to the EU endpoint and unknown codes fall back to US.
• test/auth.test.js — hashPassword() produces RFC 1321 MD5; apiPost() retries once on PetLibro error code 1009 (NOT_YET_LOGIN) after re-authenticating; it sends only the token header (no Authorization: Bearer); authenticate() rejects when credentials are missing.
• test/debug-dump.test.js — debugDeviceDump flag emits exactly one dump line containing the raw device payload; default-off path emits nothing; passwords never leak into any log channel.
• test/offline.test.js — feeder setOn throws HapStatusError(SERVICE_COMMUNICATION_FAILURE) when device.online === false, succeeds when online or when the field is absent; fountain getWaterLevel throws when offline, returns the cached level when online, treats missing realInfo.online as still online.
• test/token-persistence.test.js — auth token round-trips to disk with mode 0600; expired or near-expired tokens are not restored; corrupt or missing files fall back silently; per-email hashing keeps multi-account installs separate and doesn't expose the email in the filename.
• test/request-id.test.js — generateRequestId() returns RFC 4122 UUID v4 strings and produces unique values across calls.

Running a single test file

node --test test/device-type.test.js

Filtering tests by name

node --test --test-name-pattern='1009' test/*.test.js

Adding tests

Test files live in test/, suffix .test.js. Internals not exported from index.js (getDeviceType, resolveBaseUrl, the classes) are reachable via require('..')._test — keep production consumers on the default Homebridge initializer.

Reporting Unsupported Devices

If your PetLibro device isn't detected, is detected as the wrong type, or doesn't behave correctly, the plugin can dump the raw JSON it gets back from PetLibro's /device/device/list endpoint. We use these payloads to add explicit detection rules for new models. The dump contains device metadata only (model, name, serial, firmware) — it does NOT include your account password or auth token.

Step 1 — Enable the debug dump

Homebridge Config UI X (recommended):

1. Open the Homebridge web UI.
2. Go to Plugins → PetLibro Smart Feeder & Fountain → Settings (gear icon).
3. Scroll to Debug: Dump Raw Device List and toggle it on.
4. Click Save.

Manual config.json:

Add "debugDeviceDump": true to your platform block:

{
  "platform": "PetLibroPlatform",
  "email": "[email protected]",
  "password": "your-petlibro-password",
  "debugDeviceDump": true
}

Step 2 — Restart Homebridge

• Config UI X: click the orange power icon in the top bar.
• CLI / systemd: sudo systemctl restart homebridge
• Docker: docker restart homebridge
• macOS Homebrew service: brew services restart homebridge

Step 3 — Capture the dump from the log

Where the log lives depends on your install:

| Install | Log location | |---|---| | Config UI X | Logs tab in the web UI | | Debian/Ubuntu (systemd) | journalctl -u homebridge -f | | Raspberry Pi (hb-service) | sudo hb-service logs or /var/lib/homebridge/homebridge.log | | macOS Homebrew | ~/Library/Logs/homebridge/homebridge.log | | Docker | docker logs -f homebridge | | Custom install | wherever your --log-path points; usually stdout |

Look for a line starting with [debugDeviceDump] Raw /device/device/list response: followed by a pretty-printed JSON array. To find it quickly:

# systemd
journalctl -u homebridge --no-pager | grep -A 200 '\[debugDeviceDump\]'

# log file
grep -A 200 '\[debugDeviceDump\]' /var/lib/homebridge/homebridge.log

# Config UI X: in the Logs tab, type [debugDeviceDump] in the search box

Copy everything from the opening [ of the JSON array to its matching closing ].

Step 4 — Scrub anything personal

The payload typically contains:

• ✅ Safe to share: deviceSn, productName, productIdentifier, productCode, model, deviceType, firmwareVersion, online, regional flags.
• ⚠️ May want to scrub: deviceName (whatever you named it in the PetLibro app — e.g. "Mittens' Feeder — Kitchen"), wifiSsid, room labels, anything you wouldn't want public.

Replace those fields with placeholders before pasting (e.g. "deviceName": "<redacted>"). The model and serial-number prefix are what we actually need.

Step 5 — File the issue

Open a GitHub issue using the Unsupported Device template and paste the scrubbed JSON into the code block in the template.

Step 6 — Turn the flag off

Once you've captured a dump, disable debugDeviceDump in the plugin settings (or remove the line from config.json) and restart Homebridge again. Left on, it logs the full payload on every restart, which bloats your log file over time.

What we do with the payload

We use the productName / productIdentifier / deviceSn prefix fields to add an exact-match rule to getDeviceType() and a per-model entry to the device matrix in docs/plans/2026-06-18-device-expansion.md. Most models tend to work today via the existing prefix routing (PLWF* → fountain, everything else → feeder); the dump just lets us confirm that and ship explicit handling.

Contributing

Found a bug or want to contribute?

1. Check existing issues
2. Create a detailed bug report with:
   • Homebridge logs
   • Device model
   • Configuration (without credentials)
3. Test that your feeder works with the official PetLibro app

Legal Disclaimer

⚠️ This is an unofficial plugin, not affiliated with PetLibro.

• Use at your own risk
• API endpoints may change without notice
• Check PetLibro's Terms of Service before use
• The plugin is reverse-engineered from publicly available information

License

MIT License - see LICENSE file for details.

Acknowledgments

• Based on the HomeAssistant PetLibro integration by jjjonesjr33
• Built for the Homebridge platform

Enjoying this plugin? ⭐ Star the repository