在一个刚装好的 ROS 2 环境里，我敲下第一句命令：

第一次尝试
$ ros2 run micro_ros_agent micro_ros_agent udp4 --port 8888
    Package 'micro_ros_agent' not found

然后是全盘搜索，结果是空的。这台机器上根本没有这个包，也从来没安装过。

接下来我花了大概两个小时，把「装上它」这件事做完。真正浪费时间的不是编译， 而是三个前置的坑——它们都不会给你明确的提示，只会让你在错误的路上反复尝试。

01原因一：它不在 apt 里

最根本的一条：micro_ros_agent 不是 ROS 2 自带的包，官方也不提供 apt 二进制。 你在 apt search ros-humble-* 里翻多久都找不到它。

原因不难理解：micro-ROS 是给单片机用的，Agent 要跑在哪台主机、连什么传输 （UDP、串口、TCP、还是 CAN），取决于你的具体场景。官方把这部分留给你自己编译。

所以「装它」这件事的本质是：从源码构建一个 ROS 2 功能包。 这就注定要走 colcon build 那条路，而不是 apt install。

02原因二：shell 没 source ROS 2

第二个坑不会报错，只会让你困惑。我当时的环境里 ROS_DISTRO 是空的：

前置检查
$ source /opt/ros/humble/setup.bash
    $ echo $ROS_DISTRO
    humble
    $ ros2 --help            # 能出帮助信息，说明这一步对了

没 source 的时候，ros2 命令往往还能跑（因为二进制在 PATH 里）， 但很多环境变量是空的，于是后面 rosdep、colcon 的行为会变得莫名其妙。

我的做法是直接把这一行写进 ~/.bashrc，一劳永逸：

~/.bashrc
source /opt/ros/humble/setup.bash

注意发行版名字要对上——你装的是 humble 还是 jazzy，看 /opt/ros/ 下面那个目录名就知道。

03原因三：克隆失败，而且不告诉为什么

第三个坑最有意思：这台机器访问 GitHub 的下载通道被网络设备拦了。 git 协议、tarball 下载、API 调用全部不通，只有网页能正常打开。

这种环境的麻烦在于，它不会给你一个「网络被拦截」的错误，而是给你超时、 连接重置、或者干脆卡住——你会先怀疑自己打错了命令，然后怀疑 GitHub 挂了。

后来我用了两种绕法。第一种是浏览器手动下载 zip：

方式 B：手动下载（网络受限时用）
# 1. 浏览器打开并下载：
    #    https://github.com/micro-ROS/micro_ros_agent/archive/refs/heads/master.zip
    # 2. 把 zip 传到目标机器后：
    mkdir -p ~/microros_ws/src
    cd ~/microros_ws/src
    unzip ~/micro_ros_agent-master.zip
    mv micro_ros_agent-master micro_ros_agent

第二种是走镜像加速（可用性随时间变化，不一定每次都灵）：

方式 C：镜像加速
curl -L -o agent.zip \
      "https://ghfast.top/https://github.com/micro-ROS/micro_ros_agent/archive/refs/heads/master.zip"

无论用哪种方式，关键是最后目录结构要长成 ~/microros_ws/src/micro_ros_agent/—— colcon 认的是这个形状，中间多套一层文件夹它不会报错，只会静默地什么都编译不出来。

04编译

构建
sudo apt-get update
    sudo apt-get install -y git cmake python3-pip python3-rosdep
    sudo rosdep init        # 提示已初始化就跳过
    rosdep update

    cd ~/microros_ws
    source /opt/ros/humble/setup.bash
    rosdep install --from-paths src --ignore-src -r -y
    colcon build --symlink-install

在 aarch64 上大概要 5 到 15 分钟。中途如果报缺系统库， 用 apt-cache search <关键字> 找一下装上去就行，不用慌。

编译完成后验证，这一步必须 source 新工作空间，否则你还是会看到 「Package not found」——而且是同一个报错，很容易以为编译白做了：

验证
source ~/microros_ws/install/setup.bash
    ros2 pkg list | grep micro_ros_agent     # 能列出来就算成功

05连上之后，才算真正开始

