企业官网建设流程全解析

Serial Studio 键值对（Key-Value）解析模板：wire 格式、参数配置与源码实现详解

【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio

Serial Studio 的Key-value pairs（键值对）原生解析模板用于从一行文本帧中提取key=value形式的字段，并按固定顺序映射到通道，适合遥测设备以紧凑的"部分更新"方式上报数据。本文基于 app/rcc/scripts/native/key_value.md 展开，结合仓库源码（TextKeyValue.cpp 等）说明其线格式、四个可配置参数、通道锁存语义以及底层解析实现，帮助你直接上手配置并理解其行为边界。

模板定位与适用场景

键值对解析器是 Serial Studio 众多"原生模板"（Native Templates）之一。与 JSON、XML 等结构化解码器不同，它针对的是最朴素的文本遥测格式：一行内以,分隔若干键=值对。典型场景包括：

• 温湿度/气压等传感器以temperature=22.5,humidity=60.3,pressure=1013形式周期性上报；
• 设备按需只发送变化的字段，实现"增量/部分更新"上报，例如某帧只包含temperature=23.1；
• 嵌入式端不便组装 JSON 时，用最小的文本开销传递多个数值通道。

模板在仓库中登记于 app/rcc/scripts/parser/templates.json（条目file: "key_value_pairs"，显示名 "Key-value pairs"，中文译名"键值对"），并由 ParserTemplateCatalog.cpp 将 JS 侧旧文件名key_value_pairs映射到原生模板稳定 IDkey_value，再经 keyValueTemplate() 提供进程级描述符实例。

Wire 格式（帧格式）

模板要求每个数据帧是一行符合以下约定的文本：

temperature=22.5,humidity=60.3,pressure=1013

格式要点：

• 帧内多个key=value对之间用成对分隔符（Pair separator，默认,）隔开；
• 每个键与其值之间用键值分隔符（Key-value separator，默认=）连接；
• 键名与值两侧的空格会被自动修剪（trimmed()），因此temperature = 22.5这类带空格的写法也能正确解析；
• 键名区分大小写，必须与配置的 Keys 列表中的名称完全一致才能被识别。

参数配置详解

模板共暴露四个参数，均由KeyValueTemplate::params()定义（见 TextKeyValue.cpp），默认值与语义如下：

参数行为细节与校验规则

• Keys 顺序决定通道顺序：配置pressure,temperature与temperature,pressure得到的通道排列完全不同。解析器在构造时调用buildKeyIndex()（NativeTemplateSupport.cpp）将每个键映射为通道索引，因此先声明的键占用小号通道。
• Keys 不能为空：若解析后键列表为空，makeParser()返回错误"At least one key is required."（至少需要一个键），模板无法实例化解析器。
• 两个分隔符不能相同：若 Pair separator 与 Key-value separator 配置为同一字符，解析器会拒绝创建并报错 "The pair separator must differ from the key-value separator."（成对分隔符必须不同于键值分隔符）。
• Numeric values only 的判定方式：该选项开启后，每个值会经过isNumericValue()（TextKeyValue.cpp）校验——空串直接判为非法，否则通过SerialStudio::toDouble()尝试完整转换为数值；转换失败的对（如name=alpha）整对被跳过，不会写入通道。
• 未配置的键被忽略：帧中出现的键若不在 Keys 列表中，m_keyIndex查表失败，该对直接丢弃。

输出通道与锁存（Latch）语义

模板为每个配置的键输出一个通道，通道始终以配置顺序发射，起始索引为0。其最核心的行为是锁存：

某帧中缺失的键，会保留上一帧的值。

也就是说，通道值在帧间"记忆"。只要配置了temperature,humidity,pressure三个键，即使某帧只发送temperature=23.1，humidity 与 pressure 通道仍输出它们上一帧的值。这使设备可以发送部分更新，前端图表与仪表不会因字段缺失而出现空洞或跳变。

该语义由NativeLatchParser基类承载（NativeTemplate.h）：内部维护与通道数等长的QStringList m_values，storeAt(index, value)写入指定通道，latchedFrame()返回当前完整快照；同时提供reset()用于复位锁存状态。KeyValueParser构造时即以static_cast<int>(keys.size())初始化锁存槽位数量。

帧解析流程与源码实现

KeyValueParser::parseText()（TextKeyValue.cpp）的处理管线如下：

1. 用 Pair separator 将整帧切分为若干候选对（QStringView::split(m_pairSeparator)）；
2. 在每一对中用indexOf(m_kvSeparator)定位键值分隔符，找不到分隔符的对直接跳过（例如justakey这种无=的片段）；
3. 分别取=左侧为键、右侧为值，两侧都做trimmed()去空白；
4. 若开启 Numeric values only 且值无法解析为数值，跳过该对；
5. 以键名查m_keyIndex哈希表，命中则storeAt(通道索引, 值)写入锁存槽；
6. 返回latchedFrame()，即包含全部配置键的当前快照。

值得注意的一点是：模板同时实现了parseBinary()路径（TextKeyValue.cpp），将二进制帧按 UTF-8 解码后复用同一套文本解析逻辑，因此它不仅能挂在文本解码器之后，也兼容以二进制帧为载体的数据源。

与 Plain Text 解码器的配合

官方文档在 Pipeline Notes 中明确指出：该模板与Plain Text 解码器配合使用。配置时应在数据源/帧解码环节选择 Plain Text（纯文本）解码，将每行文本作为一帧交给键值对模板处理；未被 Keys 列表收录的键会被忽略，不会产生额外通道。若需要 JSON 或 URL 编码等更复杂的文本结构，可参考同目录下的 json_data.md 与 url_encoded.md 等模板。

实际配置示例

以下是一个完整的键值对模板配置（对应默认参数即可工作）：

{ "template": "key_value", "params": { "keys": "temperature,humidity,pressure", "pairSeparator": ",", "kvSeparator": "=", "numericOnly": true } }

对应的一帧有效输入：

temperature=22.5,humidity=60.3,pressure=1013

解析结果（通道按配置顺序，索引 0 起）：

若后续帧为temperature=23.0（部分更新），则 humidity 与 pressure 通道仍输出上一帧的60.3与1013。

小结

Key-value pairs 模板以极小的配置成本解决了"纯文本键值遥测流"的解析需求：四个参数（Keys 顺序、双分隔符、数值过滤）即可完成通道映射；锁存机制天然支持部分更新；源码层面对空键列表、分隔符冲突、非数值值的校验保证了配置期的快速反馈。对使用 UART、BLE 等低速链路的嵌入式遥测设备而言，这是一种兼具可读性与解析效率的推荐格式。

深入阅读：模板完整实现见 TextKeyValue.cpp，锁存基类与参数规格见 NativeTemplate.h，键索引构建与公共工具见 NativeTemplateSupport.cpp。

【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio