Serial Studio 控件（Widget）完整参考：从仪表盘组态到 Alarm Bands 告警机制

Serial Studio 控件（Widget）完整参考：从仪表盘组态到 Alarm Bands 告警机制

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

Serial Studio 是一个开源遥测仪表盘项目，支持 UART、BLE、MQTT、Modbus、CAN Bus 等多种数据源，其核心价值在于把设备上报的原始数据流实时渲染成一组可自由拖拽、缩放的仪表盘控件。本文以官方 Widget-Reference 为骨架，系统梳理全部 15+ 种控件类型的配置键、适用场景与数据集要求，并深入 Alarm Bands 告警体系与项目文件字段，同时结合仓库源码（如 WidgetResolution.cpp、AlarmMonitor.cpp、Frame.cpp）验证底层实现。读完本文，你将能在项目文件中准确配置每一种控件，理解告警带如何驱动颜色、通知与 LED 闪烁，并能在设计新仪表盘时快速选出最合适的控件。

控件类型总览

Serial Studio 的控件按数据绑定关系分为两大类，另有一类脱离数据源的实用控件：

• Group Widgets（组控件）：绑定一个"组"下的多条数据集（dataset），把组内数据综合呈现；
• Dataset Widgets（数据集控件）：仅展示单条数据集的值；
• Utility Widgets（实用控件）：不绑定任何组或数据集，属于仪表盘级工具。

其层级关系可表示如下：

控件类型在 C++ 侧由DashboardWidget枚举表示（见 SerialStudio.h），枚举序号是持久化的状态值，因此该枚举只允许追加、不允许重排；其中BarPanel固定为 90、Extension固定为 100，以避免商业版与开源版之间的序号漂移。字符串键到枚举的映射集中在 WidgetResolution.cpp，例如"gyro"/"gyroscope"都解析为DashboardGyroscope，"gps"/"map"都解析为DashboardGPS——这也是文档中"旧键名仍然兼容"说法的源码依据。

Group Widgets（组控件）

Data Grid（数据表格）

• 控件键："datagrid"。
• 以表格形式展示组内所有数据集的标题、数值与单位。
• 适用场景：多通道总览、状态监控。
• 配置：除向组中添加数据集外无需其他配置。
• 暂停/恢复语义：与 Plot 不同——暂停的 Data Grid 停止刷新，点击 Resume 会立刻拉取一份当前值的全新快照，丢弃暂停期间到达的所有数据；而暂停的 Plot 只是停止向缓冲区追加新样本，既有历史数据保持完整。

Bar Panel（条形面板）

• 控件键："barpanel"（在 WidgetResolution.cpp 中被解析为DashboardBarPanel）。
• 组内每条数据集渲染为一行"带标签的条"：标题 + 报警带分区轨道 + 实时数值。
• 报警带始终以"变暗区域"完整绘制在轨道上；填充色取当前激活带的颜色（正常为绿色，数值越过带边界后变为黄色/红色）。
• Bar Style选项（Project Editor 中配置）：Auto（默认，根据面板形状自动选择）、Horizontal（横向行）、Vertical（耙齿状纵列）。
• 启用了Hold Min/Max Markers的数据集会自上次数据重置以来观测到的最低/最高值处绘制刻度标记。
• 适用场景：一目了然监控大量相关通道（温度、压力、EGT 耙），此时颜色只表达严重度、不表达其他含义。
• 配置：为每条数据集设置widgetMin/widgetMax作为轨道量程，再定义 alarm bands 作为严重度着色依据。

Multi-Plot（多曲线图）

• 控件键："multiplot"。
• 在共享坐标轴上叠加多条数据集曲线，支持逐曲线显隐切换、Y 轴自动缩放。
• 适用场景：对比相关信号，例如三轴加速度计随时间的变化。
• 配置：将需要显示的数据集标记graph: true即可。

GPS Map（GPS 地图）

