python-yarbo 0.1.0__py3-none-any.whl

python_yarbo-0.1.0.dist-info/METADATA

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: python-yarbo
+Version: 0.1.0
+Summary: Python library for local and cloud control of Yarbo robot mowers via MQTT
+Project-URL: Homepage, https://github.com/markus-lassfolk/python-yarbo
+Project-URL: Repository, https://github.com/markus-lassfolk/python-yarbo
+Project-URL: Bug Tracker, https://github.com/markus-lassfolk/python-yarbo/issues
+Project-URL: Documentation, https://github.com/markus-lassfolk/python-yarbo#readme
+Project-URL: Changelog, https://github.com/markus-lassfolk/python-yarbo/blob/main/CHANGELOG.md
+Project-URL: yarbo-reversing, https://github.com/markus-lassfolk/yarbo-reversing
+Author: Markus Lassfolk
+License: MIT
+License-File: LICENSE
+Keywords: iot,mower,mqtt,robot,smart-home,snow-blower,yarbo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: paho-mqtt>=2.0
+Requires-Dist: sentry-sdk>=2.0
+Provides-Extra: cloud
+Requires-Dist: cryptography>=42.0; extra == 'cloud'
+Provides-Extra: dev
+Requires-Dist: bandit[toml]>=1.7; extra == 'dev'
+Requires-Dist: cryptography>=42.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-aiofiles; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# python-yarbo
+
+[![CI](https://github.com/markus-lassfolk/python-yarbo/actions/workflows/ci.yml/badge.svg)](https://github.com/markus-lassfolk/python-yarbo/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/python-yarbo.svg)](https://pypi.org/project/python-yarbo/)
+[![Python versions](https://img.shields.io/pypi/pyversions/python-yarbo.svg)](https://pypi.org/project/python-yarbo/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Python library for **local and cloud control** of [Yarbo](https://yarbo.com/) robot
+mowers and snow blowers — built from reverse-engineered protocol knowledge.
+
+> **Status**: Alpha (0.1.0) — local MQTT control is functional and confirmed working
+> on hardware. Cloud API is partially functional (JWT auth migration in progress).
+
+## Features
+
+- 🔌 **Local MQTT control** — no cloud account required
+- 💡 **Full LED control** — 7 independent channels (head, fill, body, tail)
+- 🔊 **Buzzer control**
+- 🌨️ **Snow chute direction** (snow blower models)
+- 📡 **Live telemetry stream** — battery, state, position, heading
+- 🔍 **Auto-discovery** — finds Yarbo brokers on your local network
+- ☁️ **Cloud API** — robot management, scheduling, notifications
+- ⚡ **Async-first** — built on asyncio with sync wrappers for scripts
+- 🏠 **Home Assistant ready** — see [`home-assistant-yarbo`](https://github.com/markus-lassfolk/home-assistant-yarbo) (coming soon)
+
+## Requirements
+
+- Python ≥ 3.11
+- Same WiFi network as the robot (for local control)
+- `paho-mqtt` ≥ 2.0 (included)
+- `aiohttp` ≥ 3.9 (included)
+
+## Installation
+
+```bash
+pip install python-yarbo
+```
+
+For cloud API features (RSA password encryption):
+
+```bash
+pip install "python-yarbo[cloud]"
+```
+
+## Quick Start
+
+### Async (recommended)
+
+```python
+import asyncio
+from yarbo import YarboClient
+
+async def main():
+    async with YarboClient(broker="192.168.1.24", sn="24400102L8HO5227") as client:
+        # Get a telemetry snapshot
+        status = await client.get_status()
+        if status:
+            print(f"Battery: {status.battery}%  State: {status.state}")
+
+        # Light control
+        await client.lights_on()
+        await asyncio.sleep(2)
+        await client.lights_off()
+
+        # Buzzer
+        await client.buzzer(state=1)
+
+        # Live telemetry stream
+        async for telemetry in client.watch_telemetry():
+            print(f"Battery: {telemetry.battery}%  Heading: {telemetry.heading}°")
+            if telemetry.battery and telemetry.battery < 20:
+                print("Low battery!")
+                break
+
+asyncio.run(main())
+```
+
+### Sync (scripts / REPL)
+
+```python
+from yarbo import YarboClient
+
+client = YarboClient.connect_sync(broker="192.168.1.24", sn="24400102L8HO5227")
+client.lights_on()
+client.buzzer()
+client.disconnect()
+```
+
+### Auto-discovery
+
+```python
+import asyncio
+from yarbo import discover_yarbo, YarboClient
+
+async def main():
+    print("Scanning for Yarbo robots...")
+    robots = await discover_yarbo()
+
+    if not robots:
+        print("No robots found")
+        return
+
+    print(f"Found: {robots[0]}")
+    async with YarboClient(broker=robots[0].broker_host, sn=robots[0].sn) as client:
+        await client.lights_on()
+
+asyncio.run(main())
+```
+
+### Cloud login (account management)
+
+```python
+import asyncio
+from yarbo import YarboCloudClient
+
+async def main():
+    async with YarboCloudClient(
+        username="your@email.com",
+        password="yourpassword",
+        rsa_key_path="/path/to/rsa_public_key.pem",  # from APK
+    ) as client:
+        robots = await client.list_robots()
+        for robot in robots:
+            print(f"{robot.sn}: {robot.name} (online: {robot.is_online})")
+
+        version = await client.get_latest_version()
+        print(f"App: {version['appVersion']}  Firmware: {version['firmwareVersion']}")
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### `YarboClient` (hybrid)
+
+| Method | Description |
+|--------|-------------|
+| `async with YarboClient(broker, sn)` | Connect via async context manager |
+| `await client.get_status()` | Single telemetry snapshot → `YarboTelemetry` |
+| `await client.watch_telemetry()` | Async generator of `YarboTelemetry` |
+| `await client.lights_on()` | All LEDs → 255 |
+| `await client.lights_off()` | All LEDs → 0 |
+| `await client.set_lights(YarboLightState)` | Per-channel LED control |
+| `await client.buzzer(state=1)` | Buzzer on (1) or off (0) |
+| `await client.set_chute(vel)` | Snow chute direction |
+| `await client.get_controller()` | Acquire controller role (auto-called) |
+| `await client.publish_raw(cmd, payload)` | Arbitrary MQTT command |
+| `await client.list_robots()` | Cloud: bound robots |
+| `YarboClient.connect_sync(broker, sn)` | Sync wrapper factory |
+
+### `YarboLocalClient` (MQTT-only)
+
+Same interface as `YarboClient`, local only, no cloud features.
+
+### `YarboLightState`
+
+```python
+from yarbo import YarboLightState
+
+# All on
+state = YarboLightState.all_on()
+
+# Custom
+state = YarboLightState(
+    led_head=255,      # Front white
+    led_left_w=128,    # Left fill white
+    led_right_w=128,   # Right fill white
+    body_left_r=255,   # Left body red
+    body_right_r=255,  # Right body red
+    tail_left_r=0,     # Left tail red
+    tail_right_r=0,    # Right tail red
+)
+async with YarboClient(...) as client:
+    await client.set_lights(state)
+```
+
+### `YarboTelemetry`
+
+Parsed from `DeviceMSG` nested schema (`BatteryMSG`, `StateMSG`, `RTKMSG`, `CombinedOdom`).
+
+| Field | Type | Source | Description |
+|-------|------|--------|-------------|
+| `battery` | `int \| None` | `BatteryMSG.capacity` | State of charge (0–100 %) |
+| `state` | `str \| None` | derived | `"idle"` or `"active"` |
+| `working_state` | `int \| None` | `StateMSG.working_state` | Raw state (0=idle, 1=active) |
+| `charging_status` | `int \| None` | `StateMSG.charging_status` | 2 = charging/docked |
+| `error_code` | `int \| str \| None` | `StateMSG.error_code` | Active fault code |
+| `heading` | `float \| None` | `RTKMSG.heading` | Compass heading (degrees) |
+| `position_x` | `float \| None` | `CombinedOdom.x` | Odometry X (metres) |
+| `position_y` | `float \| None` | `CombinedOdom.y` | Odometry Y (metres) |
+| `phi` | `float \| None` | `CombinedOdom.phi` | Odometry heading (radians) |
+| `speed` | `float \| None` | flat | Current speed (m/s) |
+| `raw` | `dict` | — | Complete raw DeviceMSG dict |
+
+## Cloud vs Local
+
+| Feature | Local MQTT | Cloud REST |
+|---------|-----------|------------|
+| Robot control (lights, buzzer, …) | ✅ Yes | ❌ No |
+| Live telemetry | ✅ Yes | ❌ No |
+| List bound robots | ❌ No | ✅ Yes |
+| Account management | ❌ No | ✅ Yes |
+| Robot rename / bind / unbind | ❌ No | ✅ Yes |
+| Notifications | ❌ No | ✅ Yes |
+| Works offline | ✅ Yes | ❌ No |
+| Requires cloud account | ❌ No | ✅ Yes |
+
+> **⚠️ Cloud MQTT not implemented.** The Yarbo backend also provides a Tencent
+> TDMQ MQTT broker (`mqtt-b8rkj5da-usw-public.mqtt.tencenttdmq.com:8883`) for
+> remote control without LAN access. This library does **not** implement cloud
+> MQTT — there is no remote-control fallback. All robot commands go via the
+> local broker only.
+
+## Security Notes
+
+> ⚠️ **The Yarbo local MQTT broker accepts anonymous connections without
+> authentication.** Anyone on your WiFi network can connect and send commands
+> to your robot.
+
+Recommendations:
+- Keep the robot on a dedicated IoT VLAN and firewall it from the internet.
+- Do **not** port-forward port 1883 to the internet.
+- Consider a firewall rule that allows only your home automation host to reach
+  port 1883 on the robot's IP.
+
+## Protocol Notes
+
+This library was built from reverse-engineering the Yarbo Flutter app and
+live packet captures. Key protocol facts:
+
+- **MQTT broker**: Local EMQX at `192.168.1.24:1883` or `192.168.1.55:1883`
+  (check which IP your robot uses — both have been observed in production)
+- **Payload encoding**: `zlib.compress(json.dumps(payload).encode())`
+  (exception: `heart_beat` topic uses plain uncompressed JSON)
+- **Controller handshake**: `get_controller` must be sent before action commands
+- **Topics**: `snowbot/{SN}/app/{cmd}` (publish) and
+  `snowbot/{SN}/device/{feedback}` (subscribe)
+- **Telemetry topic**: `DeviceMSG` (~1–2 Hz) with nested schema:
+  `BatteryMSG.capacity`, `StateMSG.working_state`, `RTKMSG.heading`,
+  `CombinedOdom.x/y/phi`
+- **Not yet implemented**: Local REST API (port 8088) and TCP JSON (port 22220)
+  are documented in `yarbo-reversing` but not implemented here
+
+See [`yarbo-reversing`](https://github.com/markus-lassfolk/yarbo-reversing) for:
+- Full [command catalogue](https://github.com/markus-lassfolk/yarbo-reversing/blob/main/docs/COMMAND_CATALOGUE.md)
+- [Light control protocol](https://github.com/markus-lassfolk/yarbo-reversing/blob/main/docs/LIGHT_CTRL_PROTOCOL.md)
+- [API endpoints](https://github.com/markus-lassfolk/yarbo-reversing/blob/main/docs/API_ENDPOINTS.md)
+- [MQTT protocol reference](https://github.com/markus-lassfolk/yarbo-reversing/blob/main/docs/MQTT_PROTOCOL.md)
+
+## Related Projects
+
+| Project | Description |
+|---------|-------------|
+| [`yarbo-reversing`](https://github.com/markus-lassfolk/yarbo-reversing) | Protocol RE: Frida scripts, MITM setup, APK tools |
+| [`PSYarbo`](https://github.com/markus-lassfolk/PSYarbo) | PowerShell module (same protocol, same architecture) |
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Disclaimer
+
+This library was built by reverse engineering. It is not affiliated with or endorsed by
+Yarbo. Use at your own risk. Do not expose your robot's MQTT broker to the internet.

python_yarbo-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+yarbo/__init__.py,sha256=Hzz1uzSNFF_M7kGI7RVwgu3xASJr2dJ_LCzgy8elk7Y,3047
+yarbo/_codec.py,sha256=iyfn34p-LeHWJrNaKHVX6rAMyRrYG43W8ip03Madnu0,1944
+yarbo/auth.py,sha256=t6nP_DrKCWGNENimPR2VbK3X0Ifr4wpO8qdJJRJUE70,9413
+yarbo/client.py,sha256=o2lV9P5NAVxXXw7Xd5zx5g3SUG2yS5mkQvnBlSYLhOc,27539
+yarbo/cloud.py,sha256=DBwC7gm2nA0G0o1iPv2xWJV3vm68rHvkz5qUVG04r_8,10032
+yarbo/cloud_mqtt.py,sha256=_8fiB9mA51fdaPltlHSmi8G52abvzV90WFB7R76mpN0,4260
+yarbo/const.py,sha256=qf9SRZ8kWmZVoyvc4eargSqcu1lVYyJiyyNByYbuxd8,6896
+yarbo/discovery.py,sha256=pMy1hIkC_GyyUTd-KFXbHEVtkRRu-awCog5aDDbS6VE,7368
+yarbo/error_reporting.py,sha256=9GpLnPD0eDG5q9Ifitg2c0eqWLBisf1utSOJi9E0_VE,3195
+yarbo/exceptions.py,sha256=UQ5dg48YTx4DlVGnDepP-FA9Jxt4BkV3v4Wh_PmBbas,3443
+yarbo/local.py,sha256=Wp-M95hXVsh5GFgDkgR-Cw1bC2kzbGBAPxImEJcJP4A,59737
+yarbo/models.py,sha256=PTuNj19OX7mZ-xzxEHzVrYGMc5n3dskUDIpYzhRKzL4,26033
+yarbo/mqtt.py,sha256=mMlqpRV-lXN3_p28UtR0b4m46u4BX961QS5PvW5hwpg,20063
+yarbo/keys/README.md,sha256=2vDNU2O66QNO5FwLIw6vfeWJrRg5DeyIA95gmmpdNmU,1150
+python_yarbo-0.1.0.dist-info/METADATA,sha256=mQz2W1zkrB1RHblYTMUoQVrthsC3swnIWcn9GR7vnh8,11560
+python_yarbo-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_yarbo-0.1.0.dist-info/licenses/LICENSE,sha256=hnpk3bWclcT3ci3znvjdHFo112rtbsgEUwccm75AqT8,1072
+python_yarbo-0.1.0.dist-info/RECORD,,

python_yarbo-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

python_yarbo-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Markus Lassfolk
+
+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/__init__.py

@@ -0,0 +1,122 @@
+"""
+yarbo — Python library for local and cloud control of Yarbo robot mowers.
+
+Yarbo makes autonomous snow blowers and lawn mowers controlled via local MQTT.
+This library was built from reverse-engineering the Yarbo Flutter app and
+probing the protocol with live hardware captures.
+
+Quick start (async)::
+
+    import asyncio
+    from yarbo import YarboClient
+
+    async def main():
+        async with YarboClient(broker="192.168.1.24", sn="24400102L8HO5227") as client:
+            status = await client.get_status()
+            print(f"Battery: {status.battery}%")
+            await client.lights_on()
+            await client.buzzer()
+
+    asyncio.run(main())
+
+Quick start (sync)::
+
+    from yarbo import YarboClient
+
+    client = YarboClient.connect(broker="192.168.1.24", sn="24400102L8HO5227")
+    client.lights_on()
+    client.disconnect()
+
+Auto-discovery::
+
+    import asyncio
+    from yarbo import discover_yarbo, YarboClient
+
+    async def main():
+        robots = await discover_yarbo()
+        if robots:
+            async with YarboClient(broker=robots[0].broker_host, sn=robots[0].sn) as client:
+                await client.lights_on()
+
+    asyncio.run(main())
+
+See README.md for full documentation.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__author__ = "Markus Lassfolk"
+__license__ = "MIT"
+
+from ._codec import decode, encode
+from .client import YarboClient
+from .cloud import YarboCloudClient
+from .cloud_mqtt import YarboCloudMqttClient
+from .const import Topic
+from .discovery import DiscoveredRobot, discover_yarbo
+from .error_reporting import init_error_reporting
+from .exceptions import (
+    YarboAuthError,
+    YarboCommandError,
+    YarboConnectionError,
+    YarboError,
+    YarboNotControllerError,
+    YarboProtocolError,
+    YarboTimeoutError,
+    YarboTokenExpiredError,
+)
+from .local import YarboLocalClient
+from .models import (
+    HeadType,
+    TelemetryEnvelope,
+    YarboCommandResult,
+    YarboLightState,
+    YarboPlan,
+    YarboPlanParams,
+    YarboRobot,
+    YarboSchedule,
+    YarboTelemetry,
+)
+
+__all__ = [  # noqa: RUF022 — grouped by category, alphabetical within each
+    # Version
+    "__version__",
+    # Codec helpers
+    "decode",
+    "encode",
+    # Error reporting
+    "init_error_reporting",
+    # Discovery
+    "DiscoveredRobot",
+    "discover_yarbo",
+    # Topic helper
+    "Topic",
+    # Models (alphabetical)
+    "HeadType",
+    "TelemetryEnvelope",
+    "YarboCommandResult",
+    "YarboLightState",
+    "YarboPlan",
+    "YarboPlanParams",
+    "YarboRobot",
+    "YarboSchedule",
+    "YarboTelemetry",
+    # Clients (alphabetical)
+    "YarboClient",
+    "YarboCloudClient",
+    "YarboCloudMqttClient",
+    "YarboLocalClient",
+    # Exceptions (alphabetical)
+    "YarboAuthError",
+    "YarboCommandError",
+    "YarboConnectionError",
+    "YarboError",
+    "YarboNotControllerError",
+    "YarboProtocolError",
+    "YarboTimeoutError",
+    "YarboTokenExpiredError",
+]
+
+# Opt-out error reporting: enabled by default, disable via YARBO_SENTRY_DSN=""
+init_error_reporting()

yarbo/_codec.py

@@ -0,0 +1,63 @@
+"""
+yarbo._codec — zlib encode/decode helpers for MQTT payloads.
+
+All MQTT payloads in the Yarbo protocol are zlib-compressed JSON.
+The robot firmware checks the firmware version (>= 3.9.0, MIN_ZIP_MQTT_VERSION)
+before decompressing. All current firmware versions use zlib compression.
+
+Reference: Blutter ASM analysis of the Flutter app's MqttPublish class.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, cast
+import zlib
+
+
+def encode(payload: dict[str, Any]) -> bytes:
+    """
+    Encode a Python dict to a zlib-compressed JSON byte string.
+
+    This is the wire format for ALL MQTT publishes to the Yarbo broker.
+
+    Args:
+        payload: Dict to encode (must be JSON-serialisable).
+
+    Returns:
+        Compressed bytes ready to publish.
+
+    Example::
+
+        from yarbo._codec import encode, decode
+        raw = encode({"led_head": 255, "led_left_w": 255})
+        assert decode(raw) == {"led_head": 255, "led_left_w": 255}
+    """
+    return zlib.compress(json.dumps(payload, separators=(",", ":")).encode("utf-8"))
+
+
+def decode(data: bytes) -> dict[str, Any]:
+    """
+    Decode a zlib-compressed JSON byte string to a Python dict.
+
+    Falls back to plain JSON if decompression fails.
+
+    .. note:: ``heart_beat`` exception
+        The ``heart_beat`` topic delivers plain (uncompressed) JSON, e.g.
+        ``{"working_state": 0}``. The zlib fallback path handles this
+        transparently — no special case is needed in callers.
+
+    Args:
+        data: Raw bytes received from the MQTT broker.
+
+    Returns:
+        Decoded dict. Returns ``{"_raw": data.hex()}`` on total failure.
+    """
+    try:
+        return cast("dict[str, Any]", json.loads(zlib.decompress(data)))
+    except (zlib.error, json.JSONDecodeError):
+        pass
+    try:
+        return cast("dict[str, Any]", json.loads(data))
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        return {"_raw": data[:512].hex()}