andresjjn/alpha1s-sdk

# alpha1s **用于 UBTECH Alpha 1S 人形机器人的 Python SDK。** 2016年，UBTECH 销售了 Alpha 1S —— 一款配备 16 个 servo 的爱好者级人形机器人。随着公司业务转移，官方应用早已停止维护，成千上万的机器人因此沦为了架子上的摆设。本 SDK 通过逆向工程破解了机器人的 Bluetooth 协议，让你的机器人能够重获新生。 ``` from alpha1s import Alpha1s, poses with Alpha1s() as robot: print(robot.battery()) # {'mv': 8012, 'percent': 85, 'charging': False} robot.servo_write_all(poses.init) # stand in the calibrated neutral pose robot.play_action("Hug") # trigger a factory action stored on the robot ``` ## 安装 ``` pip install alpha1s # core (protocol + API) pip install "alpha1s[rfcomm]" # + classic Bluetooth backend (Linux — most reliable) pip install "alpha1s[ble]" # + BLE backend via bleak (cross-platform) ``` ## 协议（有趣的部分） 没有人完整地记录过 Alpha 1S 的通信协议，因此它是通过抓包和逆向工程得出的。每一个数据帧，无论是发送还是接收方向： ``` FB BF LEN PAYLOAD... CHK ED │ │ │ │ └─ fixed tail │ │ │ └─ (LEN + Σ payload) % 256 │ │ └─ command opcode + parameters │ └─ 4 + len(payload) └─ fixed 2-byte header ``` - 传输层：经典 Bluetooth **RFCOMM，通道 6**（BLE 取决于固件版本）。 - 最核心的 opcode 是 `0x23`：**一帧控制全部 16 个 servo** —— 可以实现约 2.5 Hz 的流畅全身关键帧动画。 - 该连接未加密且未经过身份验证。这对于 hacking 来说非常棒，但也请牢记这一点。 - 完整的 opcode 表位于 [`src/alpha1s/protocol.py`](src/alpha1s/protocol.py)。 ## 你将获得 | | | |---|---| | `Alpha1s` | 高级客户端：遥测、servo、动作、声音、LED | | `poses` | 硬件校准的姿势和步态（`init`、`hands_up`、`walk`、`turn`）—— 附带文档化的 servo ID 映射表 | | `protocol` | 纯粹的组帧层（compose/verify/extract）—— 无需连接机器人即可进行单元测试 | | backends | `rfcomm` (PyBluez) 和 `ble` (bleak) 统一封装在一个 `Transport` 接口下 | | safety | `battery()` 会在电量 ≤20% 时自动关闭 servo 电源，确保在行走过程中绝不会发生电压骤降 | ## 架构 ``` Alpha1s (robot.py) — what you call └── protocol.py — framing: compose / verify / extract (pure, tested) └── Transport (backends) — rfcomm.py | ble.py, picked by backend="auto" ``` Servo 映射表 (ID 0–15)： ``` 0 Shoulder R Roll 1 Shoulder L Roll 2 Arm R Pitch 3 Arm L Pitch 4 Elbow R 5 Elbow L 6 Hip R Pitch 7 Hip L Pitch 8 Hip R Roll 9 Hip L Roll 10 Knee R 11 Knee L 12 Ankle R Pitch 13 Ankle L Pitch 14 Ankle R Roll 15 Ankle L Roll ``` ## 运行测试（无需机器人） ``` pip install -e . python -m unittest discover tests -v # or: PYTHONPATH=src python -m unittest discover tests ``` 组帧层和高级 API 均通过模拟的 transport 进行了测试，其中包含了从真实连接中抓取的已知正确数据帧。 ## 诚实的局限性 - 步态关键帧是在**我的**机器人上校准的；由于 servo 的磨损和装配公差，你的设备可能需要进行几度的微调（`poses.py` 中记录了该映射表）。 - 在某些固件版本上，`leds()`（opcode `0x08`）仍需与官方协议 PDF 进行比对验证。 - 通过 PyBluez 实现的经典 RFCOMM 仅支持 Linux；这是机器人原生的通信链路，也是最可靠的途径（使用 Raspberry Pi 是完美的选择）。 ## 相关项目 - [ubtech-alpha1s-distributed-ai](https://github.com/andresjjn/ubtech-alpha1s-distributed-ai) —— 完整的现代化改造方案：唤醒词 → Whisper STT → 本地 LLM 任务规划 → TTS + 同步动作手势，分布式部署在 Raspberry Pi 5 和边缘 GPU 上。 - [alpha1s-ros2-twin](https://github.com/andresjjn/alpha1s-ros2-twin) —— Alpha 1S 的 ROS 2 / Gazebo 数字孪生（URDF，17 个关节，18 个网格）。 ## 许可证 MIT © Andrés Felipe Jején Tabares

标签：Python SDK, 云资产清单, 机器人, 物联网, 硬件控制, 蓝牙通信, 逆向工具, 逆向工程