1. 从开箱到上电：SO-ARM100套件初印象
最近拿到了一套Waveshare的SO-ARM100开源六轴机械臂套件，这玩意儿在创客圈和AI机器人社区里热度不低。它最大的卖点，一个是全开源，从结构件到控制代码都给你；另一个就是原生支持Hugging Face的LeRobot库，号称能无缝对接当下最火的AI机器人学习与开发框架。对于想从零开始捣鼓机械臂，特别是想结合视觉、强化学习这些AI技术做点实验的朋友来说，吸引力确实不小。我花了一周多时间，从开箱组装、固件烧录，到跑通第一个LeRobot的Demo，把整个过程完整走了一遍。这篇文章就从一个实际组装和开发者的角度，聊聊这套套件的细节、踩过的坑，以及如何让它真正“动”起来，特别是和LeRobot结合的部分。
开箱第一印象，套件内容相当丰富。主体是六轴机械臂的结构，所有非金属的关节和外壳部件都是光敏树脂3D打印的，质感比普通的FDM打印件要细腻光滑很多，精度也高，这对于需要精密传动的机械臂来说很关键。驱动部分用的是高扭矩总线舵机，每个关节一个，通过一根总线串联，接线比传统的PWM舵机清爽太多。控制核心是一块树莓派CM4，这意味着它本质上是一台运行Linux的小电脑，扩展性和编程灵活性是单片机主控没法比的。套件里还配了电源、各种螺丝刀、螺丝包、线材，基本上除了需要自备的树莓派CM4和SD卡，其他都齐了。对于新手，我建议在动手前，先找个宽敞、光线好的桌面，把所有零件按包装袋上的标签分分类，能省去后面组装时到处找零件的麻烦。
2. 机械臂本体组装：精度、顺序与关键调整
组装过程本身不算复杂，但非常考验耐心和细心。官方的Wiki上有详细的图文教程，但有些细节需要自己琢磨。整个组装可以大致分为底座、腰部、大臂、小臂、手腕和末端执行器这几个部分。我的建议是，严格按照官方推荐的顺序来，因为很多部件有依赖关系，装错了再返工会很痛苦。
2.1 关节组装与舵机安装
第一步是处理舵机。SO-ARM100使用的是总线舵机，每个舵机都有一个唯一的ID。在安装到机械结构上之前，强烈建议先单独给舵机上电，用提供的调试工具（通常是USB转TTL模块连接电脑）测试一下每个舵机能否被正确识别和转动。这一步能提前排除舵机本身故障或者ID冲突的问题，如果等全部装好再发现某个关节不动，拆卸会非常麻烦。测试时，注意观察舵机转动是否顺滑，有无异响。
安装舵机到3D打印件时，螺丝不要一次性拧死。先轻轻带上，确保舵机输出轴和结构件的孔位完全对准，然后再逐步对称地拧紧。如果发现螺丝拧进去很费力，千万不要用蛮力，可能是螺孔里有残留的支撑材料，用配套的M2.5丝锥稍微过一下丝就能解决。这是树脂打印件组装时的一个常见小坑。
2.2 走线与限位处理
六轴机械臂的线缆管理是个学问。SO-ARM100的舵机采用总线串联，理论上接线很简单，但实际组装时，要规划好线缆的走向，避免在运动过程中被关节挤压或拉扯。官方设计了一些线槽，要充分利用。我的经验是，在固定每个部分的壳体之前，先把线缆大致摆放到位，并留出足够的余量，特别是关节活动范围的两端。
另一个重点是软限位的设置。虽然总线舵机支持多圈转动，但机械结构本身是有物理限位的。在组装时，要特别注意每个关节的零位。通常的做法是，在组装完成后、上电初始化前，手动将每个关节移动到它的“机械零点”位置（一般是两个方向运动范围的中间点，或者结构上标记的参考位置）。然后，在后续的软件配置中，将这个位置设置为逻辑零点。这样能最大程度避免软件控制时让机械臂运动到极限位置，发生碰撞或卡死。SO-ARM100的某些关节，比如腕部，活动范围比较小，更需要注意。
2.3 整体校准与静态测试
全部组装完成后，先不要急着通电做复杂运动。用手轻轻转动每个关节，感受一下是否有明显的阻滞感或齿轮的“咔哒”声（这可能是齿轮箱内部有问题，或者安装不当导致齿轮啮合过紧）。确保所有螺丝，特别是连接舵机和结构件、连接相邻连杆的螺丝都已紧固。
接下来进行静态上电测试。连接好所有线缆，给控制板供电。此时树莓派CM4可能还没烧录系统，我们只测试舵机总线。如果使用官方的调试上位机软件，你应该能看到链路上所有舵机ID都被枚举出来。尝试给每个舵机发送一个很小的位置指令（比如从当前位置转动5度），观察它是否按预期运动，并且没有异常噪音。这个阶段的目的不是让机械臂摆姿势，而是确认每个执行单元都是“活”的，并且响应正常。
3. 软件栈搭建：从树莓派系统到LeRobot环境
机械部分搞定，接下来就是软件大脑了。SO-ARM100的核心是树莓派CM4，这意味着我们有一个完整的Linux环境来运行复杂的机器人软件栈。官方提供了两种主要的软件路径：一是使用他们基于ROS（Robot Operating System）定制的镜像，二是使用原生支持LeRobot的镜像。既然标题和热点都指向LeRobot，我们重点走第二条路。
3.1 系统镜像烧录与基础配置
首先需要准备一张至少16GB的Micro SD卡。到Waveshare的Wiki页面，找到SO-ARM100/101的资料下载，里面会有预配置好的系统镜像文件（通常是.img格式）。使用Raspberry Pi Imager或者BalenaEtcher这类工具将镜像烧录到SD卡中。烧录完成后，有一个关键步骤：在电脑上重新挂载SD卡的boot分区，你需要在这里修改一些配置文件以适应你的本地网络环境。
主要修改两个文件：
userconf.txt： 用于设置树莓派默认用户（通常是pi）的密码。按照格式pi:$6$...（加密后的密码字符串）填写。如果你图省事，可以先留空或设置简单密码，首次登录后再改。wpa_supplicant.conf： 用于配置Wi-Fi。填入你的国家代码（如CN）、SSID和密码。这样树莓派启动后就能自动连接网络，方便后续通过SSH远程操作，毕竟接着屏幕和键盘调试机械臂并不方便。
# wpa_supplicant.conf 示例内容 country=CN ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev update_config=1 network={ ssid="你的Wi-Fi名称" psk="你的Wi-Fi密码" key_mgmt=WPA-PSK }将SD卡插入CM4底板，连接电源和网线（或确保Wi-Fi已配置正确），上电启动。等待几分钟后，你可以在路由器后台查找名为SO-ARM100或类似的新设备，获取其IP地址。然后就可以用SSH客户端（如PuTTY或终端下的ssh命令）连接了。默认用户名可能是pi，密码就是你之前在userconf.txt里设置的。
3.2 LeRobot框架安装与初步验证
通过SSH登录后，你会发现系统已经做了很多预配置。但为了确保环境完整，我们最好手动验证和初始化一下LeRobot。官方镜像可能已经安装了LeRobot的部分依赖，但框架本身和示例代码可能需要拉取。
首先，更新一下系统包管理器并安装一些基础工具：
sudo apt update sudo apt upgrade -y sudo apt install git python3-pip python3-venv -y接下来，为LeRobot项目创建一个独立的Python虚拟环境是个好习惯，可以避免包版本冲突：
python3 -m venv ~/lerobot_env source ~/lerobot_env/bin/activate激活虚拟环境后，安装LeRobot。根据其官方文档，通常推荐从源码安装以获取最新功能和示例：
cd ~ git clone https://github.com/huggingface/lerobot.git cd lerobot pip install -e .这个过程会安装LeRobot核心库及其依赖，包括PyTorch、Transformers等，耗时可能比较长，取决于网络速度和CM4的性能。
安装完成后，我们可以运行一个简单的测试脚本来验证LeRobot环境是否正常，以及它能否与机械臂硬件通信。LeRobot设计上抽象了不同的机器人硬件，通过一个统一的Robot类进行交互。对于SO-ARM100，应该有一个对应的硬件驱动接口。你需要查阅Waveshare提供的、与LeRobot适配的特定代码库或配置文件。这个库可能已经预装在镜像里，也可能需要从Waveshare的GitHub仓库单独克隆。
假设驱动库位于~/so_arm100_driver，并且提供了LeRobot的集成接口。一个典型的验证步骤可能如下：
# test_arm.py from lerobot.robots import Robot import time # 初始化机器人，指定配置为'so_arm100' robot = Robot.from_name("so_arm100") # 获取当前关节状态（位置、速度等） state = robot.get_state() print(f"Current joint positions: {state['joint_positions']}") # 让所有关节移动到“零点”位置（通常是安全位置） zero_positions = [0.0, 0.0, 0.0, 0.0, 0.0, 0.0] # 具体值需根据机械臂模型调整 robot.set_goal({"joint_positions": zero_positions}) time.sleep(2) # 等待运动完成 print("Robot should now be at zero position.")注意：在第一次运行任何运动指令前，请确保机械臂周围有足够空间，并且末端没有安装任何工具或存在障碍物。最好用手扶着机械臂，准备随时断电。因为零位定义不准，或者运动范围设置不对，都可能导致机械臂突然做出大范围动作。
4. 与LeRobot深度集成：策略学习与仿真
让机械臂动起来只是第一步。SO-ARM100搭配LeRobot的真正威力在于，你可以利用Hugging Face生态中丰富的预训练模型和数据集，来教机械臂完成特定任务，比如抓取、摆放，甚至是基于视觉的复杂操作。
4.1 理解LeRobot的数据与策略范式
LeRobot的核心思想是“学习即代码”。它将机器人交互数据（状态、动作、图像等）以一种标准格式（通常存储在Hugging Face Hub上）进行管理，并提供了工具来用这些数据训练策略（Policy），或者直接加载他人训练好的策略来控制你的机器人。
对于SO-ARM100，你可以从录制你自己的演示数据开始。LeRobot提供了数据收集的API。例如，你可以通过键盘、游戏手柄或者手动拖拽（如果机械臂支持导纳控制）来操控机械臂完成一个“将积木从A点拿到B点”的任务，同时系统会记录下关节角度、末端执行器状态、以及摄像头图像（如果你接了摄像头）。这些数据会被自动整理并上传到你的HF Hub空间，形成一个数据集。
有了数据集，你就可以在本地或者云端（对于CM4，可能更需要云端）训练一个模仿学习（Imitation Learning）策略。训练代码通常也是标准化的。一个简化的流程如下：
- 从HF Hub加载你刚创建的数据集。
- 选择一个基础的策略模型架构（比如基于CNN的视觉策略网络）。
- 配置训练参数（学习率、批次大小等）。
- 开始训练，模型会学习从观察（图像+关节状态）到动作（关节目标位置或速度）的映射。
训练完成后，你可以将模型文件下载到树莓派上，然后写一个简单的推理循环：用摄像头获取当前图像，加上当前的关节状态，输入给训练好的策略模型，模型输出动作指令，再通过robot.set_goal发送给机械臂执行。这样，机械臂就能“复现”你之前教它的动作，甚至在略有不同的环境下也能泛化执行。
4.2 仿真环境的使用与迁移
在真实机械臂上直接试错，成本高且有风险。LeRobot通常与仿真环境（如MuJoCo、Isaac Sim）有很好的集成。你可以在电脑上强大的仿真环境中，用虚拟的SO-ARM100模型进行算法开发、策略训练和大量测试。Waveshare应该提供了SO-ARM100的URDF模型文件，你可以将其导入到PyBullet或MuJoCo中。
在仿真中验证通过的策略，可以通过LeRobot提供的“仿真到现实”（Sim2Real）工具链，尝试迁移到真实的SO-ARM100上。这个过程可能涉及域随机化（Domain Randomization）和在真实数据上的微调（Fine-tuning）。虽然不能保证100%成功，但能极大加快开发周期，减少对硬件的损耗。
具体操作上，你需要在仿真环境中安装LeRobot，并加载SO-ARM100的URDF。然后，你可以用与真实机器人几乎相同的API来控制仿真机器人，并收集仿真数据。训练在仿真数据上完成的策略，在部署到真实机器上前，一个实用的技巧是加入一些噪声（比如关节摩擦力变化、视觉感知噪声等），并可能在少量真实数据上对策略做最后的校准。
5. 开发中的常见问题与调试技巧
在实际把玩SO-ARM100和LeRobot的过程中，我遇到了不少问题，这里总结几个典型的和解决方法。
5.1 通信与舵机控制异常
问题现象： SSH可以连接树莓派，但LeRobot脚本无法初始化机器人，报错提示无法打开串口或与舵机总线通信失败。排查思路：
- 权限问题： Linux下访问硬件串口设备（如
/dev/ttyAMA0或/dev/ttyS0）需要权限。运行ls -l /dev/tty*查看设备，通常需要将用户加入dialout组，或者直接使用sudo运行脚本（不推荐长期使用）。更安全的方式是设置udev规则。sudo usermod -a -G dialout $USER # 然后需要注销重新登录生效 - 串口设备映射： 树莓派的硬件串口可能被蓝牙占用。需要检查
/boot/config.txt文件，确保启用了正确的串口。对于CM4，Waveshare的底板可能使用特定的串口引脚。必须确认驱动代码中打开的串口设备路径与实际硬件连接一致。可以尝试用minicom或screen工具手动连接对应串口，发送舵机协议指令测试。 - 舵机总线供电： 六个高扭矩舵机同时运动时，瞬时电流可能很大。如果电源功率不足，会导致总线电压被拉低，造成通信错误或舵机复位。确保使用官方推荐或功率足够的电源（通常是12V/5A以上）。在代码中，也可以考虑加入动作平滑处理，避免所有关节同时以最高速度启动。
5.2 LeRobot依赖包冲突与版本问题
问题现象： 在安装LeRobot或运行示例时，出现ImportError或者某些函数调用报错。排查思路：
- 坚持使用虚拟环境： 这是避免系统Python环境被污染的最佳实践。确保你在正确的虚拟环境中安装和运行。
- 仔细阅读错误信息： 错误信息通常会告诉你具体是哪个模块缺失或版本不兼容。LeRobot对PyTorch、CUDA（如果你用GPU训练）、Gymnasium等版本可能有特定要求。参考LeRobot官方仓库的
requirements.txt或pyproject.toml文件。 - 分步安装： 如果
pip install -e .一次性安装失败，可以尝试先安装核心依赖，如pip install torch torchvision（注意选择与你的系统，这里是ARM架构的树莓派OS兼容的版本，通常需要安装CPU版本），然后再安装LeRobot。 - 利用预构建镜像： Waveshare提供的预装LeRobot的镜像往往是测试过兼容性的最稳定版本。如果自己搭建环境问题太多，退回使用官方镜像是最高效的选择。
5.3 机械臂运动不准确或抖动
问题现象： 机械臂能动，但到达目标位置时有偏差，或者在保持位置时轻微抖动。排查思路：
- 校准，校准，还是校准： 重新检查并校准每个关节的软件零位。确保当软件命令所有关节为0时，机械臂处于你定义的“物理零点”姿态。可以使用一个高精度的数字水平仪或激光笔辅助对齐。
- 舵机性能调整： 总线舵机通常有PID参数可以调整。如果舵机在到达目标位置后来回振荡（抖动），可能是比例增益（P）太高或微分增益（D）太低。如果响应慢、有静差，可能需要调高积分增益（I）。Waveshare应该提供了配置软件，可以通过电脑连接总线，对每个舵机的PID参数进行微调。调整时务必小幅度修改，并记录下原始值。
- 机械结构检查： 抖动也可能源于机械松动。再次检查所有螺丝，特别是舵机与连杆、连杆与连杆之间的连接螺丝是否紧固。检查齿轮箱是否有过大间隙。
- 控制频率与滤波： 在LeRobot策略控制循环中，发送指令的频率是否稳定？是否在发送目标位置前对模型输出的动作做了平滑滤波（如低通滤波器）？过于频繁或跳变的指令也会导致舵机抖动。
6. 项目拓展与进阶玩法
当基础的抓取放置任务玩转之后，SO-ARM100结合LeRobot还有更多可能性可以挖掘。
多模态任务学习： 除了关节状态，为机械臂增加视觉感知是必然。可以搭配Waveshare的摄像头模块，或者USB摄像头。在LeRobot中，你可以设计一个同时接收图像和关节状态的策略网络。更进一步，可以接入麦克风，尝试完成“语音指令抓取特定颜色物体”这类多模态任务。Hugging Face的Transformers库里有丰富的视觉、语音预训练模型，可以提取特征，加速策略学习。
强化学习（RL）实战： 模仿学习依赖于高质量的演示数据。而强化学习让机械臂通过“试错”自我学习。你可以为SO-ARM100设计一个简单的RL环境，比如将一个环套到柱子上（套圈游戏）。定义好状态空间（关节角度、末端位置、或许还有摄像头图像）、动作空间（关节增量运动）、奖励函数（距离柱子越近奖励越高，套中得大奖）。然后使用LeRobot集成或兼容的RL算法库（如Stable-Baselines3）进行训练。在真实机械臂上做RL训练采样效率低，风险高，通常先在仿真中进行大量训练，再将策略迁移到实体。
融入更大的自动化流程： 将SO-ARM100视为一个智能执行单元。通过树莓派的GPIO或USB接口，它可以控制电磁铁、气泵（用于吸盘）、灯光等外围设备。结合OpenCV进行更复杂的视觉识别（物体分类、姿态估计），你可以搭建一个小型的智能分拣站，或者一个自动化的实验样品处理平台。LeRobot学到的策略可以作为这个流程中的核心决策模块。
社区与开源贡献： 最后，别忘了这是开源项目。如果你解决了某个棘手的bug，优化了驱动代码，或者用SO-ARM100完成了一个有趣的任务并录制了数据集，非常鼓励你将这些成果回馈给社区。在Hugging Face Hub上分享你的数据集和模型，在GitHub上提交Pull Request，或者就是在论坛和群里分享你的经验。开源生态的活力正来自于此。
