### Install roombapy

Source: https://github.com/pschmitt/roombapy/blob/main/README.md

Installs the library along with command-line interface tools.

```shell
pip install roombapy[cli]
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/pschmitt/roombapy/blob/main/README.md

Sets up pre-commit hooks to ensure code quality standards are met before commits.

```shell
pre-commit install
```

--------------------------------

### Complete Roomba Integration Workflow

Source: https://context7.com/pschmitt/roombapy/llms.txt

A comprehensive example covering device discovery, password retrieval, connection establishment, message handling, and command execution.

```python
import time
from roombapy import (
    RoombaDiscovery,
    RoombaPassword,
    RoombaFactory,
    RoombaConnectionError,
    RoombaMessage,
)
from roombapy.const import ROOMBA_STATES, ROOMBA_ERROR_MESSAGES

def main():
    # Step 1: Discover robots on the network
    print("Discovering Roomba devices...")
    discovery = RoombaDiscovery()
    robots = discovery.get_all()

    if not robots:
        print("No robots found on network")
        return

    # Use the first discovered robot
    robot_info = list(robots)[0]
    print(f"Found: {robot_info.robot_name} at {robot_info.ip}")

    # Step 2: Get password (ensure robot is in password mode)
    print("Attempting to retrieve password...")
    print("(Press HOME button on robot until tones play, then WiFi LED flashes)")

    password = RoombaPassword(robot_info.ip).get_password()
    if not password:
        print("Could not retrieve password - using placeholder")
        password = "your_password_here"  # Replace with actual password

    # Step 3: Create and connect to Roomba
    roomba = RoombaFactory.create_roomba(
        address=robot_info.ip,
        blid=robot_info.blid,
        password=password,
        continuous=True
    )

    # Step 4: Set up message handling
    def handle_message(msg: RoombaMessage):
        if "state" not in msg or "reported" not in msg["state"]:
            return

        reported = msg["state"]["reported"]

        # Display battery
        if "batPct" in reported:
            print(f"Battery: {reported['batPct']}%")

        # Display mission status
        if "cleanMissionStatus" in reported:
            status = reported["cleanMissionStatus"]
            phase = status.get("phase", "")
            state = ROOMBA_STATES.get(phase, phase)
            error = status.get("error", 0)

            print(f"State: {state}")
            if error != 0:
                print(f"Error: {ROOMBA_ERROR_MESSAGES.get(error, f'Unknown ({error})')}")

    roomba.register_on_message_callback(handle_message)

    # Step 5: Connect
    try:
        print("Connecting to Roomba...")
        roomba.connect()
        print("Connected!")
    except RoombaConnectionError as e:
        print(f"Connection failed: {e}")
        return

    # Step 6: Send commands
    time.sleep(2)  # Wait for initial state

    # Check current state before commanding
    if roomba.current_state == "Charging":
        print("Robot is charging. Starting cleaning...")
        roomba.send_command("start")
        time.sleep(10)

        print("Sending robot home...")
        roomba.send_command("dock")

    # Step 7: Monitor for a while
    try:
        print("Monitoring for 30 seconds (Ctrl+C to stop)...")
        time.sleep(30)
    except KeyboardInterrupt:
        pass
    finally:
        print("Disconnecting...")
        roomba.disconnect()

if __name__ == "__main__":
    main()
```

--------------------------------

### Send Cleaning Commands

Source: https://context7.com/pschmitt/roombapy/llms.txt

Execute various cleaning operations like start, stop, pause, and dock by sending commands over MQTT.

```python
from roombapy import RoombaFactory

roomba = RoombaFactory.create_roomba(
    address="192.168.1.100",
    blid="3XXXXXXXXXXXXXXXXX",
    password=":1:1234567890:abcdefg"
)
roomba.connect()

# Start a cleaning mission
roomba.send_command("start")

# Pause the current cleaning mission
roomba.send_command("pause")

# Resume a paused cleaning mission
roomba.send_command("resume")

# Stop the current cleaning mission
roomba.send_command("stop")

# Send the robot back to its dock/home base
roomba.send_command("dock")

# Start cleaning specific rooms (room IDs from smart map)
roomba.send_command("start", params={
    "pmap_id": "ABCDEF1234567890",
    "regions": [{"region_id": "1", "type": "rid"}]
})

