宁舟 AI实践

先搭好开发环境，再连接真实机器人。

从 Mac 工作端、树莓派硬件端到 SSH 远程连接，建立后续传感器与电机实验的稳定起点。

写于
本地整理
主题
Qmini · 树莓派 · SSH
阅读
7 分钟
草地上的白色 Qmini 双足机器人实物

这一步要解决什么

在真正连接电机、传感器和机器人控制程序之前，我们先要准备一个稳定的开发环境。

这一步的目标很简单:

  • 树莓派负责靠近硬件，插传感器、接串口、跑测试程序。
  • Mac 负责写文档、改代码、运行 Codex、整理资料。
  • Mac 通过 SSH 远程进入树莓派，不需要每次给树莓派接显示器、键盘和鼠标。
  • 配置 SSH 免密登录，让后续调试更顺滑。

对零基础读者来说，可以把这一步理解成: 先给机器人项目搭一个“工作台”。

树莓派系统怎么烧写

在开始烧写系统之前，先简单说一下树莓派是什么。

树莓派可以理解成一台很小的 Linux 电脑。它不像普通笔记本那样自带屏幕、键盘和电池，但它有处理器、内存、USB、网络接口和 GPIO 引脚，可以运行完整操作系统，也可以连接传感器、电机控制板和各种外设。

如果你是硬件初学者，可以把常见开发板按能力大致理解成几层:

  • 单片机: 最基础的小控制器，适合点灯、读按钮、控制简单传感器，资源少但实时性好。
  • ESP32: 带 Wi-Fi/蓝牙的微控制器，适合物联网、小车、无线传感器，仍然偏“控制器”。
  • 树莓派: 一台小电脑，能跑 Linux、Python、Web 服务、数据库和较复杂的软件，适合当机器人“大脑”或边缘计算节点。
  • 更强的计算平台: 例如带 GPU 的开发机、Jetson 或工控机，适合视觉、AI 推理、仿真和更重的控制任务。

Qmini 这种机器人既需要贴近硬件的控制能力，也需要运行比较复杂的软件。树莓派正好处在一个适合入门的位置: 它比单片机更像电脑，比笔记本更容易接近硬件。

树莓派需要先把操作系统写入 microSD 卡或其他启动盘。这个过程有点像给一台新电脑安装系统。

这里不展开每个按钮怎么点，因为官方教程更新更及时。建议优先看官方文档:

大体流程是:

  1. 在 Mac 上安装 Raspberry Pi Imager。
  2. 选择树莓派型号。
  3. 选择要安装的系统，比如 Raspberry Pi OS 或 Ubuntu for Raspberry Pi。
  4. 选择 microSD 卡或启动盘。
  5. 在高级设置里提前配置用户名、密码、Wi-Fi、主机名和 SSH。
  6. 写入系统，插回树莓派，通电启动。

我们当前项目使用的是树莓派上的 Ubuntu 系统，已经能通过局域网访问。

我们的开发环境长什么样

这次不是直接在树莓派上写所有东西，而是采用“Mac 工作端 + 树莓派硬件端”的方式。

流程概览
  1. SSH 远程连接<br/>像进入另一台电脑的命令行

这套结构的好处是:

  • Mac 屏幕大，适合写文章、看资料、和 Codex 协作。
  • 树莓派离硬件近，适合接 USB、串口、传感器和电机。
  • 出问题时，我们可以把树莓派上的命令输出、网页现象和传感器读数反馈给 Codex。
  • 所有项目文档都留在 Obsidian 里，方便复盘。

要达成这个美好的工作环境，我们离不开 SSH。

SSH 的全称是 Secure Shell，直译就是“安全外壳协议”。听起来有点抽象，但它的作用很直接: 让我们可以从 Mac 安全地进入树莓派的命令行。没有 SSH，我们就得给树莓派接显示器、键盘和鼠标；有了 SSH，树莓派可以安静地放在机器人旁边，Mac 仍然能远程控制它。

什么是 SSH 登录

SSH 可以理解成“安全的远程命令行”。

平时我们操作一台电脑，可能会接显示器和键盘。SSH 的作用是: 不接显示器、不接键盘，也能从另一台电脑进入它的终端。

比如我们在 Mac 终端里输入:

意思是:

  • ssh: 我要发起一个远程登录。
  • qmini: 我要用这个用户名登录。
  • raspberrypi.local: 我要连接这台树莓派的局域网地址。

登录成功后，你在 Mac 终端里输入的命令，其实是在树莓派上执行。

SSH 不只用于树莓派。很多人登录云服务器、远程维护 Linux 主机、部署网站、管理数据库和运行训练任务，也都是通过 SSH。它就像一条安全通道，把你的本地电脑和远方那台机器连接起来。

