﻿水上火箭地面站 v1.36.18 使用说明


一、安装与启动
• 解压完整运行包，双击 WaterPoweredRocket.exe；不要仅移动 EXE，使用说明与运行组件需放在旁边。
• 面向 Windows 10/11 桌面环境，建议安装 .NET Framework 4.8。Python/MATLAB 仅在训练或外部仿真时需要，在程序设置指定解释器路径。Python 环境可使用运行组件中的配置工具安装。
• 同一 Windows 会话仅允许一个正式实例；再次启动会前置已有窗口。
• 启动动画默认开启，可在“程序设置 → 常用与文件”关闭。Enter/Esc 跳过视觉过程；页面准备完成后才交接主界面。“正在进入…”期间请等待。
• 启动后显示同目录“地面站用前提醒.txt”的正文，可用顶部关闭按钮或“我明白了”退出。勾选“以后不再提醒”并点击“我明白了”后，同一版本、相同提醒内容不再自动显示；版本或内容更新后重新提醒。该文件由发布者直接编辑，请保存为 UTF-8；长正文可连续滚动。
• 右上角切换深浅主题。主题只对本次运行有效；下次启动恢复默认深色。

二、快捷键汇总
• Alt+0：地面站介绍；Alt+1：飞控状态；Alt+2：数据波形；Alt+3：视频跟踪；Alt+4：数据分析。
• Alt+5：神经网络训练；Alt+6：虚拟仿真；Alt+7：飞行路径；Alt+8：串口通讯；Alt+9：程序设置。主键盘与数字小键盘均可使用。
• Q/E：上一/下一小页签（文本编辑时保留正常输入）。F1 不切页。
• Ctrl+G：读取板端参数；Ctrl+O：打开 TEE；Ctrl+S：保存当前波形 TEE。
• Ctrl+R：开始/停止实时波形；Ctrl+Shift+R：开始/停止 CSV 记录。
• 串口通讯页 Ctrl+F：搜索通讯记录；F5：刷新端口。
• 参数数值编辑 Enter：仅保存本地值并移至下一项；按住 S 再按 Enter：保存并单独发送当前项，发送成功后移至下一项。
• 自定义文字框 Ctrl+Enter：发送文字；片头 Enter/Esc：跳过视觉过程。
• 参数列表 Ctrl：追加选择；Shift：连续选择；颜色选择窗口 Space：切换勾选。界面“快捷键提示”可随时查看。

三、连接与通讯
• 在“串口通讯”选择 COM 口、波特率与解析模式，再连接。默认 9600、8N1；必须与板端一致。COM 和波特率允许输入和正常文本框选；点击最右侧箭头展开选项。
• 单板连接无需身份握手，本地 MAIN/LOCAL-01 仅作事件标识；多板共联等待板端 WRGS:HELLO 身份行，普通遥测仍可解析。
• “快速扫描”按当前波特率逐口检测约 4 秒；两帧有效遥测可提前结束。一帧仅提示连接确认；乱码不能证明目标设备。选择结果后连接，已有连接时作为下次端口选择；可取消扫描或关闭窗口。
• “遥测断开后自动重连”可开关，默认开启；关闭后掉线需手动再次连接。开启时等原COM口恢复，按钮显示“取消重连”，状态行显示重试详情；取消会停止重试。收到新遥测才确认恢复，变号仍需手动选择。
• 可导入外部通讯软件，自动打开默认关闭，需明确开启。标准输入/输出桥接或受支持窗口控件可接管参数通道；普通 GUI 是否兼容需实际检查。
• “自定义文字发送”仅适用于地面站直接连接：单行、最多 256 字符、UTF-8 无 BOM、追加 CRLF。连接切换、重连与调参中暂停发送。
• 发送状态表示已写出，不代表板端实际生效；以板端回传和实物状态确认。不要让两个程序同时占用同一 COM 口。

