Yarbo Open Platform · Developer Guide

Full reference for the Python SDK (telemetry, maps, schedules, closed-loop odometry drive), OAuth 2.0 Device Flow, hardware-interlocked actuation APIs, On-Robot Linux Edge Sandboxes, and HDK v1.0 Hardware Attachment specifications.

1. Platform Overview & Dual Access Modes

Yarbo turns all-terrain modular yard robots into a programmable software and hardware robotics base with two complementary integration modes:

1.5 AI Agent Integration · Yarbo MCP Server (yarbo-mcp)

The Python SDK includes a zero-dependency Model Context Protocol (MCP) server (JSON-RPC 2.0 over stdio), enabling Claude Code, Claude Desktop, and compatible AI agents to inspect telemetry, manage schedules, and execute guarded actions:

{
  "mcpServers": {
    "yarbo": {
      "command": "yarbo-mcp",
      "args": [],
      "env": {
        "YARBO_EMAIL": "you@example.com",
        "YARBO_PASSWORD": "your-app-password",
        "YARBO_ENVIRONMENT": "prod"
      }
    }
  }
}

2. OAuth 2.0 Device Authorization Flow

  1. Request Device Code: Call POST /oauth/device_authorization with requested scopes (e.g., telemetry:read map:read plan:read control:state) to obtain user_code and verification_uri_complete.
  2. Explicit Owner Consent: The robot owner opens verification_uri_complete, reviews the application name and requested capabilities, signs in, and approves.
  3. Exchange Tokens: Poll POST /oauth/token (grant_type=device_code) to receive a 900s access_token and single-use rotating refresh_token.
  4. Request MQTT Broker Ticket: Call POST /oauth/broker-token (Bearer access_token + authorized device_id).
  5. TLS Telemetry & Whitelisted Queries: Subscribe over TLS port 8883 to snowbot/<SN>/device/DeviceMSG, or invoke POST /requests for whitelisted map and plan reads.
curl -s -X POST "https://authz.yarbo.ai/oauth/device_authorization" \
  -H "content-type: application/json" \
  -d '{"client_id":"ycl_...","client_secret":"ycs_...","scope":"telemetry:read map:read control:state"}'

3. Guarded Commands & Hardware Actuation API

Applications granted the control:state scope can issue hardware-interlocked commands via POST /commands or sequential 1–5 step POST /workflows:

curl -s -X POST "https://authz.yarbo.ai/commands" \
  -H "authorization: Bearer <access_token>" \
  -H "content-type: application/json" \
  -d '{
    "device_id": "YOUR_ROBOT_SN",
    "action": "blade_height",
    "height": 55,
    "confirm": true,
    "idempotency_key": "mow-height-55-001"
  }'

4. Hardware Attachment Bus & Edge Sensor Specifications

Yarbo Modular Core and Swappable Heads
1 Core + N Smart Heads: Shared tracked chassis with Snow, Mow, Blow & custom 3P attachments
Yarbo Hardware Attachment Bus Exploded View
Switched power rail, CAN & Ethernet quick-swap flange, linear actuator, and hardwired E-Stop loop
DomainInterface & ProtocolCapability / SDK EntrySafety Interlocks
Head Actuator & Mount Linear push-rod (0–64 position feedback), quick-release mechanical flange head_up / head_down / head_stop Over-current protection, hardwired E-Stop cutoff
Tool Motor Drives snow_roller (850–1800), leaf_blower (1000–2000), mower_blades & height (0–100) robot.run_module() / set_mower_height() Pre-checks head_type & body_stop_button_state == 0; auto stop frame on exit
Vision & Localization Stereo RGB snapshot, centimeter RTK, fused wheel/IMU odometry (CombinedOdom) sensor.read / telemetry.read Local gateway rate limit (120/min), explicit privacy consent
On-Robot Edge Sandbox Linux container / WASM + Unix socket gateway (/tmp/yarbo-rt10/plugin.sock) runtime: "car" 0.25 vCPU / 256MB limit, read-only rootfs, isolated from real-time MCU

4.5 Hardware Development Kit (HDK v1.0 · CAD / Pinout / CANopen & Ethernet)

HDK v1.0 provides mechanical and electrical reference specifications derived from the production Yarbo Mainboard V1.0.9 and quick-swap attachment interface so universities, robotics labs, and OEM partners can prototype custom heads cleanly:

Connector / FramePins / ChannelElectrical & Signal SpecsProtocol & Safety Interlock
J4 Power Rail
LCB30PB-M (2P)
Pin 1: VOUT_HEAD+
Pin 2: PGND
26V–42V DC (battery rail), 40A continuous / 60A peak (2s) Switched via U27 LM5069MM-2 hot-swap controller & high-side MOSFETs; hardwired E-Stop cuts power in < 2 ms
J19 Signal Bus
HY2.0-12P (12P)
Pin 1–4: 100BASE-TX + PoE
Pin 5–6: CAN_H / CAN_L
Pin 7–8: PPS+ / PPS-
Pin 9–10: TERM+ / TERM-
Pin 11–12: HEAD_DET / ISO_SGND
100M Ethernet + 12V PoE + CA-IS3050G isolated 1 Mbps CAN + RS422 PPS + 120Ω termination + presence sense Enable 120Ω termination on end-of-bus attachments via software-controlled TERM+/TERM-
CANopen SDO
0x600+ID / 0x580+ID
Custom 3P NodeIDs:
0x10..0x1F
8-byte standard frame: [cmd, idx_lo, idx_hi, sub, d0, d1, d2, d3] Isolated from official chassis and head NodeIDs (0x01..0x0F)
CANopen TPDO
0x180+ID .. 0x480+ID
0x180+ID RPM/Current/Rod
0x280+ID Rails/Temp
10 Hz–50 Hz periodic telemetry (little-endian uint16/int16) Chassis broadcast 0x68C Bit 32 is the E-Stop flag: attachments must halt within 50 ms when set to 1

5. GPS-Denied Garage Automation: Closed-Loop Odometry Drive

For indoor or covered garages without RTK/GPS reception, robot.undock() and robot.drive_odom() provide bounded closed-loop short-range navigation over fused wheel/IMU odometry:

from yarbo_sdk import YarboAccount

with YarboAccount(environment="prod") as account:
    account.login(email, password)
    robot = account.robot(device_id)

    # 1. Undock from indoor charging pad
    robot.undock(timeout=10)

    # 2. Closed-loop 6.0 m exit along initial heading (200 ms cmd_vel + 1 s safety watchdog)
    res = robot.drive_odom(
        distance_m=6.0,
        speed_m_s=0.2,
        tolerance_m=0.08,
        max_duration_seconds=60,
        odom_stale_seconds=1.5,
    )
    print(res.termination, res.distance_travelled)

Safety bounds: single move ≤ 10 m, speed ≤ 0.4 m/s. Arrival within tolerance, cancellation, timeout, stale odometry, non-zero error_code, or any E-Stop/bumper trigger halts motion immediately and transmits a zero-velocity stop frame.

6. Core REST & MQTT Endpoints

REST Base URL: https://authz.yarbo.ai · MQTT TLS Port: 8883.

MethodPathDescription
POST/applySelf-service Console registration; returns one-time sandbox client_id / client_secret
POST/portal/request-productionSubmit production quota & scope upgrade request after sandbox validation
POST/portal/statusInspect application status, tier (sandbox / production), and active rate quota
POST/oauth/device_authorizationStart OAuth 2.0 Device Flow (supports optional plugin_id and granular scope)
POST/oauth/tokenExchange device code for tokens or rotate single-use refresh_token
POST/oauth/broker-tokenIssue short-lived (3600s) scoped MQTT TLS credentials for an authorized robot
POST/oauth/revokeRevoke grant immediately and disconnect active MQTT sessions within 1–2s
POST / GET/commands · /commands/{id}Send guarded hardware commands (with confirm: true & idempotency_key) and inspect receipts
POST/requestsExecute whitelisted read queries (get_device_msg, map parameters, plans, schedules)
POST/workflowsExecute 1–5 sequential guarded actions with stop-on-failure semantics
GET / POST/plugins · /plugins/{id}/installationsBrowse verified plugins and deploy to cloud (Fargate) or car (On-Robot Linux Sandbox)
POST/dev/plugins/submitSubmit plugin source & manifest for automated S0–S4 security audit and S5 review

7. Self-Service Onboarding Walkthrough

Use the Developer Console to generate sandbox credentials, validate OAuth 2.0 Device Flow against an authorized robot, and upgrade to production quotas:

Yarbo Self-Service Developer Onboarding and OAuth 2.0 Device Flow
  1. Create Sandbox Credentials: Open Console → 1. Get Sandbox Credentials, describe your integration use case, and save the one-time client_secret (10 req/min sandbox tier).
  2. Authorize Test Robot: Initiate POST /oauth/device_authorization and approve the user_code on /device using the robot owner’s Yarbo account.
  3. Validate Telemetry & Guarded Calls: Exchange a short-lived broker ticket via POST /oauth/broker-token, verify readback-safe map/schedule previews, and test error handling.
  4. Upgrade to Production: Submit Console → 2. Request Production Access with your validation notes; once approved, your client upgrades to production (60 req/min).

8. Python SDK Daily Resource Examples

from yarbo_sdk import YarboAccount, ScheduleTiming