roomba.disconnect()
```

--------------------------------

### Instantiate and Connect to Roomba

Source: https://context7.com/pschmitt/roombapy/llms.txt

Use the RoombaFactory to create a connection instance with required credentials and manage the lifecycle of the connection.

```python
from roombapy import RoombaFactory, RoombaConnectionError

# Create a Roomba instance with required credentials
# address: IP address of the Roomba on your local network
# blid: Robot's BLID (username), obtained via discovery or from iRobot app
# password: Robot's password, obtained via discovery or HOME button method
roomba = RoombaFactory.create_roomba(
    address="192.168.1.100",
    blid="3XXXXXXXXXXXXXXXXX",
    password=":1:1234567890:abcdefg",
    continuous=True,  # True for persistent connection, False for periodic
    delay=1  # Delay between connection attempts in periodic mode
)

# Connect to the Roomba
try:
    roomba.connect()
    print("Connected to Roomba!")
except RoombaConnectionError as e:
    print(f"Failed to connect: {e}")

# When done, disconnect
roomba.disconnect()
```

--------------------------------

### Discover Roomba Devices via CLI

Source: https://context7.com/pschmitt/roombapy/llms.txt

Use the CLI to scan the local network for Roomba devices and retrieve their credentials.

```bash
# Discover all Roomba devices on the network
roombapy discover

# Example output:
# Discovered robots:
# ┍━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━┑
# │ Robot name  │ IP              │ MAC               │ BLID                │ Password                 │
# ┝━━━━━━━━━━━━━┿━━━━━━━━━━━━━━━━━┿━━━━━━━━━━━━━━━━━━━┿━━━━━━━━━━━━━━━━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━┥
# │ Living Room │ 192.168.1.100   │ AA:BB:CC:DD:EE:FF │ 3XXXXXXXXXXXXXXXXXX │ :1:1234567890:abcdefgh   │
# ┕━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━┙

# Discover a specific robot by IP address
roombapy discover 192.168.1.100

# Get raw JSON output
roombapy discover --raw
```

--------------------------------

### Connect to Event Stream

Source: https://github.com/pschmitt/roombapy/blob/main/README.md

Establishes a connection to the Roomba to stream events, which can be piped into tools like jq.

```shell
roombapy connect <ip> -p <password>
```

--------------------------------

### Connect and Stream Roomba Events

Source: https://context7.com/pschmitt/roombapy/llms.txt

Connect to a device to stream real-time JSON data, optionally piping to jq for filtering.

```bash
# Connect using auto-discovered credentials
# (requires robot to be in password mode if password not cached)
roombapy connect 192.168.1.100

# Connect with explicit credentials
roombapy connect 192.168.1.100 -b 3XXXXXXXXXXXXXXXXX -p ":1:1234567890:abcdefg"

# Connect with debouncing to filter duplicate messages
roombapy connect 192.168.1.100 -p "password" --debounce 5

# Example output (JSON stream):
# {"state":{"reported":{"batPct":100,"bin":{"present":true,"full":false}}}}
# {"state":{"reported":{"cleanMissionStatus":{"phase":"charge","error":0}}}}
# {"state":{"reported":{"signal":{"rssi":-45,"snr":48}}}}

# Pipe to jq for formatted output
roombapy connect 192.168.1.100 -p "password" | jq '.'

# Filter specific fields with jq
roombapy connect 192.168.1.100 -p "password" | jq '.state.reported.batPct // empty'
```

--------------------------------

### Configure Robot Preferences

Source: https://context7.com/pschmitt/roombapy/llms.txt

Update persistent robot settings such as cleaning passes, carpet boost, and scheduling.

```python
from roombapy import RoombaFactory

roomba = RoombaFactory.create_roomba(
    address="192.168.1.100",
    blid="3XXXXXXXXXXXXXXXXX",
    password=":1:1234567890:abcdefg"
)
roomba.connect()

# Enable two-pass cleaning mode
roomba.set_preference("twoPass", True)

# Enable carpet boost (automatic power increase on carpets)
roomba.set_preference("carpetBoost", True)

# Set cleaning passes (1 = auto, 2 = two passes)
roomba.set_preference("noAutoPasses", False)