四、在线调参
• “读取参数”发送 GET；回传值更新表格。修改本地数值不会自动发送。
• 右下角“+”新增参数，支持多组；红色“−”真正删除该组，最后一组也可删除。名称与板端一致，中文说明可留空并在主表编辑。
• 选择浮点型或整型：整型不带小数点；浮点型保存三位小数。类型随配置保存，主表不额外显示类型列。
• 输入仅允许数字和浮点型的一个小数点；非法粘贴被阻止，非法值留在原项等待修正。S 只作快捷键。
• 在参数名上按住左键上下框选；Ctrl 追加、Shift 连选，拖至边缘自动滚动。点击“设置选中参数”逐条发送 SET 名称=值，每条 CRLF，间隔至少 500 ms（最多约每秒 2 条）。不合并 SETALL，不因通用错误自动重发。
• 单项 S+Enter 同样遵守 500 ms 间隔。无连接、校验失败或发送中止时留在当前项；发送期间编辑、导入和排序暂时禁用。
• 拖最左三横线即时保存顺序；“参数排序”窗口支持多选拖动、上移、下移、置顶、置底，应用才保存，取消不变。主表和排序窗口支持右键按住框选后左键拖动，放下保留滚动位置。
• 右键可涂色/恢复默认颜色；批量颜色窗口支持勾选、全选、清空、选中项及连续拖动勾选/取消。拖到边缘自动滚动，应用只改变勾选项。
• 导入/导出 .wrparam 方案包含值、类型、顺序、颜色和中文说明；导入先预览，确认只更新本地表，不发送。旧方案缺少顺序或颜色时保留本机设置。
• 方案以 WRGS-PARAMETERS 1 开头，数据为 名称=值；附加 TYPE、ORDER、COLOR、DESCRIPTION（Base64 UTF-8）。默认目录为当前数据根的“飞行数据/参数方案”。

五、飞控状态与模型
• 查看实际回传姿态、角速度、加速度、模式、定位及模型。顶栏显示实际连接、遥测、记录、实时/历史、告警和时间。
• 程序不附带三维模型；导入后复制到模型库，按内容去重并恢复最近模型。模型缩放、视角、显示面数在对应工具及设置中调整。
• 没有遥测或定位时保留空状态；不要把电脑端模型显示当作板端状态或录像证据。

六、数据波形与记录
• 单波形底部及多文件各图下方的时间条连续拖动；主刻度从零点对齐，查看窗口可以停在任意时间位置。
• 某个文件缺少当前物理量的有效数据时，对应图中显示“该文件无该物理量数据”；真实零值正常绘制。
• 实时波形、TEE 保存、CSV 记录、录像和事件允许独立开始、停止与保存，可按需要使用已有同步选项。
• 打开历史 TEE 后选择通道；单波形用于同物理量对比，单文件多物理量显示共享时间轴的子图，多波形对比载入多个 TEE。
• 多文件对比导入、删除时保留其他曲线与视窗，后面的图随位置调整；改变物理量、样式、缩放或主题时只更新需要变化的图。
• 用鼠标框选局部放大，双击或点击“还原局部缩放”恢复；右键/中键拖动平移，鼠标滚轮不缩放。多文件图表可用滚轮上下浏览，每张图下方的时间条连续平移。使用复位、游标、事件和导出工具；局部缩放还原后显示完整时间范围。主刻度从零点对齐，间隔为 0.5 或整数；放大后连续平移不要求视口边缘对齐刻度。多文件删除仅移除所选曲线。
• “曲线颜色与样式”支持实线、虚线、点线、点划线和双点划线，实时/历史/文件对比共用并保存；同一物理量的同一通道在不同文件中共用样式。 拓展解析模式还提供 PE9、PE11、PD12、PD13 四路 PWM 和磁力计 X/Y/Z 的独立设置，任一波形模式均可打开设置。批量窗口支持 Ctrl/Shift、多选、全选、反选、只改颜色/线型及恢复选中项，取消不修改。
• 屏幕绘图按可见范围保留极值，缩放后细化；TEE 保留原始样本，CSV 按记录频率采样；屏幕限点不会额外减少存盘数据。
• 导入一次读取并校验，失败保留原来打开的数据，错误说明字段/行号。必需量无效或时间倒退拒绝；可选缺失仍兼容。导出先完整写入再替换目标文件，失败不覆盖旧目标。
• CSV记录写入失败会停止该记录，保留已写部分并提示可能未写完；波形入口和顶栏记录状态显示错误，串口接收及其他独立功能继续。
• TEE 保存通道名称注释；读取时恢复名称，多文件各用各自名称；旧 TEE 缺少名称时沿用本机名称。

