1. 项目概述：Reachy Mini无线版初印象

如果你对桌面级协作机器人感兴趣，最近应该听说过Reachy Mini。它是一款基于Raspberry Pi（树莓派）驱动的开源机器人手臂，设计初衷就是让机器人开发变得触手可及。而我今天要聊的，是它的“无线版”——一个通过Wi-Fi连接，摆脱了物理线缆束缚的版本。这不仅仅是拔掉一根USB线那么简单，它意味着你可以把机器人放在房间的任何角落，通过你的笔记本电脑远程编程、调试和控制，整个工作流程的灵活性和整洁度都上了一个台阶。对于机器人爱好者、教育工作者，或者想快速验证机器人算法原型的开发者来说，这无疑是一个极具吸引力的特性。

不过，从“开箱”到“无线畅玩”，中间还有一段必经之路：初始设置。这个过程涉及到操作系统配置、网络连接、远程访问等一系列步骤，对于刚接触树莓派或Linux的朋友来说，可能会觉得有点门槛。别担心，这篇指南就是为你准备的。我会结合我自己的实操经验，把Reachy Mini无线版的完整设置流程拆解清楚，从给SD卡刷写系统开始，一直到通过SSH远程登录并运行你的第一个程序。过程中你会遇到哪些“坑”，有哪些技巧能让设置更顺畅，我都会一一说明。无论你是完全的硬件新手，还是有一定经验的开发者，都能跟着这篇指南，让你的Reachy Mini成功“站起来”并连上网。

2. 核心需求与方案选型解析

2.1 为什么需要无线化？

在深入配置细节之前，我们先聊聊“无线”到底带来了什么。传统的机器人开发，尤其是基于树莓派的项目，常常需要拖着一根网线或者USB线。这根线不仅是电源和数据通道，很多时候也成了调试时的“绊脚石”。你想调整一下机器人的位置？先断电、拔线、移动、再插线、上电，一套流程下来，灵感可能都跑光了。

Reachy Mini无线版的核心需求，就是实现远程、无拘束的交互。具体来说，它需要满足几个关键点：

1. 远程访问：开发者可以在自己的主力电脑（Windows, macOS, Linux均可）上，通过SSH或VSCode Remote等工具，直接访问机器人内部的树莓派系统，进行文件编辑、命令执行和程序调试。
2. 网络通信：机器人上运行的程序（如用Python编写的控制脚本）需要能够与远程电脑上的程序（如可视化界面、高级规划算法）进行稳定的数据交换，通常通过ROS（机器人操作系统）或自定义的Socket/UDP协议实现。
3. 电源独立：无线意味着供电也需要独立。Reachy Mini通常由配套的电源适配器供电，确保在移动中也能持续工作。

基于这些需求，技术方案就非常明确了：基于Wi-Fi的无线局域网（WLAN）连接。树莓派内置的Wi-Fi模块足以胜任这项任务。整个设置流程的核心，就是让树莓派正确接入你的本地Wi-Fi网络，并配置好安全的远程访问通道。

2.2 工具链选型背后的逻辑

工欲善其事，必先利其器。设置Reachy Mini无线版，你需要准备几个基础工具，每一个的选择都有其道理：

• SD卡与读卡器：这是树莓派的“硬盘”。建议选择Class 10或以上、A1/A2规格的16GB或32GB microSD卡。A1/A2规格针对应用程序随机读写做了优化，能显著提升树莓派系统的运行流畅度，尤其是在频繁安装软件包时。一个可靠的USB读卡器是必备的。
• 系统烧录工具：我们需要将Reachy定制的操作系统镜像写入SD卡。这里我强烈推荐Raspberry Pi Imager。它是树莓派官方推出的工具，跨平台（Windows、macOS、Linux），界面简洁，最关键的是它集成了一个“高级选项”功能，可以在烧录前就预先配置Wi-Fi、SSH、主机名等，极大简化了初次设置流程。相比于其他第三方烧录工具，它更“懂”树莓派。
• SSH客户端：用于远程登录树莓派命令行。在macOS和Linux上，系统终端自带ssh命令，开箱即用。在Windows上，自从Windows 10 1809版本和Windows 11内置了OpenSSH客户端，你也可以直接在PowerShell或CMD里使用ssh命令，这是最原生、最推荐的方式。当然，你也可以使用老牌的PuTTY，但原生SSH在易用性和脚本化方面更有优势。
• 文本编辑器/IDE：用于编辑树莓派上的代码或配置文件。虽然可以通过SSH在命令行里用nano或vim直接编辑，但对于复杂项目，使用Visual Studio Code配合Remote - SSH扩展是体验上的巨大飞跃。它允许你像编辑本地文件一样编辑远程文件，并直接使用远程环境运行和调试代码。这是目前进行远程开发的事实标准。