# Set edge clean preference
roomba.set_preference("openOnly", False)

# Disable bin full behavior pause
roomba.set_preference("binPause", False)

# Set scheduling (days: 0=Sun through 6=Sat)
schedule = {
    "cycle": ["start", "none", "start", "none", "start", "none", "none"],
    "h": [9, 0, 9, 0, 9, 0, 0],
    "m": [0, 0, 0, 0, 0, 0, 0]
}
roomba.set_preference("cleanSchedule", schedule)

roomba.disconnect()
```

--------------------------------

### Discover Roomba and Credentials

Source: https://github.com/pschmitt/roombapy/blob/main/README.md

Scans the local network for Roomba devices and attempts to retrieve credentials automatically.

```shell
roombapy discover <optional ip address>
```

--------------------------------

### RoombaFactory.create_roomba

Source: https://context7.com/pschmitt/roombapy/llms.txt

Factory method to instantiate a Roomba connection object with required network credentials and configuration.

```APIDOC
## RoombaFactory.create_roomba

### Description
Creates a Roomba instance for controlling the robot vacuum, handling the underlying MQTT remote client and TLS configuration.

### Parameters
#### Request Body
- **address** (string) - Required - IP address of the Roomba on the local network
- **blid** (string) - Required - Robot's BLID (username)
- **password** (string) - Required - Robot's password
- **continuous** (boolean) - Optional - True for persistent connection, False for periodic
- **delay** (integer) - Optional - Delay between connection attempts in periodic mode

### Request Example
{
  "address": "192.168.1.100",
  "blid": "3XXXXXXXXXXXXXXXXX",
  "password": ":1:1234567890:abcdefg",
  "continuous": true,
  "delay": 1
}
```

--------------------------------

### RoombaDiscovery

Source: https://context7.com/pschmitt/roombapy/llms.txt

Discovers Roomba devices on the local network using UDP broadcast.

```APIDOC
## RoombaDiscovery

### Description
Discover Roomba devices on the local network using UDP broadcast. Returns RoombaInfo objects containing device details including IP address, MAC address, BLID, robot name, firmware version, and capabilities.

### Methods
- **get_all()** - Returns a set of all discovered RoombaInfo objects.
- **get(ip)** - Returns a specific RoombaInfo object for the given IP address.
```

--------------------------------

### Access Roomba Status and Error Constants

Source: https://context7.com/pschmitt/roombapy/llms.txt

Use library constants to map numeric error codes and phase strings to human-readable descriptions.

```python
from roombapy.const import ROOMBA_ERROR_MESSAGES, ROOMBA_STATES, MQTT_ERROR_MESSAGES

# ROOMBA_STATES maps phase values to human-readable states
# Example states:
# "charge" -> "Charging"
# "run" -> "Running"
# "stuck" -> "Stuck"
# "hmPostMsn" -> "End Mission"
# "pause" -> "Paused"
# "stop" -> "Stopped"
# "evac" -> "Emptying Bin"

print("Available states:")
for phase, state in ROOMBA_STATES.items():
    if state:
        print(f"  {phase}: {state}")

# ROOMBA_ERROR_MESSAGES maps error codes to descriptions
# Common errors:
# 0: "None" (no error)
# 1: "Left wheel off floor"
# 2: "Main brushes stuck"
# 14: "Bin missing"
# 15: "Robot rebooted"
# 18: "Docking issue"

print("\nCommon error codes:")
for code in [0, 1, 2, 14, 15, 18]:
    print(f"  {code}: {ROOMBA_ERROR_MESSAGES.get(code)}")

# MQTT_ERROR_MESSAGES for connection issues
# 4: "Bad username or password"
# 5: "Not authorised"
# 7: "The connection was lost"
```

--------------------------------

### Roomba.register_on_message_callback

Source: https://context7.com/pschmitt/roombapy/llms.txt

Registers a callback function to receive real-time state updates from the Roomba, including battery, bin, and mission status.

```APIDOC
## Roomba.register_on_message_callback

### Description
Registers callback functions to receive real-time state updates from the Roomba. Messages include battery status, bin status, cleaning mission progress, position coordinates, and error states.

