yarbo-data-sdk 0.1.0__py3-none-any.whl

yarbo_data_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: yarbo-data-sdk
+Version: 0.1.0
+Summary: Python SDK for Yarbo robot devices
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41.0
+Requires-Dist: paho-mqtt>=2.0
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Yarbo Data SDK
+
+Python SDK for Yarbo robot devices. Enables integration with smart home platforms and custom applications.
+
+## Features
+
+- **Authentication** — Login with email/password (RSA-encrypted), token refresh, session restore
+- **Device Management** — Query device list via REST API
+- **MQTT Real-time Data** — Subscribe to device messages and heart beats with automatic zlib decompression (firmware >= 3.9.0)
+- **Device Control** — Publish commands via MQTT with automatic compression and debug logging
+- **Request with Feedback** — Send commands and wait for device response via data_feedback topic
+- **Device Registry** — JSON-driven device capability definitions with structured field and control metadata
+- **Custom Extractors** — Extensible field extraction logic (network priority, volume scaling, RTK signal, planning/recharging status)
+
+## Installation
+
+```bash
+pip install yarbo-data-sdk
+```
+
+**Requirements**: Python >= 3.10
+
+## Quick Start
+
+```python
+from yarbo_robot_sdk import YarboClient
+
+client = YarboClient(api_base_url="https://api.yarbo.com")
+client.login("user@email.com", "password")
+
+devices = client.get_devices()
+for device in devices:
+    print(f"{device.name} ({device.sn}) - Online: {device.online}")
+```
+
+## MQTT Real-time Updates
+
+```python
+client.mqtt_connect()
+
+# Subscribe to device status messages
+def on_device_message(topic, data):
+    print(f"Status update: {data}")
+
+client.subscribe_device_message("SN123", "yarbo_Y", on_device_message)
+
+# Subscribe to heart beat
+def on_heart_beat(topic, data):
+    print(f"Heart beat: {data}")
+
+client.subscribe_heart_beat("SN123", "yarbo_Y", on_heart_beat)
+```
+
+## Device Control
+
+```python
+# Set working state
+client.mqtt_publish_command("SN123", "yarbo_Y", "set_working_state", {"state": 1, "source": "smart_home"})
+
+# Sound control
+client.mqtt_publish_command("SN123", "yarbo_Y", "set_sound_param", {"enable": True, "vol": 0.5, "mode": 0})
+
+# Headlight control (all 7 light fields required)
+client.mqtt_publish_command("SN123", "yarbo_Y", "light_ctrl", {
+    "body_left_r": 255, "body_right_r": 255, "led_head": 255,
+    "led_left_w": 255, "led_right_w": 255, "tail_left_r": 255, "tail_right_r": 255
+})
+
+# Start auto plan
+client.mqtt_publish_command("SN123", "yarbo_Y", "start_plan", {"id": 123, "percent": 0})
+
+# Pause / Resume / Stop plan
+client.mqtt_publish_command("SN123", "yarbo_Y", "pause", {})
+client.mqtt_publish_command("SN123", "yarbo_Y", "resume", {})
+client.mqtt_publish_command("SN123", "yarbo_Y", "stop", {})
+
+# Return to charge (disable wireless charging first)
+client.mqtt_publish_command("SN123", "yarbo_Y", "wireless_charging_cmd", {"cmd": 0})
+client.mqtt_publish_command("SN123", "yarbo_Y", "cmd_recharge", {"cmd": 2})
+```
+
+## Request with Feedback
+
+Some commands return data via the `data_feedback` MQTT topic:
+
+```python
+# Fetch full device status snapshot
+device_msg = client.get_device_msg("SN123", "yarbo_Y", timeout=10.0)
+
+# Fetch all auto plans
+plans = client.read_all_plan("SN123", "yarbo_Y", timeout=10.0)
+
+# Fetch GPS reference origin
+gps_ref = client.read_gps_ref("SN123", "yarbo_Y", timeout=10.0)
+```
+
+## Device Registry
+
+Access device field definitions programmatically:
+
+```python
+from yarbo_robot_sdk import get_field_definitions, get_control_field_definitions
+
+# Sensor/binary_sensor field definitions
+fields = get_field_definitions("yarbo_Y")
+for f in fields:
+    print(f"{f.path} -> {f.name} ({f.entity_type})")
+
+# Control field definitions (select/switch/number)
+controls = get_control_field_definitions("yarbo_Y")
+for c in controls:
+    print(f"{c.path} -> {c.name} ({c.entity_type})")
+```
+
+### Supported Control Topics
+
+| Topic | Description | Payload Example |
+|-------|-------------|-----------------|
+| set_working_state | Set working state | `{"state": 1, "source": "smart_home"}` |
+| set_sound_param | Sound control | `{"enable": true, "vol": 0.5, "mode": 0}` |
+| light_ctrl | Headlight control | `{"body_left_r": 255, ...}` (7 fields) |
+| start_plan | Start auto plan | `{"id": 123, "percent": 0}` |
+| pause | Pause plan | `{}` |
+| resume | Resume plan | `{}` |
+| stop | Stop plan | `{}` |
+| cmd_recharge | Return to charge | `{"cmd": 2}` |
+| wireless_charging_cmd | Wireless charging | `{"cmd": 0}` |
+| read_all_plan | Request plans | `{}` (response via data_feedback) |
+| get_device_msg | Request full status | `{}` (response via data_feedback) |
+| read_gps_ref | Request GPS ref | `{}` (response via data_feedback) |
+| get_map | Request map data | `{}` (response via data_feedback) |
+
+### Network Helper
+
+```python
+from yarbo_robot_sdk import extract_active_network
+
+# Determine active network from route_priority data
+# Returns the interface with the lowest non-negative priority value
+result = extract_active_network({"hg0": 10, "wlan0": 600, "wwan0": -1})
+# result = "Halow" (hg0 has lowest priority value)
+```
+
+## Session Persistence
+
+```python
+# Save tokens
+saved_token = client.token
+saved_refresh_token = client.refresh_token
+
+# Restore in a new client (no re-login needed)
+client2 = YarboClient(api_base_url="https://api.yarbo.com")
+client2.restore_session(
+    username="user@email.com",
+    token=saved_token,
+    refresh_token=saved_refresh_token,
+)
+```
+
+## Documentation
+
+- [API Reference](docs/api.md) — All methods, parameters, and return types
+- [MQTT Topics](docs/mqtt-topics.md) — Topic formats, payload structures, compression
+- [Device Fields](docs/device-fields.md) — Complete field definitions for all device types
+
+## License
+
+MIT