注意：在选择Wi-Fi网络时，请确保你的路由器支持2.4GHz频段。虽然树莓派4B及更新型号也支持5GHz，但2.4GHz的穿墙能力和兼容性通常更好，对于机器人这种可能移动的设备更可靠。尽量避免使用需要网页认证的公共Wi-Fi或企业级Wi-Fi（如802.1X），家庭或实验室的普通WPA2/WPA3个人网络是最佳选择。

3. 系统烧录与预配置详解

这是整个设置过程中最关键的一步，事前功夫做得好，后面能省去很多麻烦。我们将使用Raspberry Pi Imager的“高级选项”功能，实现“开箱即用”的无线配置。

3.1 获取与安装系统镜像

首先，你需要获取Reachy Mini专用的操作系统镜像。通常，你可以在Reachy的官方文档或GitHub仓库找到最新的镜像下载链接。它可能是一个.img.xz或.img.gz的压缩文件，这是一个已经预装了所有必要驱动、ROS环境和Reachy SDK的定制化Raspberry Pi OS。

1. 下载镜像：前往官方指定位置下载镜像文件。请务必核对镜像版本是否与你的Reachy Mini硬件版本匹配。
2. 安装Raspberry Pi Imager：从树莓派官网下载并安装对应你电脑操作系统的Imager工具。
3. 启动Imager并选择镜像：打开Imager，点击“Choose OS”。滚动到最底部，选择“Use custom”。在弹出的文件选择对话框中，找到并选中你刚刚下载的Reachy系统镜像文件（.img.xz文件可直接选择，Imager会自动解压）。

3.2 高级配置：一次性搞定网络与SSH

选中自定义镜像后，插入你的microSD卡，Imager会自动识别。在点击“Write”之前，请先按下键盘上的Ctrl+Shift+X（Windows/Linux）或Cmd+Shift+X（macOS）。这将打开“高级选项”菜单，这里是实现无头（无显示器）启动的核心。

你需要配置以下几项：

• Set hostname：设置主机名。例如，你可以设为reachy-mini。这会让你的机器人在网络上有一个独特的名字，方便以后通过reachy-mini.local这样的域名访问，比记IP地址方便得多。
• Enable SSH：这是必须开启的选项。选择“Use password authentication”，并设置一个你牢记的密码。这个密码将用于后续SSH登录。虽然也可以使用公钥认证（更安全），但初次设置用密码更简单。
• Configure Wi-Fi：
  • 输入你的Wi-Fi网络SSID（就是Wi-Fi名称）。
  • 输入Wi-Fi密码。
  • Wireless LAN country：务必选择正确的国家代码，例如中国是CN。这个设置关系到Wi-Fi信道的合规使用，选错可能导致无法连接。
• Set locale settings：设置时区。选择Asia/Shanghai或其他你所在的时区。正确的时区对于日志时间戳和定时任务很重要。
• （可选）Enable telemetry：树莓派的用户体验数据收集，可以选择禁用。

配置完成后，点击“Save”，然后返回主界面点击“Write”。Imager会提示你擦除SD卡，确认后便开始烧录。这个过程需要几分钟，请耐心等待直到提示“Write Successful”。

实操心得：在点击“Write”前，再次核对一遍Wi-Fi的SSID和密码，这是新手最容易出错的地方，一个字符错误就会导致机器人无法联网。另外，建议在烧录完成后，使用操作系统自带的工具（如Windows的“弹出”或macOS的“推出”）安全移除SD卡，而不是直接拔掉，以防数据损坏。

4. 首次启动与网络连接验证

烧录好的SD卡现在就是Reachy Mini的大脑了。将其插入树莓派的卡槽，连接好机器人的各关节（按照硬件手册操作），最后接通电源。

4.1 启动过程与指示灯解读

上电后，树莓派会开始启动。观察树莓派板载的LED指示灯：

• 红色LED（PWR）：常亮，表示供电正常。
• 绿色LED（ACT）：会不规则地闪烁，表示系统正在从SD卡读取数据。启动完成后，闪烁频率会变低或呈现规律性闪烁。