在我们的 Qmini 项目里，SSH 就是打通 Mac 工作端和机器人大脑的核心通道。后面我们启动 N100 Web Viewer、查看串口、安装 Python 依赖、检查日志，都是通过这条通道完成的。

为什么要配置 SSH 免密登录

一开始 SSH 登录需要输入密码。偶尔登录一次没问题，但机器人调试会频繁连接树莓派，反复输入密码很麻烦，也容易打断节奏。

SSH 免密登录的原理可以这样理解:

  • Mac 上有一把“私钥”，自己保存，不给别人。
  • 树莓派上保存对应的“公钥”。
  • 连接时，树莓派检查: 你是不是拿着正确私钥的人。
  • 如果验证通过，就不用再输入密码。

对人来说，免密登录的好处是省事。对 Codex 这样的 Agent 来说，好处更大: 它可以直接执行远程检查、同步文件、启动服务和读取日志，不需要模拟输入密码，也不需要停下来等待你手动输入。这样整个调试过程会流畅很多。

简单说，配置 SSH 免密登录之后，Codex 操作树莓派的难度会明显降低。它可以更像一个真正的远程工程助手，而不是每一步都卡在“请输入密码”的门口。

Raspberry Pi 官方远程访问文档也建议使用 SSH key 来实现免密码连接: https://www.raspberrypi.com/documentation/remote-access/

常见配置流程:

# 在 Mac 上检查是否已有 SSH 公钥
ls ~/.ssh

# 如果没有，可以生成一个
ssh-keygen -t ed25519

# 把公钥复制到树莓派
ssh-copy-id [email protected]

# 测试免密登录
ssh -o BatchMode=yes [email protected] 'echo SSH_KEY_OK'

如果最后输出 SSH_KEY_OK，说明免密登录可用。

我们实际确认过什么

当前树莓派信息:

  • 地址: raspberrypi.local
  • 用户名: qmini
  • 系统: Ubuntu 25.04 aarch64
  • Python: 3.13.3
  • Git: 2.48.1
  • CMake: 3.31.6
  • GCC/G++: 14.2.0

我们还确认过:

  • Mac 可以通过 SSH 登录树莓派。
  • SSH key 免密登录可用。
  • 树莓派能识别 USB 串口设备。
  • 后续 N100 IMU 会通过 /dev/ttyUSB0 这类设备路径访问。

这些检查看起来琐碎，但它们很重要。机器人项目里，很多“代码问题”其实是环境没准备好。

我们如何通过 Codex 完成这一步

这一步并不是一次性完成的，而是通过一轮一轮对话收敛出来的。

我们的沟通方式大致是:

  1. 先告诉 Codex 项目目标 “我要复刻 Qmini，并且所有文档要用 Obsidian 管理。”

  2. 提供树莓派连接信息 告诉 Codex 用户名、IP 地址，以及自己已经能用 ssh [email protected] 登录。

  3. 让 Codex 解释下一步 例如为什么要配置 SSH key、dialout 是什么、为什么串口设备需要权限。

  4. 遇到错误就原样贴出来 比如 Host key verification failed. 这种错误，不要只说“连不上”，而是把终端输出发给 Codex。

  5. 让 Codex 把过程写进项目日志 这样后续忘记命令时，可以回到 Qmini 项目日志 查。

  6. 把环境和硬件职责分清楚 Mac 是工作端，树莓派是硬件端。这个边界清楚后，后续开发 N100 Web Viewer 就顺利很多。

可以复制给自己 Agent 的提示词:

我正在复刻 Qmini 机器人。请先帮我搭建开发环境，而不是直接写机器人控制程序。
我的工作端是 Mac，硬件端是树莓派。
目标:
1. 说明树莓派系统烧写应参考哪些官方教程。
2. 帮我通过 SSH 从 Mac 连接树莓派。
3. 配置 SSH key 免密登录。
4. 检查树莓派 Python、Git、CMake、GCC 等基础工具版本。
5. 把每一步结果写入 Obsidian 项目日志。
如果我提供终端报错，请先解释报错含义，再给出下一步命令。

这一阶段的结果

完成这一步后，我们拥有了一个清晰的工作方式:

  • Mac 上写文档、看资料、和 Codex 协作。
  • 树莓派上跑命令、接硬件、启动调试服务。
  • 两者通过 SSH 连接。
  • 关键配置写入项目日志。

这就是后续复刻 Qmini 的基础工作台。

下一步

下一篇我们会进入第一个真正的小工具: 给 Qmini 复刻做一个可视化姿态调试器。

在那一步里，我们会把 N100 IMU 接到树莓派，通过 Python 读取数据，再用浏览器显示 3D 姿态。