yarbo_data_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+yarbo_robot_sdk/__init__.py,sha256=KpRXjaq6gm9EuDyquef8-b4rwIEpEwxLuPyZEpXQpno,814
+yarbo_robot_sdk/auth.py,sha256=IQ_-TK7WINyx8JT0QMml1xkSm5hid8pjpOWvQYy1sVg,4563
+yarbo_robot_sdk/client.py,sha256=RGB08NIGUZMwludNmS4IiMQ08LJEKzd8YKBJgbiKTBE,16301
+yarbo_robot_sdk/codec.py,sha256=odW6vnUh3Lclzp0svlo5wY_jO6axj-N2KSlZNRgi5V8,2678
+yarbo_robot_sdk/config.py,sha256=OGhdvYZEjFliRvDym3ZG-ZO_fEMh5q2DdqoeSLKgBP4,383
+yarbo_robot_sdk/config_provider.py,sha256=ur3VfS_6W6Hhxb8VMiQHTxYe7Kin3tgXjJbajpTG9Jo,2539
+yarbo_robot_sdk/device_helpers.py,sha256=fD5UCTtyi9956BFA6c9R06h9vcyTAmRlwxp-zM1dCo0,10047
+yarbo_robot_sdk/device_registry.py,sha256=wSPeyj1tc82mfYo8u1-KxoWKSv6e5FbEETGReqx8zAU,9395
+yarbo_robot_sdk/endpoints.py,sha256=0_kVOmmWH_J9hqBaKrM5mUNzcHRMXdc2dRvZXQ2cULU,164
+yarbo_robot_sdk/exceptions.py,sha256=8eMKgWdhDR0sev4RhgZcMTamIGCyR5UESjSalDMQrOQ,633
+yarbo_robot_sdk/models.py,sha256=vKHY5tHpeqXZRDHYH_3KUvqsl_CKuFFPOG-VOyFlQMM,3619
+yarbo_robot_sdk/mqtt_client.py,sha256=ayYGsf6N-cmuQfaF5zZrlz0t7Ql0y4dry6INrX4HfqY,5765
+yarbo_robot_sdk/rest_client.py,sha256=n5w4b8t9tcKi9ejNprymDobGNybjF-IbSF2F2Z4xkL0,2220
+yarbo_robot_sdk/devices/yarbo_Y.json,sha256=91ytut2UHAod42HdjmTcuDvYcngo2E37zPLe3Uzdbps,10938
+yarbo_data_sdk-0.1.0.dist-info/METADATA,sha256=AGdQhbtmxDnIgxwf6sxJ1EemKLkS4FB4QoHSSCDFOnk,5976
+yarbo_data_sdk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+yarbo_data_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=89cswvj-Zn7s_llS9OEkvKgTAOXDhJy65tJwqzV4ROs,1062
+yarbo_data_sdk-0.1.0.dist-info/RECORD,,

yarbo_data_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

yarbo_data_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yarbo
+
+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.

yarbo_robot_sdk/__init__.py