• 控件键："map"（Project Editor 新建 GPS Map 组时写入该键；"gps"同样被接受，见 WidgetResolution.cpp）。
• 基于瓦片地图的实时位置跟踪，绘制轨迹路径，显示经纬度与海拔，自动居中最新位置，支持鼠标缩放与平移。
• 适用场景：车辆跟踪、无人机遥测、野外测量。
• 数据要求：需要包含纬度、经度（可选海拔）的数据集。
• 注意事项：地图瓦片需要联网加载，已浏览区域会缓存；只有第一种基础地图样式免费，Base Map下拉框中的其他样式需要 Pro 许可。

Gyroscope（陀螺仪）

• 控件键："gyro"（同时接受"gyroscope"）。
• 姿态指示器，显示偏航（yaw）、俯仰（pitch）、横滚（roll）。
• 数据要求：恰好 3 条数据集（yaw、pitch、roll）。
• 期望以度为单位的绝对角度；若传感器只输出角速率（deg/s），请用Integrate Rate to Angle变换模板先做积分。
• 适用场景：IMU 可视化、无人机姿态、机器人方向。

Accelerometer（加速度计）

• 控件键："accelerometer"。
• 三轴加速度可视化，自动计算合成 G 力，显示 pitch、roll、峰值 G、幅值，可配置最大 G 量程。
• 数据要求：恰好 3 条数据集（X、Y、Z 加速度）。
• 适用场景：振动分析、撞击检测、运动感知。

LED Panel（LED 面板）

• 组控件，对标记led: true的数据集自动创建。
• 每条数据集对应一颗多状态指示灯。定义报警带后，LED 以值所在带的颜色点亮，在数据集标题旁显示该带的label，当值位于标记blink的带内时 LED 闪烁；值位于所有带之外时 LED 熄灭（即"信号牌面板"行为）。未定义报警带时，回退到旧的单阈值逻辑：值达到或超过ledHigh（默认 80）时以数据集颜色点亮。
• 适用场景：状态标志、限位指示、数字 I/O 状态、信号牌面板。
• 配置：在每条数据集上设led: true，然后要么定义alarmBands（见后文 Alarm bands），要么设ledHigh。源码中 PropertyHooks.cpp 的ledBandsAbsent正是通过d.alarmBands.empty()判断是否应回退到旧阈值模式。

Terminal（终端）

• 特殊控件：只要控制台（console）启用就始终可用。
• VT-100 仿真，支持 ANSI 颜色，展示原始文本数据流，可配置字体与显示选项；键盘输入会被转发给连接的设备。

3D Plot（Pro）

• 控件键："plot3d"。
• 3D 散点与轨迹可视化，支持环绕（orbit）或自由相机导航、可选红/青 3D 眼镜立体显示（anaglyph stereo）、插值支持。
• 数据要求：建议用 3 条数据集分别标记 x/y/z；未标记的轴按 0 渲染。
• 渲染管线：基于 Serial Studio 自研的 QPainter 3D 管线（见 plot3d_eye.frag 等着色器），无需 GPU 或 OpenGL 驱动，可在包括树莓派在内的低端硬件上运行。
• Pro 功能（需许可或免费试用）。

Image View（Pro）

• 控件键："image"。
• 从设备实时流式接收 JPEG/PNG/BMP/WebP 图像；支持自动检测或手动帧分隔符配置；每个控件有独立的帧读取器，图像帧与 CSV 遥测可共存于同一字节流；提供导出、缩放、图像滤镜等工具栏。
• 适用场景：摄像头画面、热成像、视觉检测。
• 组级配置字段：
  • imgDetectionMode："autodetect"（默认，按格式魔数识别）或"manual"（用户自定义分隔符）；
  • imgStartSequence：起始分隔符（十六进制，仅 manual 模式）；
  • imgEndSequence：结束分隔符（十六进制，仅 manual 模式）。
• 不需要组内数据集，控件直接从传输流读取原始图像字节。
• Pro 功能。

Canvas（Pro）