CSV 记录频率与停止保存
• 记录频率是各回传更新类别的最高采样频率，不再让一种高频帧挤掉另一种更新；同一 CSV 每秒行数可能高于该数值。
• 更新掩码仍代表原回传帧，不把持有值改成新更新。旧 CSV 继续可读。
• CSV 在独立队列后台写盘，停止与退出等待已接受的数据完成写入。队列满或磁盘失败明确停止并提示文件可能未写完，不报告正常完成。

七、录像、路径与独立回放
• 摄像头“画面参数”可重新读取设备当前参数，不自动应用；Windows 11 可进入系统摄像头设置。系统默认值和 Windows“相机”的应用内处理可能不同，后者不保证可全部复制。
• 内置摄像头清晰度以实际输出为准，连接状态同时显示采集格式与预览尺寸。预览区域放大不会增加细节；本机 Integrated Camera 支持的最高格式为 1280×720、30 fps MJPG，其他设备以各自能力为准。
• 画面参数只提供驱动支持的项目；“恢复默认/自动”先填入编辑项，点击“应用参数”才改变设备，不强制锐化或伪造对焦。
• 现代摄像头从设备能力中选择支持的高清格式，右侧显示实际采集尺寸、帧率和像素格式。预览区拉大不会增加采集细节；设备输出、对焦、光照、USB 带宽及格式都会影响清晰度。
• “分辨率 / 格式”打开大尺寸选择窗口，只列出设备返回的格式；应用时重建预览，失败尝试恢复原格式。录制期间不能修改，录像重建沿用所选格式。
• “画面参数”提供驱动支持的亮度、对比度、曝光、对焦等项目，支持的自动模式可切换；不支持的项目不显示，也可打开驱动属性页。没有可编辑项目表示当前驱动未提供相应接口。
• “旧摄像头兼容模式（VFW）”适用于提供 Video for Windows 接口的旧摄像头或采集卡，不按设备年龄或品牌判断。现代 USB/UVC、手机或虚拟摄像头可能无法在该通道打开；此时关闭兼容模式，刷新后使用现代模式。
• 视频跟踪页选择摄像头后预览、录像，并按需要配置波形同步；实际编码兼容性以现场录像文件为准。
• 飞行路径展示真实差分 GPS/相对位置和 PC 制导路径；未收到定位时路径为空。
• “独立历史回放”打开 TEE/CSV，关联 AVI/MP4/WMV/MOV 录像，使用播放、暂停、拖动时间轴、0.1×—10×倍速和录像时间偏移同步。
• 本机新录制的 CSV/保存的实时 TEE，会按实际重叠时间与录像保存 .wrpair 旁车清单。独立回放可自动找到对应录像、切换片段并应用时间偏移；采集与录像仍分别开始/停止。请连同清单保留文件夹结构；旧记录、清单缺失或录像移动失效时仍可手动选择和调整偏移。此为电脑端软件时间对齐，不是硬件同步。
• 以摄像头录像为主要证据，测量值、曲线、路径为辅助；不由遥测推算地平仪或三维运动。
• 旧文件缺少告警日志时只缺少事件，其他功能正常；没有定位时路径为空。无录像或编码无法打开时仍可回放测量。

八、数据分析
• “单组数据分析”载入 CSV/TEE，按相对时间查看曲线与指标；“多组数据对比”递归读取文件夹中的重复试验。
• 姿态、角速度、加速度、RMSE、IAE、ISE、超调、调节时间等计算说明在“地面站介绍 → 数据分析详细说明”；公式随正文一起滚动，已内置于程序，无需安装 LaTeX。所需字段缺失时不得当作实测结果。
• 分析根据目标角序列判断自稳/制导。PWM 偏差与饱和时长只使用板端四路 PWM 回传，不使用电脑模拟值。
• 在“程序设置 → 数据与分析”选择显示指标；可导出计算公式、指标、图像及报告。表格列顺序固定。