启动 Agent：

启动 Agent
ros2 run micro_ros_agent micro_ros_agent udp4 -i 192.168.31.100 --port 8888

ESP32 那边烧好程序一连上，日志会刷出一长串。这几行是握手成功的标志：

Agent 日志
[1786983463.562502] info | UDPv4AgentLinux.cpp | init              | running...            | port: 8888
    [1786983475.555139] info | Root.cpp            | create_client     | create                | client_key: 0x0EA1126F, session_id: 0x81
    [1786983475.555289] info | SessionManager.hpp  | establish_session | session established   | client_key: 0x0EA1126F, address: 10.230.61.237:47138
    [1786983475.628974] info | ProxyClient.cpp     | create_participant| participant created   | client_key: 0x0EA1126F, participant_id: 0x000(1)
    [1786983475.887035] info | ProxyClient.cpp     | create_topic      | topic created         | client_key: 0x0EA1126F, topic_id: 0x000(2)
    [1786983476.033583] info | ProxyClient.cpp     | create_publisher  | publisher created     | client_key: 0x0EA1126F, publisher_id: 0x000(3)
    [1786983476.243162] info | ProxyClient.cpp     | create_datareader | datareader created    | client_key: 0x0EA1126F, datareader_id: 0x000(6)

读日志能读出两件事：

  • 首次连接花了大约 12 秒（init 到 create_client 之间）， 这不是 bug，是 UDP 广播发现机制的正常代价。
  • 实体是在 0.7 秒内逐个建起来的：participant → topic → publisher → subscriber → reader。 如果卡在某一行不动了，你就知道是哪个环节没走通。

还有一个我当时没在意、后来才觉得可疑的细节：Agent 监听在 192.168.31.100， 但会话里记录的客户端地址是 10.230.61.237。两者不在同一网段， 说明中间还有一层设备在做地址转换。这类不对称值得记一笔—— 它常常是「能握手，但数据不稳」的根源。

06握手成功 ≠ 数据流畅

看到 session established 时我松了一口气，以为最难的部分过去了。 然后我测了一下话题频率：

ros2 topic hz /robot/ping
average rate: 0.330
            min: 3.030s max: 3.030s std dev: 0.00000s window: 1
    average rate: 0.276
            min: 3.030s max: 4.814s std dev: 0.63409s window: 5
    average rate: 0.448
            min: 0.027s max: 4.814s std dev: 1.65541s window: 9
    average rate: 0.745
            min: 0.024s max: 4.814s std dev: 1.29310s window: 22

最慢的一次间隔是 4.814 秒，最快 0.024 秒，标准差一度到 1.65 秒。 也就是说：连接是通的，消息也确实在到达，但节奏完全不可控。

对 ping/pong 这种测试无所谓，对控制指令就很致命了。 这份输出是我后来去查局域网延迟的起点——那次排查写在了 另一篇笔记里。

07一张排查表

现象 先查什么
ros2 run 报 Package not found 是不是没 source ~/microros_ws/install/setup.bash？编译真的成功了吗？
clone 卡住或超时 换浏览器手动下载 zip，或走镜像加速
colcon 编译 0 个包 目录层级对不对？（必须是 src/micro_ros_agent/package.xml）
Agent 起来了但 ESP32 连不上 防火墙放行 UDP 端口；确认 -i 绑的是本机真实 IP
端口被占用 ros2 daemon stop，或者换端口（两边要一致）

08一句话总结

装 micro-ROS Agent 的难点不在编译，在先确认你面对的是哪一类问题： 是「包不存在」（要编译），是「环境没准备好」（要 source）， 还是「源码拿不到」（要绕网络）。这三件事的解法完全不同， 但它们在终端里长得一模一样——都是某句命令没反应。

分清楚了，剩下的事情二十分钟就能做完。

关于本文
整理自 2026 年 8 月的便签记录，日志为当时的真实输出（ROS 2 / Ubuntu on aarch64）。 系统版本与包名请按自己的环境替换。
2026.09.20 整理
补上了 ros2 topic hz 那段数据——原始笔记里只写了「好像不太稳」， 把数字摊开之后才看清问题的量级。