Develop

[markus-lassfolk]

Summary

Closes #

Type of change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to change)
• 🧹 Refactor / code cleanup (no behaviour change)
• 📝 Documentation update
• ⚙️ CI/CD / tooling change

Changes made

Testing

• Added / updated pytest tests
• All tests pass locally (pytest tests/)
• Tested manually against Yarbo hardware (if applicable — describe setup below)

Quality checklist

• ruff lint: Zero errors (ruff check src/ tests/)
• ruff format: No formatting issues (ruff format --check src/ tests/)
• mypy: Zero new type errors (mypy src/yarbo/)
• Tests pass: pytest tests/ — all green
• CHANGELOG.md updated under [Unreleased]
• Docs updated (docstrings, README if API changed)
• No secrets, credentials, IP addresses, or serial numbers in code, comments, or commits
• Follows coding standards in CONTRIBUTING.md

Screenshots / output (optional)

---

Reviewer note: Branch must be up-to-date with develop and all CI checks must pass before merge.

---

Note

Medium Risk
Touches core MQTT transport/client code and adds many new robot control commands (including destructive operations), plus a small breaking API tweak (start_plan/chute steering params), so regressions would affect primary device control paths.

Overview
Adds GitHub CodeQL scanning for the Python codebase with a custom config that ignores tests/ + archive/ and suppresses several privacy/info-exposure query categories.

Expands the local control surface substantially by adding many typed MQTT command helpers to YarboLocalClient and delegating equivalents on YarboClient (robot power/emergency controls, lighting/sound, camera/detection, plans/schedules, navigation/maps, WiFi, diagnostics, OTA, safety/fencing, and map/plan destructive operations with confirm gates). This includes a new _request_data_feedback helper to standardize request/response handling.

Adjusts packaging and telemetry/error tooling: makes sentry-sdk an optional extra, switches error reporting from opt-out to opt-in via env vars, strengthens breadcrumb scrubbing, and updates MQTT TLS setup/connection flow (including using tls_set_context). Tests are updated/added to cover the new command methods and revised TLS/error-reporting behavior.

^{Written by Cursor Bugbot for commit 3daca57. This will update automatically on new commits. Configure here.}

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for all 3 issues found in the latest run.

• ✅ Fixed: Duplicate publish_command shadows no-controller-check variant
  • Removed the duplicate publish_command method at line 1255 that was shadowing the no-controller-check variant, restoring the intended coordinator-friendly behavior.
• ✅ Fixed: sentry-sdk required despite new optional dependency group
  • Removed sentry-sdk from mandatory dependencies in pyproject.toml, making error reporting truly optional via the [sentry] extra group.
• ✅ Fixed: Breadcrumb scrubbing removed from Sentry event filter
  • Restored breadcrumb scrubbing logic to redact sensitive data from breadcrumb messages and data fields, preventing credential leakage in error reports.

Preview (5a33dc8031)

diff --git a/pyproject.toml b/pyproject.toml
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -25,7 +25,6 @@
 dependencies = [
     "paho-mqtt>=2.0",
     "aiohttp>=3.9",
-    "sentry-sdk>=2.0",
 ]
 
 [project.optional-dependencies]

diff --git a/src/yarbo/error_reporting.py b/src/yarbo/error_reporting.py
--- a/src/yarbo/error_reporting.py
+++ b/src/yarbo/error_reporting.py
@@ -4,6 +4,7 @@
 
 import logging
 import os
+import re
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -47,7 +48,7 @@
         return
 
     try:
-        import sentry_sdk
+        import sentry_sdk  # noqa: PLC0415
 
         sentry_sdk.init(
             dsn=effective_dsn,
@@ -64,26 +65,50 @@
         _LOGGER.debug("Error reporting initialized (dsn=%s...)", effective_dsn[:30])
     except ImportError:
         _LOGGER.debug("sentry-sdk not installed; error reporting disabled")
-    except Exception as exc:
+    except Exception as exc:  # noqa: BLE001
         _LOGGER.warning("Failed to initialize error reporting: %s", exc)
 
 
 # Non-sensitive field names that contain "_key" but must not be redacted.
 _KEY_ALLOWLIST: frozenset[str] = frozenset({"entity_key"})
 
+# Pattern to detect key-like strings in breadcrumb messages (e.g., "apikey", "access_key")
+_SCRUB_KEY_PATTERN = re.compile(r"(?:_|api|access|auth|private)key", re.IGNORECASE)
 
+
+def _is_sensitive_key(key_lower: str) -> bool:
+    """Check if a key name looks sensitive and should be redacted."""
+    if any(s in key_lower for s in ("password", "token", "secret", "credential")):
+        return True
+    if key_lower in _KEY_ALLOWLIST:
+        return False
+    return (
+        key_lower == "key"
+        or "_key" in key_lower
+        or key_lower.startswith("key_")
+        or key_lower.endswith("key")
+    )
+
+
 def _scrub_event(event: dict, hint: dict) -> dict:  # type: ignore[type-arg]
     """Remove sensitive data before sending."""
     if "extra" in event:
         for key in list(event["extra"]):
-            key_lower = key.lower()
-            if any(s in key_lower for s in ("password", "token", "secret", "credential")):
+            if _is_sensitive_key(key.lower()):
                 event["extra"][key] = "[REDACTED]"
-            elif (
-                key_lower == "key"
-                or "_key" in key_lower
-                or key_lower.startswith("key_")
-                or key_lower.endswith("key")
-            ) and key_lower not in _KEY_ALLOWLIST:
-                event["extra"][key] = "[REDACTED]"
+
+    if "breadcrumbs" in event and "values" in event["breadcrumbs"]:
+        for breadcrumb in event["breadcrumbs"]["values"]:
+            if "message" in breadcrumb:
+                msg = str(breadcrumb["message"])
+                msg_lower = msg.lower()
+                keywords = ("password", "token", "secret", "credential")
+                sensitive = any(s in msg_lower for s in keywords)
+                if sensitive or _SCRUB_KEY_PATTERN.search(msg):
+                    breadcrumb["message"] = "[REDACTED]"
+            if "data" in breadcrumb and isinstance(breadcrumb["data"], dict):
+                for key in list(breadcrumb["data"]):
+                    if _is_sensitive_key(key.lower()):
+                        breadcrumb["data"][key] = "[REDACTED]"
+
     return event

diff --git a/src/yarbo/local.py b/src/yarbo/local.py
--- a/src/yarbo/local.py
+++ b/src/yarbo/local.py
@@ -1251,16 +1251,6 @@
         await self._ensure_controller()
         await self._transport.publish(cmd, payload)
 
-
-    async def publish_command(self, cmd: str, payload: dict[str, Any]) -> None:
-        """Alias for :meth:`publish_raw` — publish an arbitrary command to the robot.
-
-        Args:
-            cmd:     Topic leaf (e.g. ``"set_blade_height"``).
-            payload: Dict payload (will be zlib-encoded).
-        """
-        await self.publish_raw(cmd, payload)
-
     # ------------------------------------------------------------------
     # Blade / mowing configuration
     # ------------------------------------------------------------------

[Copilot]

Pull request overview

This PR expands the typed, method-based API surface for controlling Yarbo devices over local MQTT, adds/updates unit tests around the new commands, and updates CI/security tooling (pip-audit, CodeQL), alongside changes to error reporting defaults.

Changes:

• Add many new typed command methods to YarboLocalClient and delegate them through YarboClient.
• Add extensive unit test coverage for the new typed commands and a small fix to cloud MQTT default-username testing.
• Update MQTT connection behavior and enhance repository security automation (pip-audit workflow changes, add CodeQL).

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
tests/test_typed_commands.py	New unit tests for newly added typed command methods + YarboClient delegation spot-checks.
tests/test_cloud_mqtt.py	Ensure default username test is deterministic by clearing env var.
src/yarbo/mqtt.py	Run paho connect() off the event loop to avoid blocking.
src/yarbo/local.py	Add many typed command helpers + a generic data_feedback helper + raw publish helpers.
src/yarbo/client.py	Add delegation methods mirroring the new local typed API.
src/yarbo/error_reporting.py	Change Sentry/GlitchTip initialization behavior and simplify scrubbing logic.
src/yarbo/init.py	Update package-level description docstring.
pyproject.toml	Bump version/description and add optional dependency group.
README.md	Update project positioning text (local control) and disclaimer wording.
.github/workflows/security.yml	Change pip-audit invocation approach.
.github/workflows/codeql.yml	Add CodeQL analysis workflow.
.github/workflows/ci.yml	Adjust gate job shell checks.
.github/codeql/codeql-config.yml	Configure CodeQL query filters and ignored paths.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for all 3 issues found in the latest run.

• ✅ Resolved by another fix: Duplicate _DEFAULT_DSN definition with stale comments
  • This bug was already fixed in a previous commit on the fix/bug-detection-issues branch before this autofix run.
• ✅ Resolved by another fix: Comment claims opt-in but code is opt-out
  • This bug was already fixed in a previous commit on the fix/bug-detection-issues branch before this autofix run.
• ✅ Fixed: Removed local methods break client facade delegation
  • Restored all seven missing methods (check_camera_status, camera_calibration, firmware_update_now, firmware_update_tonight, firmware_update_later, get_saved_wifi_list, bag_record) to YarboLocalClient.

Preview (ba106badb3)

diff --git a/.github/codeql/codeql-config.yml b/.github/codeql/codeql-config.yml
new file mode 100644
--- /dev/null
+++ b/.github/codeql/codeql-config.yml
@@ -1,0 +1,20 @@
+name: "Yarbo CodeQL Config"
+
+# Disable queries that flag core IoT features as privacy issues
+# GPS coordinates, IP addresses, MAC addresses, and hostnames are
+# fundamental to robot mower discovery and control — not PII leaks.
+query-filters:
+  - exclude:
+      tags contain: security/cwe/cwe-532  # Clear-text logging (we handle this ourselves)
+  - exclude:
+      tags contain: security/cwe/cwe-359  # Privacy violation (GPS, IP, MAC are core features)
+  - exclude:
+      tags contain: security/cwe/cwe-200  # Information exposure (device telemetry is the product)
+  - exclude:
+      id: py/clear-text-logging-sensitive-data
+  - exclude:
+      id: py/clear-text-storage-sensitive-data
+
+paths-ignore:
+  - tests
+  - archive

diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
new file mode 100644
--- /dev/null
+++ b/.github/workflows/codeql.yml
@@ -1,0 +1,27 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+permissions:
+  security-events: write
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        language: [python]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          config-file: .github/codeql/codeql-config.yml
+      - uses: github/codeql-action/autobuild@v3
+      - uses: github/codeql-action/analyze@v3

diff --git a/pyproject.toml b/pyproject.toml
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -25,10 +25,12 @@
 dependencies = [
     "paho-mqtt>=2.0",
     "aiohttp>=3.9",
-    "sentry-sdk>=2.0",
 ]
 
 [project.optional-dependencies]
+sentry = [
+    "sentry-sdk>=2.0",
+]
 cloud = [
     "cryptography>=42.0",
 ]

diff --git a/src/yarbo/__init__.py b/src/yarbo/__init__.py
--- a/src/yarbo/__init__.py
+++ b/src/yarbo/__init__.py
@@ -1,5 +1,5 @@
 """
-yarbo — Python library for local and cloud control of Yarbo robot mowers.
+yarbo — Python library for local control of Yarbo robot mowers and snow blowers via MQTT.
 
 Yarbo makes autonomous snow blowers and lawn mowers controlled via local MQTT.
 This is a community-developed library for the Yarbo protocol, built through
@@ -58,7 +58,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 __author__ = "Markus Lassfolk"
 __license__ = "MIT"
 

diff --git a/src/yarbo/_cli.py b/src/yarbo/_cli.py
--- a/src/yarbo/_cli.py
+++ b/src/yarbo/_cli.py
@@ -205,8 +205,8 @@
 
 def _maybe_report_mqtt(args: argparse.Namespace, client: YarboLocalClient) -> None:
     """If --report-mqtt was set, send captured MQTT dump to GlitchTip."""
-    if getattr(args, "report_mqtt", False):
-        report_mqtt_dump_to_glitchtip(client.get_captured_mqtt())
+    # MQTT capture functionality has been removed from YarboLocalClient
+    pass
 
 
 async def _with_client(
@@ -218,10 +218,6 @@
             broker=args.broker,
             sn=args.serial,
             port=getattr(args, "port", 1883),
-            mqtt_log_path=getattr(args, "log_mqtt", None),
-            debug=getattr(args, "debug", False),
-            debug_raw=getattr(args, "debug_raw", False),
-            mqtt_capture_max=_mqtt_capture_max(args),
         )
         await client.connect()
         try:
@@ -248,10 +244,6 @@
                 broker=ep.ip,
                 port=ep.port,
                 sn=ep.sn,
-                mqtt_log_path=getattr(args, "log_mqtt", None),
-                debug=getattr(args, "debug", False),
-                debug_raw=getattr(args, "debug_raw", False),
-                mqtt_capture_max=_mqtt_capture_max(args),
             )
             await client.connect()
         except (YarboError, OSError, TimeoutError) as e:

diff --git a/src/yarbo/client.py b/src/yarbo/client.py
--- a/src/yarbo/client.py
+++ b/src/yarbo/client.py
@@ -204,6 +204,300 @@
         """Publish an arbitrary MQTT command to the robot."""
         await self._local.publish_raw(cmd, payload)
 
+    async def publish_command(self, cmd: str, payload: dict[str, Any]) -> None:
+        """Alias for :meth:`publish_raw` — publish an arbitrary MQTT command to the robot."""
+        await self._local.publish_command(cmd, payload)
+
+    # -- Robot control --
+
+    async def shutdown(self) -> None:
+        """Power off the robot."""
+        await self._local.shutdown()
+
+    async def restart_container(self) -> None:
+        """Restart the EMQX container on the robot."""
+        await self._local.restart_container()
+
+    async def emergency_stop(self) -> None:
+        """Trigger an emergency stop."""
+        await self._local.emergency_stop()
+
+    async def emergency_unlock(self) -> None:
+        """Clear the emergency stop state."""
+        await self._local.emergency_unlock()
+
+    async def dstop(self) -> None:
+        """Soft-stop the robot (decelerate to halt)."""
+        await self._local.dstop()
+
+    async def resume(self) -> None:
+        """Resume operation after a pause or soft-stop."""
+        await self._local.resume()
+
+    async def cmd_recharge(self) -> None:
+        """Send the robot back to its charging dock."""
+        await self._local.cmd_recharge()
+
+    # -- Lights & sound --
+
+    async def set_head_light(self, enabled: bool) -> None:
+        """Enable or disable the head light."""
+        await self._local.set_head_light(enabled)
+
+    async def set_roof_lights(self, enabled: bool) -> None:
+        """Enable or disable the roof lights."""
+        await self._local.set_roof_lights(enabled)
+
+    async def set_laser(self, enabled: bool) -> None:
+        """Enable or disable the laser."""
+        await self._local.set_laser(enabled)
+
+    async def set_sound(self, volume: int, song_id: int = 0) -> None:
+        """Set the speaker volume (0-100)."""
+        await self._local.set_sound(volume, song_id)
+
+    async def play_song(self, song_id: int) -> None:
+        """Play a sound/song by ID."""
+        await self._local.play_song(song_id)
+
+    # -- Camera & detection --
+
+    async def set_camera(self, enabled: bool) -> None:
+        """Enable or disable the camera."""
+        await self._local.set_camera(enabled)
+
+    async def set_person_detect(self, enabled: bool) -> None:
+        """Enable or disable person detection."""
+        await self._local.set_person_detect(enabled)
+
+    async def set_usb(self, enabled: bool) -> None:
+        """Enable or disable the USB port."""
+        await self._local.set_usb(enabled)
+
+    # -- Plans & scheduling --
+
+    async def start_plan_direct(self, plan_id: int, percent: int = 100) -> None:
+        """Start a work plan by numeric ID (direct command, no response)."""
+        await self._local.start_plan_direct(plan_id, percent)
+
+    async def read_plan(self, plan_id: int, timeout: float = 5.0) -> dict[str, Any]:
+        """Request plan detail and await the data_feedback response."""
+        return await self._local.read_plan(plan_id, timeout)
+
+    async def read_all_plans(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request all plan summaries and await the data_feedback response."""
+        return await self._local.read_all_plans(timeout)
+
+    async def delete_plan_direct(self, plan_id: int, confirm: bool = False) -> None:
+        """Delete a plan by numeric ID. Pass confirm=True to proceed (destructive)."""
+        await self._local.delete_plan_direct(plan_id, confirm=confirm)
+
+    async def delete_all_plans(self, confirm: bool = False) -> None:
+        """Delete all stored plans from the robot. Pass confirm=True to proceed (destructive)."""
+        await self._local.delete_all_plans(confirm=confirm)
+
+    async def pause_planning(self) -> None:
+        """Pause the currently running plan (direct command, no response)."""
+        await self._local.pause_planning()
+
+    async def in_plan_action(self, action: str) -> None:
+        """Send an in-plan action command."""
+        await self._local.in_plan_action(action)
+
+    async def read_schedules(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request all schedules and await the data_feedback response."""
+        return await self._local.read_schedules(timeout)
+
+    # -- Navigation & maps --
+
+    async def start_waypoint(self, index: int) -> None:
+        """Start navigation to a waypoint by index."""
+        await self._local.start_waypoint(index)
+
+    async def read_recharge_point(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request the saved recharge/dock point and await the data_feedback response."""
+        return await self._local.read_recharge_point(timeout)
+
+    async def save_charging_point(self) -> None:
+        """Save the robot's current position as the charging/dock point."""
+        await self._local.save_charging_point()
+
+    async def read_clean_area(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request the clean area definition and await the data_feedback response."""
+        return await self._local.read_clean_area(timeout)
+
+    async def get_all_map_backup(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request all map backups and await the data_feedback response."""
+        return await self._local.get_all_map_backup(timeout)
+
+    async def save_map_backup(self) -> None:
+        """Save a backup of the current map."""
+        await self._local.save_map_backup()
+
+    # -- WiFi & connectivity --
+
+    async def get_wifi_list(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request the list of available WiFi networks and await the data_feedback response."""
+        return await self._local.get_wifi_list(timeout)
+
+    async def get_connected_wifi(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request the connected WiFi network name and await the data_feedback response."""
+        return await self._local.get_connected_wifi(timeout)
+
+    async def start_hotspot(self) -> None:
+        """Start the robot's WiFi hotspot."""
+        await self._local.start_hotspot()
+
+    async def get_hub_info(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request hub information and await the data_feedback response."""
+        return await self._local.get_hub_info(timeout)
+
+    # -- Diagnostics --
+
+    async def read_no_charge_period(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request no-charge period configuration and await the data_feedback response."""
+        return await self._local.read_no_charge_period(timeout)
+
+    async def get_battery_cell_temps(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request battery cell temperature data and await the data_feedback response."""
+        return await self._local.get_battery_cell_temps(timeout)
+
+    async def get_motor_temps(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request motor temperature data and await the data_feedback response."""
+        return await self._local.get_motor_temps(timeout)
+
+    async def get_body_current(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request body current telemetry and await the data_feedback response."""
+        return await self._local.get_body_current(timeout)
+
+    async def get_head_current(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request head current telemetry and await the data_feedback response."""
+        return await self._local.get_head_current(timeout)
+
+    async def get_speed(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request current speed telemetry and await the data_feedback response."""
+        return await self._local.get_speed(timeout)
+
+    async def get_odometer(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request odometer data and await the data_feedback response."""
+        return await self._local.get_odometer(timeout)
+
+    async def get_product_code(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request the product code and await the data_feedback response."""
+        return await self._local.get_product_code(timeout)
+
+    async def set_charge_limit(self, min_pct: int, max_pct: int) -> None:
+        """Set battery charge limits."""
+        await self._local.set_charge_limit(min_pct, max_pct)
+
+    async def set_turn_type(self, turn_type: int) -> None:
+        """Set the turning behaviour type."""
+        await self._local.set_turn_type(turn_type)
+
+    # -- Motor & mechanical --
+
+    async def set_motor_protect(self, state: int) -> None:
+        """Enable or disable motor protection mode."""
+        await self._local.set_motor_protect(state)
+
+    async def set_trimmer(self, state: int) -> None:
+        """Enable or disable the trimmer."""
+        await self._local.set_trimmer(state)
+
+    # -- Blowing / edge / smart features --
+
+    async def set_edge_blowing(self, state: int) -> None:
+        """Enable or disable edge blowing."""
+        await self._local.set_edge_blowing(state)
+
+    async def set_smart_blowing(self, state: int) -> None:
+        """Enable or disable smart blowing."""
+        await self._local.set_smart_blowing(state)
+
+    async def set_heating_film(self, state: int) -> None:
+        """Enable or disable heating film (anti-ice)."""
+        await self._local.set_heating_film(state)
+
+    async def set_module_lock(self, state: int) -> None:
+        """Lock or unlock an accessory module."""
+        await self._local.set_module_lock(state)
+
+    # -- Autonomous modes --
+
+    async def set_follow_mode(self, state: int) -> None:
+        """Enable or disable follow mode."""
+        await self._local.set_follow_mode(state)
+
+    async def set_draw_mode(self, state: int) -> None:
+        """Enable or disable draw/mapping mode."""
+        await self._local.set_draw_mode(state)
+
+    # -- OTA / firmware updates --
+
+    async def set_auto_update(self, state: int) -> None:
+        """Enable or disable automatic firmware (Greengrass) updates."""
+        await self._local.set_auto_update(state)
+
+    async def set_camera_ota(self, state: int) -> None:
+        """Enable or disable IP camera OTA updates."""
+        await self._local.set_camera_ota(state)
+
+    # -- Vision / recording --
+
+    async def set_smart_vision(self, state: int) -> None:
+        """Enable or disable smart vision processing."""
+        await self._local.set_smart_vision(state)
+
+    async def set_video_record(self, state: int) -> None:
+        """Enable or disable video recording."""
+        await self._local.set_video_record(state)
+
+    # -- Safety / fencing --
+
+    async def set_child_lock(self, state: int) -> None:
+        """Enable or disable the child lock."""
+        await self._local.set_child_lock(state)
+
+    async def set_geo_fence(self, state: int) -> None:
+        """Enable or disable geo-fencing."""
+        await self._local.set_geo_fence(state)
+
+    async def set_elec_fence(self, state: int) -> None:
+        """Enable or disable the electric fence."""
+        await self._local.set_elec_fence(state)
+
+    async def set_ngz_edge(self, state: int) -> None:
+        """Enable or disable NGZ edge enforcement."""
+        await self._local.set_ngz_edge(state)
+
+    # -- Manual drive extras --
+
+    async def set_velocity_manual(self, linear: float, angular: float) -> None:
+        """Send a velocity command in manual drive mode."""
+        await self._local.set_velocity_manual(linear, angular)
+
+    async def set_sound_param(self, volume: int, enabled: int) -> None:
+        """Set sound volume and enable/disable audio output."""
+        await self._local.set_sound_param(volume, enabled)
+
+    # -- Map management (destructive) --
+
+    async def erase_map(self, confirm: bool = False) -> None:
+        """Erase the robot's stored map. Pass confirm=True to proceed (destructive)."""
+        await self._local.erase_map(confirm=confirm)
+
+    async def map_recovery(self, map_id: str, confirm: bool = False) -> None:
+        """Restore a map from backup. Pass confirm=True to proceed (destructive)."""
+        await self._local.map_recovery(map_id, confirm=confirm)
+
+    async def save_current_map(self) -> None:
+        """Save the robot's current map state."""
+        await self._local.save_current_map()
+
+    async def save_map_backup_list(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Save map backup and retrieve all map backup names and IDs."""
+        return await self._local.save_map_backup_list(timeout)
+
     # ------------------------------------------------------------------
     # Plan management (delegated to YarboLocalClient)
     # ------------------------------------------------------------------

diff --git a/src/yarbo/error_reporting.py b/src/yarbo/error_reporting.py
--- a/src/yarbo/error_reporting.py
+++ b/src/yarbo/error_reporting.py
@@ -8,16 +8,12 @@
 
 import json
 import logging
+import os
 import re
 from typing import Any
 
-logger = logging.getLogger(__name__)
+_LOGGER = logging.getLogger(__name__)
 
-# Sensitive-key scrubbing helpers — compiled once at import time.
-_SCRUB_KEY_KEYWORDS: tuple[str, ...] = ("password", "token", "secret", "credential", "key")
-_SCRUB_MSG_KEYWORDS: tuple[str, ...] = ("password", "token", "secret", "credential")
-_SCRUB_KEY_PATTERN = re.compile(r"(?:_|api|access|auth|private)key", re.IGNORECASE)
-
 # Default DSN for the python-yarbo GlitchTip project.
 # Enabled by default during beta to help find issues.
 # Opt-out: set YARBO_SENTRY_DSN="" or pass enabled=False.
@@ -28,8 +24,9 @@
     dsn: str | None = None,
     environment: str = "production",
     enabled: bool = True,
+    tags: dict[str, str] | None = None,
 ) -> None:
-    """Initialize Sentry/GlitchTip error reporting.
+    """Initialize Sentry/GlitchTip error reporting for python-yarbo.
 
     Enabled by default during beta with a built-in DSN. No PII is collected;
     credentials and sensitive keys are scrubbed before sending.
@@ -41,56 +38,85 @@
              ``SENTRY_DSN`` environment variables, then the built-in default.
         environment: Environment tag (production/development/testing).
         enabled: Master switch. If False, no SDK initialization occurs.
+        tags: Optional extra tags (e.g. robot_serial, library_version).
     """
     if not enabled:
         return
 
-    import os  # noqa: PLC0415
-
-    # Check for explicit disable via empty env var
+    # Resolve DSN: explicit arg > YARBO_SENTRY_DSN env var > SENTRY_DSN env var > built-in default
     env_dsn = os.environ.get("YARBO_SENTRY_DSN")
     if env_dsn is not None and env_dsn == "":
-        return  # Explicitly disabled
+        _LOGGER.debug('Error reporting explicitly disabled via YARBO_SENTRY_DSN=""')
+        return
+    effective_dsn = dsn or env_dsn or os.environ.get("SENTRY_DSN") or _DEFAULT_DSN
 
-    dsn = dsn or env_dsn or os.environ.get("SENTRY_DSN") or _DEFAULT_DSN
-
-    if not dsn:
+    if not effective_dsn:
         return
 
     try:
         import sentry_sdk  # noqa: PLC0415
 
         sentry_sdk.init(
-            dsn=dsn,
+            dsn=effective_dsn,
             environment=environment,
             traces_sample_rate=0.1,
             send_default_pii=False,
-            before_send=_scrub_event,  # type: ignore[arg-type, unused-ignore]
+            before_send=_scrub_event,
         )
-        logger.debug("Error reporting initialized (dsn=%s...)", dsn[:30])
+
+        if tags:
+            for key, value in tags.items():
+                sentry_sdk.set_tag(key, value)
+
+        _LOGGER.debug("Error reporting initialized (dsn=%s...)", effective_dsn[:30])
     except ImportError:
-        logger.debug("sentry-sdk not installed; error reporting disabled")
+        _LOGGER.debug("sentry-sdk not installed; error reporting disabled")
     except Exception as exc:  # noqa: BLE001
-        logger.warning("Failed to initialize error reporting: %s", exc)
+        _LOGGER.warning("Failed to initialize error reporting: %s", exc)
 
 
+# Non-sensitive field names that contain "_key" but must not be redacted.
+_KEY_ALLOWLIST: frozenset[str] = frozenset({"entity_key"})
+
+# Pattern to detect key-like strings in breadcrumb messages (e.g., "apikey", "access_key")
+_SCRUB_KEY_KEYWORDS: tuple[str, ...] = ("password", "token", "secret", "credential", "key")
+_SCRUB_MSG_KEYWORDS: tuple[str, ...] = ("password", "token", "secret", "credential")
+_SCRUB_KEY_PATTERN = re.compile(r"(?:_|api|access|auth|private)key", re.IGNORECASE)
+
+
+def _is_sensitive_key(key_lower: str) -> bool:
+    """Check if a key name looks sensitive and should be redacted."""
+    if any(s in key_lower for s in ("password", "token", "secret", "credential")):
+        return True
+    if key_lower in _KEY_ALLOWLIST:
+        return False
+    return (
+        key_lower == "key"
+        or "_key" in key_lower
+        or key_lower.startswith("key_")
+        or key_lower.endswith("key")
+    )
+
+
 def _scrub_event(event: dict, hint: dict) -> dict:  # type: ignore[type-arg]
     """Remove sensitive data before sending."""
     if "extra" in event:
         for key in list(event["extra"]):
-            if any(s in key.lower() for s in _SCRUB_KEY_KEYWORDS):
+            if _is_sensitive_key(key.lower()):
                 event["extra"][key] = "[REDACTED]"
 
     if "breadcrumbs" in event and "values" in event["breadcrumbs"]:
         for breadcrumb in event["breadcrumbs"]["values"]:
             if "message" in breadcrumb:
                 msg = str(breadcrumb["message"])
-                sensitive = any(s in msg.lower() for s in _SCRUB_MSG_KEYWORDS)
+                msg_lower = msg.lower()
+                keywords = ("password", "token", "secret", "credential")
+                sensitive = any(s in msg_lower for s in keywords)
                 if sensitive or _SCRUB_KEY_PATTERN.search(msg):
                     breadcrumb["message"] = "[REDACTED]"
             if "data" in breadcrumb and isinstance(breadcrumb["data"], dict):
                 for key in list(breadcrumb["data"]):
-                    if any(s in key.lower() for s in _SCRUB_KEY_KEYWORDS):
+                    if _is_sensitive_key(key.lower()):
                         breadcrumb["data"][key] = "[REDACTED]"
 
     return event
@@ -117,11 +143,11 @@
     try:
         import sentry_sdk  # noqa: PLC0415
     except ImportError:
-        logger.debug("sentry-sdk not installed; MQTT dump not sent")
+        _LOGGER.debug("sentry-sdk not installed; MQTT dump not sent")
         return False
 
     if not sentry_sdk.is_initialized():
-        logger.debug("Error reporting not initialized; MQTT dump not sent")
+        _LOGGER.debug("Error reporting not initialized; MQTT dump not sent")
         return False
 
     trimmed = messages[-max_messages:] if len(messages) > max_messages else messages
@@ -135,7 +161,7 @@
         level="info",
         extras={"mqtt_dump": dump, "message_count": len(scrubbed)},
     )
-    logger.info("MQTT dump sent to GlitchTip (%d messages)", len(scrubbed))
+    _LOGGER.info("MQTT dump sent to GlitchTip (%d messages)", len(scrubbed))
     return True
 
 

diff --git a/src/yarbo/local.py b/src/yarbo/local.py
--- a/src/yarbo/local.py
+++ b/src/yarbo/local.py
@@ -6,10 +6,10 @@
 
 Prerequisites:
 - The host machine must be on the same WiFi as the robot.
-- The robot's EMQX broker IP must be known (use :func:`yarbo.discover` or set explicitly).
+- The robot's EMQX broker IP must be known (default: 192.168.1.24).
 - ``paho-mqtt`` must be installed: ``pip install 'python-yarbo'``.
 
-Protocol notes (from hardware testing):
+Protocol notes (from live captures):
 - All MQTT payloads are zlib-compressed JSON (see ``_codec``).
 - ``get_controller`` MUST be sent before action commands (e.g. light_ctrl).
 - Topics: ``snowbot/{SN}/app/{cmd}`` (publish) and
@@ -17,14 +17,17 @@
 - Commands are generally fire-and-forget; responses on ``data_feedback``.
 
 Transport limitations (NOT YET IMPLEMENTED):
-- Local REST API (robot LAN, port 8088) — direct HTTP REST on the robot network.
+- Local REST API (``192.168.8.8:8088``) — direct HTTP REST on the robot network.
   Endpoints are unknown; requires further sniffing or SSH exploration.
-- Local TCP JSON (robot LAN, port 22220) — a JSON-over-TCP protocol discovered
+- Local TCP JSON (``192.168.8.1:22220``) — a JSON-over-TCP protocol discovered
   in libapp.so (uses ``com`` field with ``@n`` namespace notation).
 - This module is MQTT-only. Both unimplemented transports are TODO items.
 
 References:
-    Protocol documentation (command catalogue, light control protocol, MQTT protocol reference)
+    yarbo-reversing/scripts/local_ctrl.py — working reference implementation
+    yarbo-reversing/docs/COMMAND_CATALOGUE.md — full command catalogue
+    yarbo-reversing/docs/LIGHT_CTRL_PROTOCOL.md — light control protocol
+    yarbo-reversing/docs/MQTT_PROTOCOL.md — protocol reference
 """
 
 from __future__ import annotations
@@ -44,14 +47,7 @@
     TOPIC_LEAF_PLAN_FEEDBACK,
 )
 from .exceptions import YarboNotControllerError, YarboTimeoutError
-from .models import (
-    HeadType,
-    YarboCommandResult,
-    YarboLightState,
-    YarboPlan,
-    YarboSchedule,
-    YarboTelemetry,
-)
+from .models import YarboCommandResult, YarboLightState, YarboPlan, YarboSchedule, YarboTelemetry
 from .mqtt import MqttTransport
 
 if TYPE_CHECKING:
@@ -70,7 +66,7 @@
 
     Example (async context manager)::
 
-        async with YarboLocalClient(broker="<rover-ip>", sn="YOUR_SERIAL") as client:
+        async with YarboLocalClient(broker="192.168.1.24", sn="24400102L8HO5227") as client:
             await client.lights_on()
             await client.buzzer(state=1)
             async for telemetry in client.watch_telemetry():
@@ -78,63 +74,33 @@
 
     Example (manual lifecycle)::
 
-        client = YarboLocalClient(broker="<rover-ip>", sn="YOUR_SERIAL")
+        client = YarboLocalClient(broker="192.168.1.24", sn="24400102L8HO5227")
         await client.connect()
         await client.lights_on()
         await client.disconnect()
 
     Args:
-        broker:         MQTT broker IP (from discover() or set explicitly; required).
+        broker:         MQTT broker IP address.
         sn:             Robot serial number.
         port:           Broker port (default 1883).
         auto_controller: If ``True`` (default), automatically send
                          ``get_controller`` before the first action command.
-        mqtt_log_path:  If set, append every raw MQTT message (topic + payload JSON) to this file.
-        debug:          If ``True``, print every MQTT message sent/received to stderr
-                         (human-readable).
-        debug_raw:      If ``True`` and debug is on, print one-line JSON per message
-                         (no formatting).
-        mqtt_capture_max: If > 0, keep the last N messages in a buffer;
-                         use :meth:`get_captured_mqtt` to retrieve them
-                         (e.g. for ``report_mqtt_dump_to_glitchtip``).
     """
 
     def __init__(
         self,
-        broker: str,
+        broker: str = LOCAL_BROKER_DEFAULT,
         sn: str = "",
         port: int = LOCAL_PORT,
         auto_controller: bool = True,
-        mqtt_log_path: str | None = None,
-        debug: bool = False,
-        debug_raw: bool = False,
-        mqtt_capture_max: int = 0,
     ) -> None:
-        if not broker:
-            raise ValueError(
-                "broker IP must be set to the robot's EMQX broker address; "
-                "use yarbo.discovery.discover() to find it automatically."
-            )
         self._broker = broker
         self._sn = sn
         self._port = port
         self._auto_controller = auto_controller
-        self._transport = MqttTransport(
-            broker=broker,
-            sn=sn,
-            port=port,
-            mqtt_log_path=mqtt_log_path,
-            debug=debug,
-            debug_raw=debug_raw,
-            mqtt_capture_max=mqtt_capture_max,
-        )
+        self._transport = MqttTransport(broker=broker, sn=sn, port=port)
         self._controller_acquired = False
-        self._last_status: YarboTelemetry | None = None
 
-    def get_captured_mqtt(self) -> list[dict[str, Any]]:
-        """Return captured MQTT messages (when mqtt_capture_max > 0). For GlitchTip reports."""
-        return self._transport.get_captured_mqtt()
-
     # ------------------------------------------------------------------
     # Context manager
     # ------------------------------------------------------------------
@@ -166,7 +132,6 @@
     async def connect(self) -> None:
         """Connect to the local MQTT broker."""
         self._transport.add_reconnect_callback(self._on_reconnect)
-        logger.debug("Connecting to broker %s:%d (sn=%s)", self._broker, self._port, self._sn)
         await self._transport.connect()
         logger.info(
             "YarboLocalClient connected to %s:%d (sn=%s)",
@@ -177,7 +142,6 @@
 
     async def disconnect(self) -> None:
         """Disconnect from the local MQTT broker."""
-        logger.debug("Disconnecting from broker %s:%d (sn=%s)", self._broker, self._port, self._sn)
         await self._transport.disconnect()
 
     @property
@@ -342,7 +306,7 @@
             vel: Chute velocity / direction integer. Positive = right, negative = left.
 
         Reference:
-            Protocol documentation (light control protocol, cmd_chute section)
+            yarbo-reversing/docs/LIGHT_CTRL_PROTOCOL.md#cmd_chute
         """
         await self._ensure_controller()
         await self._transport.publish("cmd_chute", {"vel": vel})
@@ -369,15 +333,7 @@
         if envelope:
             topic = envelope.get("topic", "")
             payload = envelope.get("payload", {})
-            telemetry = YarboTelemetry.from_dict(payload, topic=topic)
-            self._last_status = telemetry
-            logger.debug(
-                "Received status snapshot: battery=%s state=%s head=%s",
-                telemetry.battery,
-                telemetry.state,
-                telemetry.head_name,
-            )
-            return telemetry
+            return YarboTelemetry.from_dict(payload, topic=topic)
         return None
 
     async def watch_telemetry(self) -> AsyncIterator[YarboTelemetry]:
@@ -410,59 +366,9 @@
                     t.plan_state = _plan_payload.get("state")
                     t.area_covered = _plan_payload.get("areaCovered")
                     t.duration = _plan_payload.get("duration")
-                self._last_status = t
-                logger.debug(
-                    "Telemetry: battery=%s state=%s head=%s",
-                    t.battery,
-                    t.state,
-                    t.head_name,
-                )
                 yield t
 
     # ------------------------------------------------------------------
-    # Head validation
-    # ------------------------------------------------------------------
-
-    def _validate_head_type(self, required: HeadType | tuple[HeadType, ...]) -> None:
-        """Validate that the attached head matches the required type(s).
-
-        Args:
-            required: A single :class:`~yarbo.models.HeadType` or a tuple of
-                      acceptable head types.
-
-        Raises:
-            ValueError: If a head status has been received and the attached head
-                        does not match *required*.
-
-        If no status has been received yet (``_last_status`` is ``None`` or
-        ``head_type`` is absent), a warning is logged and the command is allowed
-        through to preserve compatibility with firmware that reports head type
... diff truncated: showing 800 of 2625 lines

[cursor]

Cursor Bugbot has reviewed your changes and found 5 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for all 5 issues found in the latest run.

• ✅ Fixed: Camera and firmware commands skip controller handshake
  • Added missing await self._ensure_controller() calls before _publish_and_wait in check_camera_status, camera_calibration, firmware_update_now, firmware_update_tonight, and firmware_update_later methods.
• ✅ Fixed: MQTT debug and capture parameters silently dropped
  • Forwarded mqtt_log_path, debug, debug_raw, and mqtt_capture_max parameters to MqttTransport constructor and changed get_captured_mqtt to return self._transport.get_captured_mqtt() instead of an empty local list.
• ✅ Fixed: publish_command delegates to wrong local method
  • Changed YarboClient.publish_command to call self._local.publish_command instead of self._local.publish_raw to preserve the intended semantic difference.
• ✅ Fixed: New set_roller_speed is now identical to set_roller
  • Consolidated set_roller_speed to call set_roller internally to avoid code duplication and ensure consistent behavior.
• ✅ Fixed: New set_velocity_manual duplicates existing set_velocity
  • Consolidated set_velocity_manual to call set_velocity internally to avoid code duplication and ensure consistent behavior.

Preview (479f00ce34)

diff --git a/src/yarbo/client.py b/src/yarbo/client.py
--- a/src/yarbo/client.py
+++ b/src/yarbo/client.py
@@ -205,8 +205,8 @@
         await self._local.publish_raw(cmd, payload)
 
     async def publish_command(self, cmd: str, payload: dict[str, Any]) -> None:
-        """Alias for :meth:`publish_raw` — publish an arbitrary MQTT command to the robot."""
-        await self._local.publish_raw(cmd, payload)
+        """Publish a command without auto-acquiring controller (for coordinator patterns)."""
+        await self._local.publish_command(cmd, payload)
 
     # -- Robot control --
 

diff --git a/src/yarbo/local.py b/src/yarbo/local.py
--- a/src/yarbo/local.py
+++ b/src/yarbo/local.py
@@ -102,13 +102,16 @@
         self._sn = sn
         self._port = port
         self._auto_controller = auto_controller
-        self._transport = MqttTransport(broker=broker, sn=sn, port=port)
+        self._transport = MqttTransport(
+            broker=broker,
+            sn=sn,
+            port=port,
+            mqtt_log_path=mqtt_log_path,
+            debug=debug,
+            debug_raw=debug_raw,
+            mqtt_capture_max=mqtt_capture_max,
+        )
         self._controller_acquired = False
-        self._mqtt_log_path = mqtt_log_path
-        self._debug = debug
-        self._debug_raw = debug_raw
-        self._mqtt_capture_max = mqtt_capture_max
-        self._captured_mqtt: list[dict[str, Any]] = []
 
     # ------------------------------------------------------------------
     # Context manager
@@ -155,7 +158,7 @@
 
     def get_captured_mqtt(self) -> list[dict[str, Any]]:
         """Return captured MQTT messages (populated when mqtt_capture_max > 0)."""
-        return list(self._captured_mqtt)
+        return self._transport.get_captured_mqtt()
 
     @property
     def is_connected(self) -> bool:
@@ -909,10 +912,12 @@
 
     async def check_camera_status(self) -> YarboCommandResult:
         """Request current camera status."""
+        await self._ensure_controller()
         return await self._publish_and_wait("check_camera_status", {})
 
     async def camera_calibration(self) -> YarboCommandResult:
         """Trigger camera calibration."""
+        await self._ensure_controller()
         return await self._publish_and_wait("camera_calibration", {})
 
     # ------------------------------------------------------------------
@@ -1368,8 +1373,7 @@
         Args:
             speed: Speed value (robot-defined units).
         """
-        await self._ensure_controller()
-        await self._transport.publish("cmd_roller", {"speed": speed})
+        await self.set_roller(speed)
 
     # ------------------------------------------------------------------
     # Motor & mechanical
@@ -1492,14 +1496,17 @@
         """
         if not confirm:
             raise ValueError("firmware_update_now is destructive — pass confirm=True to proceed.")
+        await self._ensure_controller()
         return await self._publish_and_wait("firmware_update_now", {})
 
     async def firmware_update_tonight(self) -> YarboCommandResult:
         """Schedule a firmware update for tonight."""
+        await self._ensure_controller()
         return await self._publish_and_wait("firmware_update_tonight", {})
 
     async def firmware_update_later(self) -> YarboCommandResult:
         """Defer a pending firmware update."""
+        await self._ensure_controller()
         return await self._publish_and_wait("firmware_update_later", {})
 
     # ------------------------------------------------------------------
@@ -1584,8 +1591,7 @@
             linear:  Linear velocity (forward positive).
             angular: Angular velocity (counter-clockwise positive).
         """
-        await self._ensure_controller()
-        await self._transport.publish("cmd_vel", {"vel": linear, "rev": angular})
+        await self.set_velocity(linear, angular)
 
     # ------------------------------------------------------------------
     # Map management (destructive)

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for all 3 issues found in the latest run.

• ✅ Fixed: watch_telemetry no longer caches latest telemetry status
  • Restored self._last_status = t before yielding telemetry in watch_telemetry to cache the latest status for head type validation.
• ✅ Fixed: dict() on non-dict data crashes unlike old code
  • Restored defensive type checking with data if isinstance(data, dict) else {"data": data} in get_global_params and get_map to handle non-dict responses gracefully.
• ✅ Fixed: YarboClient.publish_command delegates to wrong local method
  • Changed YarboClient.publish_command to delegate to self._local.publish_command() instead of self._local.publish_raw() to preserve the no-auto-acquire semantics.

Preview (d284139028)

diff --git a/.github/codeql/codeql-config.yml b/.github/codeql/codeql-config.yml
new file mode 100644
--- /dev/null
+++ b/.github/codeql/codeql-config.yml
@@ -1,0 +1,20 @@
+name: "Yarbo CodeQL Config"
+
+# Disable queries that flag core IoT features as privacy issues
+# GPS coordinates, IP addresses, MAC addresses, and hostnames are
+# fundamental to robot mower discovery and control — not PII leaks.
+query-filters:
+  - exclude:
+      tags contain: security/cwe/cwe-532  # Clear-text logging (we handle this ourselves)
+  - exclude:
+      tags contain: security/cwe/cwe-359  # Privacy violation (GPS, IP, MAC are core features)
+  - exclude:
+      tags contain: security/cwe/cwe-200  # Information exposure (device telemetry is the product)
+  - exclude:
+      id: py/clear-text-logging-sensitive-data
+  - exclude:
+      id: py/clear-text-storage-sensitive-data
+
+paths-ignore:
+  - tests
+  - archive

diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
new file mode 100644
--- /dev/null
+++ b/.github/workflows/codeql.yml
@@ -1,0 +1,27 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+permissions:
+  security-events: write
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        language: [python]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          config-file: .github/codeql/codeql-config.yml
+      - uses: github/codeql-action/autobuild@v3
+      - uses: github/codeql-action/analyze@v3

diff --git a/pyproject.toml b/pyproject.toml
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -25,10 +25,12 @@
 dependencies = [
     "paho-mqtt>=2.0",
     "aiohttp>=3.9",
-    "sentry-sdk>=2.0",
 ]
 
 [project.optional-dependencies]
+sentry = [
+    "sentry-sdk>=2.0",
+]
 cloud = [
     "cryptography>=42.0",
 ]

diff --git a/src/yarbo/__init__.py b/src/yarbo/__init__.py
--- a/src/yarbo/__init__.py
+++ b/src/yarbo/__init__.py
@@ -1,5 +1,5 @@
 """
-yarbo — Python library for local and cloud control of Yarbo robot mowers.
+yarbo — Python library for local control of Yarbo robot mowers and snow blowers via MQTT.
 
 Yarbo makes autonomous snow blowers and lawn mowers controlled via local MQTT.
 This is a community-developed library for the Yarbo protocol, built through
@@ -58,7 +58,7 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "2026.3.10"
 __author__ = "Markus Lassfolk"
 __license__ = "MIT"
 
@@ -140,5 +140,5 @@
     "YarboTokenExpiredError",
 ]
 
-# Opt-out error reporting: enabled by default, disable via YARBO_SENTRY_DSN=""
+# Opt-in error reporting: enabled if YARBO_SENTRY_DSN or SENTRY_DSN env var is set.
 init_error_reporting()

diff --git a/src/yarbo/client.py b/src/yarbo/client.py
--- a/src/yarbo/client.py
+++ b/src/yarbo/client.py
@@ -204,6 +204,300 @@
         """Publish an arbitrary MQTT command to the robot."""
         await self._local.publish_raw(cmd, payload)
 
+    async def publish_command(self, cmd: str, payload: dict[str, Any]) -> None:
+        """Publish an arbitrary MQTT command to the robot (alias for publish_raw)."""
+        await self._local.publish_command(cmd, payload)
+
+    # -- Robot control --
+
+    async def shutdown(self) -> None:
+        """Power off the robot."""
+        await self._local.shutdown()
+
+    async def restart_container(self) -> None:
+        """Restart the EMQX container on the robot."""
+        await self._local.restart_container()
+
+    async def emergency_stop(self) -> None:
+        """Trigger an emergency stop."""
+        await self._local.emergency_stop()
+
+    async def emergency_unlock(self) -> None:
+        """Clear the emergency stop state."""
+        await self._local.emergency_unlock()
+
+    async def dstop(self) -> None:
+        """Soft-stop the robot (decelerate to halt)."""
+        await self._local.dstop()
+
+    async def resume(self) -> None:
+        """Resume operation after a pause or soft-stop."""
+        await self._local.resume()
+
+    async def cmd_recharge(self) -> None:
+        """Send the robot back to its charging dock."""
+        await self._local.cmd_recharge()
+
+    # -- Lights & sound --
+
+    async def set_head_light(self, enabled: bool) -> None:
+        """Enable or disable the head light."""
+        await self._local.set_head_light(enabled)
+
+    async def set_roof_lights(self, enabled: bool) -> None:
+        """Enable or disable the roof lights."""
+        await self._local.set_roof_lights(enabled)
+
+    async def set_laser(self, enabled: bool) -> None:
+        """Enable or disable the laser."""
+        await self._local.set_laser(enabled)
+
+    async def set_sound(self, volume: int, song_id: int = 0) -> None:
+        """Set the speaker volume (0-100)."""
+        await self._local.set_sound(volume, song_id)
+
+    async def play_song(self, song_id: int) -> None:
+        """Play a sound/song by ID."""
+        await self._local.play_song(song_id)
+
+    # -- Camera & detection --
+
+    async def set_camera(self, enabled: bool) -> None:
+        """Enable or disable the camera."""
+        await self._local.set_camera(enabled)
+
+    async def set_person_detect(self, enabled: bool) -> None:
+        """Enable or disable person detection."""
+        await self._local.set_person_detect(enabled)
+
+    async def set_usb(self, enabled: bool) -> None:
+        """Enable or disable the USB port."""
+        await self._local.set_usb(enabled)
+
+    # -- Plans & scheduling --
+
+    async def start_plan_direct(self, plan_id: int, percent: int = 100) -> None:
+        """Start a work plan by numeric ID (direct command, no response)."""
+        await self._local.start_plan_direct(plan_id, percent)
+
+    async def read_plan(self, plan_id: int, timeout: float = 5.0) -> dict[str, Any]:
+        """Request plan detail and await the data_feedback response."""
+        return await self._local.read_plan(plan_id, timeout)
+
+    async def read_all_plans(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request all plan summaries and await the data_feedback response."""
+        return await self._local.read_all_plans(timeout)
+
+    async def delete_plan_direct(self, plan_id: int, confirm: bool = False) -> None:
+        """Delete a plan by numeric ID. Pass confirm=True to proceed (destructive)."""
+        await self._local.delete_plan_direct(plan_id, confirm=confirm)
+
+    async def delete_all_plans(self, confirm: bool = False) -> None:
+        """Delete all stored plans from the robot. Pass confirm=True to proceed (destructive)."""
+        await self._local.delete_all_plans(confirm=confirm)
+
+    async def pause_planning(self) -> None:
+        """Pause the currently running plan (direct command, no response)."""
+        await self._local.pause_planning()
+
+    async def in_plan_action(self, action: str) -> None:
+        """Send an in-plan action command."""
+        await self._local.in_plan_action(action)
+
+    async def read_schedules(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request all schedules and await the data_feedback response."""
+        return await self._local.read_schedules(timeout)
+
+    # -- Navigation & maps --
+
+    async def start_waypoint(self, index: int) -> None:
+        """Start navigation to a waypoint by index."""
+        await self._local.start_waypoint(index)
+
+    async def read_recharge_point(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request the saved recharge/dock point and await the data_feedback response."""
+        return await self._local.read_recharge_point(timeout)
+
+    async def save_charging_point(self) -> None:
+        """Save the robot's current position as the charging/dock point."""
+        await self._local.save_charging_point()
+
+    async def read_clean_area(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request the clean area definition and await the data_feedback response."""
+        return await self._local.read_clean_area(timeout)
+
+    async def get_all_map_backup(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request all map backups and await the data_feedback response."""
+        return await self._local.get_all_map_backup(timeout)
+
+    async def save_map_backup(self) -> None:
+        """Save a backup of the current map."""
+        await self._local.save_map_backup()
+
+    # -- WiFi & connectivity --
+
+    async def get_wifi_list(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request the list of available WiFi networks and await the data_feedback response."""
+        return await self._local.get_wifi_list(timeout)
+
+    async def get_connected_wifi(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request the connected WiFi network name and await the data_feedback response."""
+        return await self._local.get_connected_wifi(timeout)
+
+    async def start_hotspot(self) -> None:
+        """Start the robot's WiFi hotspot."""
+        await self._local.start_hotspot()
+
+    async def get_hub_info(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request hub information and await the data_feedback response."""
+        return await self._local.get_hub_info(timeout)
+
+    # -- Diagnostics --
+
+    async def read_no_charge_period(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request no-charge period configuration and await the data_feedback response."""
+        return await self._local.read_no_charge_period(timeout)
+
+    async def get_battery_cell_temps(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request battery cell temperature data and await the data_feedback response."""
+        return await self._local.get_battery_cell_temps(timeout)
+
+    async def get_motor_temps(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request motor temperature data and await the data_feedback response."""
+        return await self._local.get_motor_temps(timeout)
+
+    async def get_body_current(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request body current telemetry and await the data_feedback response."""
+        return await self._local.get_body_current(timeout)
+
+    async def get_head_current(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request head current telemetry and await the data_feedback response."""
+        return await self._local.get_head_current(timeout)
+
+    async def get_speed(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request current speed telemetry and await the data_feedback response."""
+        return await self._local.get_speed(timeout)
+
+    async def get_odometer(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request odometer data and await the data_feedback response."""
+        return await self._local.get_odometer(timeout)
+
+    async def get_product_code(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Request the product code and await the data_feedback response."""
+        return await self._local.get_product_code(timeout)
+
+    async def set_charge_limit(self, min_pct: int, max_pct: int) -> None:
+        """Set battery charge limits."""
+        await self._local.set_charge_limit(min_pct, max_pct)
+
+    async def set_turn_type(self, turn_type: int) -> None:
+        """Set the turning behaviour type."""
+        await self._local.set_turn_type(turn_type)
+
+    # -- Motor & mechanical --
+
+    async def set_motor_protect(self, state: int) -> None:
+        """Enable or disable motor protection mode."""
+        await self._local.set_motor_protect(state)
+
+    async def set_trimmer(self, state: int) -> None:
+        """Enable or disable the trimmer."""
+        await self._local.set_trimmer(state)
+
+    # -- Blowing / edge / smart features --
+
+    async def set_edge_blowing(self, state: int) -> None:
+        """Enable or disable edge blowing."""
+        await self._local.set_edge_blowing(state)
+
+    async def set_smart_blowing(self, state: int) -> None:
+        """Enable or disable smart blowing."""
+        await self._local.set_smart_blowing(state)
+
+    async def set_heating_film(self, state: int) -> None:
+        """Enable or disable heating film (anti-ice)."""
+        await self._local.set_heating_film(state)
+
+    async def set_module_lock(self, state: int) -> None:
+        """Lock or unlock an accessory module."""
+        await self._local.set_module_lock(state)
+
+    # -- Autonomous modes --
+
+    async def set_follow_mode(self, state: int) -> None:
+        """Enable or disable follow mode."""
+        await self._local.set_follow_mode(state)
+
+    async def set_draw_mode(self, state: int) -> None:
+        """Enable or disable draw/mapping mode."""
+        await self._local.set_draw_mode(state)
+
+    # -- OTA / firmware updates --
+
+    async def set_auto_update(self, state: int) -> None:
+        """Enable or disable automatic firmware (Greengrass) updates."""
+        await self._local.set_auto_update(state)
+
+    async def set_camera_ota(self, state: int) -> None:
+        """Enable or disable IP camera OTA updates."""
+        await self._local.set_camera_ota(state)
+
+    # -- Vision / recording --
+
+    async def set_smart_vision(self, state: int) -> None:
+        """Enable or disable smart vision processing."""
+        await self._local.set_smart_vision(state)
+
+    async def set_video_record(self, state: int) -> None:
+        """Enable or disable video recording."""
+        await self._local.set_video_record(state)
+
+    # -- Safety / fencing --
+
+    async def set_child_lock(self, state: int) -> None:
+        """Enable or disable the child lock."""
+        await self._local.set_child_lock(state)
+
+    async def set_geo_fence(self, state: int) -> None:
+        """Enable or disable geo-fencing."""
+        await self._local.set_geo_fence(state)
+
+    async def set_elec_fence(self, state: int) -> None:
+        """Enable or disable the electric fence."""
+        await self._local.set_elec_fence(state)
+
+    async def set_ngz_edge(self, state: int) -> None:
+        """Enable or disable NGZ edge enforcement."""
+        await self._local.set_ngz_edge(state)
+
+    # -- Manual drive extras --
+
+    async def set_velocity_manual(self, linear: float, angular: float) -> None:
+        """Send a velocity command in manual drive mode."""
+        await self._local.set_velocity_manual(linear, angular)
+
+    async def set_sound_param(self, volume: int, enabled: int) -> None:
+        """Set sound volume and enable/disable audio output."""
+        await self._local.set_sound_param(volume, enabled)
+
+    # -- Map management (destructive) --
+
+    async def erase_map(self, confirm: bool = False) -> None:
+        """Erase the robot's stored map. Pass confirm=True to proceed (destructive)."""
+        await self._local.erase_map(confirm=confirm)
+
+    async def map_recovery(self, map_id: str, confirm: bool = False) -> None:
+        """Restore a map from backup. Pass confirm=True to proceed (destructive)."""
+        await self._local.map_recovery(map_id, confirm=confirm)
+
+    async def save_current_map(self) -> None:
+        """Save the robot's current map state."""
+        await self._local.save_current_map()
+
+    async def save_map_backup_list(self, timeout: float = 5.0) -> dict[str, Any]:
+        """Save map backup and retrieve all map backup names and IDs."""
+        return await self._local.save_map_backup_list(timeout)
+
     # ------------------------------------------------------------------
     # Plan management (delegated to YarboLocalClient)
     # ------------------------------------------------------------------
@@ -342,9 +636,9 @@
         """Set snow push direction (snow blower head only)."""
         return await self._local.push_snow_dir(direction=direction)
 
-    async def set_chute_steering_work(self, state: int) -> None:
-        """Enable or disable chute auto-steering (snow blower head only)."""
-        return await self._local.set_chute_steering_work(state=state)
+    async def set_chute_steering_work(self, angle: int) -> None:
+        """Set the chute steering angle during work (snow blower head only)."""
+        return await self._local.set_chute_steering_work(state=angle)
 
     # ------------------------------------------------------------------
     # Camera commands (delegated to YarboLocalClient)

diff --git a/src/yarbo/error_reporting.py b/src/yarbo/error_reporting.py
--- a/src/yarbo/error_reporting.py
+++ b/src/yarbo/error_reporting.py
@@ -13,6 +13,9 @@
 
 logger = logging.getLogger(__name__)
 
+# Default DSN (override with YARBO_SENTRY_DSN or SENTRY_DSN).
+_DEFAULT_DSN = "https://c690590f8f664d609f6abe4cb0392d53@glitchtip.lassfolk.cc/2"
+
 # Sensitive-key scrubbing helpers — compiled once at import time.
 _SCRUB_KEY_KEYWORDS: tuple[str, ...] = ("password", "token", "secret", "credential", "key")
 _SCRUB_MSG_KEYWORDS: tuple[str, ...] = ("password", "token", "secret", "credential")
@@ -21,7 +24,6 @@
 # Default DSN for the python-yarbo GlitchTip project.
 # Enabled by default during beta to help find issues.
 # Opt-out: set YARBO_SENTRY_DSN="" or pass enabled=False.
-_DEFAULT_DSN = "https://c690590f8f664d609f6abe4cb0392d53@glitchtip.lassfolk.cc/2"
 
 
 def init_error_reporting(
@@ -84,14 +86,9 @@
     if "breadcrumbs" in event and "values" in event["breadcrumbs"]:
         for breadcrumb in event["breadcrumbs"]["values"]:
             if "message" in breadcrumb:
-                msg = str(breadcrumb["message"])
-                sensitive = any(s in msg.lower() for s in _SCRUB_MSG_KEYWORDS)
-                if sensitive or _SCRUB_KEY_PATTERN.search(msg):
-                    breadcrumb["message"] = "[REDACTED]"
+                breadcrumb["message"] = _scrub_string(str(breadcrumb["message"]))
             if "data" in breadcrumb and isinstance(breadcrumb["data"], dict):
-                for key in list(breadcrumb["data"]):
-                    if any(s in key.lower() for s in _SCRUB_KEY_KEYWORDS):
-                        breadcrumb["data"][key] = "[REDACTED]"
+                breadcrumb["data"] = _scrub_breadcrumb_data(breadcrumb["data"])
 
     return event
 
@@ -150,7 +147,7 @@
 
 def _scrub_dict(d: dict[str, Any]) -> dict[str, Any]:
     """Recursively redact values for keys that look sensitive."""
-    result = {}
+    result: dict[str, Any] = {}
     for k, v in d.items():
         if any(s in k.lower() for s in _SCRUB_KEY_KEYWORDS):
             result[k] = "[REDACTED]"
@@ -161,3 +158,28 @@
         else:
             result[k] = v
     return result
+
+
+def _scrub_string(value: str) -> str:
+    """Return a redacted string if it appears to contain sensitive data."""
+    lowered = value.lower()
+    if any(s in lowered for s in _SCRUB_MSG_KEYWORDS) or _SCRUB_KEY_PATTERN.search(value):
+        return "[REDACTED]"
+    return value
+
+
+def _scrub_breadcrumb_data(value: Any) -> Any:
+    """Scrub breadcrumb data values as well as sensitive keys."""
+    if isinstance(value, dict):
+        cleaned: dict[str, Any] = {}
+        for k, v in value.items():
+            if any(s in k.lower() for s in _SCRUB_KEY_KEYWORDS):
+                cleaned[k] = "[REDACTED]"
+            else:
+                cleaned[k] = _scrub_breadcrumb_data(v)
+        return cleaned
+    if isinstance(value, list):
+        return [_scrub_breadcrumb_data(v) for v in value]
+    if isinstance(value, str):
+        return _scrub_string(value)
+    return value

diff --git a/src/yarbo/local.py b/src/yarbo/local.py
--- a/src/yarbo/local.py
+++ b/src/yarbo/local.py
@@ -6,10 +6,10 @@
 
 Prerequisites:
 - The host machine must be on the same WiFi as the robot.
-- The robot's EMQX broker IP must be known (use :func:`yarbo.discover` or set explicitly).
+- The robot's EMQX broker IP must be known (default: 192.168.1.24).
 - ``paho-mqtt`` must be installed: ``pip install 'python-yarbo'``.
 
-Protocol notes (from hardware testing):
+Protocol notes (from live captures):
 - All MQTT payloads are zlib-compressed JSON (see ``_codec``).
 - ``get_controller`` MUST be sent before action commands (e.g. light_ctrl).
 - Topics: ``snowbot/{SN}/app/{cmd}`` (publish) and
@@ -17,14 +17,17 @@
 - Commands are generally fire-and-forget; responses on ``data_feedback``.
 
 Transport limitations (NOT YET IMPLEMENTED):
-- Local REST API (robot LAN, port 8088) — direct HTTP REST on the robot network.
+- Local REST API (``192.168.8.8:8088``) — direct HTTP REST on the robot network.
   Endpoints are unknown; requires further sniffing or SSH exploration.
-- Local TCP JSON (robot LAN, port 22220) — a JSON-over-TCP protocol discovered
+- Local TCP JSON (``192.168.8.1:22220``) — a JSON-over-TCP protocol discovered
   in libapp.so (uses ``com`` field with ``@n`` namespace notation).
 - This module is MQTT-only. Both unimplemented transports are TODO items.
 
 References:
-    Protocol documentation (command catalogue, light control protocol, MQTT protocol reference)
+    yarbo-reversing/scripts/local_ctrl.py — working reference implementation
+    yarbo-reversing/docs/COMMAND_CATALOGUE.md — full command catalogue
+    yarbo-reversing/docs/LIGHT_CTRL_PROTOCOL.md — light control protocol
+    yarbo-reversing/docs/MQTT_PROTOCOL.md — protocol reference
 """
 
 from __future__ import annotations
@@ -70,7 +73,7 @@
 
     Example (async context manager)::
 
-        async with YarboLocalClient(broker="<rover-ip>", sn="YOUR_SERIAL") as client:
+        async with YarboLocalClient(broker="192.168.1.24", sn="24400102L8HO5227") as client:
             await client.lights_on()
             await client.buzzer(state=1)
             async for telemetry in client.watch_telemetry():
@@ -78,30 +81,22 @@
 
     Example (manual lifecycle)::
 
-        client = YarboLocalClient(broker="<rover-ip>", sn="YOUR_SERIAL")
+        client = YarboLocalClient(broker="192.168.1.24", sn="24400102L8HO5227")
         await client.connect()
         await client.lights_on()
         await client.disconnect()
 
     Args:
-        broker:         MQTT broker IP (from discover() or set explicitly; required).
+        broker:         MQTT broker IP address.
         sn:             Robot serial number.
         port:           Broker port (default 1883).
         auto_controller: If ``True`` (default), automatically send
                          ``get_controller`` before the first action command.
-        mqtt_log_path:  If set, append every raw MQTT message (topic + payload JSON) to this file.
-        debug:          If ``True``, print every MQTT message sent/received to stderr
-                         (human-readable).
-        debug_raw:      If ``True`` and debug is on, print one-line JSON per message
-                         (no formatting).
-        mqtt_capture_max: If > 0, keep the last N messages in a buffer;
-                         use :meth:`get_captured_mqtt` to retrieve them
-                         (e.g. for ``report_mqtt_dump_to_glitchtip``).
     """
 
     def __init__(
         self,
-        broker: str,
+        broker: str = LOCAL_BROKER_DEFAULT,
         sn: str = "",
         port: int = LOCAL_PORT,
         auto_controller: bool = True,
@@ -110,31 +105,19 @@
         debug_raw: bool = False,
         mqtt_capture_max: int = 0,
     ) -> None:
-        if not broker:
-            raise ValueError(
-                "broker IP must be set to the robot's EMQX broker address; "
-                "use yarbo.discovery.discover() to find it automatically."
-            )
         self._broker = broker
         self._sn = sn
         self._port = port
         self._auto_controller = auto_controller
-        self._transport = MqttTransport(
-            broker=broker,
-            sn=sn,
-            port=port,
-            mqtt_log_path=mqtt_log_path,
-            debug=debug,
-            debug_raw=debug_raw,
-            mqtt_capture_max=mqtt_capture_max,
-        )
+        self._transport = MqttTransport(broker=broker, sn=sn, port=port)
         self._controller_acquired = False
         self._last_status: YarboTelemetry | None = None
+        self._mqtt_log_path = mqtt_log_path
+        self._debug = debug
+        self._debug_raw = debug_raw
+        self._mqtt_capture_max = mqtt_capture_max
+        self._captured_mqtt: list[dict[str, Any]] = []
 
-    def get_captured_mqtt(self) -> list[dict[str, Any]]:
-        """Return captured MQTT messages (when mqtt_capture_max > 0). For GlitchTip reports."""
-        return self._transport.get_captured_mqtt()
-
     # ------------------------------------------------------------------
     # Context manager
     # ------------------------------------------------------------------
@@ -166,7 +149,6 @@
     async def connect(self) -> None:
         """Connect to the local MQTT broker."""
         self._transport.add_reconnect_callback(self._on_reconnect)
-        logger.debug("Connecting to broker %s:%d (sn=%s)", self._broker, self._port, self._sn)
         await self._transport.connect()
         logger.info(
             "YarboLocalClient connected to %s:%d (sn=%s)",
@@ -177,9 +159,12 @@
 
     async def disconnect(self) -> None:
         """Disconnect from the local MQTT broker."""
-        logger.debug("Disconnecting from broker %s:%d (sn=%s)", self._broker, self._port, self._sn)
         await self._transport.disconnect()
 
+    def get_captured_mqtt(self) -> list[dict[str, Any]]:
+        """Return captured MQTT messages (populated when mqtt_capture_max > 0)."""
+        return list(self._captured_mqtt)
+
     @property
     def is_connected(self) -> bool:
         """True if the MQTT connection is active."""
@@ -342,7 +327,7 @@
             vel: Chute velocity / direction integer. Positive = right, negative = left.
 
         Reference:
-            Protocol documentation (light control protocol, cmd_chute section)
+            yarbo-reversing/docs/LIGHT_CTRL_PROTOCOL.md#cmd_chute
         """
         await self._ensure_controller()
         await self._transport.publish("cmd_chute", {"vel": vel})
@@ -369,60 +354,11 @@
         if envelope:
             topic = envelope.get("topic", "")
             payload = envelope.get("payload", {})
-            telemetry = YarboTelemetry.from_dict(payload, topic=topic)
-            self._last_status = telemetry
-            logger.debug(
-                "Received status snapshot: battery=%s state=%s head=%s",
-                telemetry.battery,
-                telemetry.state,
-                telemetry.head_name,
-            )
-            return telemetry
+            result = YarboTelemetry.from_dict(payload, topic=topic)
+            self._last_status = result
+            return result
         return None
 
-    async def watch_telemetry(self) -> AsyncIterator[YarboTelemetry]:
-        """
-        Async generator yielding live telemetry from ``DeviceMSG`` messages.
-
-        Filters the envelope stream to ``DeviceMSG`` messages only and yields
-        a :class:`~yarbo.models.YarboTelemetry` for each one (~1-2 Hz).
-
-        To access raw envelopes from all topics, use
-        :meth:`~yarbo.mqtt.MqttTransport.telemetry_stream` on the transport
-        directly.
-
-        Example::
-
-            async for telemetry in client.watch_telemetry():
-                print(f"Battery: {telemetry.battery}%  State: {telemetry.state}")
-                if telemetry.battery and telemetry.battery < 10:
-                    break
-        """
-        # Cache plan_feedback data to merge into each DeviceMSG telemetry object
-        _plan_payload: dict[str, Any] = {}
-        async for envelope in self._transport.telemetry_stream():
-            if envelope.kind == TOPIC_LEAF_PLAN_FEEDBACK:
-                _plan_payload = envelope.payload
-            elif envelope.is_telemetry:
-                t = envelope.to_telemetry()
-                if _plan_payload:
-                    t.plan_id = _plan_payload.get("planId")
-                    t.plan_state = _plan_payload.get("state")
-                    t.area_covered = _plan_payload.get("areaCovered")
-                    t.duration = _plan_payload.get("duration")
-                self._last_status = t
-                logger.debug(
-                    "Telemetry: battery=%s state=%s head=%s",
-                    t.battery,
-                    t.state,
-                    t.head_name,
-                )
-                yield t
-
-    # ------------------------------------------------------------------
-    # Head validation
-    # ------------------------------------------------------------------
-
     def _validate_head_type(self, required: HeadType | tuple[HeadType, ...]) -> None:
         """Validate that the attached head matches the required type(s).
 
@@ -434,10 +370,8 @@
             ValueError: If a head status has been received and the attached head
                         does not match *required*.
 
-        If no status has been received yet (``_last_status`` is ``None`` or
-        ``head_type`` is absent), a warning is logged and the command is allowed
-        through to preserve compatibility with firmware that reports head type
-        after the first status message.
+        If no status has been received yet, a warning is logged and the command
+        is allowed through.
         """
         if isinstance(required, HeadType):
             required = (required,)
@@ -462,6 +396,38 @@
             req_names = " or ".join(h.name for h in required)
             raise ValueError(f"Command requires {req_names} head, but {current.name} is attached")
 
+    async def watch_telemetry(self) -> AsyncIterator[YarboTelemetry]:
+        """
+        Async generator yielding live telemetry from ``DeviceMSG`` messages.
+
+        Filters the envelope stream to ``DeviceMSG`` messages only and yields
+        a :class:`~yarbo.models.YarboTelemetry` for each one (~1-2 Hz).
+
+        To access raw envelopes from all topics, use
+        :meth:`~yarbo.mqtt.MqttTransport.telemetry_stream` on the transport
+        directly.
+
+        Example::
+
+            async for telemetry in client.watch_telemetry():
+                print(f"Battery: {telemetry.battery}%  State: {telemetry.state}")
+                if telemetry.battery and telemetry.battery < 10:
+                    break
+        """
+        # Cache plan_feedback data to merge into each DeviceMSG telemetry object
+        _plan_payload: dict[str, Any] = {}
+        async for envelope in self._transport.telemetry_stream():
+            if envelope.kind == TOPIC_LEAF_PLAN_FEEDBACK:
+                _plan_payload = envelope.payload
+            elif envelope.is_telemetry:
+                t = envelope.to_telemetry()
+                if _plan_payload:
+                    t.plan_id = _plan_payload.get("planId")
+                    t.plan_state = _plan_payload.get("state")
+                    t.area_covered = _plan_payload.get("areaCovered")
+                    t.duration = _plan_payload.get("duration")
+                yield t
+
     # ------------------------------------------------------------------
     # Internal helper: publish + wait for data_feedback
     # ------------------------------------------------------------------
@@ -500,7 +466,7 @@
     # Plan management
     # ------------------------------------------------------------------
 
-    async def start_plan(self, plan_id: str, percent: int = 100) -> YarboCommandResult:
+    async def start_plan(self, plan_id: str) -> YarboCommandResult:
         """Start the plan identified by *plan_id*.
 
         Args:
@@ -513,7 +479,7 @@
             YarboTimeoutError: If no acknowledgement is received.
         """
         await self._ensure_controller()
-        return await self._publish_and_wait("start_plan", {"planId": plan_id, "percent": percent})
+        return await self._publish_and_wait("start_plan", {"planId": plan_id})
 
     async def stop_plan(self) -> YarboCommandResult:
         """Stop the currently running plan.
@@ -682,71 +648,6 @@
         await self._ensure_controller()
         return await self._publish_and_wait("del_plan", {"planId": plan_id})
 
-    async def delete_all_plans(self, *, confirm: bool = False) -> YarboCommandResult:
-        """Delete all saved plans on the robot.
-
-        Args:
-            confirm: Must be ``True`` to confirm this destructive operation.
-
-        Returns:
-            :class:`~yarbo.models.YarboCommandResult` on success.
-
-        Raises:
-            ValueError:        If *confirm* is not ``True``.
-            YarboTimeoutError: If no acknowledgement is received.
-        """
-        if not confirm:
... diff truncated: showing 800 of 2748 lines

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

Bugbot Autofix prepared fixes for both issues found in the latest run.

• ✅ Fixed: Operator precedence causes crash on timeout in _request_data_feedback
  • Added parentheses to fix operator precedence so isinstance check evaluates before attempting to call .get() on potentially None value.
• ✅ Fixed: watch_telemetry no longer updates _last_status for head validation
  • Restored the self._last_status = t assignment that was removed during refactoring to maintain head-type validation functionality.

Preview (3daca5790c)

diff --git a/src/yarbo/local.py b/src/yarbo/local.py
--- a/src/yarbo/local.py
+++ b/src/yarbo/local.py
@@ -426,6 +426,7 @@
                     t.plan_state = _plan_payload.get("state")
                     t.area_covered = _plan_payload.get("areaCovered")
                     t.duration = _plan_payload.get("duration")
+                self._last_status = t
                 yield t
 
     # ------------------------------------------------------------------
@@ -1313,7 +1314,7 @@
                 command_name=cmd,
                 _queue=wait_queue,
             )
-            return msg.get("data", {}) or {} if isinstance(msg, dict) else {}
+            return (msg.get("data", {}) or {}) if isinstance(msg, dict) else {}
         except Exception:
             self._transport.release_queue(wait_queue)
             raise

[cursor]

Operator precedence causes crash on timeout in _request_data_feedback

High Severity

The expression msg.get("data", {}) or {} if isinstance(msg, dict) else {} is parsed by Python as msg.get("data", {}) or ({} if isinstance(msg, dict) else {}) because or has higher precedence than the ternary if...else. When msg is None (the timeout case from wait_for_message), this calls None.get(...) and raises an AttributeError instead of returning {}. The intended expression needs parentheses: (msg.get("data", {}) or {}) if isinstance(msg, dict) else {}.

 

[cursor]

watch_telemetry no longer updates _last_status for head validation

Medium Severity

The refactored watch_telemetry method removed the self._last_status = t assignment that was present in the old code. This means telemetry received via watch_telemetry no longer updates _last_status, so _validate_head_type (used by set_blade_height, push_snow_dir, set_chute_steering_work, set_roller_speed, etc.) will either always warn "Head type unknown" or use a stale value from a previous get_status call, degrading head-type safety checks.