首次启动时间会稍长，因为系统可能会进行扩展文件系统等初始化操作。请等待至少2-3分钟。

4.2 确认IP地址与网络连通性

现在，你需要知道你的Reachy Mini在局域网里获得了什么IP地址。有几种方法：

1. 路由器管理界面查询：这是最可靠的方法。登录你家路由器的管理后台（通常地址是192.168.1.1或192.168.0.1），在“已连接设备”或“DHCP客户端列表”中，查找你刚才设置的主机名（如reachy-mini）或设备名为“raspberrypi”的设备，后面就会显示其分配到的IP地址，例如192.168.1.105。
2. 使用mDNS域名访问：如果你在Imager中设置了主机名，并且你的电脑支持mDNS（macOS和大多数Linux发行版默认支持，Windows 10/11需要安装“Bonjour Print Services”或使用支持mDNS的工具），你可以直接尝试用主机名加.local后缀来访问。在终端里ping一下试试：

   ping reachy-mini.local

   如果能看到来自类似192.168.1.105的回复，说明网络连通且mDNS解析成功。这是最方便的访问方式。
3. 网络扫描工具：可以使用如nmap（命令行）或“Fing”（手机App）等工具，扫描局域网内的所有设备，从中找出树莓派。

记下你找到的IP地址或确认域名可用，这是下一步远程登录的通行证。

常见问题：如果找不到设备，首先检查电源和SD卡是否接触良好，绿色ACT灯是否闪烁。然后确认Wi-Fi配置无误，并且机器人处于路由器信号覆盖良好的位置。可以尝试将机器人和路由器靠近一些。如果还是不行，可能需要一个微型HDMI线连接显示器，或者通过串口查看启动日志来排查问题，但这属于进阶故障排除了。

5. SSH远程登录与基础环境配置

成功获取IP地址后，我们就可以从你的电脑远程操控Reachy Mini了。

5.1 首次SSH登录

打开你电脑上的终端（Windows PowerShell / CMD， macOS Terminal， Linux Terminal）。

使用以下命令登录，将<ip_address>替换为你实际获取的IP地址，或者使用reachy-mini.local这样的域名：

ssh pi@<ip_address>

例如：

ssh pi@192.168.1.105

或者

ssh pi@reachy-mini.local

系统会提示你“The authenticity of host ... can't be established. Are you sure you want to continue connecting?”，这是正常的，因为这是你第一次连接这台机器。输入yes并回车。

接着，会提示你输入密码。输入你在Raspberry Pi Imager高级选项中设置的那个密码。输入时屏幕不会有任何显示（这是Unix系统的安全特性），正常输入后回车即可。

如果一切顺利，你会看到命令行提示符从你本地电脑的样式，变成了类似pi@reachy-mini:~ $的样子。恭喜，你已经成功进入了Reachy Mini的内部系统！

5.2 初始系统检查与更新

登录后，第一件事是检查系统状态并进行必要的更新，确保环境是最新的。

1. 检查磁盘空间和内存：

   df -h # 查看磁盘使用情况 free -h # 查看内存使用情况

   确保根目录有足够的空间（通常几个GB的空余是健康的）。

2. 更新软件包列表：这不会升级任何软件，只是从服务器获取最新的软件包信息。

   sudo apt update

3. 升级已安装的软件包：这一步会下载并安装所有可用的更新，可能需要一些时间，取决于网络速度和更新大小。强烈建议在首次设置时执行。

   sudo apt full-upgrade -y

   -y参数表示自动回答“yes”，避免中途需要确认。

4. （可选）检查Reachy相关服务：根据Reachy文档，可能有一些预装的服务或ROS节点。你可以检查它们是否在运行：

   systemctl list-units --type=service | grep reachy # 或者查看ROS相关进程（如果预装了ROS） # ps aux | grep ros

注意事项：sudo apt full-upgrade是一个比较全面的升级命令，它会处理依赖关系的变化，甚至可能移除某些不再需要的旧包。在稳定的生产环境中需谨慎，但对于开发环境，保持更新通常能获得更好的兼容性和安全性。升级过程中如果遇到询问配置文件是否保留的提示，通常选择“保持当前本地版本”即可。

6. 进阶配置与开发环境搭建

基础访问搞定后，我们可以配置一些更便捷的工具和环境，让后续的开发工作更加高效。

6.1 配置SSH密钥认证（免密登录）