### Parameters
- **callback** (function) - Required - A function that accepts a RoombaMessage object as an argument.
```

--------------------------------

### Access Roomba Device Information

Source: https://context7.com/pschmitt/roombapy/llms.txt

Use RoombaDiscovery to find devices on the network and access their attributes like IP, MAC, and firmware version.

```python
from roombapy import RoombaDiscovery
from roombapy.roomba_info import RoombaInfo

discovery = RoombaDiscovery()
robots = discovery.get_all()

for info in robots:
    # RoombaInfo fields:
    # - hostname: str - e.g., "Roomba-3XXXXXXXXXX" or "iRobot-3XXXXXXXXXX"
    # - firmware: str - software version (aliased from 'sw')
    # - ip: str - local IP address
    # - mac: str - MAC address
    # - robot_name: str - user-assigned name (aliased from 'robotname')
    # - sku: str - model SKU
    # - capabilities: dict - feature capabilities
    # - password: str | None - password if obtained
    # - blid: str (property) - extracted from hostname

    print(f"Robot: {info.robot_name}")
    print(f"  Hostname: {info.hostname}")
    print(f"  BLID: {info.blid}")  # Computed from hostname
    print(f"  IP: {info.ip}")
    print(f"  MAC: {info.mac}")
    print(f"  Firmware: {info.firmware}")
    print(f"  SKU: {info.sku}")
```

--------------------------------

### Discover Roomba Devices

Source: https://context7.com/pschmitt/roombapy/llms.txt

Discover Roomba devices on the local network using UDP broadcast. This function returns a set of RoombaInfo objects, each containing details like IP address, MAC address, BLID, robot name, firmware version, and capabilities. You can discover all robots or a specific one by IP address.

```python
from roombapy import RoombaDiscovery, RoombaInfo

# Create discovery instance
discovery = RoombaDiscovery()

# Discover all Roomba devices on the network
# Sends UDP broadcasts and collects responses
robots: set[RoombaInfo] = discovery.get_all()

for robot in robots:
    print(f"Found: {robot.robot_name}")
    print(f"  IP: {robot.ip}")
    print(f"  MAC: {robot.mac}")
    print(f"  BLID: {robot.blid}")
    print(f"  Firmware: {robot.firmware}")
    print(f"  SKU: {robot.sku}")
    print(f"  Capabilities: {robot.capabilities}")

# Discover a specific Roomba by IP address
robot = discovery.get("192.168.1.100")
if robot:
    print(f"Found robot: {robot.robot_name} with BLID: {robot.blid}")
else:
    print("Robot not found at specified IP")

```

--------------------------------

### Roomba.send_command

Source: https://context7.com/pschmitt/roombapy/llms.txt

Sends control commands to the Roomba to manage cleaning missions.

```APIDOC
## Roomba.send_command

### Description
Sends control commands to the Roomba to start, stop, pause, resume, or dock the robot. Commands are sent over MQTT.

### Parameters
#### Request Body
- **command** (string) - Required - The action to perform (e.g., "start", "stop", "pause", "resume", "dock")
- **params** (object) - Optional - Additional parameters for specific commands like room cleaning
```

--------------------------------

### Register Roomba Message Callback

Source: https://context7.com/pschmitt/roombapy/llms.txt

Register a function to receive real-time state updates from the Roomba. This includes battery status, bin status, mission progress, and error states. Ensure the callback function is defined before registering it.

```python
from roombapy import RoombaFactory, RoombaMessage
import json

def on_roomba_message(message: RoombaMessage) -> None:
    """Handle incoming Roomba state messages."""
    print(json.dumps(message, indent=2))

    # Access specific state values
    if "state" in message and "reported" in message["state"]:
        reported = message["state"]["reported"]

        # Check battery percentage
        if "batPct" in reported:
            print(f"Battery: {reported['batPct']}&")

        # Check bin status
        if "bin" in reported:
            if reported["bin"].get("full"):
                print("Warning: Bin is full!")
            if not reported["bin"].get("present"):
                print("Warning: Bin is missing!")

        # Check mission status
        if "cleanMissionStatus" in reported:
            status = reported["cleanMissionStatus"]
            print(f"Phase: {status.get('phase')}")
            print(f"Error code: {status.get('error')}")

roomba = RoombaFactory.create_roomba(
    address="192.168.1.100",
    blid="3XXXXXXXXXXXXXXXXX",
    password=":1:1234567890:abcdefg"
)