@@ -0,0 +1,33 @@
+"""Yarbo Robot SDK - Python SDK for Yarbo robot devices."""
+
+from yarbo_robot_sdk.client import YarboClient
+from yarbo_robot_sdk.device_helpers import (
+    convert_local_to_gps,
+    convert_map_to_geojson,
+    extract_active_network,
+    extract_field,
+)
+from yarbo_robot_sdk.device_registry import (
+    get_control_field_definitions,
+    get_field_definitions,
+)
+from yarbo_robot_sdk.exceptions import (
+    AuthenticationError,
+    TokenExpiredError,
+    YarboSDKError,
+)
+from yarbo_robot_sdk.models import Device
+
+__all__ = [
+    "YarboClient",
+    "YarboSDKError",
+    "AuthenticationError",
+    "TokenExpiredError",
+    "Device",
+    "get_field_definitions",
+    "get_control_field_definitions",
+    "extract_field",
+    "extract_active_network",
+    "convert_local_to_gps",
+    "convert_map_to_geojson",
+]

yarbo_robot_sdk/auth.py

@@ -0,0 +1,121 @@
+"""Authentication manager — login, token refresh, RSA password encryption."""
+
+import base64
+
+import requests
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding
+
+from yarbo_robot_sdk import endpoints
+from yarbo_robot_sdk.config import REQUEST_TIMEOUT
+from yarbo_robot_sdk.exceptions import (
+    AuthenticationError,
+    TokenExpiredError,
+    YarboSDKError,
+)
+
+
+class AuthManager:
+    """Manages authentication lifecycle: login, token storage, refresh."""
+
+    def __init__(self, api_base_url: str, rsa_public_key: str):
+        self._api_base_url = api_base_url
+        self._rsa_public_key = rsa_public_key
+        self._username: str | None = None
+        self._token: str | None = None
+        self._refresh_token: str | None = None
+
+    def login(self, username: str, password: str) -> None:
+        """Encrypt password with RSA and call the login endpoint."""
+        if not username:
+            raise AuthenticationError("Username must not be empty")
+        if not password:
+            raise AuthenticationError("Password must not be empty")
+
+        encrypted_password = self._encrypt_password(password)
+        try:
+            resp = requests.post(
+                f"{self._api_base_url}{endpoints.AUTH_LOGIN}",
+                json={"username": username, "password": encrypted_password},
+                timeout=REQUEST_TIMEOUT,
+            )
+        except requests.RequestException as exc:
+            raise YarboSDKError(f"Login request failed: {exc}") from exc
+
+        if resp.status_code == 401:
+            raise AuthenticationError("Invalid username or password")
+        if not resp.ok:
+            raise YarboSDKError(f"Login failed with status {resp.status_code}: {resp.text}")
+
+        data = resp.json()
+        payload = data.get("data", data)  # Support {"code":0,"data":{...}} wrapper
+        self._username = username.lower()
+        self._token = payload.get("accessToken") or payload.get("token")
+        self._refresh_token = payload.get("refreshToken") or payload.get("refresh_token")
+
+    def refresh(self) -> None:
+        """Use refresh_token to obtain a new token."""
+        if not self._refresh_token:
+            raise TokenExpiredError("No refresh token available, please login again")
+
+        try:
+            resp = requests.post(
+                f"{self._api_base_url}{endpoints.AUTH_REFRESH}",
+                json={"refresh_token": self._refresh_token},
+                timeout=REQUEST_TIMEOUT,
+            )
+        except requests.RequestException as exc:
+            raise YarboSDKError(f"Token refresh request failed: {exc}") from exc
+
+        if resp.status_code == 401:
+            raise TokenExpiredError("Refresh token expired, please login again")
+        if not resp.ok:
+            raise YarboSDKError(f"Token refresh failed with status {resp.status_code}")
+
+        data = resp.json()
+        payload = data.get("data", data)  # Support {"code":0,"data":{...}} wrapper
+        self._token = payload.get("accessToken") or payload.get("token")
+        new_refresh = payload.get("refreshToken") or payload.get("refresh_token")
+        if new_refresh:
+            self._refresh_token = new_refresh  # Auth0 Refresh Token Rotation
+
+    def restore(self, username: str, token: str, refresh_token: str) -> None:
+        """Restore a previous session from saved tokens."""
+        self._username = username.lower()
+        self._token = token
+        self._refresh_token = refresh_token
+
+    @property
+    def username(self) -> str | None:
+        return self._username
+
+    @property
+    def token(self) -> str | None:
+        return self._token
+
+    @property
+    def refresh_token(self) -> str | None:
+        return self._refresh_token
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._token is not None
+
+    def _encrypt_password(self, password: str) -> str:
+        """Encrypt password using RSA-OAEP + SHA-256, return base64-encoded ciphertext."""
+        try:
+            public_key = serialization.load_pem_public_key(
+                self._rsa_public_key.encode()
+            )
+        except Exception as exc:
+            raise YarboSDKError(f"Invalid RSA public key: {exc}") from exc
+
+        ciphertext = public_key.encrypt(
+            password.encode(),
+            padding.OAEP(
+                mgf=padding.MGF1(algorithm=hashes.SHA256()),
+                algorithm=hashes.SHA256(),
+                label=None,
+            ),
+        )
+        return base64.b64encode(ciphertext).decode()