Reverse-Engineering a Smart Cat Litter Box for Home Assistant

When we bought a new Furrytail smart automatic litter box for our cats, it immediately solved the manual scooping problem. But smart home hardware is only as smart as its ecosystem integration.

I had a specific automation in mind: every time our cats used the litter box 3 times, our robot vacuum should automatically trigger a spot-clean around the litter box enclosure.

The roadblock: Furrytail had no official Home Assistant integration, no public API documentation, and ran on a proprietary IoT cloud backend (Granwin / 吾尾 cloud, rather than standard Tuya).

To make the automation a reality, I reverse-engineered the mobile app traffic using mitmproxy and built a custom Home Assistant integration: hass-furrytail.

---

1. Intercepting the Traffic with mitmproxy

To understand how the mobile app communicated with the litter box, I routed my phone’s network traffic through a local proxy:

1. Proxy Setup: Ran mitmproxy on my local machine and configured the Wi-Fi HTTP proxy settings on my iPhone to point to my workstation on port 8080.
2. CA Certificate Installation: Installed the mitmproxy root certificate authority profile on the iOS device and enabled full SSL trust in Certificate Trust Settings.
3. Traffic Inspection: Opened the Furrytail Home app, triggered a manual cleaning cycle, inspected device telemetry, and watched the HTTP requests stream into the proxy console.

[Mobile App] ──(HTTPS via mitmproxy CA)──> [mitmproxy :8080] ──> [app.prod-iot.furrytail.net]
                                                 │
                                           Captured Schemas:
                                           - POST /app/user/login
                                           - POST /app/device/status
                                           - POST /app/record/visit

---

2. Reverse-Engineering the API

The app communicated with an IoT endpoint at app.prod-iot.furrytail.net. Through inspecting the request bodies and headers, I mapped out the core communication protocol:

• Authentication (POST /app/user/login): Required a specific merchantId header alongside the user credentials, returning a bearer session token.
• Single-Session Constraint: Furrytail enforces a strict single active session per account. Logging into Home Assistant immediately logged out the phone app. The workaround was creating a second dedicated email account, adding it as a family member to the Home in the mobile app, and using those credentials exclusively for Home Assistant.
• Telemetry & State Polling: The cloud returns rich real-time state:
  • Current machine state (idle, cleaning, emptying, leveling).
  • Last visit timestamp, visit duration, and cat weight.
  • Granular pet profiles and night-light brightness controls.

---

3. Building the Home Assistant Integration

With the endpoints documented, I wrote hass-furrytail as a native custom component:

1. Config Flow UI: Implemented config_flow.py allowing users to configure the integration directly from the Home Assistant UI without touching configuration.yaml.
2. DataUpdateCoordinator: Set up asynchronous polling every 2 minutes via coordinator.py to retrieve device health and historical visit telemetry.
3. Entity Architecture:
   • Binary Sensors: Cleaning cycle active, device online.
   • Sensors: Total visit count, last visit duration, pet weight, and firmware versions.
   • Controls: Command buttons for manual clean, litter flattening, and dimmable night-light switches.

---

4. The 3-Visit Vacuum Automation

With live sensors exposed in Home Assistant, building the targeted cleaning routine was straightforward:

1. Counter Helper: Created a helper counter counter.cat_litter_visits that increments each time the litter box records a completed visit.
2. Threshold Trigger: When counter.cat_litter_visits reaches 3:
   • Send a command to the robot vacuum to navigate to the litter box coordinates and run a localized sweep.
   • Reset counter.cat_litter_visits back to 0.
3. Safety Condition: Ensured the vacuum only triggers when the litter box state is idle and no cat is currently inside the enclosure.

---

Open Source & Next Steps

The complete custom component is open-source and installable via HACS (Home Assistant Community Store):

Repository: github.com/CamiloValderruten/hass-furrytail

This project is a reminder of why open platforms like Home Assistant matter. Even when consumer IoT devices are locked inside proprietary clouds, a bit of network inspection and clean Python integration can bring complete local automation back under your control.