每次登录都要输密码很麻烦，也不够安全。配置SSH密钥对，可以实现免密且更安全的登录。

1. 在本地电脑生成密钥对（如果还没有的话）： 在你的本地电脑终端（不是在树莓派上）运行：

   ssh-keygen -t ed25519 -C "your_email@example.com"

   按回车接受默认的密钥保存路径（通常是~/.ssh/id_ed25519）。你可以设置一个密钥密码（passphrase）来增加一层保护，也可以直接回车留空（方便但安全性稍低）。

2. 将公钥上传到Reachy Mini： 继续在本地终端，使用以下命令将公钥复制到树莓派上。确保你已经用密码登录过一次（如上一步所做）：

   ssh-copy-id pi@reachy-mini.local

   输入一次pi用户的密码。成功后，会提示“Number of key(s) added: 1”。

3. 验证免密登录： 现在，再次尝试SSH登录：

   ssh pi@reachy-mini.local

   如果配置正确，你将无需输入密码直接登录。如果设置了passphrase，则只需要输入passphrase（这是本地解锁密钥的密码，不是树莓派的登录密码）。

6.2 使用VSCode进行远程开发

命令行SSH适合执行命令，但写代码还是需要一个强大的编辑器。VSCode的Remote-SSH扩展完美解决了这个问题。

1. 在本地VSCode中安装扩展：打开VSCode，进入扩展市场，搜索并安装“Remote - SSH”扩展。
2. 连接远程主机：安装后，VSCode左侧活动栏会出现一个远程资源管理器图标。点击它，在SSH TARGETS旁边点击“+”号，输入ssh pi@reachy-mini.local，回车。然后选择一个配置文件保存（通常选第一个）。
3. 连接到主机：在SSH TARGETS列表里，你会看到刚添加的reachy-mini.local，鼠标悬停，点击右侧出现的“Connect to Host in New Window”连接图标。
4. 选择平台：第一次连接时，VSCode会在新窗口中打开，并提示你选择远程主机的平台，选择“Linux”。
5. 等待环境安装：VSCode会自动在远程主机（即你的Reachy Mini）上安装一个轻量级的服务器组件。完成后，你就进入了完全的远程开发模式。左下角会显示“SSH: reachy-mini.local”。
6. 开始开发：现在，你可以像操作本地文件夹一样打开远程树莓派上的项目目录（例如/home/pi/reachy_ws，如果Reachy SDK安装在此）。你可以使用终端（集成终端会自动连接到SSH会话）、运行和调试代码，所有操作都在树莓派上执行。

实操心得：使用VSCode Remote后，你本地电脑的性能不再限制开发体验，因为代码运行和编译都在树莓派上完成。这对于资源有限的嵌入式设备开发来说非常理想。记得在远程环境中安装你需要的VSCode扩展（如Python扩展），这些扩展会安装在远程侧。

6.3 配置静态IP地址（可选但推荐）

DHCP动态分配的IP地址可能会变，虽然用主机名（.local）可以解决，但有些网络环境或应用对固定IP有要求。为树莓派设置静态IP是个好习惯。

重要：设置静态IP需要在路由器上操作，或者修改树莓派的DHCP配置使其“保留”某个IP。更规范的方法是在路由器管理后台，根据树莓派的MAC地址，为其分配一个固定的DHCP保留地址。这样既保证了IP不变，又由路由器统一管理，避免冲突。

如果你确实需要在树莓派上配置静态IP，可以编辑网络配置文件。但请注意，Reachy的定制镜像网络配置方式可能与原生Raspberry Pi OS不同。最安全的方法是使用raspi-config工具（如果预装了）：

sudo raspi-config

然后导航至System Options->Wireless LAN，在其中可以设置静态IP。或者，手动编辑/etc/dhcpcd.conf文件（操作前建议备份）：

sudo nano /etc/dhcpcd.conf

在文件末尾添加（根据你的网络修改）：

interface wlan0 static ip_address=192.168.1.150/24 static routers=192.168.1.1 static domain_name_servers=192.168.1.1 8.8.8.8

保存退出（Ctrl+X， 然后 Y， 回车），并重启网络或树莓派：

sudo systemctl restart dhcpcd

警告：错误配置静态IP可能导致失去网络连接。如果发生这种情况，你需要通过有线网络或直接连接显示器来修复。

7. 运行你的第一个Reachy程序

