SmartBench/cmvr-es

Fork 0

xtkuang 4f36cf4957 feat(quic): support multi-platform heartbeats

2026-08-14 12:40:53 +08:00

8.6 KiB

Raw Blame History

Config 模块开发指南

config/ 保存 CMVR-ES 的默认运行配置。配置格式是 Protobuf TextFormat，Schema 位于 ../../protos/cmvr/config/。

返回项目总览。

配置树

cmvr_es.pb.txt
├── logger/logger.pb.txt
├── manager/device_manager.pb.txt
│   └── devices/<category>/*.pb.txt
└── manager/task_manager.pb.txt
    └── tasks/<task>/*.pb.txt

入口文件：

路径规则

无参数运行时，程序读取：

<cmvr_es 可执行文件所在目录>/config/cmvr_es.pb.txt

安装后的 output/bin/cmvr_es 因此会读取 output/bin/config/cmvr_es.pb.txt；直接运行 build/cmvr_es 则会查找 build/config/cmvr_es.pb.txt，不会自动跳到安装目录。传入显式根配置时使用 --config：

./output/bin/cmvr_es --config /etc/cmvr-es/cmvr_es.pb.txt

设备、任务和证书等相对配置路径均以根配置文件所在目录解析。模型等资源通过 ConfigHelper::resolveResourceFile() 在配置根及父目录中查找；生产部署仍建议使用明确绝对路径。

日志配置中的相对 directory 以可执行文件目录解析，不以配置根解析。

新增设备配置

增加同类设备后端时：

在 protos/cmvr/config/<category>_config/ 增加后端 message；
在类别设备 message 的 oneof backend 中增加字段；
在 devices/<category>/ 的 .pb.txt 中增加实例；
实例外层 id 必须唯一；
在 manager/device_manager.pb.txt 增加相同 id、正确 type 和配置路径；
开发默认保持 enable: false；
同步类别 factory 和 CMake；
在无硬件环境验证关闭状态，在真机环境单独开启。

设备集合中的 ID 与 DeviceManager 条目 ID 不一致时，工厂会拒绝创建。

新增任务配置

在 protos/cmvr/config/ 增加任务配置和 root message；
在 tasks/<task_name>/ 增加默认 .pb.txt；
在 task_manager.pb.txt 增加唯一任务 ID；
配置正确的 TaskType 和 TaskRunMode；
周期任务设置大于零的 control_period_s；
服务任务使用 TASK_RUN_MODE_BLOCKING_SERVICE；
默认关闭依赖网络、证书或硬件的新任务。

任务实现流程见 ../task/README.md。

默认值与校验

不依赖 proto3 数值零值表达危险的生产默认值；
timeout、队列大小、帧大小和周期应在代码中校验；
新增 loader 对不认识的 enum 和未设置的 oneof 必须明确失败；当前个别历史路径仍有退化默认行为，不应复制；
设备端口、坐标系、速度和单位写入注释；
enable 应由 manager 层控制，后端内部的 enable 字段不能替代 manager 开关；
QUIC 任务需要在 TaskManager 中显式开启；
QUIC 零媒体轨道是合法配置。

QUIC 多平台

QuicEdgeTask 可以同时连接多个平台。原有顶层 server_host、server_port、tls 继续表示主平台；每个 platforms 条目会与主平台并行运行。也可以不配置顶层目标，只使用一个或多个 platforms 条目：

platforms {
  id: "operations"
  server_host: "192.168.0.222"
  server_port: 4433
  enable_media: false
  tls {
    ca_file: "certs/cmvr-quic-ca.crt"
    server_name: "192.168.0.222"
  }
}
platforms {
  id: "analytics"
  server_host: "192.168.0.223"
  server_port: 4433
  enable_media: true
  tls {
    ca_file: "certs/cmvr-quic-ca.crt"
    server_name: "192.168.0.223"
  }
}

平台 ID 和 host:port 必须分别唯一；配置兼容主平台时，其平台 ID 使用任务 QuicEdgeConfig.id，新增条目也不能与它重名。每个平台拥有独立的 QUIC 连接、注册会话、心跳序号、ACK 超时和重连退避，一个平台断线不会阻塞其他平台。 enable_media 默认为 false，此时仍发送注册、心跳、网络接口和设备状态，但不会复制音视频；设为 true 才会把全局 tracks 转发到该平台。兼容的顶层主平台保持原有媒体行为。

gRPC 相机实时流

tasks/grpc_server_task/grpc_server_task.pb.txt 中的两个低延迟参数仅作用于 gRPC RGB 编码流，不改变机械臂、AGV 等控制 RPC：

camera_stream_max_pending_frames：单个客户端允许的待发送帧数，超过后清空该客户端积压；默认 2；
camera_stream_max_frame_age_ms：从设备回调进入边缘系统起计算的最大帧龄，超过后不再发送；默认 250 ms。

两个字段填 0 或旧配置未包含字段时使用默认值。丢弃 H.264/H.265 帧后服务会请求 IDR 并等待关键帧恢复。如果现场采集、编码本身稳定超过 250 ms，应根据日志中的 age_ms 调高帧龄阈值，而不是增大环形队列。

新二进制可以读取未包含这两个字段的旧配置；旧二进制不能解析包含新字段的 TextFormat。部署时必须同步更新程序与配置，不能只把新版 grpc_server_task.pb.txt 复制给旧的 output/bin/cmvr_es。

配置验证

构建后可以用 protoc --encode 对单个 TextFormat 文件做语法和字段验证。例如：

output/bin/protoc \
  -I protos \
  --encode=cmvr.config.QuicEdgeRootConfig \
  protos/cmvr/config/quic_edge_config/quic_edge_config.proto \
  < cmvr-es/config/tasks/quic_edge_task/quic_edge_task.pb.txt \
  > /tmp/quic_edge_config.pb

该命令只验证 Proto Text 解析，不验证文件、设备、证书、网络和跨字段语义。最终仍需运行组件测试和进程烟雾测试。

双边遥操配置

源码仓库保持唯一根入口 cmvr_es.pb.txt。统一的 manager/device_manager.pb.txt 已声明 ume_left、ume_right、ti5_motors 和 right_arm；统一的 manager/task_manager.pb.txt 已声明 ume_teleop 和 gRPC server。角色差异不通过增加新的源码根配置文件表达，而由两台机器各自的外部部署配置决定。

UME 主端部署配置应只启用本机需要的 UME 设备和 ume_teleop Task：

ume_left、ume_right 在 DeviceManager 层默认关闭；
devices/arm/ume_arms.pb.txt 内部的 hardware_enabled 也默认关闭；
两层硬件门必须在完成 CAN 映射、限位标定和安全验收后分别启用；
当前 Task 只实现会话、重连、心跳和 latest-only 指令邮箱，尚无生产算法调用 submitSetpoint()，返回 effort 也尚未接入本地触觉协调器。

机器人从端部署配置应只启用经过验收的机械臂设备以及所需的 gRPC server：

ti5_motors、right_arm 默认关闭；
ArmTeleop 服务后端默认关闭，模型哈希必须由部署配置明确给出；
当前 MotorRobotArm::servoJ() 仍是逐关节顺序写，不满足遥操作组伺服能力门；
启动 gRPC server 不代表允许遥操作执行，也不能绕过设备层硬件门。

部署时应把完整配置树分别复制到两台机器的外部目录，并继续使用相同的标准文件名：

/etc/cmvr-es/ume/cmvr_es.pb.txt
/etc/cmvr-es/robot/cmvr_es.pb.txt

两套根配置都继续引用各自目录下同名的 manager/device_manager.pb.txt 和 manager/task_manager.pb.txt。运行命令为：

./output/bin/cmvr_es --config /etc/cmvr-es/ume/cmvr_es.pb.txt
./output/bin/cmvr_es --config /etc/cmvr-es/robot/cmvr_es.pb.txt

UME 主端需要填写从端地址、会话 manifest 和认证配置；机器人从端需要填写现场机械臂配置。不要把生产 IP、token、私钥或设备标定值提交到仓库默认配置。

生产配置

cmake --install 会重建 output/bin/config/。生产配置应复制到 /etc/cmvr-es/ 等外部目录并显式传入。

不提交真实设备密码、token、私钥和生产地址；
证书与私钥放在独立 certs/，使用最小读取权限；
为不同站点维护独立配置根，不在运行时修改仓库样例；
发布前检查所有 enable、IP、端口和设备 ID；
变更配置 Schema 时同步 Proto 兼容性文档和平台生成代码。

提交检查

TextFormat 可以被对应 root message 解析
ID、类别和引用路径完全一致
新硬件和新网络任务默认关闭
参数单位、范围和安全默认值明确
没有生产凭据
安装覆盖不会丢失现场配置
无设备启动仍然成功

8.6 KiB Raw Blame History Unescape Escape