名称： sphero-mini
描述： 通过蓝牙低功耗（BLE）控制 Sphero Mini 机器人球。可滚动、变色、读取传感器、绘制图形，还能逗猫玩耍。使用 bleak 库实现跨平台 BLE 支持（macOS/Windows/Linux）。
主页： https://github.com/trflorian/sphero_mini_win
元数据：
{
"openclaw":
{
"emoji": "⚽",
"requires": { "bins": ["python3"], "packages": ["bleak"] },
"install":
[
{
"id": "sphero-bleak",
"kind": "pip",
"package": "bleak",
"label": "安装 bleak（适用于 macOS/Windows/Linux 的蓝牙低功耗库）",
},
],
},
}

Sphero Mini 控制

使用 Python 和 bleak 库，通过蓝牙低功耗（BLE）控制你的 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("你的-MAC-地址")
    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("你的-MAC-地址")
    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 随机运动 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"电池电压：{voltage}V")

使用提示

• 唤醒 Sphero：连接前摇晃它以从深度休眠中唤醒
• 连接超时：如果连接失败，摇晃 Sphero 后重试
• 寻找 Sphero：脚本运行结束后，Sphero 会设置为白色以便于寻找
• 猫咪安全：与猫咪玩耍时使用柔软表面，避免损坏

示例：逗猫模式

逗猫模式脚本让 Sphero：
- 随机方向运动（速度 40-120）
- 随机变换颜色（6 种鲜艳色彩）
- 不可预测地暂停（30% 概率短暂停顿）
- 运行 1 分钟
- 结束后变为白色以便寻找

非常适合娱乐猫咪！🐱

故障排除

无法连接

1. 摇晃 Sphero 唤醒它
2. 确保它未连接到 Sphero Edu 应用
3. 检查 MAC/UUID 地址是否正确
4. 尝试增加 sphero_mini_bleak.py 中的超时时间

Sphero 不运动

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 - 跨平台蓝牙低功耗库

注意：此库仅适用于 Sphero Mini。对于其他 Sphero 型号（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