Sphero Mini Control

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

Security Scan

The package appears to implement a legitimate Sphero Mini BLE controller and only installs bleak, but there are multiple inconsistencies (missing/mismatched scripts and API names) that make the bundle sloppy and warrant review before running.

Purpose & Capability

Name/description match the included code and the only declared dependency is bleak (a BLE library). Requiring python3 and bleak is proportional for a Bluetooth robot control skill.

Instruction Scope

SKILL.md and README contain usage examples that reference some files/functions that are not present or have different names in the bundle (e.g., calls to getBatteryVoltage vs. getVoltage, references to scripts/set_color.py which is not in the manifest). scripts/sphero_control.py imports 'sphero_mini' which is not included (the main library present is sphero_mini_bleak.py). These mismatches could cause confusion or cause users to run the wrong commands; instructions also suggest optional curl downloads from GitHub raw URLs in docs (not executed by install but could prompt users to fetch extra code).

Install Mechanism

Install spec only uses pip to install the well-known 'bleak' package. No arbitrary URL downloads, no archive extraction, and no nonstandard install locations were declared.

Credentials

The skill requests no environment variables, no credentials, and no config paths. There are no surprising secret or credential requests relative to the stated purpose.

Persistence & Privilege

always is false and the skill does not request elevated platform privileges or modify other skills/config. It runs as normal user-space scripts and does not request permanent presence.

What to consider before installing

This package largely does what it claims (BLE control for a Sphero Mini) and installs only the standard bleak library, but there are several mismatches and missing files that make it risky to run without inspection. Before installing/running: 1) Review scripts/sphero_mini_bleak.py (you already have it) and confirm the API names used (e.g., getVoltage vs getBatteryVoltage) and the AntiDOS write are acceptable; 2) Note missing or inconsistent files referenced in docs (sphero_control.py imports sphero_mini which isn't included; SKILL.md/README mention set_color.py and getBatteryVoltage which are absent or differently named). Either fix imports or run the scripts that explicitly import sphero_mini_bleak.py. 3) Do not run curl commands from docs without verifying the target URLs; those example commands would download third-party code. 4) Run BLE scripts from an unprivileged account and be prepared to grant Bluetooth permissions (on Linux you may need capabilities or sudo). If you want to proceed, test on a system where unexpected behavior (e.g., uncontrolled robot movement) is safe and review any external code referenced in the documentation first.

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