Skip to main content

Python package for controlling Whisker automatic robots.

Project description

pypi downloads Buy Me A Coffee/Beer Purchase Litter-Robot

pylitterbot

Python package for controlling Whisker connected self-cleaning litter boxes and feeders.

This is an unofficial API for controlling various Whisker automated robots. It currently supports Litter-Robot 3 (with connect), Litter-Robot 4 and Feeder-Robot.

Disclaimer

This API is experimental and was reverse-engineered by monitoring network traffic and decompiling source code from the Whisker app since no public API is currently available at this time. It may cease to work at any time. Use at your own risk.

Installation

Install using pip

pip install pylitterbot

Alternatively, clone the repository and run

poetry install

Usage

import asyncio

from pylitterbot import Account

# Set email and password for initial authentication.
username = "Your username"
password = "Your password"


async def main():
    # Create an account.
    account = Account()

    try:
        # Connect to the API and load robots.
        await account.connect(username=username, password=password, load_robots=True)

        # Print robots associated with account.
        print("Robots:")
        for robot in account.robots:
            print(robot)
    finally:
        # Disconnect from the API.
        await account.disconnect()


if __name__ == "__main__":
    asyncio.run(main())

which will output something like:

Name: Litter-Robot Name, Serial: LR3C012345, id: a0123b4567cd8e

To start a clean cycle

await robot.start_cleaning()

If no exception occurred, your Litter-Robot should now perform a clean cycle.

Currently the following methods are available in the Robot class:

  • refresh()
  • start_cleaning()
  • reset_settings()
  • set_panel_lockout()
  • set_night_light()
  • set_power_status()
  • set_sleep_mode()
  • set_wait_time()
  • set_name()
  • get_activity_history()
  • get_insight()

Contributing

Thank you for your interest in contributing! Follow these steps to set up your environment and ensure your changes meet the project's standards.

Setup

  1. Clone this repository:
    git clone https://github.com/natekspencer/pylitterbot.git
    cd pylitterbot
    
  2. Install dependencies and pre-commit hooks:
    poetry install
    pre-commit install
    

Guidelines

  • Code Formatting: Ensure your code is properly formatted. This project uses ruff for linting and formatting.
  • Typing: All code must be fully typed. Use mypy to check for type issues:
    mypy .
    
  • Testing: Add tests for any new features or changes. Run the test suite with:
    pytest
    
  • Commit Messages: Follow conventional commit messages, e.g., feat: add new feature or fix: resolve issue with X

Submitting Changes

  1. Create a new branch for your feature or fix:
    git checkout -b feature/your-feature
    
  2. Make your changes and commit them.
  3. Push to your fork and open a pull request.

I appreciate your contributions! 🚀


TODO

  • Improve support for Litter-Robot 4
  • Improve support for Feeder-Robot

Support Me

I'm not employed by Whisker and provide this python package as-is.

If you don't already own a Litter-Robot, please consider using my referral link to purchase your own robot and save $50!

If you already own a Litter-Robot and/or want to donate to me directly, consider buying me a coffee (or beer) instead by using the link below:

Buy Me a Coffee at ko-fi.com

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pylitterbot-2024.2.2.tar.gz (30.9 kB view details)

Uploaded Source

Built Distribution

pylitterbot-2024.2.2-py3-none-any.whl (39.3 kB view details)

Uploaded Python 3

File details

Details for the file pylitterbot-2024.2.2.tar.gz.

File metadata

  • Download URL: pylitterbot-2024.2.2.tar.gz
  • Upload date:
  • Size: 30.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.3 CPython/3.11.0 Linux/6.11.0-1015-azure

File hashes

Hashes for pylitterbot-2024.2.2.tar.gz
Algorithm Hash digest
SHA256 f18bcc4bc8ba34e63ee39db34fabfd833e3b88f6a35c4a41e1ba3f954e34adbc
MD5 3b2ea31445390a865306f05d0241d089
BLAKE2b-256 7c2f3f855f2823c9af5399eb8426565bc1e4bde061668a61154af56e16844aba

See more details on using hashes here.

File details

Details for the file pylitterbot-2024.2.2-py3-none-any.whl.

File metadata

  • Download URL: pylitterbot-2024.2.2-py3-none-any.whl
  • Upload date:
  • Size: 39.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.3 CPython/3.11.0 Linux/6.11.0-1015-azure

File hashes

Hashes for pylitterbot-2024.2.2-py3-none-any.whl
Algorithm Hash digest
SHA256 bd26f412dc1cc97e5bce271be7b9bc1f74be336c69e43b72499823fce8fa43be
MD5 267f20bd6ad4d61872a1f257ada98c3e
BLAKE2b-256 f21f8d1e1193049c7da72f8a928552873e9fb95ccff492c52a39abd22cdf9505

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page