sphero-mini – OpenClaw Skill

---

name: sphero-mini description: Control Sphero Mini robot ball via Bluetooth Low Energy. Roll, change colors, read sensors, draw shapes, and play with cats. Uses bleak for cross-platform BLE support (macOS/Windows/Linux). homepage: https://github.com/trflorian/sphero_mini_win metadata: { "openclaw": { "emoji": "⚽", "requires": { "bins": ["python3"], "packages": ["bleak"] }, "install": [ { "id": "sphero-bleak", "kind": "pip", "package": "bleak", "label": "Install bleak (Bluetooth Low Energy library for macOS/Windows/Linux)", }, ], }, }

Sphero Mini Control

Control your Sphero Mini robot ball via Bluetooth Low Energy using Python and bleak.

Features

• 🎨 LED Control - Change main LED color and back LED intensity
• 🎯 Movement - Roll in any direction at variable speeds
• 🎲 Random Mode - Cat play mode with unpredictable movements
• 📐 Draw Shapes - Squares, stars, circles with programmable patterns
• 🔋 Power Management - Wake, sleep, and check battery status
• 🧭 Heading Control - Reset and control orientation
• 🖥️ Cross-platform - Works on macOS, Windows, and Linux (uses bleak, not bluepy)

Setup

1. Install Dependencies

All platforms:

pip3 install bleak

2. Find Your Sphero Mini's MAC/UUID

macOS/Windows: Use the included scan script:

python3 scripts/scan_sphero.py

Look for a device named like "SM-XXXX" (Sphero Mini).

3. Update MAC Address

Edit the scripts and replace SPHERO_MAC with your device's address.

Quick Start

Scan for Sphero Mini

python3 scripts/scan_sphero.py

Change Color

import asyncio
from sphero_mini_bleak import SpheroMini

async def change_color():
    sphero = SpheroMini("YOUR-MAC-ADDRESS")
    await sphero.connect()
    await sphero.wake()
    
    # Set to red
    await sphero.setLEDColor(255, 0, 0)
    await asyncio.sleep(2)
    
    await sphero.disconnect()

asyncio.run(change_color())

Roll Forward

import asyncio
from sphero_mini_bleak import SpheroMini

async def roll_forward():
    sphero = SpheroMini("YOUR-MAC-ADDRESS")
    await sphero.connect()
    await sphero.wake()
    
    # Roll forward at speed 100
    await sphero.roll(100, 0)
    await asyncio.sleep(3)
    
    # Stop
    await sphero.roll(0, 0)
    await sphero.disconnect()

asyncio.run(roll_forward())

Pre-built Scripts

🐱 Cat Play Mode (Random Movement)

python3 scripts/cat_play.py

Makes Sphero move randomly for 1 minute with color changes - perfect for playing with cats!

📐 Draw Shapes

# Draw a square
python3 scripts/draw_square.py

# Draw a star
python3 scripts/draw_star.py

🎨 Color Control

# Set specific color
python3 scripts/set_color.py red
python3 scripts/set_color.py 255 0 128  # Custom RGB

Common Commands

Movement

# Roll (speed: 0-255, heading: 0-359 degrees)
await sphero.roll(speed=100, heading=0)    # Forward
await sphero.roll(100, 90)                  # Right
await sphero.roll(100, 180)                 # Backward
await sphero.roll(100, 270)                 # Left
await sphero.roll(0, 0)                     # Stop

LED Control

# Main LED color (RGB values 0-255)
await sphero.setLEDColor(red=255, green=0, blue=0)      # Red
await sphero.setLEDColor(0, 255, 0)                     # Green
await sphero.setLEDColor(0, 0, 255)                     # Blue
await sphero.setLEDColor(128, 0, 128)                   # Purple

# Back LED brightness (0-255)
await sphero.setBackLED(255)  # Full brightness
await sphero.setBackLED(0)    # Off

Power Management

# Wake from sleep
await sphero.wake()

# Go to sleep (low power, BLE still on)
await sphero.sleep()

# Check battery voltage
voltage = await sphero.getBatteryVoltage()
print(f"Battery: {voltage}V")

Tips

• Wake Sphero: Shake it to wake from deep sleep before connecting
• Connection timeout: If connection fails, shake Sphero and try again
• Finding Sphero: After scripts finish, Sphero is set to white for easy visibility
• Cat safety: Use soft surfaces when playing with cats to avoid damage

Example: Cat Play Mode

The cat play mode script makes Sphero:

• Move in random directions (40-120 speed)
• Change colors randomly (6 vibrant colors)
• Stop unpredictably (30% chance for brief pauses)
• Run for exactly 1 minute
• End with white color so you can find it

Perfect for entertaining cats! 🐱

Troubleshooting

Cannot Connect

