企业官网建设流程全解析

Microduck 是一个搭载强化学习（RL）行走策略的小型双足机器人项目。本文带你从零手工配置其 Raspberry Pi Zero 2 W 控制板：启用 I2C 读取 IMU 姿态、关闭串口登录控制台、彻底修复导致 14 个 XL330 舵机掉线的 UART 冲突，并搭建 Wi-Fi 免休眠、Python 依赖与输入权限的完整运行环境。只需约 30 分钟，即可得到一台可稳定行走的机器人主板。

为什么必须手工配置树莓派？

Microduck 的部署代码运行在 Raspberry Pi Zero 2 W 上，依赖三条硬件总线：

其中最容易踩的坑是：串口控制台（serial login console）若开着，内核和 getty 会持续向/dev/ttyAMA0写字节，直接污染舵机总线，表现为舵机校验和报错、无响应。而官方镜像由 cloud-init 驱动，仅用raspi-config关一次控制台还不够——它会静默回滚。下面按仓库 setup_rasp.md 的流程逐步操作。

第 1 步：用 Raspberry Pi Imager 写入系统

使用 Raspberry Pi Imager 完成 SD 卡初始化，关键选项：

1. 设备：Raspberry Pi Zero 2 W
2. 系统：Raspberry Pi OS Lite（64-bit）
3. 主机名：microduck
4. 时区、用户名/密码：按需设置
5. Wi-Fi：填写本地 2.4 GHz 网络的 SSID 和密码（Zero 2 W 只支持 2.4 GHz）
6. 开启 SSH 密码认证

首次启动会自动扩展分区并安装更新，请耐心等待 1–3 分钟，切勿断电。

第 2 步：建立 SSH 连接

同一 Wi-Fi 下，先在电脑上找到机器人 IP：

ping microduck.local

然后在~/.ssh/config中配置别名：

Host microduck HostName 192.168.XXX.XXX User <用户名>

复制免密密钥后，一条ssh microduck即可登录：

ssh-keygen -t ed25519 ssh-copy-id microduck

第 3 步：导入 config.txt，启用 I2C 等接口

仓库预置了完整硬件配置，直接拷入即可（见 config.txt）：

scp docs/dev/config.txt microduck:config.txt # 在 Pi 上执行 sudo mv config.txt /boot/firmware/config.txt sudo reboot

该文件的关键项及作用：

注意：这里开启的是UART 硬件，控制台是否关闭由下一步处理，二者必须分开对待。

第 4 步：raspi-config 启用 I2C、关闭串口控制台

重启后执行：

sudo raspi-config

按以下路径操作：

• Interface Options → I2C → 启用（Enable）
• Interface Options → Serial Port：
  • 串口登录控制台（login shell）：关闭（No）
  • 串口硬件（hardware）：保持启用（Yes）

第 5 步：修复舵机 UART 冲突（关键一步）

⚠️ 到此为止还不够。镜像由 cloud-init 驱动，其user-data中的rpi.interfaces.serial若为true，每次 cloud-init 作为新实例运行（包括换 Wi-Fi 触发的cloud-init clean）都会重新打开串口控制台，悄悄撤销你的 raspi-config 设置，舵机随即再次失联。

治本方法是编辑/boot/firmware/user-data，改为细粒度写法——关控制台、留硬件：

rpi: interfaces: serial: console: false hardware: true

验证并干净地应用：

sudo cloud-init schema -c /boot/firmware/user-data # 应提示 "Valid schema" sudo cloud-init clean && sudo reboot

若你的 cloud-init 版本拒绝细粒度写法，回退方案：直接删除rpi.interfaces.serial整行（cloud-init 便不再碰串口），UART 靠config.txt的enable_uart=1保持开启，控制台用 raspi-config 手动关一次即可。

验证 I2C 与 UART 是否配置成功

三项检查全部通过才算完成：

1. 控制台已关：cat /proc/cmdline中不再包含console=ttyAMA0
2. I2C 在线：用i2cdetect -y 1能看到 BNO08x 设备地址；代码在 imu_reader.py 中自动探测常见地址，总线号与安装姿态四元数定义于 constants.py
3. 舵机可达：用 Dynamixel Wizard 以 1 Mbps 扫描，应能看到全部 19 个舵机 ID

此后该配置可抵御任何 cloud-init 重跑，舵机始终保持可达。

第 6 步：环境收尾——Wi-Fi 省电、自动更新、依赖与权限

Wi-Fi 免休眠（防止 Pi 空闲时 SSH 卡死）：

sudo nmcli con mod <按Tab补全你的WiFi连接名> wifi.powersave disable

关闭系统自动更新（机器人上自动升级依赖很危险）：

sudo touch /etc/apt/apt.conf.d/99disable-auto-upgrades

写入APT::Periodic::*全 0 的配置后重启。

安装 Python 包管理器 uv（部署依赖由uv sync --frozen管理）：

curl -LsSf https://astral.sh/uv/install.sh | sh

输入设备权限（免 root 读取手柄/dev/input/js*）：

sudo usermod -aG input $USER

常见问题速查

写在最后

配置完成后，建议先运行make direction-check核对每个舵机方向，再扶住机器人执行首次行走。完整命令表与手柄无头模式见 usage.md。掌握"硬件开、控制台关、cloud-init 不插手"这三条原则，你的 Microduck 主板就稳了 🦆