# Register callback before connecting
roomba.register_on_message_callback(on_roomba_message)

# Connect and start receiving messages
roomba.connect()

# Master state accumulates all received data
# Access current state at any time:
# roomba.master_state - full state dictionary
# roomba.current_state - current mission state (Charging, Running, etc.)
# roomba.bin_full - boolean bin status
# roomba.error_code - current error code if any
# roomba.error_message - human-readable error message
# roomba.co_ords - robot position {"x": 0, "y": 0, "theta": 180}

```

--------------------------------

### Roomba.register_on_disconnect_callback

Source: https://context7.com/pschmitt/roombapy/llms.txt

Registers a callback function to handle disconnection events from the Roomba.

```APIDOC
## Roomba.register_on_disconnect_callback

### Description
Register callback functions to handle disconnection events. Useful for implementing reconnection logic or notifying users of connection issues.

### Parameters
- **callback** (function) - Required - A function that accepts a TransportErrorMessage object as an argument.
```

--------------------------------

### Roomba.set_preference

Source: https://context7.com/pschmitt/roombapy/llms.txt

Updates robot preferences and settings such as cleaning passes and schedules.

```APIDOC
## Roomba.set_preference

### Description
Sets robot preferences and settings. Settings are published to the robot's delta topic and persist across cleaning sessions.

### Parameters
#### Request Body
- **preference** (string) - Required - The setting key (e.g., "twoPass", "carpetBoost", "cleanSchedule")
- **value** (any) - Required - The value to set for the preference
```

--------------------------------

### Register Roomba Disconnect Callback

Source: https://context7.com/pschmitt/roombapy/llms.txt

Register a function to handle disconnection events from the Roomba. This is useful for implementing automatic reconnection logic or notifying users about connection issues. The callback receives an error message if the disconnection was not normal.

```python
from roombapy import RoombaFactory, RoombaConnectionError
from roombapy.const import TransportErrorMessage
import time

def on_disconnect(error: TransportErrorMessage) -> None:
    """Handle disconnection events."""
    if error:
        print(f"Disconnected with error: {error}")
        # Implement reconnection logic here
    else:
        print("Disconnected normally")

roomba = RoombaFactory.create_roomba(
    address="192.168.1.100",
    blid="3XXXXXXXXXXXXXXXXX",
    password=":1:1234567890:abcdefg"
)

roomba.register_on_disconnect_callback(on_disconnect)
roomba.connect()

```

--------------------------------

### Retrieve Roomba Password

Source: https://context7.com/pschmitt/roombapy/llms.txt

Retrieve the password from a Roomba device. This requires the Roomba to be on its Home Base and in password retrieval mode (indicated by a flashing WiFi LED). Ensure you initiate password retrieval within approximately one minute of enabling the mode.

```python
from roombapy import RoombaPassword, RoombaDiscovery

# First discover the robot to get its IP
discovery = RoombaDiscovery()
robot = discovery.get("192.168.1.100")

if robot:
    # Create password retriever
    # IMPORTANT: Before calling get_password():
    # 1. Ensure Roomba is on its Home Base and powered on
    # 2. Press and hold HOME button until you hear a series of tones
    # 3. Release button - WiFi LED should be flashing
    # 4. You have ~1 minute to retrieve the password

    password_retriever = RoombaPassword(robot.ip)
    password = password_retriever.get_password()

    if password:
        print(f"Retrieved password: {password}")
        print(f"BLID: {robot.blid}")
        # Store these credentials securely for future connections
    else:
        print("Could not retrieve password.")
        print("Make sure the robot is in password mode (WiFi LED flashing)")
        print("Some newer models require cloud-based password retrieval")

```

--------------------------------

### RoombaPassword

Source: https://context7.com/pschmitt/roombapy/llms.txt

Retrieves the password from a Roomba device in password retrieval mode.

```APIDOC
## RoombaPassword

### Description
Retrieve the password from a Roomba device. The robot must be on its Home Base and in password retrieval mode (press and hold HOME button until you hear a series of tones, then WiFi LED should flash).

### Parameters
- **ip** (string) - Required - The IP address of the Roomba device.

### Methods
- **get_password()** - Returns the password string if successful, otherwise returns None.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.