botslab360 0.1.0__tar.gz

botslab360-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 placix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

botslab360-0.1.0/PKG-INFO

@@ -0,0 +1,254 @@
+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

botslab360-0.1.0/README.md

@@ -0,0 +1,235 @@
+# 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

botslab360-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "botslab360"
+version = "0.1.0"
+description = "Async Python client for Botslab/360 robot vacuums"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+
+dependencies = [
+    "cryptography>=42",
+    "httpx>=0.27,<1",
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8",
+]
+
+[project.urls]
+Source = "https://github.com/placix/python-botslab360"
+Issues = "https://github.com/placix/python-botslab360/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+pythonpath = ["src"]
+testpaths = ["tests"]

botslab360-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

botslab360-0.1.0/src/botslab360/__init__.py

@@ -0,0 +1,26 @@
+"""Async authentication for Botslab/360 smart-home devices."""
+
+from .auth import BotslabAuth, credentials_from_tokens, derive_qid
+from .client import Botslab360Client
+from .exceptions import (
+    ApiError,
+    AuthenticationError,
+    Botslab360Error,
+    InvalidSessionError,
+)
+from .models import Device, QihooCredentials, RobotStatus, SmartSession
+
+__all__ = [
+    "ApiError",
+    "AuthenticationError",
+    "Botslab360Client",
+    "Botslab360Error",
+    "BotslabAuth",
+    "Device",
+    "InvalidSessionError",
+    "QihooCredentials",
+    "RobotStatus",
+    "SmartSession",
+    "credentials_from_tokens",
+    "derive_qid",
+]