环境配置妥当，是时候让机器人动一动了。我们假设Reachy SDK已经预装在系统中（通常位于/home/pi/reachy_ws这样的工作空间）。

1. 激活ROS环境：Reachy基于ROS，首先需要source ROS的安装脚本。

   source /opt/ros/noetic/setup.bash # 假设是ROS Noetic版本 # 如果SDK安装在workspace，还需要source workspace source /home/pi/reachy_ws/devel/setup.bash

   为了方便，可以将这些source命令添加到~/.bashrc文件中，这样每次打开新终端都会自动设置。

2. 启动Reachy核心服务：通常，Reachy提供了一个启动所有必要节点（电机驱动、传感器、模型描述等）的launch文件。

   roslaunch reachy_bringup bringup.launch

   等待终端输出显示所有节点都已成功启动，没有报错。这表示机器人的“大脑”和“神经系统”已经就绪。

3. 运行一个简单的测试脚本：打开另一个SSH终端或VSCode的新终端（因为上一个终端被launch文件占用了）。在新的终端里，同样先source环境，然后运行一个Python示例脚本。例如，让所有关节移动到零位：

   # 你可以创建一个简单的 test_move.py 文件 # 内容可能类似于（具体API请参考Reachy官方文档）： # from reachy_sdk import ReachySDK # reachy = ReachySDK(host='localhost') # 连接本地ROS # reachy.turn_on('all') # reachy.goto_position({...}) # 具体的目标位置字典 # 然后运行： # python test_move.py

   你应该能看到Reachy Mini的各关节开始平滑地运动到指定位置。

注意事项：首次运行机器人程序前，请确保机器人周围有足够空间，没有障碍物，并且机器人本身被稳固地放置（或安装在底座上）。从低速、小幅度运动开始测试，逐步增加。仔细阅读官方文档中的API说明，理解每个关节的运动范围和限制，避免因指令错误导致机械损伤。

8. 常见问题排查与网络优化

即使按照指南操作，你也可能会遇到一些问题。这里汇总了一些常见情况及其解决方法。

8.1 SSH连接失败

8.2 Wi-Fi连接不稳定

机器人移动时，Wi-Fi信号可能会波动，导致SSH卡顿或ROS通信延迟。

• 优化信号：尽量让机器人在路由器可视范围内工作，避免厚墙阻隔。可以考虑使用Wi-Fi信号中继器。
• 使用有线网络作为备用：对于固定工位的开发，在机器人附近预留一个网口，通过USB以太网适配器连接，可以获得最稳定、低延迟的连接。
• 监控网络质量：在树莓派上，可以使用iwconfig wlan0查看无线连接质量（Link Quality和Signal level）。数值越高越好。
• 调整ROS通信参数：如果使用ROS1，网络不稳定时可能会遇到/clock不同步等问题。可以尝试在ROS master机器上设置ROS_MASTER_URI和ROS_IP环境变量为树莓派的固定IP，而不是localhost或主机名。

8.3 系统性能与资源管理

树莓派的算力有限，同时运行ROS、Python脚本和VSCode远程服务器可能会感到吃力。

• 关闭图形界面：Reachy的定制系统可能默认是命令行界面，这很好。如果启动了图形桌面（LXDE），会占用大量内存和CPU。可以通过sudo raspi-config->System Options->Boot / Auto Login->Console Autologin确保启动到命令行。
• 管理自启动服务：使用systemctl list-unit-files --type=service查看所有服务。如果不是必须的，可以禁用一些不相关的服务以节省资源：sudo systemctl disable <service-name>。
• 使用htop监控资源：安装htop(sudo apt install htop)，它是一个强大的交互式进程查看器，可以直观地看到CPU、内存和交换空间的使用情况，并管理进程。

8.4 软件包依赖与Python环境

在安装额外的Python包时，可能会遇到版本冲突。

• 使用虚拟环境：对于你自己的项目，强烈建议使用Python虚拟环境（venv）来隔离依赖。在项目目录下运行python3 -m venv venv，然后source venv/bin/activate激活它。在此环境下用pip install安装的包不会影响系统全局环境。
• 优先使用apt：对于系统级的库或ROS相关的包，优先使用sudo apt install来安装。pip安装的二进制包可能与系统架构不兼容。
• 注意ARM架构：树莓派是ARM架构（通常是armhf或arm64），有些Python包没有预编译的ARM版wheel，需要从源码编译，这可能会失败或需要安装额外的编译工具（如python3-dev,build-essential）。