Sphero Mini 控制

通过 Bluetooth Low Energy（蓝牙低功耗）使用 Python 和 bleak 控制你的 Sphero Mini 机器人球。

功能特性

• 🎨 LED 控制 — 调整主 LED 颜色与背光 LED 亮度
• 🎯 运动控制 — 以可变速度向任意方向滚动
• 🎲 随机模式 — “猫玩模式”，执行不可预测的运动
• 📐 绘制图形 — 支持正方形、星形、圆形等，支持自定义编程图案
• 🔋 电源管理 — 唤醒、休眠及查询电池状态
• 🧭 朝向控制 — 重置并精确控制球体朝向
• 🖥️ 跨平台支持 — 兼容 macOS、Windows 和 Linux（基于 bleak，不依赖 bluepy）

环境准备

1. 安装依赖项

所有平台：

pip3 install bleak

2. 查找 Sphero Mini 的 MAC 地址 / UUID

macOS / Windows：
使用附带的扫描脚本：

python3 scripts/scan_sphero.py

在结果中查找名称类似 "SM-XXXX" 的设备（即 Sphero Mini）。

3. 更新 MAC 地址

编辑各脚本文件，将其中的 SPHERO_MAC 替换为你设备的实际地址。

快速上手

扫描 Sphero Mini

python3 scripts/scan_sphero.py

更改颜色

import asyncio
from sphero_mini_bleak import SpheroMini

async def change_color():
    sphero = SpheroMini("YOUR-MAC-ADDRESS")
    await sphero.connect()
    await sphero.wake()
    
    # 设置为红色
    await sphero.setLEDColor(255, 0, 0)
    await asyncio.sleep(2)
    
    await sphero.disconnect()

asyncio.run(change_color())

向前滚动

import asyncio
from sphero_mini_bleak import SpheroMini

async def roll_forward():
    sphero = SpheroMini("YOUR-MAC-ADDRESS")
    await sphero.connect()
    await sphero.wake()
    
    # 以速度 100 向前滚动
    await sphero.roll(100, 0)
    await asyncio.sleep(3)
    
    # 停止
    await sphero.roll(0, 0)
    await sphero.disconnect()

asyncio.run(roll_forward())

预置脚本

🐱 猫玩模式（随机运动）

python3 scripts/cat_play.py

使 Sphero Mini 在 1 分钟内随机运动并变换颜色——非常适合逗猫！

📐 绘制图形

# 绘制正方形
python3 scripts/draw_square.py

# 绘制星形
python3 scripts/draw_star.py

🎨 颜色控制

# 设置指定颜色
python3 scripts/set_color.py red
python3 scripts/set_color.py 255 0 128  # 自定义 RGB 值

常用命令

运动控制

# 滚动（速度：0–255；朝向：0–359 度）
await sphero.roll(speed=100, heading=0)    # 向前
await sphero.roll(100, 90)                  # 向右
await sphero.roll(100, 180)                 # 向后
await sphero.roll(100, 270)                 # 向左
await sphero.roll(0, 0)                     # 停止

LED 控制

# 主 LED 颜色（RGB 值范围：0–255）
await sphero.setLEDColor(red=255, green=0, blue=0)      # 红色
await sphero.setLEDColor(0, 255, 0)                     # 绿色
await sphero.setLEDColor(0, 0, 255)                     # 蓝色
await sphero.setLEDColor(128, 0, 128)                   # 紫色

# 背光 LED 亮度（0–255）
await sphero.setBackLED(255)  # 最大亮度
await sphero.setBackLED(0)    # 关闭

电源管理

# 从休眠中唤醒
await sphero.wake()

# 进入休眠（低功耗，BLE 仍保持开启）
await sphero.sleep()

# 查询电池电压
voltage = await sphero.getBatteryVoltage()
print(f"Battery: {voltage}V")

使用提示

• 唤醒 Sphero：连接前请摇晃 Sphero Mini，使其从深度休眠中唤醒
• 连接超时：若连接失败，请摇晃 Sphero Mini 后重试
• 定位 Sphero：脚本运行结束后，Sphero Mini 将自动设为白色，便于寻找
• 猫咪安全：与猫互动时请使用柔软表面，避免设备损伤

示例：猫玩模式

猫玩模式脚本会使 Sphero Mini 执行以下行为：

• 以 40–120 的速度随机方向移动
• 在 6 种高饱和度颜色之间随机切换
• 以 30% 概率触发短暂停顿（不可预测）
• 精确运行 1 分钟
• 结束时设为白色，方便你快速找到它

专为逗猫设计！🐱

故障排查

无法连接

1. 摇晃 Sphero Mini 以唤醒设备
2. 确保其未连接至 Sphero Edu App
3. 确认 MAC / UUID 地址输入正确
4. 尝试在 sphero_mini_bleak.py 中增大连接超时时间

Sphero Mini 不运动

1. 务必首先调用 await sphero.wake()
2. 唤醒后等待 1–2 秒再发送运动指令
3. 检查电池电量是否充足

颜色不变化

1. 在两次颜色设置之间添加 await asyncio.sleep(0.5)
2. 确保已调用 await sphero.wake()

库引用说明

本项目使用以下开源库：

• sphero_mini_win by trflorian — 基于 bleak 的 Sphero Mini 控制库
• bleak — 跨平台 Bluetooth Low Energy（BLE）库

注意：本库仅适用于 Sphero Mini。如需控制其他型号（如 BB8、SPRK+、Bolt），请改用 pysphero。

高级用法

自定义运动模式

创建你自己的运动路径：

async def figure_eight():
    # 绘制数字“8”轨迹
    for i in range(2):  # 循环两次
        for heading in range(0, 360, 10):
            await sphero.roll(80, heading)
            await asyncio.sleep(0.1)

彩虹色循环

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)

文档说明

• SKILL.md — 当前文档
• references/api.md — 完整 API 参考手册
• references/troubleshooting.md — 常见问题与解决方案
• scripts/ — 即开即用的示例脚本目录

许可证

MIT