librealsense RealDDS 设备控制协议详解从 Control 消息到 DFU 固件升级【免费下载链接】librealsenseRealSense SDK项目地址: https://gitcode.com/GitHub_Trending/li/librealsense导读本文围绕 librealsense 仓库中 RealDDS 协议的 control.md 文档系统讲解客户端如何通过 DDS 主题向设备服务器server下发控制命令Control包括选项读写query-option/set-option/query-options、硬件复位hw-reset、内部硬件命令hwm以及完整 DFU 固件升级流程dfu-start/dfu-ready/dfu-apply。读者读完本文后将掌握 RealDDS 控制消息的完整 JSON 格式、回复Reply标识与错误处理约定、hexarray编码规则并能结合 dds-device-impl.cpp 的源码理解客户端如何解析与回写选项值。什么是 Control客户端到服务器的命令通道在 RealDDS 架构中服务器server即设备端与客户端client通过 DDS 主题通信。Control 是从客户端发往服务器的命令例如开始推流设置某个选项值。这与 notifications.md 中描述的、由服务器单向广播给客户端的通知消息方向相反。控制消息的载体是 flexible 消息其底层 IDL 结构为struct flexible { flexible_data_format data_format; octet version[4]; sequence octet, 4096 data; };即控制消息以 JSON当前唯一实际使用的格式文本封装在 4K 字节上限的data序列中通过topic-root下的控制主题传输。QoS 为RELIABLE可靠与VOLATILE易失保证命令不丢失但不做历史留存。回复Replies机制如何识别这条回复属于哪条命令控制消息发出后服务器必须将处理结果重新广播出去使其他客户端也能感知状态变化。这个广播走的就是 notifications 主题topic-root/notification。为了让客户端能把一条回复与它发出的具体控制对应起来协议约定了如下标识规则回复携带与原始控制相同的id。这意味着控制消息与通知消息必须使用彼此独立的标识符命名空间避免歧义。id也可以从回复中附带的control字段见下文中取回配合sample使用。服务器收到控制消息时DDS 样本会附带一个publication handle它是 writer含 participant的GUID用于标识控制来源每个控制样本还有来自sample-identity的唯一序列号。缺少这两者客户端将无法判断控制请求的来源也就无法决定自己是否正在等待该回复。因此回复必须包含sample字段内容是发起控制请求的 participant 的 GUID 加序列号形如sample: [010f6ad8708c95e000000000.303,4]此外回复必须携带成功/失败状态只要状态不是OK回复就必须包含status字段状态不是OK时还必须包含explanation字段人类可读的失败原因字符串类似异常对象的what()。协议还建议回复携带原始控制请求本身回复中的control字段应包含原始控制请求各控制类型可保留一定自由度。恢复模式Recovery Mode下回复也必须照常工作根据 discovery.md恢复模式设备在device-info中以recovery: true标识此时控制与通知主题依然存在于 topic-root 之下但只接受更新类控制与回复且不提供任何推流能力。错误回复Errors错误就是status不是OK的回复。explanation用于说明失败原因下面是一个完整的错误回复示例{ control: { id: query-option, option-name: opt16 }, sample: [010f9a5f64d95fd300000000.403, 1], status: error, explanation: Test Device does not support option opt16 }多条控制能否合并不能。与 notifications.md 中通知可打包成数组不同控制消息不支持多条合并每条控制必须独立发送、独立回复。选项读写query-option与set-optionquery-option读取设备中单个选项的valueset-option设置该值。字段约定id取query-option或set-optionoption-name是选项名称字符串stream-name是该选项所属的流名称对设备级选项应省略该字段对流级选项必须提供否则服务端无法定位选项。对set-option还需提供value字段作为要设置的值注意回复中返回的value可能与请求值不同服务器可能做钳位、量化或上下文修正。读取单个选项的示例{ id: query-option, option-name: IP address }回复应包含原始控制外加一个value{ sample: [010f9a5f64d95fd300000000.403, 1], value: 1.2.3.4, control: { id: query-option, option-name: IP address } }set-option行为完全一致只是把value放进控制请求中{ sample: [010f9a5f64d95fd300000000.403, 1], value: 10.0, control: { id: set-option, stream-name: Color, option-name: Exposure, value: 10.5 } }新值应落在 initialization.md 中设备初始化时通告的该选项取值范围内例如数值选项的minimum/maximum/stepping约束。选项值是否合法由设备服务器最终裁决若set-option指定了不受支持或上下文无效的值服务器应返回错误。客户端源码视角回复如何被消费在仓库的客户端实现 dds-device-impl.cpp 中on_set_option统一处理set-option与query-option两类回复——因为两者都会返回一个值。处理要点与文档约定一一对应先调用dds_device::check_reply检查回复状态出错时直接忽略客户端不关心错误回复强制要求回复中携带control对象否则抛出runtime_error(missing control object)——正是文档所说回复必须包含原始控制否则无法知道这是哪个选项从control中取stream-name为空则视为设备选项_options非空则在_streams中定位对应流找不到抛出stream stream_name not found从回复取value在目标选项中按option-name匹配后调用option-set_value(value_j)更新本地副本匹配失败抛出option option_name not found。可见客户端并不把回复中的值当既成事实直接使用而是据此同步更新本地选项缓存这正是回复值可能与请求值不同的落点。批量查询query-optionsquery-options与query-option类似但一次返回全部选项值可按流、按传感器或按设备维度查询查询流级选项提供stream-name查询设备级选项提供stream-name: 空字符串查询传感器级选项提供sensor-name不带任何维度字段全局返回所有流及设备的所有选项。示例{ id: query-options, stream-name: Color }回复返回一个名为option-values的流名→选项名→值映射{ sample: [010f9a5f64d95fd300000000.403, 1], option-values: { IP address: 1.2.3.4, Color: { Exposure: 10.0, Gain: 5 }, Depth: { Exposure: 15.0 } }, control: { id: query-options } }设备选项直接平铺在option-values中如上面的IP address流选项则嵌套在该流名称的子层级中如Color/Depth。客户端源码 dds-device-impl.cpp 的on_query_options表明该消息既可以作为某条控制的回复也可以由设备独立作为通知发出两者采用同样的形态与处理逻辑。周期性更新periodic updates由服务器主动变更未经控制消息的选项值应通过query-options通知广播出去且不带control和sample字段{ id: query-options, option-values: { Color: { Exposure: 8.0, }, Depth: { Exposure: 20.0 } } }协议建议服务器至少周期性推送此类更新具体周期可能由配置项决定以免所有客户端反复轮询设备。这与回复必须广播以通知其他客户端的整体设计一致状态变化要让订阅方都能感知。硬件复位hw-resethw-reset让服务器执行一次硬件复位若支持使设备回到与上电后一致的状态{ id: hw-reset }若附加布尔字段recovery为true则设备将复位到恢复模式若设备不支持该能力则报错{ id: hw-reset, recovery: true }该命令会得到一条回复若回复为成功通常还会伴随一个 disconnection断连事件服务器主动下线时会在device-info上发送{topic-root: ..., stopping: true}客户端据此立刻移除设备而不必等待 DDS 的默认断连超时当前为 10 秒。内部硬件命令hwmhwm用于向硬件发送内部命令。使用不当可能变砖设备该命令可能实现、也可能未实现且未做文档化。服务器负责校验并确保一切符合预期。data字段是必需的。{ id: hwm, data: 1400abcd1000000000000000000000000000000000000000 }上面这条是GVDGet Version DataHWM 命令。回复可以预期强烈建议在回复中附带原始控制以便明确执行了什么操作。回复中的data字段应存在即命令结果{ sample: [010f9a5f64d95fd300000000.403, 1], control: { id: hwm, data: 1400abcd1000000000000000000000000000000000000000 }, data: 10000000011004000e01ffffff01010102000f05000000000000000064006b0000001530ffffffffffffffffffffffffffffffff0365220706600000ffff3935343031300094230500730000ffffffffffffffff0aff3939394146509281a1ffffffffffffffffff9281a1ffffffffffffffffffffffffffffffffffffffffff1f0fffffffffffffffff000027405845ffffffffffffffff908907ffffff01ffffff050aff00260000000200000001000000010000000100000001000000000600010001000100030303020200000000000100070001ffffffffffffffffffffffffffffffffffff014a34323038362d31303001550400ae810100c50004006441050011d00000388401002e0000002dc00000ff }更详细的构建方式verbose method如果调用方了解所需的操作码opcode与数据也可以让服务器代为构建HWM 命令opcode字符串必填param1、param2、param3、param4均为 32 位整数其含义取决于opcode默认值为0可选字段data指向命令数据如需要并将成为生成的 HWM 命令的一部分。若存在可选字段build-command且值为true则回复的data只包含生成的 HWM 命令本身而不实际执行它——适合先在客户端侧预览/验证命令内容。hexarray类型编码规则HWM 的data使用一种名为hexarray的特殊 JSON 编码来表示字节数组。它不像常规数组那样写成[0,100,2,255]而是编码为十六进制字符串006402ff即从下标 0 起所有连续字节的十六进制表示。规则如下只使用小写字母字符集[0-9a-f]长度必须为偶数每个字节占 2 个十六进制位第一对十六进制位对应第一个字节第二对对应第二个字节依此类推。DFU 固件升级流程DFUDevice Firmware Update设备固件升级是更新设备固件的机制。设备既可以在恢复模式下运行该流程也可以在正常运行期间执行。整体时序如下dfu-start启动 DFU 流程客户端随后在dfu主题上发布固件二进制镜像镜像校验通过后设备发回dfu-ready通知客户端在合适时机发送dfu-apply应用固件。DFU 传输固件镜像用的是 blob 消息其 IDL 为struct blob { sequenceoctet data; };可以承载任意大小、任意格式的数据适合大数据传输能放进 4K 限制内的数据则应优先用 flexible。DFU 场景下dfu主题采用可靠RELIABLEQoS。dfu-start启动升级dfu-start启动 DFU 流程设备会订阅 topic-root 下的dfu主题接受 blob 消息可靠传输{ id: dfu-start, size: 2097152, crc: 65358876 }size固件镜像字节数用于确保设备分配足够内存、做好接收准备crc校验值用于确认镜像完整无损。设备会回复一条消息表示镜像已可以接收。dfu-ready镜像接收与校验设备会等待一段时间接收镜像超时则可能以错误退出。约束如下只能接收一个镜像且必须来自发起 DFU 的同一个 participant镜像收到后会做兼容性检查若不兼容、不完整或缺失等会向客户端返回错误{ id: dfu-ready, status: error, explanation: incompatible FW version (5.17.0.1) }若status不是OK设备应回到 DFU 之前的状态整个流程需要重新开始此时可移除dfu订阅接收阶段结束。dfu-apply应用固件当上述步骤全部成功且客户端就绪后发送dfu-apply使固件生效{ id: dfu-apply }若任何原因需要取消本次 DFU可发送同样的消息并携带cancel: true。无论成功、失败还是取消设备都必须立即回复且回复发生在 DFU 真正生效之前。随后设备花时间让镜像生效期间推荐持续发送与回复同形态的进度通知{ id: dfu-apply, progress: 0.2 }过程中随时可能出错出错时设备预期会自行复位流程需要从头再来。镜像成功应用后设备会执行一次硬件复位并正常重启。任何重启之前设备都会在device-info上发送断连事件客户端以该断连作为 DFU 结束的信号参见 discovery.md。控制协议与相邻文档的关系控制通道不是孤立的它与 RealDDS 其他协议文档构成完整闭环相邻能力关联文档与控制的关系设备发现与断连discovery.md提供topic-root控制主题挂载其下hw-reset/DFU 成功会触发断连事件初始化initialization.md通告选项名、取值范围、默认值与只读属性是set-option合法性判定的依据通知广播notifications.md所有控制的回复均经由 notification 主题重新广播设备模型device.md说明设备级选项等上下文细节全套文档的入口与目录见 third-party/realdds/doc/readme.md控制消息相关的客户端解析实现集中在 dds-device-impl.cppon_set_option、on_query_options、on_query_filter等处理函数是阅读本文后继续深入源码的最佳起点。小结RealDDS 的控制协议用一套控制-回复-广播模型统一了选项管理、硬件复位与固件升级每个控制都有唯一id与sampleGUID序列号可溯源回复必须广播到通知主题以便所有客户端同步状态错误通过statusexplanation表达。选项读写支持单值与批量两种模式批量模式还承担了服务器主动推送选项变化的职责hwm提供了直接操作硬件的低层通道而 DFU 三段式流程dfu-start→dfu-ready→dfu-apply则为固件升级提供了从内存预留、镜像校验到最终应用的完整保障并以断连事件作为升级完成的明确信号。【免费下载链接】librealsenseRealSense SDK项目地址: https://gitcode.com/GitHub_Trending/li/librealsense创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考