• 数据分析与数据集分析读取 CSV；TEE 在数据波形中查看。
• 导入 CSV 后可输入起止秒数并点击“分析选定时间段”，恢复全部时间返回全文件；图表、指标及原有导出使用当前范围，选择无效时保留上一结果。
• 结果区提供“信号分布”和“执行器与关联”：程序自动计算分布、四路 PWM 统计、变化片段和角速度候选时滞；关联不等于因果或控制效益。

九、神经网络训练
• 数据收集与训练参数列表提供“全选/取消全选”和“反选”，只改变对应列表的勾选，保留滚动位置。
• 数据收集的自定义变量操作和刷新参数在对应列表底部；模型名称长时可横向滚动查看。
• 左侧模型列表可按住右键拖动框选，Ctrl 加选，选好后按 Delete 或点击删除按钮批量删除，需确认；训练或收集中请先停止。模型删除包含所选模型目录内的数据。
• 新开模型时自动生成临时名称；选择输入、输出、采样与训练配置，再收集实时数据或载入历史数据。当前模型右侧可结束并打包，在弹窗中输入正式模型名。
• 参数选择表支持连续滚动、鼠标勾选、方向键、空格、Home/End 和 PageUp/PageDown；横向滚动时左侧勾选框固定。
• 基础参数可直接训练；点击“高级参数…”打开独立窗口，按需修改并确定（取消不改变参数），训练状态与日志显示运行过程。模型推理的“预测时间 Δt（秒）”设置单点预测经过时间。
• 可管理共享数据集、查看训练进度与验证结果、后台训练、保存/导入模型包并推理；各模型数据目录独立。
• 配置 Python 与依赖后再启动训练；取消/失败以界面状态为准，确认模型包可载入后再使用。
• 当前主要模型学习状态变化量。单点预测给出 Δt 后状态；轨迹递推输出状态，其他输入（包括给定 PWM）保持不变，不自动模拟未来控制输入。
• 验证成绩只对应所用数据与工况，不代表实机控制可靠性；不会自动写入板端或自动修改 PID。

十、虚拟仿真
• 自稳/制导仿真共用固定宽度的设置区滚动条，分别保留滚动位置与曲线勾选。
• 内置计算支持自稳与制导；外部 .py/.m 用于自稳，制导使用内置计算。外部脚本必须满足“仿真计算说明”的接口，不支持任意程序仅凭同名参数自动调参。
• 设置对应 Python/MATLAB 路径；Python 模块需提供指定仿真类、状态与 step()，MATLAB 推荐 result = 文件名(wrgs)，至少输出 time,roll,pitch,yaw。完整参数名、单位及输入输出要求见介绍页“仿真计算说明”。
• 运行组件中的 Python 适配器是通信桥接；外部算法不要求必须 PID，但界面九个增益只有被脚本实际使用才有效。OBJ 仅提供可视外观，不提供物理参数。
• 配置初始姿态、目标、参数、时长后计算、播放、查看曲线并导出 CSV/TEE。统一脚本输入输出约定见“仿真计算说明”。
• 制导仿真显示位置与目标虚线，结束后显示末点目标距离；仿真用于算法比较，不能替代实机保护。

十一、程序设置与文件命名
• 常用与文件：存储位置、启动动画、鼠标导入、文件命名；计算与通讯：解释器、模型、解析、告警、协议；数据与分析：12 路用户名称与显示项目。
• 鼠标仅导入 .cur；同一个箭头在深浅主题共用，无需切换再导入。保存本地副本，“恢复默认鼠标”恢复主题默认样式；手形/文本/平移/缩放/等待保留相应默认光标。
• 命名模板用 {参数完整英文名} 读取当前表格值；支持 {date}、{time}、{datetime}、{type}、{n}。不填扩展名，保存时自动添加。
• 自定义参数填 名称=值，以分号或换行分隔，模板用 {名称} 引用；名称以英文字母开头，包含字母/数字/下划线，最多 32 字符。
• 未定义参数显示 UNSET-名称；非法文件名字符换成下划线，重名自动追加序号；预览即时更新，每次保存仍可改名称与位置。
• 例：{datetime}_{type}_N{n}；PID 例：P-Kp{Kp_att_pitch}_Kd{Kd_att_pitch}__N{n}。
• 新选存储位置创建 WATERPOCKET 目录；旧配置继续使用已保存路径，更改存储位置只改变后续默认路径，已有文件及正在记录的文件不搬迁。
• 12 路用户数据使用 F1～FC；编辑名称短暂停顿或离开输入框后保存，不需逐字重建绘图。

