[](https://pypi.org/project/pylitterbot)
[](https://pypi.org/project/pylitterbot)
[](https://ko-fi.com/natekspencer)
[](https://share.litter-robot.com/x/YZ325z)
# 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
```bash
pip install pylitterbot
```
Alternatively, clone the repository and run
```bash
poetry install
```
## Usage
```python
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
```python
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:
```bash
git clone https://github.com/natekspencer/pylitterbot.git
cd pylitterbot
```
2. Install dependencies and pre-commit hooks:
```bash
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:
```bash
mypy .
```
- **Testing:** Add tests for any new features or changes. Run the test suite with:
```bash
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:
```bash
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](https://share.litter-robot.com/x/YZ325z) 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:
<a href='https://ko-fi.com/natekspencer' target='_blank'><img height='35' style='border:0px;height:46px;' src='https://az743702.vo.msecnd.net/cdn/kofi3.png?v=0' border='0' alt='Buy Me a Coffee at ko-fi.com' />
Raw data
{
"_id": null,
"home_page": "https://github.com/natekspencer/pylitterbot",
"name": "pylitterbot",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9.2",
"maintainer_email": null,
"keywords": "Whisker, Litter-Robot, Feeder-Robot, litter box, pet feeder, asynchronous",
"author": "Nathan Spencer",
"author_email": "natekspencer@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7c/2f/3f855f2823c9af5399eb8426565bc1e4bde061668a61154af56e16844aba/pylitterbot-2024.2.2.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/pylitterbot)\n[](https://pypi.org/project/pylitterbot)\n[](https://ko-fi.com/natekspencer)\n[](https://share.litter-robot.com/x/YZ325z)\n\n# pylitterbot\n\nPython package for controlling Whisker connected self-cleaning litter boxes and feeders.\n\nThis is an unofficial API for controlling various Whisker automated robots. It currently supports Litter-Robot 3 (with connect), Litter-Robot 4 and Feeder-Robot.\n\n## Disclaimer\n\nThis 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.\n\n## Installation\n\nInstall using pip\n\n```bash\npip install pylitterbot\n```\n\nAlternatively, clone the repository and run\n\n```bash\npoetry install\n```\n\n## Usage\n\n```python\nimport asyncio\n\nfrom pylitterbot import Account\n\n# Set email and password for initial authentication.\nusername = \"Your username\"\npassword = \"Your password\"\n\n\nasync def main():\n # Create an account.\n account = Account()\n\n try:\n # Connect to the API and load robots.\n await account.connect(username=username, password=password, load_robots=True)\n\n # Print robots associated with account.\n print(\"Robots:\")\n for robot in account.robots:\n print(robot)\n finally:\n # Disconnect from the API.\n await account.disconnect()\n\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\nwhich will output something like:\n\n```\nName: Litter-Robot Name, Serial: LR3C012345, id: a0123b4567cd8e\n```\n\nTo start a clean cycle\n\n```python\nawait robot.start_cleaning()\n```\n\nIf no exception occurred, your Litter-Robot should now perform a clean cycle.\n\nCurrently the following methods are available in the Robot class:\n\n- refresh()\n- start_cleaning()\n- reset_settings()\n- set_panel_lockout()\n- set_night_light()\n- set_power_status()\n- set_sleep_mode()\n- set_wait_time()\n- set_name()\n- get_activity_history()\n- get_insight()\n\n## Contributing\n\nThank you for your interest in contributing! Follow these steps to set up your environment and ensure your changes meet the project's standards.\n\n### Setup\n\n1. Clone this repository:\n ```bash\n git clone https://github.com/natekspencer/pylitterbot.git\n cd pylitterbot\n ```\n2. Install dependencies and pre-commit hooks:\n ```bash\n poetry install\n pre-commit install\n ```\n\n### Guidelines\n\n- **Code Formatting:** Ensure your code is properly formatted. This project uses `ruff` for linting and formatting.\n- **Typing:** All code must be fully typed. Use `mypy` to check for type issues:\n ```bash\n mypy .\n ```\n- **Testing:** Add tests for any new features or changes. Run the test suite with:\n ```bash\n pytest\n ```\n- **Commit Messages:** Follow conventional commit messages, e.g., feat: add new feature or fix: resolve issue with X\n\n### Submitting Changes\n\n1. Create a new branch for your feature or fix:\n ```bash\n git checkout -b feature/your-feature\n ```\n2. Make your changes and commit them.\n3. Push to your fork and open a pull request.\n\nI appreciate your contributions! \ud83d\ude80\n\n---\n\n## TODO\n\n- Improve support for Litter-Robot 4\n- Improve support for Feeder-Robot\n\n---\n\n## Support Me\n\nI'm not employed by Whisker and provide this python package as-is.\n\nIf you don't already own a Litter-Robot, please consider using [my referral link](https://share.litter-robot.com/x/YZ325z) to purchase your own robot and save $50!\n\nIf 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:\n\n<a href='https://ko-fi.com/natekspencer' target='_blank'><img height='35' style='border:0px;height:46px;' src='https://az743702.vo.msecnd.net/cdn/kofi3.png?v=0' border='0' alt='Buy Me a Coffee at ko-fi.com' />\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python package for controlling Whisker automatic robots.",
"version": "2024.2.2",
"project_urls": {
"Homepage": "https://github.com/natekspencer/pylitterbot",
"Repository": "https://github.com/natekspencer/pylitterbot"
},
"split_keywords": [
"whisker",
" litter-robot",
" feeder-robot",
" litter box",
" pet feeder",
" asynchronous"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f21f8d1e1193049c7da72f8a928552873e9fb95ccff492c52a39abd22cdf9505",
"md5": "267f20bd6ad4d61872a1f257ada98c3e",
"sha256": "bd26f412dc1cc97e5bce271be7b9bc1f74be336c69e43b72499823fce8fa43be"
},
"downloads": -1,
"filename": "pylitterbot-2024.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "267f20bd6ad4d61872a1f257ada98c3e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9.2",
"size": 39329,
"upload_time": "2025-07-09T17:16:17",
"upload_time_iso_8601": "2025-07-09T17:16:17.555768Z",
"url": "https://files.pythonhosted.org/packages/f2/1f/8d1e1193049c7da72f8a928552873e9fb95ccff492c52a39abd22cdf9505/pylitterbot-2024.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7c2f3f855f2823c9af5399eb8426565bc1e4bde061668a61154af56e16844aba",
"md5": "3b2ea31445390a865306f05d0241d089",
"sha256": "f18bcc4bc8ba34e63ee39db34fabfd833e3b88f6a35c4a41e1ba3f954e34adbc"
},
"downloads": -1,
"filename": "pylitterbot-2024.2.2.tar.gz",
"has_sig": false,
"md5_digest": "3b2ea31445390a865306f05d0241d089",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9.2",
"size": 30927,
"upload_time": "2025-07-09T17:16:18",
"upload_time_iso_8601": "2025-07-09T17:16:18.419660Z",
"url": "https://files.pythonhosted.org/packages/7c/2f/3f855f2823c9af5399eb8426565bc1e4bde061668a61154af56e16844aba/pylitterbot-2024.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 17:16:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "natekspencer",
"github_project": "pylitterbot",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "pylitterbot"
}
JSON