• 控件键："painter"。
• 用户脚本化仪表盘控件：脚本定义一个 JavaScriptpaint(ctx, w, h)回调（以及可选的onFrame()回调），在每个仪表盘 tick 直接渲染到控件的位图上。
• 内置 18 个模板：示波器、迷你图网格、表盘、极坐标图、雷达扫描、人工地平线、热力图、LED 矩阵、矢量场、XY 示波器等。
• 脚本通过datasets全局对象读取组内数据集，通过frame.number/frame.timestampMs读取仪表盘 tick 元数据。
• 适用场景：内置控件无法覆盖的定制可视化——仪表仿制、项目专属布局、实验室仪器式读数。
• 性能与安全：按仪表盘刷新率重绘（默认 60 Hz，可配置 1–240 Hz）；单次调用 250 ms 未返回会被看门狗终止。
• 完整 API 见 Painter-Widget.md。
• Pro 功能。

Web View（网页视图）

• 控件键："webview"。
• 在仪表盘组内嵌入网页，底层为 Qt WebEngine（Chromium）。
• 组级配置字段：
  • webViewUrl：要加载的地址。
• 组内无需数据集。
• 适用场景：嵌入实时地图、3D 模型查看器、硬件厂商的 Web 仪表盘或任意 HTML 内容，与遥测数据并排展示。ISS Tracker 示例就使用它显示 NASA 的 glTF 空间站模型。
• 构建要求：需要启用 Qt WebEngine 的构建；未启用时控件显示 "Web View Unavailable" 占位符，而不是导致项目加载失败。

Dataset Widgets（数据集控件）

Plot（曲线图）

• 对标记graph: true的数据集自动创建（对应字段名plt）。
• 单曲线 2D 时间序列折线图，Y 轴自动缩放。
• 可通过项目文件键plotMin/plotMax（C++ 字段pltMin/pltMax）配置绘图量程。
• 可通过xAxis键（C++ 字段xAxisId）指定另一数据集作为自定义 X 轴，从而得到 XY/散点图。
• 支持暂停/恢复。
• 适用场景：单信号监控、趋势分析。

FFT Plot（FFT 频谱图）

• 对标记fft: true的数据集自动创建。
• 基于 KissFFT 的实时频谱分析（KissFFT 位于 lib/KissFFT）。
• 可配置 FFT 窗口大小：8 到 262144 个采样（2 的幂），默认 256。
• 可选择的窗函数（15 种，从 Rectangular 到 Flat Top），默认 Blackman-Harris，用于降低频谱泄漏；Waterfall 控件使用同一窗函数。
• 可配置采样率决定频率轴（默认 100 Hz）；可配置频率范围fftMin/fftMax。
• 适用场景：振动频率分析、音频频谱、信号质量评估。
• 配置字段：fftSamples（窗口大小）、fftWindow（窗函数）、fftSamplingRate（Hz）、fftMin、fftMax。

Waterfall（Pro）

• 对标记waterfall: true的数据集自动创建。
• 滚动的时间-频率图（频谱图）：每行是一个 FFT 幅值谱，最新行绘制在顶部，旧行向下滚动。
• 复用数据集的 FFT 设置（fftSamples、fftWindow、fftSamplingRate、fftMin、fftMax）；若希望 FFT 图与瀑布图并存，同时启用fft: true与waterfall: true即可。
• 幅值换算为 dB；动态范围（minDb/maxDb）可从控件工具栏调整。
• 内置配色：Viridis、Inferno、Magma、Plasma、Turbo、Jet、Hot、Grayscale。
• 滚轮缩放、拖拽平移、悬停显示频率/时间读数，工具栏可重置视图。
• 可配置历史深度（存储行数）。
• Y 轴来源：默认使用经过时间；设置waterfallYAxis为另一数据集的uniqueId，即可用该数据集的值驱动 Y 轴——典型用于阶次跟踪图（例如 RPM 对频率）。
• 配置字段：waterfall: true、waterfallYAxis（0 = 时间；否则为用作 Y 轴的数据集uniqueId），外加上述 FFT 字段。
• Pro 功能。

Bar（条形）

• 数据集控件键："bar"。
• 带量程的水平条形仪表；彩色分段报警区，每段有严重度（Info / OK / Warning / Critical）；显示当前值与单位。
• 适用场景：液位指示、资源占用、有界数值。
• 配置字段（项目文件键）：widgetMin（默认 0）、widgetMax（默认 0）、alarmBands（数组，见 Alarm bands）。widgetMin/widgetMax对应 C++ 字段wgtMin/wgtMax。
• 双页滑动视图：第 0 页为模拟条，第 1 页为大型等宽数字读数；横向滑动（或点击底部指示点）切换。激活页按控件保存在项目文件中，每个 Bar 磁贴记住自己的偏好。

