sphero-mini

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