with YarboAccount(environment="prod") as account:
    account.login(email, password)
    robot = account.robot(device_id)

    # 1. One-shot telemetry snapshot & hardware capability check
    snap = robot.status()
    cap_report = robot.read_capabilities()

    # 2. Read yard maps & update zone attributes with baseline + readback verification
    maps = robot.maps.read()
    res_map = robot.maps.update("area", area_id, {"name": "Front Lawn"})

    # 3. Rename a work plan & configure timezone-explicit recurring schedule
    res_plan = robot.plans.rename(plan_id, "Weekend Perimeter Clean")
    timing = ScheduleTiming.local(
        "08:30", "10:00",
        week_day=0b0111110,
        zone="America/New_York",
        start_date="2026-11-05",
        end_date="2026-11-05",
    )
    res_sched = robot.schedules.set_timing(schedule_id, timing)

9. Error Codes & Rate Limits

Error CodeMeaningRecommended Handling
authorization_pendingRobot owner has not approved the consent screen yetContinue polling at the returned interval
access_deniedOwner declined consent or target robot is outside grant scopeStop polling and prompt the user to review device grants
invalid_scopeClient or token lacks required scope (e.g., control:state)Request a new authorization grant including the needed scope
confirmation_requiredActuation call omitted "confirm": trueObtain explicit user confirmation and pass confirm: true
commands_disabledPlatform-wide safety kill switch is activePause actuation requests until service status clears
invalid_grantGrant revoked by owner, refresh token expired, or replay detectedPurge stored tokens immediately and do not auto-reconnect
quota_exceeded (429)Rate limit exceeded (Sandbox 10/min, Prod 60/min, Commands 5/min/robot)Back off exponentially before retrying

10. Cloud & On-Robot Plugin Submission & Local Route Control

Each plugin bundle declares a manifest.json and entry script (plugin.py) targeting either AWS Fargate (cloud) or the isolated On-Robot Linux Sandbox (car):

{
  "id": "yarbo.route-control",
  "version": "0.1.0",
  "name": "Car Route Controller",
  "description": "Closed-loop local waypoint route tracking via on-robot capability gateway",
  "runtime": "python3.11",
  "entry": "plugin.py",
  "capabilities": ["telemetry.read", "control.motion"]
}
  1. Self-Service Submission (Automated S0–S4 Audit): Submit your credentials, manifest fields, and plugin.py on Plugins (or via POST /dev/plugins/submit). The service packages, SHA-256 signs, and runs S0–S4 static & privilege checks, placing passing builds in pending_review.
  2. S5 Marketplace Approval: Once approved in Admin, the plugin transitions to active in the marketplace catalog.
  3. One-Click Robot Deployment: Deploy to an authorized robot SN with runtime car; the on-robot agent verifies the signature and starts the sandbox container (requested → installing → active).

On-robot containers run without public internet access and invoke bounded motion methods over the local Unix socket gateway (POST http://localhost/v1/gateway/invoke → /tmp/yarbo-rt10/plugin.sock, capped at 300 calls/min):

11. Release Changelog

VersionDateHighlights
0.2.0a18
Latest
2026-11-04 Yarbo MCP Server (yarbo-mcp) & Live Indoor Odom Calibration: Zero-dependency Model Context Protocol server over stdio exposing 13 tools (6 read-only inspection, 4 readback-verified config edits, 3 bounded actuation tools), guarded by confirm=True and YARBO_MCP_READ_ONLY=1. Completed Phase 3 live robot calibration for SDK-LOCAL-001 in GPS-denied indoor environments.
0.2.0a17 2026-11-03 SDK-LOCAL-001 Closed-Loop Odometry & HDK v1.0: Added robot.undock(), robot.drive_odom() (200 ms cmd_vel streaming + 1 s telemetry watchdog + zero-velocity stop), and examples/garage_demo.py. Released HDK v1.0 (3D STEP flange model, J4/J19 pinout SVG, CANopen JSON & DBC) and production OAuth 2.0 Device Flow.
0.2.0a16 2026-10-22 Simplified Daily Resource APIs: Added ergonomic facades for robot.status(), robot.maps, robot.plans, robot.schedules, and robot.jobs with offline previews (preview_*) and automatic readback verification.
0.2.0a10 2026-10-21 Bounded Actuation, Map/Plan Codecs & Capability Inspection: Added bounded velocity drive, tool motor control (snow_roller, leaf_blower, mower_blades), cutting deck height (0–100), Rover BLE map packet decoding, offline map compatibility checks, and read_capabilities().
0.1.0 2026-10-20 Initial Read-Only Telemetry SDK (SDK-RO-001): Passive TLS 8883 MqttReader, YarboAccount session management, explicit one-shot get_device_msg queries, and per-field reception timestamps.

12. License & Commercial Partnership

SDK source code is provided under the PolyForm Noncommercial License 1.0.0, subject to the Yarbo Data SDK Terms of Use (V1.1). Commercial integrations, dealer fleet operations, and commercial hardware attachments require a separate written license from Yarbo (software@yarbo.com).