Gauge（表盘）

• 数据集控件键："gauge"。
• 圆形/弧形表盘，每个报警带对应外缘彩色弧段。
• 配置模型与 Bar 相同（min/max、bands）。
• 适用场景：速度表、RPM、压力、温度。
• 配置字段：widgetMin、widgetMax、alarmBands，对应 C++ 字段wgtMin/wgtMax。
• 双页滑动视图：第 0 页为模拟表盘，第 1 页为大型数字读数，激活页按控件持久化。

Compass（罗盘）

• 数据集控件键："compass"。
• 航向指示器（0 到 360 度），自动把数值航向转换为罗经方位（N、NE、E、SE、S、SW、W、NW）。
• 适用场景：航向与方位、风向、朝向。
• 双页滑动视图：第 0 页为罗盘玫瑰，第 1 页为大型数字读数（航向 + 罗经方位），激活页持久化。源码中切换到 compass 控件时会把量程自动改写为 0–360 并清空报警带（见 PropertyHooks.cpp 的onWidgetChanged）。

Meter（仪表）

• 数据集控件键："meter"。
• 模拟半圆弧仪表：扫掠指针、刻度线、彩色弧带、数值读数。
• 与 Bar、Gauge 相同的 min/max + bands 模型。
• 适用场景：VU 式读数、信号强度、压力、电压。
• 配置字段：widgetMin（默认 0）、widgetMax（默认 0）、alarmBands，对应 C++ 字段wgtMin/wgtMax。
• 双页滑动视图：第 0 页为半圆弧仪表，第 1 页为大型数字读数，激活页持久化。

Alarm Bands（告警带）

Bar、Gauge、Meter、Bar Panel、LED Panel 这五类控件都会渲染一条或多条alarm band（告警带）。每条带是一个连续的数值区间，带颜色与严重度分级。带总是完整绘制——Bar/Bar Panel 轨道上的变暗区域，或 Gauge/Meter 表盘边缘的弧段——而填充或指针始终取当前激活带的颜色，因此正常区间的值显示为积极的绿色信号。值落在所有带之外时，会钳制到最近一条带的严重度，即超量程数据总是以 Critical 呈现，而不会被归类为"未分类"；LED Panel 的条目以激活带的颜色点亮。"APU 转速表"惯例（低于正常为白色、正常区间为绿色、黄色告警、红色红线）是典型配置，但任意区间与颜色的组合都是允许的。

带的 schema

在数据集的alarmBands数组下，每个条目是一个对象：

重叠、缺口与钳制语义

• 带之间可以留缺口、可以重叠、不必覆盖全量程；
• 重叠时按列表顺序取第一个匹配的带，而非最后一个；
• 缺口只是让被绘制的轨道/背景不着色：条形填充或指针本身仍取某个带的颜色，并钳制到最近的那条带。

编辑器与预设

通过数据集工具栏的Alarm Bands按钮（位于Transform旁）打开专用对话框进行编辑，内含预设（Tachometer、Speedometer、Engine Temperature、Pressure、Battery Voltage、Fuel Level、Signal Strength、CPU / System Load、OK / Warning / Critical、Indicator (On / Off)、Fault Indicator）、逐带取色器、严重度选择器、闪烁开关与实时预览条。该对话框的后端提交逻辑见 EditorCommit.cpp 与 EditorForms.cpp。

通知触发逻辑

当值进入严重度 ≥ Warning 的带时，Serial Studio 会在 "Alarms" 频道发布通知：带严重度 2 发Warning，严重度 3 发Critical（副标题携带带的label）。告警跟踪在仪表盘层面按数据集运行，因此即使显示该数据集的控件被隐藏或未实例化，通知也会触发。冷却（cooldown）按严重度层级而非按数据集计算：Warning 会被最近的 Warning 或 Critical 抑制 3 秒，而 Critical 只被最近的 Critical 抑制——因此从 Warning 升级到 Critical 总是立即发布。

