Serial Studio 项目编辑器完全指南从 JSON 项目文件到仪表盘的完整建模【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-StudioSerial Studio 的项目编辑器Project Editor是创建、编辑和调试 JSON 项目文件的图形化工具它决定了应用如何解释串口、网络、BLE 等数据源送来的字节流并在仪表盘Dashboard上呈现为分组、数据集与控件。本文以 Project-Editor.md 为主体骨架结合仓库源码如 core/Core/Checksum.cpp、core/Core/SerialStudio.h逐层讲解项目层级、帧解析与校验和参数、分组与数据集建模、脚本解析器、多源架构与排错方法读完即可独立搭建并调试一个完整的遥测项目。项目编辑器是什么项目编辑器让你创建和编辑 JSON 项目文件这些文件定义了 Serial Studio 如何解释传入的数据并在仪表盘上显示。你可以通过工具栏的Project Editor按钮打开它也可以从设备设置面板中的扳手按钮进入。编辑器的主窗口位于 app/qml/ProjectEditor/ProjectEditor.qml其后端模型与命令处理位于 core/Ui/ProjectEditor/ProjectEditor.cpp。一个项目文件描述三件事数据的结构——分组Group与数据集Dataset如何组织如何从线路上检测并解析帧——帧检测、解码与解析器用户可以向设备发送哪些操作命令——Action。Serial Studio 在连接设备时读取该文件并根据它构建仪表盘。即编辑项目是建模阶段连接设备是生效阶段。项目层级结构项目树总览一个 Serial Studio 项目文件对应一棵树树的每一层都映射到仪表盘的某一部分有两个关键的组织规则每个Action和每个Source都直接挂在项目根下——不存在中间的 Actions 或 Sources 节点三个例外项目级脚本Control Loop、Lua Library、JavaScript Library归入Project Scripts节点实时数据导出MQTT Publisher、InfluxDB SinkPro 版本归入Data Export节点分组归入Dashboard Widgets节点。树视图在左侧面板展示项目层级例如Project Root Project Scripts Control Loop Lua Library JavaScript Library Data Export MQTT Publisher InfluxDB Sink Action: Reset Device Source: Main Device Frame Parser Dashboard Widgets Group: Sensors Dataset: Temperature [IDX 1] Dataset: Humidity [IDX 2] Dataset: Pressure [IDX 3] Group: Status Dataset: Battery [IDX 4]方括号中的数字是数据集的帧索引frame index即它在解析后数据数组中的位置。点击任一节点右侧属性面板就会显示对应表单。帧索引映射传入数据帧中的每个值都被赋予一个从 1 开始的帧索引配置数据集时引用它设备发送23.5,1013,45.2解析器返回数组[23.5, 1013, 45.2]则 Temperature索引 1、Pressure索引 2、Humidity索引 3。索引是 1 基的索引 1 对应数组元素 0。整个项目内每个索引应当唯一新增数据集时编辑器会自动分配当前最大索引 1删除数据集留下的空缺不会被自动填补。编辑器界面布局编辑器窗口分为三个区域顶部工具栏、左侧树视图、右侧属性面板。工具栏文件操作在左侧其余工具栏是添加按钮按创建对象分组New / Open / Save / Save As文件操作。SaveCtrlS / CmdS把项目写入磁盘Open加载现有的.json或.ssproj文件。Protobuf从 Protocol Buffers.proto模式生成项目。所有构建版本均可用只有其生成的 Pro 控件需要许可证或免费试用详见 Auto-Generating Projects。Restore恢复最近的自动快照详见 Backups Recovery。Lock设置密码并锁定编辑器详见 Project Lock。Add DevicePro为多设备项目添加另一个数据源。Output / Action / Slider / Toggle / Knob / Text Field / Button添加一个输出控件面板或一个动作。Dataset / Plot / FFT Plot / Gauge / Level Indicator / Compass / LED Indicator向选中分组添加数据集并预配置对应控件。Group / Image / Web View / Canvas / Table / Multi-Plot / 3D Plot / Accelerometer / Gyroscope / GPS Map添加带对应分组控件的分组Image、Canvas、3D Plot 为 Pro 功能。每个按钮及其图标都列在 Toolbar Button Reference 中。树视图与导航快捷操作标题栏左侧是Back和Forward按钮按文件管理器或浏览器的方式在访问过的节点间步进Back 返回上一个选中的节点Forward 回到后退前的节点后退后选择新节点会丢弃此前的前进轨迹。已删除的节点会自动跳过。导航还有三种触发方式鼠标上的前进/后退键例如罗技 MX Master在编辑器任意位置按AltLeft后退与AltRight前进树获得键盘焦点时按Backspace后退——仅在文本框未聚焦时生效不会干扰输入。标题栏右侧是Move Up/Move Down在当前选中节点的兄弟节点间重排与右键菜单中的对应项效果一致。New Folder和Move to Folder不在标题栏上需从右键上下文菜单进入选中分支根节点时属性面板中也会出现Add Folder按钮。属性面板右侧面板显示选中树节点的表单每次更改立即作用于项目模型。表单字段取决于选中的是项目根、分组、数据集、动作还是数据源。Project Overview项目总览图选中项目根节点后右侧面板切换为Project Overview又称 Summary——整个项目配置的只读图从左到右分为四列Sources设备每个数据源一张卡片含总线类型、帧检测与解码器Frame parsers and actions每个数据源附带的解析脚本以及全局动作按钮Groups数据集容器与分组级控件Multi-Plot、GPS、Accelerometer 等Datasets每个数据集一个胶囊块其变换块如有绘制在分组与数据集胶囊之间。共享表、输出控件和工作区作为独立卡片绘制在旁箭头展示解析字节如何流入数据集、变换如何馈送给下游消费者。总览图由 core/Ui/ProjectEditor/EditorSummaries.cpp 生成可交互使用双击任意块跳转到对应配置表单源卡片打开源设置、分组卡片打开分组表单、数据集胶囊打开数据集表单、帧解析卡片打开脚本编辑器、动作卡片打开动作表单、共享表卡片打开表编辑器、输出控件卡片打开输出编辑器右键任意块弹出针对该节点的菜单添加兄弟分组、向该分组添加数据集、重命名、上移/下移、复制、删除、编辑帧解析器或画布代码。右键空白背景则提供添加源 / 添加表 / 添加动作快捷项项目整体形状定下来后无需回到左侧树即可继续生长Ctrl滚轮缩放图普通滚动平移Shift滚动水平平移工具栏带重置缩放按钮。总览图既是 sanity check我的分组控件有没有它需要的三个数据集也是项目过大、树视图装不下时的导航面。用文件夹组织项目当分组超过几个后扁平树会变得很长。文件夹让你把条目归入带名字、可折叠的容器保持树可读。文件夹在所有版本免费与 Pro中均可用纯属组织用途绝不改变数据解析方式。存在三棵相互独立的文件夹树每个分支一棵Group folders组织分组Table folders组织共享表Workspace folders组织工作区。一个分支的文件夹不能容纳另一分支的条目分组文件夹只放分组不放表。未放入任何文件夹的条目留在其分支的顶层。Groups Folder: Powertrain Folder: Battery Group: Cell Voltages Group: Pack Temps Group: Motor Group: Cabin (top level, no folder)创建与填充文件夹添加文件夹选中分支根Groups、Variables 或 Workspaces属性面板工具栏出现Add Folder按钮或右键分支选择New Folder嵌套文件夹选中已有文件夹点击Add Sub-folder或右键选New Sub-Folder可任意深度嵌套移入条目右键分组、表、工作区或文件夹使用Move to Folder子菜单它镜像文件夹树可放入任意深度或回到顶层直接添加进文件夹选中文件夹后对应的添加按钮Add Group、Add Shared Table、Add Workspace会直接把新条目创建在该文件夹内。工作区配置文件Workspace profiles工作区配置文件是工作区文件夹的命名子集某个操作员、测试台或机型变体应看到的工作区。一个服务多种引擎变体的项目可以把所有分组和工作区保存在一个文件里为每个变体声明一个 profile。定义在工作区视图仅自定义工作区中Add Profile勾选要显示的文件夹。勾选的文件夹显示其整个子树什么都没勾选的 profile 显示所有内容。Profile 随项目保存加载时选择含两个及以上 profile 的项目打开时会询问显示哪一个并记住该文件的答案。以--profile name启动应用可跳过询问运行时也可用project.workspace.profile.select选择影响范围只影响任务栏的工作区列表和切换器。Project Editor 始终显示整个项目自动的按分组工作区仍然可见项目数据不受任何影响。重命名与删除选中文件夹用Rename改名。Delete删除文件夹但绝不删除其内容文件夹内的条目与子文件夹会提升到被删文件夹的父级若原本就在顶层则提升到顶层。确认对话框会明确说明这一点例如 The folder is removed; its groups and sub-folders move up to the parent.对表文件夹还会提示被移动表的访问路径随之改变。分组文件夹如何塑造仪表盘在自动仪表盘布局中任务栏 Start 菜单里的工作区树会镜像你的分组文件夹树为级联菜单文件夹变成子菜单工作区变成可点击项。两条规则决定分组如何变成工作区叶子分组文件夹无子文件夹折叠成单个工作区聚合其内所有分组的全部控件工作区取文件夹名位于容器文件夹有子文件夹中的分组或顶层分组获得自己的工作区以分组命名。这样你可以把若干小分组放进一个叶子文件夹、合并到一个仪表盘屏幕而较大的分组保留在自己的屏幕上。表和文件夹的工作区文件夹仅是组织用途对仪表盘无副作用。持久化与兼容性文件夹以增量方式保存在.ssproj文件中即groupFolders、tableFolders、workspaceFolders三个数组见 core/Pipeline/DataModel/Project/ProjectPersistence.cpp 中的序列化逻辑每个分组、表和工作区携带一个parentFolderId位于顶层时省略。先于文件夹功能的老项目加载时行为不变没有文件夹数组就全部视为顶层。使用文件夹的项目在旧版构建中也能打开——旧版忽略未知键并显示扁平树。一步一步创建项目第 1 步新建项目打开 Project Editor点击工具栏New在树中点击项目根进行配置设置Project Title显示在仪表盘页眉。第 2 步配置帧解析在树中选中数据源每个项目至少有一个默认名为 Device A单设备项目也一样配置字节流如何切成帧、每帧如何解码、哪个解析器把它变成值。这些设置位于源表单上选中项目根只会显示 Project Title 字段。检测、解码与完整性校验以下设置运行在解析器之前适用于所有解析器类型Built-In、Lua、JavaScript 一视同仁设置说明选项Frame detection methodSerial Studio 如何在字节流中找到帧边界。End Delimiter Only帧以已知序列如\n结尾最常见Start End Delimiter以起始和结束标记界定如/*与*/Start Delimiter Only每个帧以头开始下一个头结束上一个No Delimiters整个捕获块即一帧用于定长或带长度前缀的协议。Start delimiter / end delimiter实际的定界符字符串哪些生效取决于检测方式。任意字符串如\n、/*、*/。Hex delimiters勾选表示定界符以十六进制书写。如换行为0A。Data conversion (decoder)定界符内的字节在交给解析器前如何解码。Plain Text (UTF8)默认文本模式Hexadecimal每两个字节读作一个十六进制值Base64先做 Base64 解码Binary (Direct)原始字节直接作为字节数组/表传给解析器。Checksum algorithm附加到每帧的可选完整性校验校验失败的帧被丢弃。XOR-8, MOD-256, CRC-8, CRC-16, CRC-16-MODBUS, CRC-16-CCITT, Fletcher-16, CRC-32, Adler-32。选错解码/检测组合会静默产生乱码二进制或永远切不出帧。尤其注意Plain Text 走QString::fromUtf8任何非合法 UTF-8 的字节大多数二进制负载含0x00或大于0x7F的值都会被替换为UFFFD原始字节丢失。非文本数据务必选Binary (Direct)。底层检测/解码枚举定义在 core/Core/SerialStudio.hFrameDetection的四个取值与 core/Core/IO/FrameConfig.hFrameConfig结构体默认起始序列为/*、结束序列为*/。校验和参数。算法名称在多项式、初始值和字节序上各不相同为期望特定配置的设备选错算法会让每一帧都静默地校验失败。下表给出各算法的完整参数与检查值其实现均可在 core/Core/Checksum.cpp 中逐行核对算法宽度多项式初值反射 in/out字节序Check123456789XOR-88-bit-0x00-单字节0x31MOD-2568-bit-模和0x00-单字节0xDDCRC-88-bit0x310xFFno / no单字节0xF7CRC-1616-bit0x10210xFFFFno / no大端0x29B1CRC-16-MODBUS16-bit0x8005反射 0xA0010xFFFFyes / yes小端0x4B37CRC-16-CCITT16-bit0x10210x0000no / no大端0x31C3Fletcher-1616-bit-模和0-大端0x1EDECRC-3232-bit0x04C11DB7反射 0xEDB883200xFFFFFFFFyes / yes大端0xCBF43926Adler-3232-bit-模和1-大端0x091E01DECheck 列是算法对 ASCII 字符串123456789算出的校验值可用于确认设备端实现是否使用同一配置。CRC-16 与 CRC-16-CCITT 共用0x1021多项式但初值不同0xFFFF对0x0000名字相近却对同一输入产生不同字节不可互换。CRC-16-MODBUS 是多字节校验中唯一的例外Serial Studio 按最低有效字节在前写出表中其余多字节校验均按最高有效字节在前。源码中这一差异体现在打包函数上——packU16BE/packU32BE与packU16LE见 core/Core/Checksum.cpp 的checksumFunctionMap。两个默认值对手写或很老的项目文件很重要当项目的sources数组整体缺失旧版单源格式时帧检测方式默认Start End Delimiter当sources数组中的单个条目省略该键时默认End Delimiter Only。编辑器保存的新项目总是显式写出该键因此这两个默认值只会在手工编写或预多源时代生成的文件上出现。每个保存的源都会同时写出短 JSON 别名checksum、decoder和长名checksumAlgorithm、decoderMethod加载时若两者都在长名优先。短别名是遗留的、仅用于加载的兼容字段——手改项目文件时不要针对它们。解析器语言解析器把解码后的帧变成值数组每个值对应一个数据集帧索引。在解析器编辑器工具栏的 Platform 下拉框选择语言语言配置什么最适合Built-In不写代码。选一个模板并填写其参数表单。新项目的默认解析器。常见线格式零配置上手定界/CSV、定宽、键值、NMEA 0183/2000、JSON、XML、YAML、MessagePack、Modbus、UBX、MAVLink、COBS/SLIP以及批量/时间序列多帧数据。Lua一个parse(frame)函数推荐脚本语言。模板覆盖不到的自定义逻辑脚本开销最低。JavaScript一个parse(frame)函数。偏好 JavaScript 或需要JSON.parse式手感的自定义逻辑。Built-In 的参数表单因模板而异例如Delimited text暴露分隔符、可选引号字符和 trim/skip-empty 开关而Modbus frames暴露通道数、寄存器偏移和 signed-registers 开关。完整模板目录与参数见 Frame Parser Scripting。源码层面Native内置模板语言用 JSON 描述符{template: ..., params: ...}表示解析器参数校验在 core/Ui/ProjectEditor/Editors/FrameParserModel.cpp 的validateParams中执行。Lua 或 JavaScript 的parse()编写见下文第 7 步Built-In 模板不需要脚本——参数表单本身就是配置可直接跳到第 3 步。第 3 步添加分组分组组织相关数据集并决定仪表盘上使用哪个分组级控件。点击工具栏中的一个分组按钮Group为普通容器Table、Multi-Plot、Accelerometer、Gyroscope、GPS Map等为预配置控件在树中选中新分组进行配置设置Group Title例如 Environmental Sensors设置Composite Widget分组控件类型选择器控件说明数据集要求Data Grid所有值的表格视图任意数量Bar Panel每个数据集一根告警带配色条任意数量Multiple Plot叠加的时间序列曲线一个及以上Accelerometer3D 加速度可视化恰好 3 个X, Y, ZGyroscope3D 姿态可视化恰好 3 个X, Y, ZGPS Map地图上的地理跟踪2 或 3 个lat, lon, 可选 alt3D Plot (Pro)3D 散点/轨迹恰好 3 个X, Y, ZImage View (Pro)二进制图像流无图像数据在帧内Canvas Widget (Pro)自定义 JavaScript 渲染画布任意数量Web View内嵌网页任意数量None无分组控件数据集单独显示任意数量第 4 步添加数据集数据集映射到设备输出的各个数据字段。在树中选中一个分组点击工具栏Dataset或旁边的数据集控件按钮Plot、FFT Plot、Gauge、Level Indicator、Compass、LED Indicator配置数据集属性General通用Dataset Title显示标签例如 TemperatureMeasurement Unit测量单位后缀例如 deg C、hPa、%Frame Index解析后数据数组中的 1 基位置。设备发23.5,1013,45.2时Temperature1、Pressure2、Humidity3Widget数据集级可视化Bar、Gauge、Compass、Meter 或 None。四种控件在仪表盘上以两页滑动视图呈现——第 0 页是模拟可视化第 1 页是大号等宽数字读数当前激活页按控件保存在项目文件中Minimum Value / Maximum Value数据集的基础值域默认均为 0。控件与 FFT 在自身 min/max 未设置时回退到该值域。Plot Settings绘图设置Enable Plot WidgetYes/No 选择器非复选框选Yes将该数据集作为时间序列绘图。FFT频率分析Enable FFT Analysis启用频域分析FFT Window Size窗口大小64、128、256、512、1024 等FFT Window Function变换前施加的窗函数用于降低频谱泄漏同时影响 FFT 图与水瀑布图。默认Blackman-Harris。可选Rectangular (None)、Bartlett (Triangular)、Hann、Hamming、Blackman、Blackman-Harris、Nuttall、Blackman-Nuttall、Flat Top、Welch、Bartlett-Hann、Bohman、Cosine (Sine)、Lanczos、ParzenFFT Sampling Rate (Hz, required)必须与真实数据速率一致频率轴标注才正确Minimum Value (optional) / Maximum Value (optional)FFT 图的 Y 轴范围留空时回退到 General 节的 Minimum Value / Maximum Value。Waterfall水瀑布图ProEnable Waterfall Plot为该数据集显示滚动的时频图频谱图。复用上述 FFT 设置窗口、采样率、范围Waterfall Y Axis垂直轴来源。默认Time较老的频谱向下滚动改选其他数据集则用该数据集的值驱动 Y 轴——典型用于阶次跟踪例如 RPM 对频率。LEDShow in LED Panel在 LED 面板中显示该数据集LED On Threshold (required)超过该阈值 LED 点亮。仅当数据集没有告警带时显示一旦定义了告警带就由告警带驱动 LED 的颜色、标签和闪烁状态。Alarm bands告警带Alarm Bands数据集工具栏位于Transform旁打开对话框为 Bar、Gauge、Meter 和 LED 数据集定义带严重级别的彩色值域。每个带含 min/max 范围、严重级别Info / OK / Warning / Critical、可选的颜色覆盖与标签以及 LED 面板的闪烁开关。为没有告警带的 LED 数据集打开对话框时会从LED On Threshold预填一个带使既有配置原地迁移。Widget Settings控件设置Minimum Value (optional) / Maximum Value (optional)Bar、Gauge、Meter 显示的值域留空时回退到 General 节的 Minimum Value / Maximum Value。第 5 步添加动作可选动作在仪表盘上放置按钮向连接的设备发送命令。点击工具栏Action配置动作Action Title按钮标签例如 Reset DeviceAction Icon从内置图标集选择Send as Binary勾选后负载以十六进制字节而非文本输入Transmit Data要发送的字符串或十六进制字节例如RSTEnd-of-Line Sequence追加行结束符New Line\n、Carriage Return\r、CRLF\r\n或 None。仅在Send as Binary关闭时可编辑若在切到二进制模式前已配置了序列它仍会作为原始字节追加在十六进制负载之后Auto-Execute on Connect设备连接时自动发送该命令Timer Mode模式行为Off仅手动点击默认。Auto Start连接时定时器自动启动按配置间隔重复发送命令。Start on Trigger第一次点击时启动定时器命令重复直到停止。Toggle on Trigger每次点击切换重复定时器的开/关。Repeat N Times每次点击按固定次数Repeat Count发送命令间隔为配置的 Interval。Interval (ms)重复间隔毫秒数默认 100 ms模式为 Off 时禁用Repeat CountRepeat N Times 模式下的发送次数默认 3。完整动作参考含多源目标与示例见 Actions 页面。第 6 步添加数据源多设备项目数据源定义数据从哪里来。单设备项目有一个隐式源多设备项目使用显式源。点击工具栏Add DevicePro配置Title描述性标签例如 Arduino UnoBus TypeSerial Port、Network Socket、Bluetooth LE或ProAudio Input、Modbus、CAN Bus、Raw USB、HID Device、Process、MQTT SubscriberFrame Detection / Delimiters与第 2 步相同字段每源独立配置Data Conversion / Checksum与第 2 步相同字段每源独立配置Connection Settings总线特定参数COM 口、波特率、IP 地址等随项目保存。每个源都有独立的 Frame Parser 标签页用于配置每源解析脚本。第 7 步编写帧解析脚本可选本步适用于Lua和JavaScript解析器。如果你在第 2 步选了Built-In模板参数表单就是你的解析器无需写脚本可直接跳过。对不是纯 CSV、也没有 Built-In 模板覆盖的数据写一个parse()函数把每帧变换成值数组。Serial Studio 支持 Lua默认推荐与 JavaScript语言在解析器编辑器工具栏的 Platform 下拉框选择。在树中选中一个源单源项目也可选 Frame Parser 节点打开 Frame Parser 视图在 Platform 下拉框选择脚本语言编写函数Lua默认function parse(frame) -- frame 是字符串PlainText/Hex/Base64或字节表Binary (Direct)。 -- 返回与数据集帧索引对应的值表。 local result {} for field in frame:gmatch(([^,])) do result[#result 1] field end return result endJavaScriptfunction parse(frame) { // frame 是字符串PlainText/Hex/Base64或字节数组Binary (Direct)。 // 返回与数据集帧索引对应的值数组。 return frame.split(,); }解析器代码随输入自动存入项目。用Validate按钮检查脚本语法检查 对第一个源的运行时探测见第 7b 步用Test With Sample Data以样例帧运行。规则函数必须命名为parse且必须接受至少一个参数帧负载。JavaScript 会特别拒绝已废弃的双参数parse(frame, separator)形式但声明额外的未使用参数是允许的Lua 完全不检查参数个数必须返回表Lua或数组JavaScript每个元素映射到一个数据集帧索引在parse()外部声明的全局变量在多次调用之间持久存在适合有状态协议用console.log()两种语言或print()Lua 简写把调试消息打印到 Serial Studio 终端。完整的console表log、debug、info、warn、error在 JavaScript 和 Lua 中均可使用error还会弹出应用通知warn在设置中启用Route Warnings to Notifications时同样如此默认关闭。示例二进制协议Lua。function parse(frame) -- frame 是 Binary (Direct) 模式下的字节表1 基索引 local temp (frame[1] 8) | frame[2] local humidity (frame[3] 8) | frame[4] return {temp / 10.0, humidity / 10.0} end第 7b 步用 Test 对话框测试整条管线解析器工具栏上的Test With Sample Data按钮打开Test Frame Parser对话框。它运行与实时仪表盘相同的字节到通道管线因此你在这里看到的就是仪表盘对同一输入会看到的结果。代码编辑器工具栏上的独立Validate按钮不止检查语法它先编译脚本再用运行时探测帧调用parse()——依次尝试0、单字节数组和——以捕获只有运行时才暴露的错误。探测仅对多源项目中的第一个源执行其余源只做语法检查。对话框有三个区段Pipeline configuration管线配置检测模式、起始/结束定界符、hex 定界符开关、解码方法与校验和算法。它们与活动源联动在对话框里修改会立即改写项目源实时帧读取器也会拾取该变化无需单独的 Apply 步骤Frame data input帧数据输入一个输入框输入要测试的原始流字节。勾选Hex可以空格分隔的十六进制对输入字节01 A2 FF 3C——这是喂二进制协议的安全方式。纯文本模式按 UTF-8 读取输入。在输入框中按Return或点击对话框底部的Evaluate运行管线并填充下方结果Pipeline results管线结果统计行显示frames extracted | bytes consumed | bytes buffered | dropped。其下是一棵树把每个提取帧展开为原始字节hex、解码器输出解析器实际收到的内容以及每个通道一个节点的解析行。自上而下读树能精确定位失败阶段零帧提取定界符/检测模式与输入不匹配复查起始/结束字段有帧但行为空解析器运行了但没返回数组——通常是parse()返回了nil、undefined或非数组值有行但数量不对parse()中的索引映射有误对比行索引与各数据集的Frame Index字段对话框中有且正确的行在仪表盘上缺失数据集上的变换在拒绝该值返回nil/NaN或控件 min/max 在裁剪它。该对话框底层对应 core/Pipeline/DataModel/Scripting/FrameParserPipeline.h 中的PipelineSpec/PipelineResult结构——PipelineResult记录了提取数、消耗字节、剩余字节与丢弃帧数与界面统计行一一对应runFrameParserPipeline系列函数实现提取 解码 解析的整条链路。解码检测设置如何到达解析器第 2 步配置的检测模式、定界符和解码器在解析器之前运行。它们决定每个帧在哪里开始和结束以及parse(frame)收到什么Plain Text 收到QString::fromUtf8字符串十六进制或 Base64 收到对应字符串Binary (Direct) 收到原始字节缓冲区Lua 中为 1 基表JavaScript 中为带长度键的对象。完整选项列表与 UTF-8 陷阱见第 2 步的表。数据集值变换每个数据集都可以选配一个transform(value)函数把原始解析值转换为工程值再交给仪表盘。变换适用于标定、单位换算、滤波和信号调理。添加变换选中数据集点击工具栏Transform按钮打开带语法高亮、内置模板和实时测试区的专用编辑器。完整文档见 Dataset Value Transforms。多源架构当项目有多个源时每个源代表一台独立物理设备拥有自己的连接、总线类型、帧检测和解析器Built-In、Lua 或 JavaScript。在树中每台设备添加一个源通过分组或数据集属性中的Input Device下拉框把分组分配给源在主窗口点击 Connect 时所有设备同时连接每台设备的数据独立路由到其分配的分组与数据集。保存与加载点击SaveCtrlS / CmdS把项目以.ssproj文件写入磁盘之后可用Open重新打开或设为默认项目后自动加载关闭编辑器或打开其他文件时Serial Studio 会提示保存未保存的更改用Examples浏览器主工具栏打开工作项目文件作为参考。项目文件在磁盘上被更改时Serial Studio 监视打开的项目文件。检查比较的是文件内容而非时间戳因此应用自身的保存不会触发它只有外部更改才会。被其他程序修改文本编辑器、git checkout、同步工具弹出 Project file changed on disk 提示询问是否重新加载。有未保存更改时提示会警告重新加载将丢弃这些更改。回答No保留内存中的项目并标记为已修改下一次保存会覆盖外部编辑被删除或重命名发布警告通知并将项目标记为已修改。保存项目即可在原路径重建文件。重新加载会替换内存中的项目。Restore对话框仍列出重新加载前拍摄的快照因此误触发的重新加载可从 Backups Recovery 撤销。常见错误与修复数据集索引不匹配症状。控件显示 0、错误数据或无数据。修复。检查每个数据集的帧索引是否与解析器返回数组的正确位置对应。索引 1第一个元素、索引 2第二个元素依此类推。帧解析器错误症状。控制台显示 undefined 或解析错误。修复检查控制台中的错误消息添加console.log()调用检查原始帧与解析输出确保函数始终返回数组绝不返回字符串、对象或 undefined编辑解析器代码后使用Validate确认脚本语法与运行时均干净。定界符不匹配症状。检测不到帧或数据乱码。修复打开 Console 视图检查原始字节开启十六进制视图以发现隐藏字符如\r或\0常用选择\n大多数串口设备、\r\nWindows 风格或自定义标记如/*与*/。控件与数据类型不匹配症状。控件出现但显示不正确。修复Gauge、Bar、Meter 需要有界的数值。在 Widget Settings 中设置 Minimum Value / Maximum ValueAccelerometer 和 Gyroscope 分组需要恰好 3 个数据集GPS Map 需要 2 或 3 个数据集纬度、经度、可选海拔Compass 期望 0 到 360 之间的值。分组控件缺数据集症状。分组控件不出现在仪表盘上。修复。确保分组的数据集数量满足其控件类型要求参见第 3 步的表。实用技巧用Duplicate右键快速创建相似的分组或数据集树中数据集名称旁显示帧索引便于快速参考切换到 Dashboard 前先用 Console 视图测试配置把会话记录为 CSV再用 CSV Player 在无硬件连接的情况下迭代仪表盘布局使用清晰的数据集标题和单位——它们直接显示在仪表盘控件上为仪表、条形图和表头设置合适的 Minimum Value / Maximum Value而不是依赖自动缩放。延伸阅读Widget Reference全部控件类型的完整指南Frame Parser ScriptingLua 与 JavaScript 解析器完整参考Dataset Value Transforms数据集级标定、滤波与单位换算Data Flow数据在 Serial Studio 中的流动路径Operation ModesConsole Only、Quick Plot 与 Project File 三种模式Troubleshooting常见问题的修复。【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考