ESPHome Litterbox Monitor

A DIY smart litterbox: four load cells under the box, an HX711, and an ESP32 running ESPHome. A state analyzer on the chip turns the raw 10 Hz weight signal into everything listed below — no camera, no cloud, no external compute — and surfaces it in Home Assistant as native sensors, buttons, and actions.

Features

• Knows which cat is which. Identifies visiting cats by weight (up to 5) and tracks each cat's weight over time — no collars, no cameras.
• Logs every visit. Per-cat daily counts of visits, pees, and poops, plus visit duration and total visits since the last scoop.
• PoopSense. Tells #1 from #2 using nothing but the weight signal. How it works ->
• Tells you when to scoop. Tracks how much waste has piled up since the last clean — and detects the clean itself, so the counters reset on their own when you scoop.
• Tells you when to deep clean. Configurable reminder for full litter changes.
• Watches the litter level. Estimates how much litter is left in the box so you know when to top up.
• Takes care of itself. Auto-tares to cancel scale drift.

What You Need

Load cells

• 4× strain gauge load cells, one per corner of the baseboard (commonly available on AliExpress); 5-12.5 kg each covers most setups.
• Sizing is a balancing act: strong enough to survive the cat's landing, small enough that PoopSense can still see grams. For a typical single-cat setup, 4× 6-8 kg cells hit the sweet spot.
• The full math — sizing formula, worked examples, and resolution table — lives in the load cell sizing guide.

Load cell amplifier (HX711)

• Any HX711 breakout board will work, BUT:
• Boards with separate VCC (5V for load cells) and VDD (3.3V for ESP32 logic) are recommended for best accuracy.
  • Recommended, known good example: Sparkfun HX711 v1.1
  • BEWARE Some no-name breakout boards have separate VCC and VDD pins but electrically tie them together. Supplying 5V to these will kill the esp chip. Validate these with a multimeter before applying power.

ESP32

• Use a variant with a hardware FPU: the classic ESP32 (what the config targets and the development build runs) or the ESP32-S3.
• PoopSense leans on float math — per-sample filtering at 10 Hz and standard-deviation crunching at 0.1 g precision after every visit — so variants that emulate floats in software (S2, C3, C6) are untested.

Litterbox and base

• For large breeds, the IKEA SAMLA 79x57x18 cm/55 l is a good DIY litterbox.
• Can be paired with a suitable IKEA KOMPLEMENT shelf as a base.

Calibration tools

You'll also want these on hand for the calibration step later:

• A known good kitchen scale.
• A bathroom scale (for weighing the cats).
• Calibration weights adding up to roughly your everyday load — box + litter + cat (~20 kg on the XL build). Several small water bottles work great; one big jug does not — see Calibration for why.

Assembly

Follow this great SparkFun HX711 Hookup Guide for wiring the load cells to the HX711 and mounting them under the baseboard.

Wire the HX711 to the ESP32. The configuration defaults to:

HX711 pin	ESP32 pin
DOUT / DT	GPIO16
SCK / CLK	GPIO4

You can use different pins — just update the hx711 sensor section of the YAML to match your wiring.

Firmware Setup

1. Clone this repo (or copy both litterbox-monitor.yaml and state_analyzer.h into the same directory — both files are required).

2. Create a secrets.yaml next to them defining: wifi_ssid, wifi_password, litterbox_api_key, litterbox_ota_password, and litterbox_ap_password.

3. Edit the substitutions block at the top of the YAML:

   • cats — your cat names (e.g. "Fluffy", "Whiskers", "Mittens"). 1-5 cats are supported; add or remove entries as needed. Only the cats you define will have corresponding weight and daily visit sensors in Home Assistant, so configure this before first flashing. (After flashing, you'll set each cat's weight with the set_cat_weight action — see Calibration.)
   • timezone — your local timezone (used by the daily counters).

4. If you wired the HX711 to different GPIO pins, update the hx711 sensor section accordingly (see Assembly).

5. Flash with ESPHome as usual.

Calibration

1. Gather calibration weights adding up to roughly what the cells will carry day to day — box + litter + cat (~20 kg on the XL build) — and measure them to the nearest gram in batches your kitchen scale is comfortable with (2 L bottles, two at a time, on a "5 kg max" scale).

   Several small bottles at working load beat one big jug: scales are only accurate mid-range — here's why.

2. Set the Calibration Known Weight number entity to the weight you measured (in grams).