底层实现见 AlarmMonitor.cpp：每个含报警带的数据集被构建为一个Tracker（第 84–113 行），evaluateAlarms()按uniqueId解析数据集并调用processValue()（第 169–215 行）；bandIndexFor()先查上次命中的带（快速路径），再顺序扫描（第 147–163 行），这与"重叠时取第一个匹配带"的文档语义一致。通知发布前会把值钳制到wgtMin–wgtMax范围（第 173–174 行），与模拟控件的语义对齐。

旧版兼容

旧版 Serial Studio 写入的项目文件携带alarmEnabled/alarmLow/alarmHigh而非alarmBands。加载时它们会被转换为两条Warning严重度的带（[wgtMin..alarmLow]与[alarmHigh..wgtMax]），转换逻辑实现在 Frame.cpp 的readDatasetAlarmBands()中。旧键不会被写回：重新保存的项目只携带alarmBands。对于 Canvas 脚本（Pro），dataset.alarmLow与dataset.alarmHigh仍可作为派生值读取（第一条/最后一条Warning+带边界），保证旧脚本继续工作。

Utility Widgets（实用控件）

Clock 与 Stopwatch 是仪表盘级实用控件，不挂接任何组或数据集。从Start menu（Dashboard 面板）切换启用，它们与 Terminal、Notifications 一起作为总览条目出现在任务栏。启用状态持久化在QSettings的Dashboard/ClockEnabled与Dashboard/StopwatchEnabled。

Clock（时钟）

• 从 Dashboard Start menu 切换启用。
• 双页滑动视图：第 0 页为模拟钟面（银色表圈仪表风格、时/分/秒针、12 小时数字）；第 1 页为大型等宽数字读数（12 小时制 + 完整日期）。
• 由系统时钟驱动，每秒滴答一次。
• 激活页持久化在应用QSettings的ClockWidget/clockPageIndex。
• 适用场景：屏幕录像中的可见会话时间戳、实验室/操作员仪表盘。

Stopwatch（秒表）

• 从 Dashboard Start menu 切换启用。
• 单页控件：大型HH:MM:SS.mmm读数，Start/Stop、Lap、Reset按钮与可滚动的计次表。
• 仅本地计时；数据不持久化到项目、不传输、不发送给设备。
• 适用场景：台架测试、会话期间的运行/测试计时。

控件配置速查表

数据集字段参考

项目文件中每条数据集都支持下列与可视化相关的字段（C++ 侧对应实现见 Frame.h 与 DatasetSerialization.cpp）：

仪表盘布局

• 控件以迷你窗口形式出现在仪表盘画布上。
• 拖拽标题栏移动；从边缘与角落调整大小。
• 可将单个控件最小化到任务栏，或最大化铺满画布。
• 右键画布弹出上下文菜单：平铺窗口（tile）、设置壁纸。
• 控件位置与尺寸通过widgetSettings按项目保存，跨会话保持。
• 若项目定义了 Actions，Actions 面板以横向条形式显示在控件上方。
• 仪表盘渲染顺序遵循DashboardWidget枚举（见 SerialStudio.h）：Terminal、DataGrid、MultiPlot、Accelerometer、Gyroscope、GPS、Plot3D、FFT、LED、Plot、Bar、Gauge、Compass、Meter、Clock、Stopwatch、Web View、ImageView、OutputPanel、NotificationLog、Waterfall、Painter。

多数控件的顶边带一条小型图标按钮工具栏，当控件足够大时出现。每个控件工具栏上的每个按钮都收录在 Toolbar & Button Reference 的 "Dashboard widget toolbars" 一节。

如何选择正确的控件

深入阅读

• Project Editor：如何在项目中配置控件。
• Toolbar & Button Reference：每个控件工具栏与应用中的每个按钮。
• Operation Modes：仪表盘模式与帧检测。
• Data Flow：数据如何从驱动经管线到达控件。
• Painter-Widget：Canvas 控件的完整脚本 API。

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