pylitterbot

To interact with your robots, use the Account class. You must provide your Whisker account credentials to connect to the API. It is recommended to use an async context and ensure you call disconnect() to clean up the connection.

By default, account.connect(load_robots=True) will load all robots associated with your account. You can also filter for specific robot families by passing a list of classes to the robot_types argument in the Account constructor.

import asyncio
from pylitterbot import Account, LitterRobot4, LitterRobot5

username = "Your username"
password = "Your password"

async def main():
    # Filter for specific robot types during initialization
    account = Account(robot_types=[LitterRobot4, LitterRobot5])

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

        print("Robots:")
        for robot in account.robots:
            print(robot)
    finally:
        # Always disconnect
        await account.disconnect()

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

The LitterRobotSession class is the primary entry point for interacting with the Litter-Robot cloud API. It manages authentication via Cognito, handles token refreshing automatically, and provides helper methods for HTTP requests.

It can be used as an asynchronous context manager to ensure the underlying aiohttp.ClientSession is closed correctly.

To use it, you can either initialize it with existing tokens or use the .login(username, password) method to authenticate with credentials.

from pylitterbot.session import LitterRobotSession

async def main():
    # Using as an async context manager
    async with LitterRobotSession() as session:
        # Login with credentials
        await session.login("your_email@example.com", "your_password")
        
        # Perform requests
        data = await session.get("https://api.litter-robot.com/v2/robots")
        print(data)

import asyncio
asyncio.run(main())

The MCP server exposes several tools categorized by function:

Status and Info

• get_robots
• get_robot_status
• get_activity_history
• get_insight
• get_pets

Commands

• start_cleaning
• reset_robot
• give_snack
• set_power_status

Settings

• set_name
• set_night_light
• set_night_light_brightness
• set_night_light_mode
• set_panel_lockout
• set_wait_time
• set_sleep_mode

Compound Operations

• fleet_overview: Prioritized status across all robots with alerts.
• clean_all_ready: Start cleaning on all robots in READY state.
• sync_settings: Copy one robot's settings to all others of the same model.
• pet_usage_report: Activity data across all robots with pet info.
• maintenance_forecast: Estimate when each robot needs emptying.
• household_digest: Time-bounded summary of all activity.
• troubleshooting_report: Diagnostic bundle for a robot with errors.
• robot_comparison: Compare settings and metrics across robots.

The SleepSchedule class allows you to manage and query the sleep/activity windows for a device. It supports parsing schedules from raw API data (dictionaries or lists), creating schedules from timestamps, and checking if a specific time falls within a sleep window.

Key capabilities:

• Parsing: Convert raw JSON-like structures into SleepSchedule objects.
• Window Detection: Use get_window(dt) to find the start and end datetime of the current sleep period.
• Status Checking: Use is_active(dt) to determine if the device is currently in a sleep state at a given time.
• Day-specific configuration: Access specific daily settings via get_day(day).

from datetime import datetime, timedelta, timezone
from pylitterbot.sleep_schedule import SleepSchedule, DayOfWeek

# Example: Parsing a schedule from a dictionary
raw_data = {
    "MONDAY": {"sleepTime": 1320, "wakeTime": 360, "isEnabled": True},
    "TUESDAY": {"sleepTime": 1320, "wakeTime": 360, "isEnabled": True}
}
schedule = SleepSchedule.parse(raw_data)

# Check if currently in sleep mode
if schedule.is_active():
    print("Device is sleeping")

# Get the specific time window for the current sleep period
window = schedule.get_window()
if window:
    start, end = window
    print(f"Sleeping from {start} to {end}")