RFrame CLI User Guide
Draft for website testing. This is a condensed English draft, not a complete translation. Both language versions await final content-owner updates. Original technical details, code comments, tables, and illustrations are retained in Chinese in the expandable reference below.
1. Dependencies and installation
The robby-data-tools Deb package provides /usr/bin/rframe. It requires r-frame, r-log, and a compatible jsoncpp installation. The Deb declares only the first two dependencies; do not assume jsoncpp is installed automatically. Install r-frame-plugin when full ROS 2 communication, message parsing, and discovery are required. Keep Robby package versions consistent.
Use the configured package repository or the delivered Deb files. Prefer apt when dependency resolution is needed. The standard package includes the YAML runtime it needs; source builds require the yaml-cpp development library. Original installation commands and configuration examples are retained below.
2. Command overview
| Command group | Purpose |
|---|---|
rframe bag | Record topics to MCAP, replay recordings, and inspect files. |
rframe topic | List and inspect topics, print messages, measure streams, and publish data. |
rframe service | List, inspect, and call services. |
rframe discovery | Monitor discovered resources or capture a snapshot. |
Use -h or --help for the installed command's supported options. Stop long-running commands with Ctrl+C. For scripts, prefer supported --json output to parsing aligned text tables.
3. Recording, playback, and file information
Use rframe bag record to record selected topics, rframe bag play to replay an MCAP file, and rframe bag info to inspect it. Review topic filters, file segmentation, buffering, time ranges, playback controls, and transport selection before running. The appendix retains the parameter tables and examples.
4. Topic inspection and messaging
list shows topics and endpoint counts; info shows types, transports, and endpoints. Use echo to inspect messages and stats to observe rate, message size, and throughput. pub publishes messages or raw bytes. Confirm the message type, loaded type support, transport, and JSON/YAML body format.
5. Service inspection and calls
Use rframe service list, info, and call to discover, inspect, and invoke services. Check the service type, availability, request body, transport, and runtime environment. Topic publication and service calls share the documented JSON/YAML body rules.
6. Resource discovery
rframe discovery monitor provides an interactive live view; snapshot returns a one-time view. Review the supported filters and output options for the installed version. The monitor owns the terminal, so diagnostic logs are written to files rather than mixed into its display.
7. Logs and troubleshooting
Diagnostic levels are off, error, warn, info, debug, and trace. Terminal diagnostics default to off; file logs normally retain info. Use --log-level when diagnosing a problem. Logs default to $HOME/logs/rframe_cli/; RFRAME_CLI_LOG_ROOT overrides the root.
If a topic is discovered but cannot be read, check type loading, transport, and dependencies. For missing recordings, review recorder filters and configuration. For unexpected playback transport, review routing and --transport. Check jsoncpp version, ABI, and library search paths when loading fails. Consult the command's --help for authoritative options.
8. Original technical reference (Chinese)
Expand the original chapters, tables, code, and illustrations
本文介绍 RFrame 对外提供的 rframe CLI 命令和工具，方便日常使用和调试。
使用前：依赖与安装
Deb 包及其依赖
统一 CLI 由 robby-data-tools Deb 提供，安装后公开入口为 /usr/bin/rframe。
| Deb 包 | 是否必需 | 用途 |
|---|---|---|
robby-data-tools | 必需 | 提供 rframe 命令及录制、回放和诊断功能 |
r-frame | 必需 | 基础通信组件 |
r-log | 必需 | 日志组件 |
jsoncpp（如 robby-jsoncpp） | 必需，用户自行准备 | JSON 处理库；当前不会随本包自动安装 |
r-frame-plugin | 按需安装 | 扩展 ROS2 通信、消息解析和发现能力；需要完整 ROS2 功能时建议安装 |
yaml-cpp | YAML 解析依赖 | 供 topic pub / service call 解析正文；标准安装包随附所需共享运行库，静态链接版本无需额外运行库 |
robby-data-tools 的 Deb Depends 仅声明 r-frame、r-log，APT 会从已配置的软件源解析这两项依赖。jsoncpp 仍是运行所需的库，需用户自行准备，并确认版本、ABI 和动态库搜索路径兼容；安装本包不保证 jsoncpp 已就绪。r-frame-plugin 是可选包：只使用基础 SHM/Zenoh 功能时可以不安装；需要完整 ROS2 功能时再安装。建议所有 Robby Deb 使用同一发布版本。
推荐安装方式
先准备兼容的 jsoncpp；已配置对应软件源且交付环境使用 robby-jsoncpp 时，可显式安装：
sudo apt install robby-jsoncpp
环境已提供兼容库时无需重复安装。jsoncpp 就绪后，从已配置的 Robby 软件源安装工具：
sudo apt install robby-data-tools
# 需要完整 ROS2 通信、消息解析和发现能力时安装
sudo apt install r-frame-plugin
如果收到的是单独的本地 Deb 文件，使用：
sudo apt install ./robby-data-tools_*.deb
# 需要完整 ROS2 通信、消息解析和发现能力时安装
sudo apt install r-frame-plugin
如果所有 Deb 均以文件形式离线交付，可让 apt 一次安装本地文件。以下使用交付的 robby-jsoncpp；环境已有兼容库时可删除该项：
sudo apt install \
./r-log_*.deb \
./r-frame_*.deb \
./robby-jsoncpp_*.deb \
./robby-data-tools_*.deb \
./r-frame-plugin_*.deb
最后一项 r-frame-plugin_*.deb 是可选包；不需要完整 ROS2 功能时从命令中删除。建议优先使用 apt，因为 dpkg -i 不会自动下载缺失依赖。
标准 Deb 安装通常无需另装 YAML 开发包。源码编译需要 yaml-cpp 开发库，Ubuntu 可执行 sudo apt install libyaml-cpp-dev；自定义部署需确保匹配的运行库可被加载。
安装后的路径与配置文件
Deb 安装完成后，CLI 相关文件位于以下位置：
/usr/bin/
└── rframe # 用户直接运行的统一命令
/opt/robby/robby-data-tools/
├── setup.bash # Bash 环境和 Tab 补全入口
├── bin/ # rframe 启动程序；通常无需直接使用
├── libexec/rframe/ # 各子命令的内部程序；不要直接调用
├── config/replay/
│ ├── robby_recorder_player_config.json # bag record/play 配置模板
│ └── plugins.json # 插件加载配置，通常无需修改
├── share/bash-completion/completions/rframe
├── lib/ # 运行库
└── plugins/ # 随包安装的录制、回放插件
可用 dpkg -L robby-data-tools 查看当前版本实际安装的完整文件清单。
CLI 用户通常只需要关注以下文件：
/usr/bin/rframe：日常使用入口。直接执行即可，不需要进入/opt/robby/robby-data-tools/bin/。/opt/robby/robby-data-tools/setup.bash：需要在当前 Bash 中启用 Tab 补全或手动加载运行环境时使用。/opt/robby/robby-data-tools/config/replay/robby_recorder_player_config.json：rframe bag record和rframe bag play的默认配置模板，可设置录制范围、缓冲策略、回放速度、输出方式和日志选项。其主要是设置一些CLI入参无法设置的高级参数，一般不需要用户设置。只有CLI的入参无法满足用户需求时，才考虑通过config文件来配置。
建议不要直接修改 /opt 下的配置模板，因为安装或升级 Deb 时文件可能被新版本替换。需要自定义录制或回放配置时，先复制到自己的工作目录，再通过 --config 指定：
cp /opt/robby/robby-data-tools/config/replay/robby_recorder_player_config.json \
./my_rframe_bag_config.json
# 按需编辑配置后使用；--all 也可以换成具体 topic
rframe bag record --config ./my_rframe_bag_config.json --all
rframe bag play --config ./my_rframe_bag_config.json recording_00001.mcap
plugins.json 不是 rframe bag record/play --config 所使用的配置文件。普通 CLI 用户无需修改它；只有部署方调整插件安装位置或启用状态时才需要关注。
运行日志和录制生成的 MCAP 文件不属于 Deb 的安装文件：日志默认写到 $HOME/logs/rframe_cli/，MCAP 写到命令指定或当前工作目录下的输出路径。
安装或升级后进行基本验证：
command -v rframe
rframe --version # cli工具的build版本，并非rframe包的版本
rframe --help
rframe topic list --help
rframe topic info --help
rframe discovery snapshot --help
正常情况下 command -v rframe 输出 /usr/bin/rframe。
其中，rframe --version 输出 rframe CLI build <版本号>，表示 CLI 的编译版本，不是底层 r-frame 运行库版本，也不保证与 Deb 包版本相同。安装包版本可用 dpkg-query -W -f='${Version}\n' robby-data-tools 查询。
1. 命令概览
rframe
├── bag
│ ├── record 录制 topic 到 MCAP
│ ├── play 回放 MCAP
│ └── info 查看 MCAP 信息
├── topic
│ ├── list 列出 topic 和发布/订阅数量
│ ├── info 查看指定 topic 的类型、通信方式和端点
│ ├── echo 输出 topic 消息
│ ├── stats 观测 topic 频率、大小和吞吐
│ └── pub 发布普通消息或原始字节消息
├── service
│ ├── list 列出 service
│ ├── info 查看 service 类型、通信方式和可用性
│ └── call 调用 service
└── discovery
├── monitor 实时查看 topic/service
└── snapshot 一次性查看 topic/service
查看帮助和版本：
rframe --help
rframe --version
rframe help bag
rframe help topic echo
rframe bag play --help
各命令按 Bag、Topic、Service、Discovery 分组介绍。所有长时间运行的命令均可通过 Ctrl+C 结束。
日志级别支持 off、error、warn、info、debug、trace。CLI 终端默认只输出命令结果，诊断日志级别为 off；文件日志默认仍保留到 info。可通过 --log-level 打开终端诊断日志，指定 debug/trace 时文件日志同步提升；discovery monitor 独占终端，诊断日志只写文件。
日志默认写入 $HOME/logs/rframe_cli/，按命令保存到 bag_record/、topic_echo/ 等子目录。可用 RFRAME_CLI_LOG_ROOT 修改根目录；指定目录不可写时会尝试默认目录及临时目录。
所有命令均可使用 -h / --help 查看参数。脚本采集优先使用命令提供的 --json，不要依赖文本表格的空格列宽。Topic/Service 查询默认只显示概要，--verbose 增加详情；各命令的具体输出见下文。
1.1 运行环境和 Tab 补全
Deb 正常安装后，直接运行 rframe 不要求提前 source：/usr/bin/rframe 启动入口会为本次命令加载 ROS2 和运行库路径。
如需在当前 Bash 中启用 group、action、参数值和 MCAP/JSON 文件的 Tab 补全，建议执行：
source /opt/robby/robby-data-tools/setup.bash
setup.bash 会按当前 ROS_DISTRO（未设置时默认 humble）尝试加载 ROS2、设置 RobbyDataTools 的 PATH/LD_LIBRARY_PATH，并注册 rframe Bash 补全。ROS2 不存在时会保留非 ROS2 功能，只输出警告。必须在 Bash 中使用 source；直接执行脚本不会把环境变量和补全函数保留到当前 shell。
只想加载补全、不修改当前 shell 的其他环境时，可以执行：
source /opt/robby/robby-data-tools/share/bash-completion/completions/rframe
上述设置只对当前终端生效；新开终端后需要重新 source。需要长期启用时，可将第一条命令加入用户的 ~/.bashrc。补全功能面向 Bash，加载后可用下面的方式检查：
rframe <Tab> # 补全 bag、topic、service、discovery
rframe bag <Tab> # 补全 record、play、info
rframe topic <Tab> # 补全 list、info、echo、stats、pub
rframe service <Tab> # 补全 list、info、call（以当前构建可用命令为准）
rframe bag play --transport <Tab> # 补全输出 transport
rframe bag play file<Tab> # 补全 .mcap 文件
1.2 类型加载
当前RobbyAnt机器人，内部定义和使用的类型，基本都在一个包里，涉及到这些类型时，在运行CLI工具前执行：
source /opt/robby/r-types/setup.bash
用户使用自定义类型时，在运行CLI工具前执行：
source /path/to/message_workspace/install/setup.bash # 自定义类型时
1.3 快速上手
source /opt/robby/robby-data-tools/setup.bash # 提供tab补全
source /opt/robby/r-types/setup.bash # R2机器人自定义类型
source /path/to/message_workspace/install/setup.bash # 自定义类型时
rframe xxx # 执行实际指令
2. 录制回放与文件信息：rframe bag
2.1 录制：rframe bag record
用法
订阅指定或自动发现的 topic，并写入 MCAP 文件。支持录制 ROS2、SHM 和 Zenoh 数据；Zenoh 发现默认开启。
rframe bag record [options] <topic1> [topic2 ...]
至少需要指定位置 topic、--regex、--all，或提供包含录制范围的配置文件。
参数
| 参数 | 说明 |
|---|---|
<topic>... | 精确指定一个或多个 topic；可同时录制多个名称 |
-o, --output <file> | 录制基础路径，不是最终文件名；会去掉最后一个扩展名并追加五位分段编号和 .mcap |
-a, --all | 录制全部发现到的 topic，但仍应用黑名单和系统 topic 排除规则 |
-k, --black-list <topic> | 排除一个 topic；可重复指定，优先级高于其他筛选条件 |
-x, --regex <pattern> | 包含匹配 topic 的 ECMAScript 正则；对完整 topic 名进行匹配，与位置 topic 取并集，可用 .*text.* 匹配中间片段 |
-t, --time <seconds> | 录制启动后的最长运行时间，单位秒，可输入非负小数，如 0.5、60；0 表示不自动停止，默认 0，不接受 ms/m 等后缀 |
--exclude-system-topics | 排除配置中的系统 topic，默认为 /parameter_events 和 /rosout |
--no-exclude-system-topics | 允许录制系统 topic |
-m, --segment-size <MB> | 单个分段的容量阈值，输入非负整数 MB；达到阈值后创建下一段，0 表示关闭容量分段 |
-i, --segment-interval <s> | 单个分段的最长录制时长，输入非负整数秒；达到阈值后创建下一段，0 表示关闭时间分段 |
-c, --compress <type> | MCAP Chunk 压缩方式：default（当前为 Zstd）、none、lz4 或 zstd |
-S, --shm-size <KB> | SHM reader 内存大小覆盖值，输入非负整数 KB；通常仅在发现信息缺失或诊断时设置 |
--buffer-policy <policy> | 缓冲区满时使用 block、drop-old 或 drop-new；默认 drop-new |
--buffer-size <count> | 缓冲区消息数量上限，输入非负整数；0 或未设置时默认使用 1000，与字节上限任一先到即视为缓冲区满 |
--buffer-bytes <MB> | 缓冲区数据量上限，输入非负整数 MB；0 或未设置时默认使用 512 MB，与消息数上限共同生效 |
--enable-zenoh-discovery | 启用 Zenoh 设备发现；当前已默认开启 |
--disable-zenoh-discovery | 禁用 Zenoh 设备发现；仅在确定不录制 Zenoh 数据时使用 |
--config <path> | 读取指定 JSON 高级配置；未指定时自动查找默认配置，详见 2.4 节 |
--log-level <level> | 终端诊断日志级别，默认 off |
文件名与分段
--output 指定的是基础路径，不是最终文件名。即使没有发生分段，生成的文件名也会包含 _00001：
-o sensors.mcap -> sensors_00001.mcap
-o sensors -> sensors_00001.mcap
路径最后一个扩展名会先被去掉，再追加编号和 .mcap。发生容量或时间轮转时，后续文件依次为：
sensors_00001.mcap
sensors_00002.mcap
sensors_00003.mcap
未指定 -o 时，基础名形如 output_YYYYMMDD_HHMMSS_ffffff.mcap，实际首段仍带 _00001。启动日志中的 Recording to: 会显示当前实际文件路径。
注意：输出目录需要事先存在且可写。回放时应传入实际带编号的文件；完整回放分段录制时，要按编号传入全部分段。不要复用已有基础名，以免同名分段文件被覆盖。
筛选和缓冲规则
- 黑名单优先级最高。
--all表示除黑名单和默认系统 topic 外全部录制；与位置 topic/正则同时使用时，包含条件会被忽略并给出警告。- 未使用
--all时，位置 topic 与正则匹配结果取并集。 block会阻塞入口生产者，但不保证完全不丢消息；输出队列满时仍可能丢弃，需合理配置缓冲容量。drop-old保留新数据；drop-new保留已排队数据。- 同时设置
--segment-size和--segment-interval时，任一阈值先达到都会轮转；它们只控制分段，不控制录制总时长。总时长由--time控制。 --segment-size是轮转触发阈值，不是严格的文件大小上限；正在写入的消息或 MCAP Chunk 可能使最终文件略大于设定值。--time和--segment-interval从命令开始运行时计时，不按消息自身的时间戳计算；实际停止时间可能有少量系统调度误差。- 建议用
Ctrl+C正常停止并等待缓冲区完成收尾，不要直接强制终止进程。
示例
# 录制指定 topic
rframe bag record /camera/image /imu/data -o sensors.mcap
# 实际首段：sensors_00001.mcap
# 录制全部已发现 topic，默认排除系统 topic
rframe bag record -a -o all.mcap
# 按正则录制 camera 命名空间
rframe bag record -x '^/camera/.*' -o camera.mcap
# 录制 60 秒后自动停止
rframe bag record -a -t 60 -o one_minute.mcap
# 每 1024 MB（1 GiB）或每 10 分钟轮转一次，先达到任一条件即生成下一段
rframe bag record -a -o long_run.mcap -m 1024 -i 600
典型输出（时间戳、topic 和统计值随现场变化）：
Recording to: sensors_00001.mcap
Buffer policy: drop-new
Subscribed topic: /camera/image
Subscribed topic: /imu/data
Recording started. Press Ctrl+C to stop.
Receiving topic: /camera/image
Receiving topic: /imu/data
Recording stopped.
Summary:
Duration: 10.012 s
Messages: 301 written
Data: 11.80 MiB
Topics: 2
Files:
sensors_00001.mcap (301 messages, 11.80 MiB)
Topic statistics:
/camera/image: 300 messages, 11.79 MiB, 30.00 Hz
/imu/data: 1 messages, 256 B
Subscribed topic: 表示已经开始订阅该 topic；Receiving topic: 表示已经收到该 topic 的第一条消息。尚未发现匹配的发布者时会显示 Waiting for matching publishers...。退出时会显示录制汇总；如果没有收到消息，会显示 No messages were received.；发生丢弃或写入失败时也会给出数量并返回失败状态。需要进一步排查时可增加 --log-level debug。
2.2 回放：rframe bag play
用法
按 MCAP 的 log_time（录制时间）顺序回放一个或多个 MCAP 文件，支持 topic 筛选、时间范围、速率、循环和通信方式选择。
默认不按消息的 publish_time 排序。文件缺少消息索引，或当前运行库不支持按 log_time 读取时，会提示并回退到文件写入顺序。
rframe bag play [options] <file1> [file2 ...]
录制生成的是带编号文件，例如 sensors_00001.mcap。如果录制已轮转成多段，应传入全部实际文件：
rframe bag play sensors_00001.mcap sensors_00002.mcap
参数
| 参数 | 说明 |
|---|---|
<file>... | 一个或多个实际 MCAP 文件；多个文件作为同一回放输入处理 |
-a, --all | 显式回放全部 topic；未设置包含筛选时默认也是全量回放 |
-w, --white-list <topic> | 只包含一个 topic；可重复指定，并与正则结果取并集 |
-k, --black-list <topic> | 排除一个 topic；可重复指定，优先级最高 |
-x, --regex <pattern> | 使用 ECMAScript 正则对完整 topic 名进行匹配；可用 .*text.* 匹配中间片段 |
-l, --loop | 播放完所选时间范围后重新开始 |
-r, --rate <factor> | 时间轴倍速；1.0 为原速、2.0 为 2 倍速、0.5 为半速，默认 1.0；默认范围 0.1～10.0，可由 JSON 的 rate_min/rate_max 调整 |
-d, --delay <seconds> | Player 启动后、发送第一条消息前的额外等待时间，单位秒，接受非负小数；0 表示不延迟，不接受单位后缀 |
-b, --begin <time> | 回放起点，边界消息包含在内；未设置则从所选输入的第一条消息开始，格式见下文 |
-e, --end <time> | 回放终点，边界消息包含在内；未设置则播放到所选输入末尾，格式见下文，且不能早于起点 |
-p, --preload <seconds> | 发送开始前，先从所选起点向后读取这段时长的数据到播放缓冲区；单位秒，接受非负小数；0 表示关闭，默认 0，不接受单位后缀 |
-T, --transport <type> | 覆盖 MCAP 记录的输出 transport；可选值见下文 |
--route-mode <mode> | 组合输出的发送策略：static 固定发送，dynamic 根据订阅者自动选择；只能配合组合 --transport 使用 |
-S, --shm-size <KB> | 设置 SHM 发送缓冲区大小，输入非负整数 KB；通常无需设置，录制信息缺失时默认使用 1 MB |
--buffer-size <count> | 播放缓冲区消息数量上限，输入非负整数；0 或未设置时默认使用 1000 |
--buffer-bytes <MB> | 播放缓冲区数据量上限，输入非负整数 MB；0 或未设置时默认使用 512 MB；与消息数上限任一先到即视为缓冲区满 |
--config <path> | 读取指定 JSON 高级配置；未指定时自动查找默认配置，详见 2.4 节 |
--log-level <level> | RFrame 控制台诊断级别，默认 off；文件日志默认仍保留到 info，指定 debug/trace 时文件同步提升 |
Topic 和时间范围
黑名单优先级最高。显式 --all 会忽略白名单和正则；否则白名单与正则结果取并集。
--begin 和 --end 是唯二支持时间单位后缀的参数，支持：
- 相对输入中首条消息时间戳的秒数，如
10、60.5；裸数字始终按秒处理； - 带单位的相对时间，如
1h30m、1m30s、2.5s、500ms；单位须按h、m、s、ms的顺序书写，不能包含空格； - 当前机器本地时区的绝对时间，如
2026-08-20-14:30:00，格式固定为YYYY-MM-DD-hh:mm:ss，精度为秒。
-b 10 -e 60 表示播放从输入首条消息时间戳后 10 秒到 60 秒的闭区间。相对时间的参照点是输入 MCAP 的首条消息，不是执行命令的当前时间。与 --loop 一起使用时，只循环所选区间。
起点或终点超出 MCAP 实际时间范围时会收敛到文件边界。应确保时间格式有效且起点不晚于终点；否则时间范围可能不会按预期生效。
--delay 是真实等待时间，不会改变 MCAP 时间范围；--preload 是读取范围，不是额外等待指定秒数。预加载仍受 --buffer-size 和 --buffer-bytes 限制。
--transport 输出传输
不指定 --transport 时，每个 topic 会沿用录制时的通信方式。需要强制使用指定方式时可选择：
| 写法 | 效果 |
|---|---|
--transport ros2 | 只通过 ROS2 发布 |
--transport shm | 只通过 SHM 发布 |
--transport zenoh | 只通过 Zenoh 发布 |
--transport shm,ros2 | 同时支持 SHM 和 ROS2 |
--transport shm,zenoh | 同时支持 SHM 和 Zenoh |
不支持 ROS2+Zenoh 或 SHM+ROS2+Zenoh 组合。组合输出必须包含 SHM，并搭配 ROS2 或 Zenoh。
组合输出策略：
static：默认值，固定通过选定的两种方式发送。dynamic：根据当前发现的订阅者自动选择发送方式；如果订阅者未被发现，数据可能不会从预期链路发出。
--route-mode 只能与 --transport shm,ros2 或 --transport shm,zenoh 一起使用。
使用 Zenoh 回放时，通常不需要额外配置：
- 原本通过 Zenoh 录制的数据，会按录制时的信息回放。
- ROS2 或 SHM 录制的数据，如果文件中包含完整的 ROS2 消息类型，可通过 Zenoh 发给兼容的 ROS2 Zenoh 节点。
- 原始字节或类型未知的数据会按原始数据发送，只适合能够识别这类数据的接收端；工具不会自动把它转换成其他消息类型。
- 与 ROS2 Zenoh 节点通信时，两端应使用相同的
ROS_DOMAIN_ID。未单独配置时，回放命令使用当前终端中的ROS_DOMAIN_ID。
以上 Zenoh 回放功能不要求安装可选的 r-frame-plugin。如果不确定如何选择，优先不设置 --transport，按录制信息回放。
播放中按键
| 按键 | 功能 |
|---|---|
Space | 暂停或继续 |
↑ | 加速一个配置步长，默认 0.1 倍 |
↓ | 减速一个配置步长，默认 0.1 倍 |
→ | 仅在暂停状态下发送下一条消息；运行中或已无数据时不执行 |
Ctrl+C | 停止并退出 |
单步使用方式：先按 Space 进入暂停，再按 →。成功时显示 Stepped；未暂停或没有剩余数据时显示 Step: not paused or no data。注意单步发送，是按时间顺序一条一条消息发送的，而不是每个topic发送一条数据。如果mcap文件中有多个topic的数据，每次step，也只会发送其中一个topic的一条信息。
示例
# 按录制信息回放全部 topic
rframe bag play recording_00001.mcap
# 只回放两个 topic
rframe bag play recording_00001.mcap \
-w /camera/image -w /imu/data
# 2 倍速循环回放
rframe bag play recording_00001.mcap -r 2.0 -l
# 从文件首条消息后的 10 秒开始，播放到 60 秒
rframe bag play recording_00001.mcap -b 10 -e 60
# 固定通过 SHM 和 ROS2 发送（默认策略）
rframe bag play recording_00001.mcap --transport shm,ros2 --route-mode static
# 根据订阅者情况，在 SHM 和 Zenoh 之间自动选择
rframe bag play recording_00001.mcap --transport shm,zenoh --route-mode dynamic
典型输出：
Transport plan: requested=shm planned=shm
Playing 1 file(s)
- recording_00001.mcap
Rate: 1x
Keyboard Controls:
SPACE - Pause/Resume
UP/DOWN - Adjust rate (±0.1x, range: 0.1-10x)
RIGHT/→ - Step forward one message
Ctrl+C - Stop and exit
Playback started.
Publishing topic: /camera/image
Playback stopped.
Playback summary:
Duration: 10.012 s
Messages: 300 published
Data: 1.25 MiB
Topics: 1
Topic statistics:
/camera/image: 300 messages, 1.25 MiB, 29.97 Hz
Publishing topic: 表示该 topic 已经成功发出第一条消息。停止、自然播放结束或按 Ctrl+C 退出时都会打印汇总；没有成功发布消息时会显示 No messages were published.。需要进一步排查问题时，可增加 --log-level debug。
2.3 文件信息：rframe bag info
查看一个或多个 MCAP 文件的大小、时间范围、消息数量、topic 类型和录制来源。该命令需要扫描文件，因此大文件可能需要较长时间。
rframe bag info recording_00001.mcap
rframe bag info recording_00001.mcap recording_00002.mcap --json
| 参数 | 说明 |
|---|---|
<file.mcap>... | 至少一个 MCAP 文件；多个文件分别输出，不自动合并为一个时间轴 |
--json | 输出 schema_version=1 的 JSON，适合脚本采集 |
典型输出：
File: recording_00001.mcap
Bag size: 12.34 MiB
Payload size: 11.80 MiB
Storage id: mcap
Duration: 10.000000000 s
Start: 2026-08-21 10:20:30.123456789 (1787288430.123456789)
End: 2026-08-21 10:20:40.123456789 (1787288440.123456789)
Messages: 301
Topics: 2
Indexed: yes
Transports: shm, ros2
Topic information:
Topic: /camera/image | Type: sensor_msgs/msg/Image | Count: 300 | Serialization Format: cdr | Transport: shm
Topic: /tf_static | Type: tf2_msgs/msg/TFMessage | Count: 1 | Serialization Format: cdr | Transport: ros2
文件级 Transports 表示该文件中的数据最初通过哪些通信方式录制；每个 topic 的 Transport 表示该 topic 的录制来源，不代表回放时将使用的方式。旧文件缺少这项信息时显示 -。
日常查看使用默认文本即可；脚本处理或问题排查可增加 --json。如果文件缺少消息类型或编码信息，命令会显示警告，这类 topic 在回放或内容解析时可能需要手动指定类型。同一 topic 在文件中存在不一致的类型或格式时也会告警，建议先确认数据来源再回放。
文件未正常结束、被截断、头尾无效或读取失败时，命令会报错并返回非零状态。请等待录制正常停止后再检查文件；缺少类型等元数据的警告不等于文件损坏。
2.4 JSON 配置
bag record 和 bag play 未指定 --config 时，会使用找到的第一个配置文件：
./robby_recorder_player_config.json./config/replay/robby_recorder_player_config.json/opt/robby/robby-data-tools/config/replay/robby_recorder_player_config.json
--config <path> 用于指定其他配置文件。命令行中显式提供的参数会覆盖配置文件中的对应设置。多输出组、自定义 Zenoh key 等高级功能只能通过 JSON 配置。
recorder.buffer_policy 和 recorder.ingress_policy 支持 block、drop_old、drop_new；未知值回退为 drop_new。player.buffer_policy 的未知值回退为 block。录制启动时可通过 Buffer policy 核对最终生效值。
主要是设置一些CLI入参无法设置的高级参数，一般不需要用户设置。只有CLI的入参无法满足用户需求时，才考虑通过config文件来配置。
安装目录中的文件是随 Deb 提供的默认模板。推荐复制后修改，并通过 --config 显式指定；这样配置不依赖运行命令时所在的目录，也不会在软件升级时被替换。配置文件的用途和复制示例见前文“安装后的路径与配置文件”。
3. 话题查看与收发：rframe topic
先用 list/info 查找话题和类型，再用 echo/stats 验证消息，用 pub 发布消息。list/info 不订阅业务消息，也不要求本机安装该消息定义。
list/info 默认收集 1 秒发现信息；结果偏少时可增加 --resolve-timeout。发现发布者不代表正在发送消息，发布/订阅数量也不等于业务节点数。
3.1 列出话题：rframe topic list
默认显示名称、通信方式和发布/订阅数量，包括只有订阅者的话题。加 --verbose 显示类型和各通信方式数量，不展开端点。
rframe topic list
rframe topic list --filter camera --transport ros2
rframe topic list --type sensor_msgs/msg/Image --verbose
rframe topic list --json
| 参数 | 说明 |
|---|---|
--filter <text> | 按名称、类型、通信方式或 key 做不区分大小写的子串筛选 |
--type <message_type> | 按消息类型精确筛选，例如 std_msgs/msg/String |
| `--role <pub | sub>` |
--verbose | 补充类型和各通信方式数量 |
| `--transport <shm | ros2 |
| `--locality <local | remote |
--resolve-timeout <seconds> | 发现等待时间，默认 1 秒，范围 0～60 秒，支持小数 |
--json | 以 JSON 输出，信息层级与文本一致，schema_version=2 |
--log-level <level> | 诊断日志级别，默认 off |
典型输出：
Topics (2)
Name Transports Publishers Subscribers
------------- ---------- ---------- -----------
/camera/image shm 1 2
/commands shm 0 1
--type、--filter 选择整条话题，--role、--transport、--locality 则限定端点范围。例如 --role sub 的发布者数量为 0。存在多个消息类型时显示 [CONFLICT]，请用 info 检查。
JSON 列表从 .topics[] 读取；需要类型时加 --verbose。空列表正常退出，退出码为 0。
# 需要本机安装 jq
rframe topic list --json | jq -r '.topics[].name'
3.2 查看话题详情：rframe topic info
显示指定话题的类型、发布/订阅总数和各通信方式数量；--verbose 增加逐个端点详情。
rframe topic info /camera/image
rframe topic info camera/image --transport shm --verbose
rframe topic info /camera/image --json
| 参数 | 说明 |
|---|---|
<topic> | 必填，精确话题名；可省略开头的 / |
--verbose | 展开发布者、订阅者的通信方式、类型、PID 等详情 |
| `--transport <shm | ros2 |
| `--locality <local | remote |
--resolve-timeout <seconds> | 发现等待时间，默认 1 秒，范围 0～60 秒，支持小数 |
--json | 以 JSON 输出，信息层级与文本一致，schema_version=2 |
--log-level <level> | 诊断日志级别，默认 off |
info 不接受列表专用的 --filter、--type、--role。类型未知显示 -；PID 未知时文本显示 unknown，JSON 为 0。
JSON 从 .topic 读取，只有加 --verbose 才包含 .topic.endpoints：
rframe topic info /camera/image --json | jq '.topic.backends'
rframe topic info /camera/image --json --verbose | jq '.topic.endpoints'
成功退出码为 0；指定范围内未发现话题或运行失败为 1；参数错误为 2。未发现目标时 stdout 为空，错误写入 stderr。
3.3 查看消息：rframe topic echo
订阅一个 topic 并打印消息内容。默认使用 auto 自动查找可用的 SHM、ROS2 或 Zenoh 发布者，并识别消息类型。
# 自动解析，收到一条后退出
rframe topic echo /chatter --once
# publisher 尚未启动时显式给出类型
rframe topic echo /chatter std_msgs/msg/String --once
# 打印 5 条 JSON 风格消息
rframe topic echo /chatter --type std_msgs/msg/String --limit 5 --json
# 强制使用 SHM 或 Zenoh
rframe topic echo /shm_chatter --transport shm --type std_msgs/msg/String --once
rframe topic echo /zenoh_chatter --transport zenoh --type std_msgs/msg/String --once
| 参数 | 说明 |
|---|---|
<topic> | 必填，要订阅的 topic |
[message_type] | 可选消息类型，等价于 --type |
--type <T> | 覆盖自动解析的消息类型 |
--transport <mode> | auto、ros2、shm、hybrid 或 zenoh，默认 auto；auto 的选择顺序见下文 |
--once | 输出一条消息后退出 |
--limit <N> | 收到并输出 N 条消息后退出；N 为非负整数，0 表示不限制、持续运行 |
--json | 每条消息输出一个独立 JSON value；多条消息构成 JSON stream，stdout 可直接交给 jq 逐条处理 |
--raw | 不解析消息内容，直接以十六进制显示原始字节；用于查看非标准或未知类型的数据 |
| `--zenoh-protocol <auto | native |
--resolve-timeout <seconds> | 启动时等待发布者和消息类型的最长时间，单位为非负整数秒，默认 10；0 表示立即检查、不等待 |
--shm-size <KB> | 覆盖 SHM 接收内存大小，输入非负整数 KB，仅用于诊断或发现信息不足场景 |
--log-level <level> | 终端诊断日志级别，默认 off |
--once 与 --limit 不能同时使用，--raw 与 --json 也不能同时使用。如果消息无法按指定类型解析，有限次模式会报错退出。hybrid 当前表示 SHM + ROS2；ROS2 不可用时会尝试只使用 SHM。
命令启动时默认最多等待 10 秒以发现发布者和消息类型。发布者尚未启动，或自动识别不到类型时，可通过 --type 明确指定。--resolve-timeout 只影响启动等待，不会限制后续接收消息的时长。
典型输出：
Subscribed via ZENOH to [/chatter] (type=std_msgs/msg/String)
Waiting for messages...
[2026-08-21 10:20:30.123] type: std_msgs/msg/String
data: hello
Received 1 messages
3.4 数据流统计：rframe topic stats
订阅一个 topic，持续统计最近 N 条消息的接收频率、间隔、消息大小和吞吐量。消息总数和总数据量只表示本次命令运行期间实际收到的内容。
# 自动解析 topic
rframe topic stats /camera/image
# 使用最近 20 条消息作为统计窗口
rframe topic stats /camera/image --window 20
# 强制指定 transport 和类型
rframe topic stats /camera/image \
--transport zenoh --type sensor_msgs/msg/Image --window 10
| 参数 | 说明 |
|---|---|
<topic> | 必填，要统计的 topic |
--window <N> | 计算周期时使用的最近 N 条消息滑动窗口，N 为非负整数，默认 100；输入 0 或 1 时按 2 处理 |
--type <T> | 覆盖自动解析的消息类型 |
--transport <mode> | auto、ros2、shm、hybrid 或 zenoh，默认 auto；auto 的选择顺序见下文 |
| `--zenoh-protocol <auto | native |
--resolve-timeout <seconds> | 启动时等待发布者和消息类型的最长时间，单位为非负整数秒，默认 10；0 表示立即检查、不等待 |
--shm-size <KB> | 覆盖 SHM 接收内存大小，输入非负整数 KB |
--log-level <level> | 终端诊断日志级别，默认 off |
窗口越小，对瞬时变化越敏感；窗口越大，结果越平滑。窗口表示消息条数，不是秒数。--resolve-timeout 只作用于启动解析阶段，工具开始订阅后会持续统计，直到 Ctrl+C。
典型运行输出：
Subscribed via SHM to [/camera/image] (type=sensor_msgs/msg/Image)
Waiting for messages...
average rate: 29.997 Hz (window: 20 messages)
interval: min 0.033 s, max 0.034 s, std dev 0.000 s
message size: avg 1.76 MB, min 1.76 MB, max 1.76 MB
throughput: 52.73 MB/s
按 Ctrl+C 后输出本次观测汇总：
Final stats:
total messages: 328
total data: 576.56 MB
average rate: 29.998 Hz (window: 20 messages)
interval: min 0.033 s, max 0.034 s, std dev 0.000 s
message size: avg 1.76 MB, min 1.76 MB, max 1.76 MB
throughput: 52.73 MB/s
std dev 是统计窗口内“相邻消息到达间隔”的标准差，单位为秒。数值越小表示接收周期越稳定；它反映的是观测到的时序抖动，不是消息内容的偏差。
3.5 发布消息：rframe topic pub
发布 topic 消息。普通模式根据消息类型把 JSON 或 YAML 正文转换为可发送的消息，无需指定输入格式；发送自定义原始字节时需要显式使用 --raw。
# 类型化 SHM 消息
rframe topic pub /chatter std_msgs/msg/String '{"data":"hello"}' --transport shm --once
# 等价的 YAML 写法
rframe topic pub /chatter std_msgs/msg/String '{data: hello}' --transport shm --once
# 类型化 ROS2 消息
rframe topic pub /cmd_vel geometry_msgs/msg/Twist \
'{"linear":{"x":1.0}}' --transport ros2
# 原始测试数据，同时通过 SHM 和 Zenoh 发送
rframe topic pub /diagnostic/probe --raw --size 1024 --transport shm,zenoh --count 20 --wait-subscriber 0
| 参数 | 说明 |
|---|---|
<topic> | 必填，发布 topic |
<message_type> | 类型化模式必填，例如 std_msgs/msg/String |
[message] | 可选，JSON 或 YAML 正文，默认 {}；整个正文作为一个命令行参数传入 |
-- | 结束选项解析；其后全部作为位置参数，所有选项应放在它前面 |
--transport <mode> | shm、ros2、zenoh、shm,ros2 或 shm,zenoh，默认 shm |
--raw | 发布工具生成的原始测试字节；只支持 SHM 和 Zenoh |
--size <bytes> | 原始消息的字节数，最小 24，默认 64 |
--rate <Hz> | 发送频率，单位 Hz，范围 [0.001, 1000000]，默认 1；最低频率对应 1000 秒周期 |
--count <N> | 发送 N 条后退出；默认 0，表示持续到 Ctrl+C |
--once | 发送一条后退出，等价于 --count 1；不能与 --count 同时指定 |
--wait-subscriber <seconds> | 发布前等待匹配订阅者；--once 和 --count N（N > 0）默认一直等待，显式正数设置超时，设为 0 可立即发送；持续发布默认不等待 |
--type <name> | 消息类型的位置参数替代形式 |
--key-expr <expr> | 原始 Zenoh 消息使用的自定义 key；一般不需要设置 |
--shm-size <KB> | SHM 区域大小，单位整数 KB，默认 1024 |
--log-level <level> | 终端诊断日志级别，默认 off |
可用组合：
| 模式 | 可用 transport | 说明 |
|---|---|---|
| 普通消息 | shm、ros2、zenoh、shm,ros2、shm,zenoh | 按 <message_type> 解析 JSON/YAML，可被相同类型的订阅者读取 |
| 原始消息 | shm、zenoh、shm,zenoh | 发送工具生成的测试字节，只能由支持原始数据的订阅者读取 |
--once 等价于 --count 1，但两者不能同时指定。--size、--key-expr 只对 --raw 有效。JSON/YAML 内容与消息类型定义不匹配时，命令会在发送前报错。
通过 Zenoh 发布普通消息使用 RMW 协议，--raw 使用 Native 协议；pub 不提供 --zenoh-protocol。发布普通 ROS2 消息时，应确保发布端和订阅端使用相同的 ROS_DOMAIN_ID。使用 shm,ros2 时，如果 ROS2 功能不可用，命令会只使用 SHM；如果明确选择 ros2，则会报错。原始消息应使用 topic echo --raw 查看，不能按普通 ROS2 消息解析。
使用 --once 或有限的 --count N 时，命令默认会在发送第一条消息前等待匹配的订阅者。可以用 --wait-subscriber <seconds> 设置最长等待时间，或设为 0 立即发送。该等待只能确认订阅者已被发现，不能保证对方已经处理消息。
典型输出：
Publishing CDR: topic=/chatter transport=shm type=std_msgs/msg/String size=14 bytes rate=1 Hz count=1
Published 1 message(s), 14 payload bytes
JSON/YAML 正文规则（发布与服务调用共用）
topic pub 和 service call 均支持 JSON 对象、YAML 行内映射和多行映射；正文必须是单个对象/映射，省略时使用 {}，未赋值字段保持默认值。重复字段、多个文档、未知字段、字段类型或取值范围不符都会报错。
正文外层的 shell 引号用于把内容合为一个参数；YAML 内部引号用于明确字符串类型。例如 '{data: 1000}' 的值是数字，"{data: '1000'}" 的值是字符串。True/yes/on 可表示布尔值，y/n 保持字符串；1_000 可表示整数 1000。
以下为 Bash 多行示例，$'...' 中的 \n 会转换为换行；支持 --- 文档起始标记：
rframe topic pub --once -- \
/chatter std_msgs/msg/String $'---\ndata: hello'
正文不支持 auto/now 时间填充。YAML 支持仅适用于消息正文；bag record/play --config 仍使用 JSON。
3.6 通信方式选择
echo/stats 默认使用 auto，优先 SHM，其次 ROS2，再尝试 Zenoh。SHM 无法获得消息类型时会继续尝试其他方式；无法自动识别类型时可加 --type。
尚未发现发布者但已指定类型时，auto 默认按 ROS2 等待；等待 SHM 或 Zenoh 发布者时，应显式指定 --transport shm 或 --transport zenoh。同名话题有多种通信方式、需要检查某一条链路时，也应显式指定。
pub 默认使用 SHM，支持的组合见 3.5 节。SHM/Zenoh 可独立使用；明确选择 ROS2 时，环境需提供相应 ROS2 功能。
Zenoh 协议选择（echo / stats 通用）
--zenoh-protocol 选择通信协议，--type 指定消息类型。Native 是 RFrame 的 Zenoh 通信约定，RMW 兼容 ROS 2 rmw_zenoh_cpp；Native 也可以承载 ROS 消息，不能仅凭消息类型判断协议。
| 参数 | 有发布端元数据 | 始终未发现发布端元数据 |
|---|---|---|
auto（默认） | 使用发布端公告的协议、编码和实际 key | 解析等待结束后使用 Native 默认映射 |
native | 选择 Native 发布端 | 使用 Native 默认映射 |
rmw | 选择 RMW 发布端 | 使用 RMW 映射，必须提供具体 --type |
此参数只适用于 topic echo/stats，必须与 --transport zenoh 同用。同名话题有两种协议时只选择匹配的发布端；匹配协议内仍有多种消息类型时，用 --type 指定。等待 --resolve-timeout 后仍只有其他协议或元数据不完整时会报错；已发现过发布端后，不会因其消失而改用无元数据回退。
# Native 发布端：按类型解码为 JSON
rframe topic echo /camera/image --transport zenoh --zenoh-protocol native \
--type sensor_msgs/msg/Image --once --json
# Native 数据流统计
rframe topic stats /camera/image --transport zenoh --zenoh-protocol native --window 10
# RMW 发布端：无发现信息时必须明确提供类型
rframe topic echo /chatter --transport zenoh --zenoh-protocol rmw \
--type std_msgs/msg/String --once --json
旧脚本若依赖“无发布端元数据时由 ROS 类型推断 RMW”，升级后需增加 --zenoh-protocol rmw。--raw 只跳过解码；无元数据时 RMW 的 raw 输出和 stats 仍需具体 --type，Native 的 raw 输出和 stats 可不提供类型。JSON 解码要求载荷为 CDR，且本机已加载对应消息定义。
4. 服务查看与调用：rframe service
先用 list/info 查找服务和完整调用路径，再用 call 调用。查询默认等待 3 秒，结果偏少时可用 --resolve-timeout 5 延长；查询 SHM/Zenoh 方法可能增加等待时间。
4.1 列出服务：rframe service list
rframe service list
rframe service list --type example_interfaces/srv/AddTwoInts
rframe service list --transport ros2 --filter robotic
rframe service list --json
| 参数 | 说明 |
|---|---|
--type <service_type> | 按规范化后的 service 类型精确过滤 |
--filter <text> | 对 service 名、类型和已知/补全的方法路径做不区分大小写的子串过滤 |
| `--transport <ros2 | shm |
--resolve-timeout <seconds> | 输出前收集 discovery 的时间，范围 0～60 秒，默认 3 |
--verbose | 补充服务/方法类型和各通信方式数量，不展开端点；显示查询告警 |
--no-resolve-methods | 跳过主动 RPC 方法查询；仍保留 discovery 已知的方法 |
--json | 输出 schema_version=2 的 JSON，信息层级与文本一致 |
--log-level <level> | 终端诊断日志级别，默认 off |
默认列表显示服务名、通信方式、Servers/Clients 数量和已知方法树，不显示类型。使用 --verbose 时，在同一张表中补充完整服务/方法类型和各 transport 数量，不展开原始端点；端点详情请使用 service info --verbose。
典型输出（数量随现场变化）：
Services (2)
Name Transports Servers Clients
------------------- ---------- ------- -------
/ shm 1 1
└─ /test/echo_text
/demo shm,zenoh 2 0
└─ /demo/echo
同名服务在多种通信方式下合并显示。Servers/Clients 是当前范围内各通信方式数量之和，不代表业务实例数；方法子行不重复显示数量。调用时使用完整方法路径，普通 ROS2 服务名本身就是调用路径。
默认查询 SHM/Zenoh 方法；--filter 也可按方法路径筛选所属服务。不需要方法补全时使用 --no-resolve-methods。服务不支持方法查询或查询失败时，列表可能没有方法或类型；加 --verbose 查看告警。同一方法出现多个类型时显示 [CONFLICT]，不同方法类型不同不算冲突。
JSON 从 .services[] 读取，默认不包含类型；--verbose 增加类型及各通信方式的数量，均不展开端点。
rframe service list --filter /demo/echo
rframe service list --json | jq -r '.services[].name'
4.2 查看服务详情：rframe service info
rframe service info /test/add
rframe service info /test/add --transport ros2 --verbose
rframe service info /test/add --json
| 参数 | 说明 |
|---|---|
<service_name> | 必填，逻辑 service 名或已知方法的完整调用路径；输入不带 / 时会规范化为绝对路径 |
| `--transport <ros2 | shm |
--resolve-timeout <seconds> | 输出前收集 discovery 的时间，可输入小数，范围 0～60 秒，默认 3；0 表示立即读取当前缓存 |
--verbose | 文本增加原始端点明细；JSON 增加 raw_endpoints；方法查询失败时向 stderr 告警 |
--no-resolve-methods | 跳过主动 RPC 方法查询；仍保留 discovery 已知的方法 |
--json | 输出 schema_version=2 的 JSON，信息层级与文本一致 |
--log-level <level> | 终端诊断日志级别，默认 off |
service info 不接受只用于列表筛选的 --type 和 --filter；service 名本身就是精确选择条件。
默认显示 service 名、类型、可用性，以及各通信方式下的服务端和客户端数量；查询容器且方法已知时显示 Methods；查询具体方法时只展示目标，不列出兄弟方法。需要排查发现或类型冲突问题时，再增加 --verbose 查看详细连接信息。
Service: /test/add
Type(s): example_interfaces/srv/AddTwoInts
Available: yes
Transport Type(s) Servers Clients
--------- ---------------------------------- ------- -------
ros2 example_interfaces/srv/AddTwoInts 1 0
Available: yes 表示已发现服务端，不保证业务请求一定成功。未显示方法或类型时，可增加发现等待时间，或加 --verbose 查看告警。
查询容器（如 /demo）显示已知方法列表；查询完整方法路径（如 /demo/echo）只显示该方法。输出 Count scope: service container 时，数量属于整个服务容器，不是该方法的独立实例数。
JSON 返回 {"schema_version":2,"service":{...}}。从 .service 读取服务，只有 --verbose 才包含 .service.raw_endpoints；旧版脚本需调整取值路径。
rframe service info /demo/echo --verbose
rframe service info /test/add --json | jq -r '.service.name'
rframe service info /test/add --json --verbose | jq '.service.raw_endpoints'
4.3 调用服务：rframe service call
service 类型通常可以自动识别：
rframe service call /add_two_ints '{"a": 5, "b": 7}'
无字段请求可以省略正文，默认使用 {}：
rframe service call /trigger example_interfaces/srv/Trigger
发现信息不完整、存在类型冲突或需要强制覆盖时，仍可显式指定类型：
rframe service call \
/add_two_ints \
example_interfaces/srv/AddTwoInts \
'{"a": 5, "b": 7}' \
--transport ros2 \
--timeout 5000
| 参数 | 说明 |
|---|---|
<service_name> | 必填，service 绝对路径 |
[service_type] | 可选，ROS2 service 类型；省略时自动识别 |
[request] | 可选，JSON 或 YAML 请求正文，默认 {}；整个正文作为一个命令行参数传入 |
-- | 结束选项解析；其后全部作为位置参数，所有选项应放在它前面 |
--transport <mode> | auto、ros2、shm、hybrid 或 zenoh，默认 auto |
--resolve-timeout <seconds> | 启动时等待发现 service 和类型的时间，范围 0～60 秒，默认 1 |
--shm-service-prefix <prefix> | 指定真实 SHM 容器前缀，仅限 --transport shm；省略时自动解析，字面 / 与空字符串是同一根容器；方法参数传完整调用路径 |
--timeout <ms> | 单次查询或业务响应超时，正整数毫秒，默认 3000；不是命令总耗时上限 |
--json | stdout 只输出 JSON response，便于脚本处理；诊断和错误仍写入 stderr |
--log-level <level> | 终端诊断日志级别，默认 off |
auto 自动选择可用的调用方式；ros2、shm 和 zenoh 固定使用指定方式；hybrid 在 ROS2 和 SHM 之间选择可用路径，同一次调用不会执行两遍。使用 Zenoh 调用时，通常需要显式提供 [service_type]。
SHM 调用默认自动查找服务容器。通常只需提供完整调用路径和类型；多个容器匹配同一路径时会报歧义，需用 --transport shm --shm-service-prefix <prefix> 明确选择。
例如，服务容器 /robot 注册了 echo，其类型为 example_interfaces/srv/SetBool：
# 自动解析 SHM 容器前缀
rframe service call /robot/echo example_interfaces/srv/SetBool \
'{"data":true}' --transport shm
# 多个容器匹配同一路径时，明确指定容器（仍会验证方法）
rframe service call /robot/echo example_interfaces/srv/SetBool \
'{"data":true}' --transport shm --shm-service-prefix /robot
--shm-service-prefix 仅用于 --transport shm，方法参数仍传完整调用路径。空字符串 '' 和 / 表示同一根容器，/robot 与 /robot/ 也表示同一容器。显式前缀只限定查询范围，仍须验证方法已公布，不能绕过方法解析。自动识别不到 service 类型时，仍需显式提供 [service_type]。
--resolve-timeout 控制启动发现等待，--timeout 控制单次查询或业务响应等待，两者都不是整个命令的总耗时上限。SHM 目标无法确定时会报错；auto 可尝试 ROS2。业务请求超时后不会改用其他容器重发。
显式请求接受 JSON 或 YAML，无需指定输入格式；正文语法错误在启动发现前返回。例如 '{"data": true}' 和 '{data: True}' 都可用于布尔字段。省略请求等价于传入 {}。自动发现不到类型或发现多个冲突类型时，命令会要求显式提供 [service_type]，不会随机选择。
正文规则见 3.5 节。--json 只控制响应输出格式，无需为 YAML 请求设置该选项。
# YAML 行内映射
rframe service call /add_two_ints example_interfaces/srv/AddTwoInts '{a: 5, b: 7}'
# 多行 YAML；选项放在 -- 前
rframe service call --transport ros2 --timeout 5000 -- \
/add_two_ints example_interfaces/srv/AddTwoInts $'---\na: 5\nb: 7'
典型输出：
Request: {"a": 5, "b": 7}
Transport selection: auto
Response:
{
"sum": 12
}
Transport selection 显示本次选择的策略；选择 auto 时，实际通信方式由运行环境决定。使用 --json 时，stdout 不带 Response: 前缀：
{
"sum": 12
}
4.4 运行环境
- 查看 service 列表和详情不要求启用 ROS2；SHM、Zenoh 服务仍可正常显示。
- 调用 SHM 服务不要求启用 ROS2，但系统必须能找到对应的 service 消息定义。如果提示类型构造失败，请先加载提供该类型的 ROS2、r-types 或用户工作空间环境。
- 自动识别不到 service 类型时，请在命令中显式提供
[service_type]。 - 明确选择
--transport ros2时，需要安装并启用相应的 ROS2 扩展；否则命令会报错。组合模式在 ROS2 不可用时可能只使用 SHM。
5. 资源发现：rframe discovery
monitor 用于实时浏览，snapshot 用于一次性查询和导出。两者显示 Topic/Service，不提供 ROS2 node 列表。
5.1 实时查看：rframe discovery monitor
以终端交互界面实时显示当前发现的 topic 和 service，包括 SHM、ROS2 和 Zenoh。
# 使用默认 500 ms 刷新间隔
rframe discovery monitor
# 每 200 ms 刷新
rframe discovery monitor --refresh 200
| 参数 | 说明 |
|---|---|
--refresh <ms> | 页面刷新周期，单位为正整数毫秒，默认 500；例如 200 表示每 0.2 秒刷新一次，必须大于 0 |
--log-level <level> | 设置诊断日志详细度；TUI 独占终端，运行日志不直接写控制台，文件默认至少保留到 info |
交互按键
| 按键 | 功能 |
|---|---|
↑ / ↓ | 移动选择 |
Enter | 查看 topic/service 详情；过滤编辑时提交过滤条件 |
/ | 进入过滤编辑；编辑时可作为普通 / 字符输入 |
Backspace | 删除过滤字符 |
Esc | 取消编辑、清除已提交过滤，或从详情返回列表 |
Ctrl+C | 退出 |
过滤不区分大小写，可匹配名称中的任意一段字符。资源列表按 topic/service 名过滤；详情页还可以按通信方式、角色、PID、key 和类型过滤。详情页按 Esc 返回列表，再按一次 Esc 清除过滤条件。
如果看不到 Zenoh 发布者，请确认发布端已启用发现功能，并检查两端网络是否允许 Zenoh 发现通信。
主页面典型显示：
=== RFrame Discovery Monitor ===
Topics: 2/2 | Services: 1/1
Name Kind Publishers Subscribers Servers Clients
> /camera/image Topic 1 2 - -
/localization/pose Topic 1 1 - -
/robot/control Service - - 1 1
Keys: Up/Down=Navigate | /=Filter | Enter=Select | Ctrl+C=Exit
进入 /camera/image 详情后，可以查看每个发布者或订阅者的通信方式、角色、PID、endpoint ID 和消息类型。选中 Zenoh endpoint 时，页面底部还会显示实际 key_expr、wire protocol 与 payload encoding；元数据缺失时显示 unavailable。终端宽度不足时，较长字段可能被截断。
5.2 一次性查看：rframe discovery snapshot
一次性输出当前发现的 topic 和 service，适合跨资源排查、脚本采集或附加到问题单。日常话题查询也可直接使用 topic list/info，两种入口均保留。默认分别显示 Topic 和 Service；需要连接详情时使用 --verbose，需要机器可读结果时使用 --json。
rframe discovery snapshot
rframe discovery snapshot /camera/image --verbose
rframe discovery snapshot --role rpc-server
rframe discovery snapshot --transport zenoh --locality remote --json
| 参数 | 说明 |
|---|---|
[resource] | 可选，精确 topic 或 service；开头 / 不影响匹配 |
--filter <text> | 对资源名、类型、通信方式、key 和已知/补全的方法路径做不区分大小写的子串过滤；命中方法时保留所属服务及完整方法树 |
--role <role> | pub/sub 只匹配逻辑 topic 的发布者/订阅者；rpc-server/rpc-client 只匹配聚合后的逻辑 service 角色 |
--transport <transport> | shm、ros2 或 zenoh |
--locality <value> | 按资源位置过滤：local 为本机进程，remote 为其他主机，unknown 为位置未知 |
--resolve-timeout <seconds> | 输出前收集 discovery 的时间，单位秒，可输入小数，范围 0～60，默认 3 |
--verbose | 文本增加完整服务/方法类型及端点详情；pid=0 表示进程号未知 |
--no-resolve-methods | 跳过主动 SHM/Zenoh 方法查询，仍保留被动发现已知的方法 |
--resolve-methods | 恢复主动方法查询，默认已开启 |
--json | 输出 schema_version=1 的完整 JSON，适合脚本处理；运行日志不混入结果 |
--log-level <level> | 终端诊断日志级别，默认 off |
服务下方会展开已知方法，方法不单独计为服务；默认隐藏服务类型，--verbose 显示完整类型和端点。--filter 可匹配方法路径，命中时保留所属服务及方法树；按方法路径查询单个详情请使用 service info。
默认补全 SHM/Zenoh 方法，可能使总耗时超过 --resolve-timeout。只需被动发现结果时，加 --no-resolve-methods。没有方法列表只表示本次未获得方法，不代表服务没有方法。
--json 输出 schema_version=1 的完整快照，默认包含类型、端点和已知方法，不受 --verbose 限制；Topic/Service 的 list/info --json 则按详情层级输出，版本为 2。
默认输出：
Topics (1)
Name Type(s) Transports Publishers Subscribers
------------- --------------------- ---------- ---------- -----------
/camera/image sensor_msgs/msg/Image ros2,shm 2 1
Services (1)
Name Transports Servers Clients
-------------- ---------- ------- -------
/robot/control shm 1 1
Summary: 1 topic(s), 1 service(s), 4 endpoint(s)
多个筛选条件需同时满足。暂未发现资源时可延长 --resolve-timeout；方法查询失败时用 --verbose 查看告警。PID 为 0 表示未知，不影响通信。
快照只反映本次发现结果，不包含历史消息数、丢包数或历史断流统计。Snapshot/Monitor 的服务汇总数量与 service list 口径不同，应按通信方式查看明细，不要直接比较总数。
6. 常见问题
topic 存在，但 echo 或 stats 启动失败
先通过 rframe discovery monitor 确认发布者和通信方式。如果无法自动识别消息类型，补充 --type <package/msg/Type>；同名 topic 存在多种通信方式时，补充 --transport。
如果 topic echo 提示 schema is unavailable for [<package/msg/Type>]，表示 topic 和类型已经发现，但当前终端找不到该消息定义；请 source 提供该类型的 ROS2、r-types 或用户工作空间后重试。
Zenoh 发布端应区分 Native 与 RMW，按 3.6 节指定 --zenoh-protocol；具体 ROS 消息类型不意味着 RMW。遇到协议冲突可用 rframe topic info <topic> --transport zenoh --verbose 检查发布端信息。若提示载荷为 raw、不是 CDR，可用 --raw 检查字节；指定协议不会改变发布端公告的载荷编码。
Recorder 没有录到某个 topic
检查黑名单、系统 topic 排除和正则范围。Zenoh topic 还需确认 discovery monitor 中能看到发布者；如果使用了 --disable-zenoh-discovery，请移除该参数。
动态回放没有走预期的通信方式
动态模式依赖订阅者发现状态。先用 rframe discovery monitor 确认对应订阅者可见；如需固定通过两种方式发送，改用 --route-mode static。
jsoncpp 缺失或版本不兼容
如果提示 libjsoncpp.so.*: cannot open shared object file，请检查兼容库是否已安装并位于动态库搜索路径中；出现涉及 Json:: 的未定义符号时，检查库版本和 ABI。当前包未声明 jsoncpp 依赖，apt install -f 不会据此自动补齐；自定义库目录需配置 LD_LIBRARY_PATH 或系统动态链接器。
如何查看某个命令的权威参数列表
rframe help <group> <command>
# 例如
rframe help bag record
rframe help discovery monitor