十二、事件告警与安全
• 告警监测失联、低帧率、传感器越界、PWM 和磁场异常；显示活动/恢复，声音可独立关闭。忽略告警或声音失败不停止遥测、绘图、记录和调参。
• 在设置中启停告警、查看事件及导入/导出 .wralert。模板首行为 WRGS-ALERT-TEMPLATE 1，编辑注释说明对应的等号右侧值后重新导入。
• 告警恢复只说明测量回到阈值内，不保证现场安全。校准与偏航归中在板端执行；按指示保持静止，等待板端完成回执。
• 地面站不能替代板端限幅、失联保护、传感器检查和急停。实际试验前确认方向、机构限位、参数范围与板端保护。

十三、通信格式与对应代码
• 运行组件/协议文档/ANO帧与TEE格式说明.txt：当前接收帧、参数、身份、校准、偏航归中、自定义文字和文件格式。
• 运行组件/协议文档/wrgs_board_example.c：GET、SET、兼容 SETALL、行缓冲和身份消息的通用 C 适配示例。
• 程序设置可导出协议及同一份示例。SETALL 仅供旧接口参考，当前选中参数发送逐条 SET。
• 示例不是现用飞控固件。需绑定真实变量、UART、并发保护和安全范围；ZEROCAL/YAWZERO 必须接实际固件处理，不能伪造成功回执。本轮没有修改或验证实机固件。

十四、推荐流程与兼容检查
• 连接 → 确认有效遥测 → 读取参数 → 按需独立开启记录/波形/录像 → 试验 → 保存 → 回放/分析。
• 旧 TEE/CSV 保持可读；告警、名称或定位缺失按缺少该功能处理。原始格式与指标导出不同，不要混作原始数据。
• 跨设备使用先检查 Windows 100%/125%/150%/175% 缩放、最大化/恢复及双屏不同 DPI。按钮、文字、页签、图表和分隔栏应完整可见。
• 实际串口、摄像头编码与低性能设备体验仍需现场复测；遇到异常记录版本、EXE SHA-256、系统缩放和操作步骤。

十五、程序异常与诊断记录
• 正常启动后自动保存本地程序错误日志：%LocalAppData%/WaterRocketGroundStation/Diagnostics。包含异常、切页/绘图/文件阶段耗时及后台任务入口；不需要打开诊断页面，不自动上传。
• 已观察到严重 UI/后台程序错误时，顶栏显示“程序异常 / 状态待确认”，尝试生成 crash-时间.zip；即使进程还在，也不说明功能正常。保留证据并重新启动后继续试验。
• 现场包包含异常堆栈、页面/环境状态与有限日志尾部，不读取原始遥测/录像或完整进程内存。强制结束、断电、部分原生崩溃及不可写目录可能没有最后记录。
• 卡顿、闪烁或遮挡未必抛出异常；请提供触发步骤与画面，开发者结合日志做同版本/同数据的设置对照，不能仅凭无异常认定软件正常。
• 启动失败时尝试在 EXE 同目录写入 startup_error.txt，包含异常类型、信息和堆栈；启动动画异常另写 startup-animation-error.txt。写入失败时不能保证生成文件。
• 切页诊断默认关闭；设置环境变量 GROUNDSTATION_TRANSITION_REPORT 后，可在 %LOCALAPPDATA%\WaterRocketGroundStation\page-transition-runtime.txt 查看时间、程序路径与切页记录，文件超过约 64 KB 时重置。它只覆盖已有切页诊断点，不能完整检测卡死或所有绘制异常。
• 自动测试输出用于开发验证，不是正常运行时自动收集的日志。目前不自动上传这些文件；现场报错时可保留实际错误文件及触发操作说明。
