{
  "schemaVersion": "1.0",
  "item": {
    "slug": "sphero-mini",
    "name": "Sphero Mini Control",
    "source": "tencent",
    "type": "skill",
    "category": "通讯协作",
    "sourceUrl": "https://clawhub.ai/JonesChi/sphero-mini",
    "canonicalUrl": "https://clawhub.ai/JonesChi/sphero-mini",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/sphero-mini",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=sphero-mini",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "references/examples.md",
      "references/api.md",
      "references/troubleshooting.md",
      "README.md",
      "scripts/draw_square.py",
      "scripts/draw_star.py"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/sphero-mini"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/sphero-mini",
    "agentPageUrl": "https://openagent3.xyz/skills/sphero-mini/agent",
    "manifestUrl": "https://openagent3.xyz/skills/sphero-mini/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/sphero-mini/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Sphero Mini Control",
        "body": "Control your Sphero Mini robot ball via Bluetooth Low Energy using Python and bleak."
      },
      {
        "title": "Features",
        "body": "🎨 LED Control - Change main LED color and back LED intensity\n🎯 Movement - Roll in any direction at variable speeds\n🎲 Random Mode - Cat play mode with unpredictable movements\n📐 Draw Shapes - Squares, stars, circles with programmable patterns\n🔋 Power Management - Wake, sleep, and check battery status\n🧭 Heading Control - Reset and control orientation\n🖥️ Cross-platform - Works on macOS, Windows, and Linux (uses bleak, not bluepy)"
      },
      {
        "title": "1. Install Dependencies",
        "body": "All platforms:\n\npip3 install bleak"
      },
      {
        "title": "2. Find Your Sphero Mini's MAC/UUID",
        "body": "macOS/Windows:\nUse the included scan script:\n\npython3 scripts/scan_sphero.py\n\nLook for a device named like \"SM-XXXX\" (Sphero Mini)."
      },
      {
        "title": "3. Update MAC Address",
        "body": "Edit the scripts and replace SPHERO_MAC with your device's address."
      },
      {
        "title": "Scan for Sphero Mini",
        "body": "python3 scripts/scan_sphero.py"
      },
      {
        "title": "Change Color",
        "body": "import asyncio\nfrom sphero_mini_bleak import SpheroMini\n\nasync def change_color():\n    sphero = SpheroMini(\"YOUR-MAC-ADDRESS\")\n    await sphero.connect()\n    await sphero.wake()\n    \n    # Set to red\n    await sphero.setLEDColor(255, 0, 0)\n    await asyncio.sleep(2)\n    \n    await sphero.disconnect()\n\nasyncio.run(change_color())"
      },
      {
        "title": "Roll Forward",
        "body": "import asyncio\nfrom sphero_mini_bleak import SpheroMini\n\nasync def roll_forward():\n    sphero = SpheroMini(\"YOUR-MAC-ADDRESS\")\n    await sphero.connect()\n    await sphero.wake()\n    \n    # Roll forward at speed 100\n    await sphero.roll(100, 0)\n    await asyncio.sleep(3)\n    \n    # Stop\n    await sphero.roll(0, 0)\n    await sphero.disconnect()\n\nasyncio.run(roll_forward())"
      },
      {
        "title": "🐱 Cat Play Mode (Random Movement)",
        "body": "python3 scripts/cat_play.py\n\nMakes Sphero move randomly for 1 minute with color changes - perfect for playing with cats!"
      },
      {
        "title": "📐 Draw Shapes",
        "body": "# Draw a square\npython3 scripts/draw_square.py\n\n# Draw a star\npython3 scripts/draw_star.py"
      },
      {
        "title": "🎨 Color Control",
        "body": "# Set specific color\npython3 scripts/set_color.py red\npython3 scripts/set_color.py 255 0 128  # Custom RGB"
      },
      {
        "title": "Movement",
        "body": "# Roll (speed: 0-255, heading: 0-359 degrees)\nawait sphero.roll(speed=100, heading=0)    # Forward\nawait sphero.roll(100, 90)                  # Right\nawait sphero.roll(100, 180)                 # Backward\nawait sphero.roll(100, 270)                 # Left\nawait sphero.roll(0, 0)                     # Stop"
      },
      {
        "title": "LED Control",
        "body": "# Main LED color (RGB values 0-255)\nawait sphero.setLEDColor(red=255, green=0, blue=0)      # Red\nawait sphero.setLEDColor(0, 255, 0)                     # Green\nawait sphero.setLEDColor(0, 0, 255)                     # Blue\nawait sphero.setLEDColor(128, 0, 128)                   # Purple\n\n# Back LED brightness (0-255)\nawait sphero.setBackLED(255)  # Full brightness\nawait sphero.setBackLED(0)    # Off"
      },
      {
        "title": "Power Management",
        "body": "# Wake from sleep\nawait sphero.wake()\n\n# Go to sleep (low power, BLE still on)\nawait sphero.sleep()\n\n# Check battery voltage\nvoltage = await sphero.getBatteryVoltage()\nprint(f\"Battery: {voltage}V\")"
      },
      {
        "title": "Tips",
        "body": "Wake Sphero: Shake it to wake from deep sleep before connecting\nConnection timeout: If connection fails, shake Sphero and try again\nFinding Sphero: After scripts finish, Sphero is set to white for easy visibility\nCat safety: Use soft surfaces when playing with cats to avoid damage"
      },
      {
        "title": "Example: Cat Play Mode",
        "body": "The cat play mode script makes Sphero:\n\nMove in random directions (40-120 speed)\nChange colors randomly (6 vibrant colors)\nStop unpredictably (30% chance for brief pauses)\nRun for exactly 1 minute\nEnd with white color so you can find it\n\nPerfect for entertaining cats! 🐱"
      },
      {
        "title": "Cannot Connect",
        "body": "Shake Sphero to wake it up\nEnsure it's not connected to the Sphero Edu app\nCheck MAC/UUID address is correct\nTry increasing timeout in sphero_mini_bleak.py"
      },
      {
        "title": "Sphero Doesn't Move",
        "body": "Call await sphero.wake() first\nWait 1-2 seconds after waking\nCheck battery level"
      },
      {
        "title": "Colors Don't Change",
        "body": "Add await asyncio.sleep(0.5) between color changes\nEnsure you called await sphero.wake()"
      },
      {
        "title": "Library Credits",
        "body": "This skill uses:\n\nsphero_mini_win by trflorian - Sphero Mini control library using bleak\nbleak - Cross-platform Bluetooth Low Energy library\n\nNote: This library is for Sphero Mini only. For other Sphero models (BB8, SPRK+, Bolt), use pysphero instead."
      },
      {
        "title": "Custom Patterns",
        "body": "Create your own movement patterns:\n\nasync def figure_eight():\n    # Draw a figure-8 pattern\n    for i in range(2):  # Two loops\n        for heading in range(0, 360, 10):\n            await sphero.roll(80, heading)\n            await asyncio.sleep(0.1)"
      },
      {
        "title": "Color Cycling",
        "body": "async def rainbow():\n    colors = [\n        (255, 0, 0), (255, 127, 0), (255, 255, 0),\n        (0, 255, 0), (0, 0, 255), (75, 0, 130), (148, 0, 211)\n    ]\n    for r, g, b in colors:\n        await sphero.setLEDColor(r, g, b)\n        await asyncio.sleep(1)"
      },
      {
        "title": "Documentation",
        "body": "SKILL.md — This file\nreferences/api.md — Complete API reference\nreferences/troubleshooting.md — Common issues and solutions\nscripts/ — Ready-to-use example scripts"
      },
      {
        "title": "License",
        "body": "MIT"
      }
    ],
    "body": "Sphero Mini Control\n\nControl your Sphero Mini robot ball via Bluetooth Low Energy using Python and bleak.\n\nFeatures\n🎨 LED Control - Change main LED color and back LED intensity\n🎯 Movement - Roll in any direction at variable speeds\n🎲 Random Mode - Cat play mode with unpredictable movements\n📐 Draw Shapes - Squares, stars, circles with programmable patterns\n🔋 Power Management - Wake, sleep, and check battery status\n🧭 Heading Control - Reset and control orientation\n🖥️ Cross-platform - Works on macOS, Windows, and Linux (uses bleak, not bluepy)\nSetup\n1. Install Dependencies\n\nAll platforms:\n\npip3 install bleak\n\n2. Find Your Sphero Mini's MAC/UUID\n\nmacOS/Windows: Use the included scan script:\n\npython3 scripts/scan_sphero.py\n\n\nLook for a device named like \"SM-XXXX\" (Sphero Mini).\n\n3. Update MAC Address\n\nEdit the scripts and replace SPHERO_MAC with your device's address.\n\nQuick Start\nScan for Sphero Mini\npython3 scripts/scan_sphero.py\n\nChange Color\nimport asyncio\nfrom sphero_mini_bleak import SpheroMini\n\nasync def change_color():\n    sphero = SpheroMini(\"YOUR-MAC-ADDRESS\")\n    await sphero.connect()\n    await sphero.wake()\n    \n    # Set to red\n    await sphero.setLEDColor(255, 0, 0)\n    await asyncio.sleep(2)\n    \n    await sphero.disconnect()\n\nasyncio.run(change_color())\n\nRoll Forward\nimport asyncio\nfrom sphero_mini_bleak import SpheroMini\n\nasync def roll_forward():\n    sphero = SpheroMini(\"YOUR-MAC-ADDRESS\")\n    await sphero.connect()\n    await sphero.wake()\n    \n    # Roll forward at speed 100\n    await sphero.roll(100, 0)\n    await asyncio.sleep(3)\n    \n    # Stop\n    await sphero.roll(0, 0)\n    await sphero.disconnect()\n\nasyncio.run(roll_forward())\n\nPre-built Scripts\n🐱 Cat Play Mode (Random Movement)\npython3 scripts/cat_play.py\n\n\nMakes Sphero move randomly for 1 minute with color changes - perfect for playing with cats!\n\n📐 Draw Shapes\n# Draw a square\npython3 scripts/draw_square.py\n\n# Draw a star\npython3 scripts/draw_star.py\n\n🎨 Color Control\n# Set specific color\npython3 scripts/set_color.py red\npython3 scripts/set_color.py 255 0 128  # Custom RGB\n\nCommon Commands\nMovement\n# Roll (speed: 0-255, heading: 0-359 degrees)\nawait sphero.roll(speed=100, heading=0)    # Forward\nawait sphero.roll(100, 90)                  # Right\nawait sphero.roll(100, 180)                 # Backward\nawait sphero.roll(100, 270)                 # Left\nawait sphero.roll(0, 0)                     # Stop\n\nLED Control\n# Main LED color (RGB values 0-255)\nawait sphero.setLEDColor(red=255, green=0, blue=0)      # Red\nawait sphero.setLEDColor(0, 255, 0)                     # Green\nawait sphero.setLEDColor(0, 0, 255)                     # Blue\nawait sphero.setLEDColor(128, 0, 128)                   # Purple\n\n# Back LED brightness (0-255)\nawait sphero.setBackLED(255)  # Full brightness\nawait sphero.setBackLED(0)    # Off\n\nPower Management\n# Wake from sleep\nawait sphero.wake()\n\n# Go to sleep (low power, BLE still on)\nawait sphero.sleep()\n\n# Check battery voltage\nvoltage = await sphero.getBatteryVoltage()\nprint(f\"Battery: {voltage}V\")\n\nTips\nWake Sphero: Shake it to wake from deep sleep before connecting\nConnection timeout: If connection fails, shake Sphero and try again\nFinding Sphero: After scripts finish, Sphero is set to white for easy visibility\nCat safety: Use soft surfaces when playing with cats to avoid damage\nExample: Cat Play Mode\n\nThe cat play mode script makes Sphero:\n\nMove in random directions (40-120 speed)\nChange colors randomly (6 vibrant colors)\nStop unpredictably (30% chance for brief pauses)\nRun for exactly 1 minute\nEnd with white color so you can find it\n\nPerfect for entertaining cats! 🐱\n\nTroubleshooting\nCannot Connect\nShake Sphero to wake it up\nEnsure it's not connected to the Sphero Edu app\nCheck MAC/UUID address is correct\nTry increasing timeout in sphero_mini_bleak.py\nSphero Doesn't Move\nCall await sphero.wake() first\nWait 1-2 seconds after waking\nCheck battery level\nColors Don't Change\nAdd await asyncio.sleep(0.5) between color changes\nEnsure you called await sphero.wake()\nLibrary Credits\n\nThis skill uses:\n\nsphero_mini_win by trflorian - Sphero Mini control library using bleak\nbleak - Cross-platform Bluetooth Low Energy library\n\nNote: This library is for Sphero Mini only. For other Sphero models (BB8, SPRK+, Bolt), use pysphero instead.\n\nAdvanced Usage\nCustom Patterns\n\nCreate your own movement patterns:\n\nasync def figure_eight():\n    # Draw a figure-8 pattern\n    for i in range(2):  # Two loops\n        for heading in range(0, 360, 10):\n            await sphero.roll(80, heading)\n            await asyncio.sleep(0.1)\n\nColor Cycling\nasync def rainbow():\n    colors = [\n        (255, 0, 0), (255, 127, 0), (255, 255, 0),\n        (0, 255, 0), (0, 0, 255), (75, 0, 130), (148, 0, 211)\n    ]\n    for r, g, b in colors:\n        await sphero.setLEDColor(r, g, b)\n        await asyncio.sleep(1)\n\nDocumentation\nSKILL.md — This file\nreferences/api.md — Complete API reference\nreferences/troubleshooting.md — Common issues and solutions\nscripts/ — Ready-to-use example scripts\nLicense\n\nMIT"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/JonesChi/sphero-mini",
    "publisherUrl": "https://clawhub.ai/JonesChi/sphero-mini",
    "owner": "JonesChi",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/sphero-mini",
    "downloadUrl": "https://openagent3.xyz/downloads/sphero-mini",
    "agentUrl": "https://openagent3.xyz/skills/sphero-mini/agent",
    "manifestUrl": "https://openagent3.xyz/skills/sphero-mini/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/sphero-mini/agent.md"
  }
}