Metadata-Version: 2.4
Name: botslab360
Version: 0.1.0
Summary: Async Python client for Botslab/360 robot vacuums
License-Expression: MIT
Project-URL: Source, https://github.com/placix/python-botslab360
Project-URL: Issues, https://github.com/placix/python-botslab360/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42
Requires-Dist: httpx<1,>=0.27
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Dynamic: license-file

# botslab360

Async Python client for Botslab / 360 robot vacuums.

This project provides an unofficial Python interface for selected 360 robot vacuum cleaners and is intended as a reusable library for integrations such as Home Assistant.

> [!WARNING]
> This project is unofficial and not affiliated with Botslab, Qihoo 360 or 360 Smart Home.
> Version `0.1.0` should be considered experimental.

## Features

Currently implemented:

- Qihoo `Q` / `T` session authentication
- Automatic `qid` derivation
- Smart Home login and session handling
- Automatic Smart Home SID refresh
- Device discovery
- Robot status retrieval
- TCP / push protocol communication
- AES decryption of push messages
- Start cleaning
- Pause cleaning
- Resume cleaning
- Return to dock
- Locate robot

Currently tested with:

- 360 S9-P / X90

Other models may work but have not yet been verified.

## Installation

```bash
pip install botslab360
```

Python 3.10 or newer is required.

## Authentication

The library currently uses authenticated Qihoo 360 account session tokens:

- `Q`
- `T`

These tokens can be obtained from an authenticated 360 web session.

They must be treated like credentials.

Never publish or log:

- `Q`
- `T`
- `qid`
- `sid`
- `pushKey`

The library does not implement automatic captcha solving or the proprietary Qihoo Account SDK.

## Basic usage

```python
import asyncio

from botslab360 import Botslab360Client


async def main() -> None:
    q = "YOUR_Q_TOKEN"
    t = "YOUR_T_TOKEN"

    async with Botslab360Client(q, t) as client:
        await client.authenticate()

        devices = await client.get_devices()

        for device in devices:
            print(device.name)
            print(device.model)

            status = await client.get_status(device)

            print(f"Battery: {status.battery}%")
            print(f"State: {status.state}")
            print(f"Charging: {status.charging}")


asyncio.run(main())
```

For real applications, do not hard-code credentials. Load them securely from configuration or environment-specific secret storage.

## Robot control

```python
async with Botslab360Client(q, t) as client:
    await client.authenticate()

    devices = await client.get_devices()
    robot = devices[0]

    await client.start_cleaning(robot)
    await client.pause(robot)
    await client.resume(robot)
    await client.return_to_dock(robot)
    await client.locate(robot)
```

## Status information

Depending on the robot model, status information may include:

- Battery level
- Robot state
- Charging state
- Fan mode
- Cleaned area in square metres
- Cleaning time in seconds
- Error code
- Online state

Example:

```text
Device: 360 Saugroboter
Model: S9-P
Battery: 100 %
State: fullcharge
Charging: True
Fan mode: strong
Cleaned area: 5
Cleaning time: 157
Error code: 0
```

## Session handling

The library distinguishes between the Qihoo account session and the Smart Home session.

Conceptually:

```text
Q + T
  ↓
qid
  ↓
Smart Home login
  ↓
sid + pushKey
  ↓
Device communication
```

If the Smart Home SID expires, the library performs one automatic re-authentication attempt using the existing `Q` and `T` tokens.

If the underlying Qihoo account session is no longer valid, the caller must provide new `Q` and `T` tokens.

## Development

Clone the repository:

```bash
git clone https://github.com/placix/python-botslab360.git
cd python-botslab360
```

Create a virtual environment:

```bash
python -m venv .venv
```

Activate it on Windows:

```powershell
.\.venv\Scripts\Activate.ps1
```

Install in editable mode:

```bash
python -m pip install -e .
```

Install test dependencies:

```bash
python -m pip install -e ".[test]"
```

Run the test suite:

```bash
pytest
```

## Project status

The library is currently under active development.

The current focus is providing a clean protocol layer that can later be used by a native Home Assistant integration.

Planned future work may include:

- Additional robot models
- Persistent push connection
- Fan speed control
- Room cleaning
- Zone cleaning
- Map support

## Security

Authentication and session values must be treated as secrets.

Do not include real credentials in:

- bug reports
- screenshots
- logs
- test fixtures
- Git commits

## License

MIT

## Links

- Source: https://github.com/placix/python-botslab360
- Issues: https://github.com/placix/python-botslab360/issues