3. Make sure the constructed base is without anything on top, resting on a flat and level surface. Use shims if you need to.

4. Press the Calibrate Scale button. This will capture the zero point (tare).

5. Place the known weights on the base and press the Calibrate Scale button again. This will complete the calibration process.

   The "Raw weight" sensor should now read the weight you placed on it, and the "Calibration Last Performed" sensor should read the current time. If this is not the case, consult the ESPHome logs for errors and repeat steps 2-5.

6. Optional Fill in "Empty Box Weight" number entity to the weight of the empty litterbox (in grams). This will improve the accuracy of the "Litter Remaining" sensor. You can place the box on the monitor and read the "Raw weight" sensor to get this value.

7. Set the litterbox on top, add the litter and trigger the Reset clean button.

8. Take the approximate weight of your cats (within 10%).

   This can be easily done with weighing yourself on a bathroom scale, then weighing yourself again while holding each cat, and subtracting the difference.

   Use the set_cat_weight action within Home Assistant to set an initial value for each cat's weight, in the order you defined them in the configuration (see Actions below).

That's it — the monitor is ready to use.

Reference

Sensors and Entities

• Cat 1-5 Weight: Last weight stored for each cat when PoopSense identifies them on a visit (only enabled cats are visible).
• Cat 1-5 Daily Visits: Number of visits per day for each cat (only enabled cats are visible).
• Cat 1-5 Daily Pee: Number of urination events today for each cat (only enabled cats are visible).
• Cat 1-5 Daily Poops: Number of defecation events today for each cat (only enabled cats are visible).
• Elimination Type: Text sensor reporting no_elimination, urination, defecation, both, or unknown after each analyzed activity.
• Event Duration: Seconds for the activity window that was analyzed (updated when PoopSense runs at the end of activity).
• Waste Weight: Estimated total accumulated waste (grams) since last clean.
• Litter Remaining: Estimated remaining litter (kg).
• Visits: Number of cat visits since last clean.
• Deep Clean Timer: Days left until next recommended deep clean / litter change.
• Cat Weight: Diagnostic sensor (disabled by default) showing the cat weight in kg from the last PoopSense result.
• Occupancy, Activity, Vibration: Diagnostic sensors for physical presence, combined activity, and scale jitter.
• Cat Event: Diagnostic occupancy-style hint when tared weight is close to a known cat for 2+ seconds (used internally for activity; PoopSense does the full visit analysis when activity ends).
• Raw/Unfiltered/Tared Weight: Diagnostic weight readings.
• WiFi Signal: Diagnostic RSSI in dBm, published once a minute as the median of four samples.

Number Entities

• Litter Change Interval: Configure the number of days between deep clean reminders (7-30 days, default: 30).
• Classification Threshold: Standard deviation threshold (in grams) that separates urination from defecation. The default of 4 g works well out of the box; raise it if defecation events are being over-reported, lower it if they're being missed. See PoopSense for details.
• Calibration Known Weight: Weight of calibration objects used during scale setup.
• Empty Box Weight: Weight of the empty litterbox for improved litter remaining calculations.

Buttons

• Reset Deep Clean Timer: Resets the deep clean countdown.

• Reset Clean: Resets tare, litter, waste, and visit counters.

  Only required if the automatic clean detection failed.

Actions (Services)

• set_cat_weight: Set a cat's weight manually via Home Assistant or API.
  • Parameters: cat (int, 1-5), weight (float)
  • Example: To set Cat 1's weight to 5.2kg, call set_cat_weight with cat=1, weight=5.2.

Synchronize Multiple Litterboxes

Running more than one litterbox? Keep the cat weights in sync with a small Home Assistant automation: when a cat's weight updates on one box, call set_cat_weight on the others.

Roadmap

• Runtime assisted calibration.
• Easier adding/removing of pets.
• Distinguish urination/defecation/no-waste events.
• Automatic periodic calibration using the empty litterbox weight.
• Calculate trends and alert for outliers.
• Distinguish cats of similar weight.
• Automatic deep clean detection.
• Error state detection (debris stuck underneath, box misaligned)

Acknowledgements

• Andy Bradford's Blog post for the initial inspiration
• markusressel/ESPHome-Smart-Scale for the auto-tare smart scale code
• DIY Cat Village Youtube channel for the IKEA litterbox hack
• Purina Petivity for not offering an XL version and propelling this DIY project.

Contributing

Feel free to open an issue or pull request.