1. Shake Sphero to wake it up
2. Ensure it's not connected to the Sphero Edu app
3. Check MAC/UUID address is correct
4. Try increasing timeout in sphero_mini_bleak.py

Sphero Doesn't Move

1. Call await sphero.wake() first
2. Wait 1-2 seconds after waking
3. Check battery level

Colors Don't Change

1. Add await asyncio.sleep(0.5) between color changes
2. Ensure you called await sphero.wake()

Library Credits

This skill uses:

• sphero_mini_win by trflorian - Sphero Mini control library using bleak
• bleak - Cross-platform Bluetooth Low Energy library

Note: This library is for Sphero Mini only. For other Sphero models (BB8, SPRK+, Bolt), use pysphero instead.

Advanced Usage

Custom Patterns

Create your own movement patterns:

async def figure_eight():
    # Draw a figure-8 pattern
    for i in range(2):  # Two loops
        for heading in range(0, 360, 10):
            await sphero.roll(80, heading)
            await asyncio.sleep(0.1)

Color Cycling

async def rainbow():
    colors = [
        (255, 0, 0), (255, 127, 0), (255, 255, 0),
        (0, 255, 0), (0, 0, 255), (75, 0, 130), (148, 0, 211)
    ]
    for r, g, b in colors:
        await sphero.setLEDColor(r, g, b)
        await asyncio.sleep(1)

Documentation

• SKILL.md — This file
• references/api.md — Complete API reference
• references/troubleshooting.md — Common issues and solutions
• scripts/ — Ready-to-use example scripts

License

MIT

Sphero Mini Control Skill for OpenClaw

Control your Sphero Mini robot ball via Bluetooth Low Energy with Python.

🎮 What Can It Do?

• 🎨 Change Colors — RGB LED control
• 🎯 Precise Movement — Roll in any direction
• 🐱 Cat Play Mode — Random movement to entertain cats
• 📐 Draw Shapes — Squares, stars, and custom patterns
• 🔋 Power Management — Wake, sleep, battery check
• 🖥️ Cross-platform — Works on macOS, Windows, and Linux

🚀 Quick Start

1. Install

pip3 install bleak

2. Find Your Sphero

python3 scripts/scan_sphero.py

3. Play!

Cat Play Mode:

python3 scripts/cat_play.py

Draw Shapes:

python3 scripts/draw_square.py
python3 scripts/draw_star.py

🐱 Cat Play Mode

Perfect for entertaining cats! Sphero will:

• Move randomly for 1 minute
• Change colors constantly (red, green, blue, yellow, magenta, cyan)
• Stop unpredictably to keep it interesting
• End with white color so you can find it

Tested with real cats — they love it! 😻

📦 What's Included

• sphero_mini_bleak.py — Main control library (bleak-based, cross-platform)
• scan_sphero.py — Find your Sphero's MAC/UUID address
• cat_play.py — Random movement mode for playing with cats
• draw_square.py — Make Sphero draw a square
• draw_star.py — Make Sphero draw a 5-pointed star
• SKILL.md — Complete usage guide

🔧 Example: Change Color

import asyncio
from scripts.sphero_mini_bleak import SpheroMini

async def purple():
    sphero = SpheroMini("YOUR-MAC-ADDRESS")
    await sphero.connect()
    await sphero.wake()
    await sphero.setLEDColor(128, 0, 128)  # Purple
    await asyncio.sleep(3)
    await sphero.disconnect()

asyncio.run(purple())

🎯 Example: Draw a Circle

import asyncio
from scripts.sphero_mini_bleak import SpheroMini

async def circle():
    sphero = SpheroMini("YOUR-MAC-ADDRESS")
    await sphero.connect()
    await sphero.wake()
    
    # Spin in a circle
    for heading in range(0, 360, 10):
        await sphero.roll(60, heading)
        await asyncio.sleep(0.1)
    
    await sphero.roll(0, 0)
    await sphero.disconnect()

asyncio.run(circle())

⚠️ Important Notes

• Wake Sphero first: Shake it to wake from deep sleep
• One Sphero Mini only: This library is specifically for Sphero Mini
• For other models (BB8, SPRK+, Bolt): Use pysphero instead
• Connection timeout: If it fails, shake Sphero and try again

🔗 Credits

• Based on sphero_mini_win by trflorian
• Uses bleak for Bluetooth LE

📖 Documentation

See SKILL.md for complete API reference and advanced examples.

🎉 Tested Features

✅ Connecting/disconnecting
✅ Color changes (red, green, blue, purple, custom RGB)
✅ Movement control (roll, stop)
✅ Drawing shapes (square, star)
✅ Cat play mode (1 minute random movement)
✅ Cross-platform support (macOS confirmed, Windows/Linux compatible)

📝 License

MIT