XGO-lite3(XGO 系列教育版机器狗) 复刻全流程
XGO-lite3(XGO 系列教育版机器狗) 从采购、打印、组装到装软件、标定和训练的 57 个步骤,附物料表、购买链接与官方出处。
原价 599.00 美元,页面显示促销价 479.20 美元(LuwuDynamics 官方商店 shop.xgorobot.com,2026‑10‑31,预售、10 天内发货;未写是否含税与运费);淘宝、京东人民币价未读取
采购
- 准备 Raspberry Pi CM4 或 CM5
准备 Raspberry Pi CM4 或 CM5,以及兼容的载板。
- 连接 SPI0 的 ST7789V LCD
准备通过 SPI0 连接的 ST7789V SPI LCD。
- 准备 Debian Linux 系统
准备基于 Debian 的 Linux 操作系统。
- 获取 XGO-lite3 机器人
从 xgorobot.com 的 XGO-lite3 页面获取该多模态机器人平台。该平台面向科技极客、STEAM教育、高校科研等不同需求。
组装
- 连接下位机与 RP1 UART
将机器人下位机的 TX/RX 飞线连接到 RP1 空闲 UART 的对应引脚。
- 连接四线 PWM 风扇
将四线 PWM 风扇的 VCC、GND、PWM 和 TACH 接到对应接口,利用 TACH 获取真实转速。
软件与固件
- 启用 UART overlay
在 `config.txt` 中启用与所连接 UART 对应的 overlay。
- 恢复蓝牙串口配置
将 `bluetoothd` 的配置改回 `ttyAMA0`。
- 串口路径改为参数传入
修改 `xgolib_dog.py` 第188行,保留已有 `port` 参数,不再写死串口路径,改用传入的参数。
- 扫描候选串口
遍历 `/dev/ttyAMA*` 和 `/dev/ttyS*` 候选串口,并向每个候选串口发送固件版本查询命令。
- 识别串口并设置回退
收到以 `M`、`L`、`W` 或 `R` 开头的合法版本号回复时即命中;未命中时退回 `/dev/ttyAMA0`,其余通过 D-Bus 调用蓝牙的 App 不受影响。
- 配置 ALSA 混音与录音
在 `/etc/asound.conf` 中配置 `dmixer` 和 `dsnooper`,让 default 的 playback 经 `plug`、`dmix` 到 `hw:0,0`,capture 经 `plug`、`dsnoop` 到 `hw:0,0`。
- 启用风扇温控驱动
在 config.txt 中启用 dtparam=fan_temp,使 pwm-fan 内核驱动控制风扇,并在 /sys/class/hwmon/hwmon2/ 暴露 pwm1 与 fan1_input。
- 联合监测电压与电量
让 l uwu-undervolt-monitor.py 通过 vcgencmd 读取 CM5 电压,并通过 xgolib.read_battery() 读取狗电池百分比,再进行联合判断和分级响应。
- 部署电池数据服务
使用 ttyAMA0 串口和 xgolib pip 包,将 l uwu-undervolt-monitor.py 部署为 systemd 服务。
- 启用日志式文件系统
在 /boot/firmware/cmdline.txt 中添加 rootflags=data=journal;install.sh 第 7 步会自动部署此项。
- 自动识别硬件配置
每次开机识别当前硬件,并切换到与 CM4 新旧批次或 CM5 对应的正确 `config.txt`。
- 隔离 CM5 配置
在 `is_cm4()` 判断处让 CM5 直接退出;固件中的 `[cm5]` 段会天然隔离,无需额外处理。
- 探测机器狗串口
向候选串口发送 xgolib 固件版本查询帧 `PROBE_FRAME`。收到任意回复或遇到 `PermissionError` 时,判定该串口存在机器狗。
- 防止配置切换循环
每次切换配置后写入 `/tmp/luwu_hw_autoconf_switched`;下次启动若探测仍失败且该标记存在,则保持当前配置。标记位于 tmpfs,断电后自动清除。
- 停止维护 xgoscreen
不再维护或迁移 xgoscreen。显示改由 fbtft 内核驱动统一管理,App 通过 PySide6 或 LinuxFB 渲染。
- 用 QLabel 显示图像
用 `QLabel.setPixmap()` 替代原来的 `LCD_2inch.ShowImage()`。
- 建立独立的 luwuos 教育包
保留老镜像的 `xgoedu` 包,不使其受到影响。新镜像使用 pip 包 `xgoedu-luwuos`,导入名仍为 `from xgoedu import XGOEDU`。
- 替换绘图底层
在 `xgoedu-luwuos` 包中,用 PySide6 的 QPainter 和 QPixmap 替代 PIL ImageDraw 与 spidev。保持原有 API 签名完全兼容。
- 加入手势识别
在新版 `edulib.py` 中使用 MediaPipe Hands 实现手势识别。
- 加入人脸检测
在新版 `edulib.py` 中使用 MediaPipe Face Detection 实现人脸检测。
- 加入骨骼姿态识别
在新版 `edulib.py` 中使用 MediaPipe Pose 实现骨骼姿态识别。
- 加入 YOLO 目标检测
在新版 `edulib.py` 中使用 onnxruntime 实现 YOLO 目标检测。
- 加入 OpenCV 识别功能
在新版 `edulib.py` 中使用 OpenCV 实现颜色、色块、巡线和球体识别。
- 加入二维码和 AprilTag 识别
在新版 `edulib.py` 中实现二维码和 AprilTag 识别。
- 提供辅助函数
在新版 `edulib.py` 中提供 `hand_pos`、`color`、`getFaceBox` 等辅助函数。
- 移交废弃功能
将表中列出的废弃功能交给 App 或系统层处理,不再作为该新包的底层功能。
- 迁移绘图 API
将旧的 PIL 与 spidev 绘图模型迁移到 Qt 绘图模型。表中的 `lcd_*` 绘图 API 可无损迁移。
- 绘图后刷新显示
每次绘图后调用 `label.setPixmap(pixmap)` 刷新显示。其行为与旧代码中的 `ShowImage()` 完全一致。
- 保持用户 API 兼容
保持用户图形化程序的方法签名不变。底层从旧绘图方式透明切换到 Qt 渲染。
- 参数化狗机器人串口
保留 `xgolib_dog.py`,将构造函数的串口路径改为 `port` 参数,默认值为 `/dev/ttyAMA0`。
- 保留老镜像教育包
老镜像继续使用 `xgoedu`,该包保持不变,不受 `xgoedu-luwuos` 新包影响。
- 按镜像安装教育包
老镜像安装 `xgoedu`,新镜像安装 `xgoedu-luwuos`。两种镜像均使用相同的 `from xgoedu import XGOEDU` 写法。
- 使用 Luwu-Imager 刷写系统镜像
下载适用于 Windows 或 macOS 的 Luwu-Imager,并使用预构建的系统镜像进行刷写。
- 从源代码安装系统
克隆 luwu_os 仓库,进入 /opt/luwu-os,并运行 configs/install.sh。该脚本处理内核覆盖层、udev 规则、ALSA 多应用音频共享、systemd 服务和 Python 依赖安装。
- 确认关键 Python 包
安装完成后,关键 Python 包包括 xgolib、xgoedu-luwuos 和 xgo-blockly-luwuos。
- 启用并启动 luwu-launcher 系统服务
通过 systemd 启用 luwu-launcher 服务,使其在开机时自动启动。
- 构建 PySide6 帧缓冲应用
使用 PySide6 构建应用,并让应用直接渲染到 Linux framebuffer。示例 BallTracker 使用 Picamera2 启动摄像头,并以 33 毫秒间隔触发帧处理。
- 通过 FIFO 路由按键事件
通过 `/tmp/luwu_keys.fifo` 将按键事件从 C++ launcher 路由到 Python 应用。
- 加载 ONNX AI 模型
将 ONNX 模型放在 `model/` 中,并通过 `onnxruntime` 加载。模型包括 YuNet 人脸检测、MediaPipe 手部姿态和人物检测、MediaPipe 姿态估计、自定义情绪识别以及 YOLO COCO 物体检测。
标定与测试
- 初始化混音器状态
由 `apps/settings/main.py` 的 `write_volume()` 初始化混音器,关闭4条 Output Mixer 回授通路,并将 Capture 设为45/63(71%)、Playback 设为255/255(100%,0dB)。
- 设置各音量控制值
代码以 `amixer scontrols` 输出的 `Playback`、`Speaker`、`Headphone` 为准;Playback 将用户0–100%重映射为 `raw = 196 + vol × 59 // 100`,Speaker和Headphone固定127,Speaker DC与Speaker AC固定5。
- 核对风扇温控曲线
核对 config.txt 温控曲线:36°C 起以 80% 转速运转,并在 40°C、52°C、58°C 逐级提速。
- 验证电池共享状态
确认服务将电量写入 /tmp/luwu_battery_level,并允许 Qt 状态栏和任何 App 只读该文件。
- 验证分级欠压响应
当电池电量高于 10% 时,将欠压视为瞬时功耗峰值并让 CM5 硬件自动降频保护,不进行软件干预。
- 验证耗尽保护关机
仅在电池确实耗尽时执行保护关机。
- 验证电池保护关机
确认电池耗尽时系统会自动保护关机,且文件系统不会损坏。
用起来
- 用积木编写并执行程序
拖拽积木模块,组合机器人动作与逻辑,然后点击下发。程序下发后在现场执行。
- 运行三个预设动作
在遥控APP中调用“摇摆”“蹲起”“跳舞”等内置预设动作,并用一键命令执行。
- 运行另外三个预设动作
在遥控APP中调用“张望”“撒尿”“俯卧撑”等内置预设动作,并用一键命令执行。
- 使用 XGO-Blockly 编程
在XGO-Blockly左侧拖拽模块编写程序,右侧查看实时Python代码与执行日志。该工具支持图形化积木编程和AI自动代码生成。
- 让 App 播放和录音
App 使用 `aplay`、`arecord` 或 Python `subprocess` 直接播放和录音,从而支持混音。
物料
- 树莓派 CM5 Lite 2 GB(CM5102000)+ 32 GB microSD 预装系统,ESP32 运动控制器,二者经 UART 通信
- 12 个腿部舵机:6V 2.3 kg·cm 塑料壳金属齿 300° 双轴 TTL 串口舵机,电位器反馈;3 自由度机械臂与夹爪
- 500 万像素摄像头、MEMS 麦克风、扬声器、2.0 英寸 320×240 IPS 屏、4 个按键、IMU
- 18650 2S 2500 mAh 电池,5V Type‑C 充电约 1.5–2 小时,续航约 2 小时
- 1 mm 铝合金结构件、ABS 腿与足端;默认站姿 250×145×170 mm、610 g
- 标准套件:防护箱、Type‑C 扩展坞、HDMI 线与视觉识别色块教具
工具
- 出厂整机,无需组装
- 重刷系统用 Luwu Imager 与 microSD 读卡器;下位机固件只能在 tools.xgorobot.com 在线烧录(Chrome/Edge)
技能
- XGO-Blockly 积木与 AI 生成代码,手扳示教录动作
- Python:xgolib 运动控制、xgoedu 视觉语音接口、MQTT 通信
- 进阶:ROS 2(参考环境 Ubuntu 26.04 + ROS 2 Lyrical)与 MuJoCo 强化学习(需 NVIDIA GPU)
软件
- Luwu-OS 2.1.3(2026‑08‑29):Qt 启动器 + PySide6 应用,含 AI 对话、手势/人脸/小球追踪、遥控图传、雷达扫描、群控表演与 Blockly
- PyPI:xgolib 1.1.10、xgoedu-luwuos 2.2.1、xgo-blockly-luwuos 1.0.6.10
- luwu-ros(CM5 ROS 2 镜像)、luwu_mjlab(MuJoCo 训练与 ONNX 导出)、URDF/MJCF 模型
- XGO App(iOS / Android,BLE 遥控)