Sphero Mini Control

Sphero Mini Control

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

Features

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

Example: Cat Play Mode

The cat play mode script makes Sphero:

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:

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

License

MIT

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())

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.