硬件连接问题

FPGA 控制器未响应

症状：实验启动时提示 “FPGA not responding”

排查步骤：

1. 检查 USB 连接是否牢固
2. 确认 FPGA 电源指示灯亮起
3. 运行 quatm.drivers.zynq.test_connection() 测试通信
4. 检查设备管理器中 FPGA 驱动是否正常加载

相机图像全黑

症状：ImageClient 收到的图像数据全为零

排查步骤：

1. 确认相机电源和冷却系统正常工作
2. 检查相机温度是否达到设定值（通常 -60°C 以下）
3. 确认镜头盖已取下
4. 使用相机自带软件测试是否有图像输出

DDS 无信号输出

症状：RF 信号功率为零或无频率输出

排查步骤：

1. 检查 DDS 板电源连接
2. 确认频率和幅度设置在有效范围内
3. 使用示波器直接测量 DDS 输出端
4. 检查 device_db.py 中 DDS 通道配置是否正确

软件问题

实验脚本加载失败

症状：Experiment Browser 中无法加载实验文件

排查步骤：

1. 确认实验文件在 experiments/ 目录下
2. 检查 build() 方法中使用 setattr_device() 声明的设备名是否与 device_db.py 一致
3. 查看终端输出的错误信息定位具体原因

数据分析结果异常

症状：拟合曲线与预期偏差大，或拟合失败

排查步骤：

1. 检查输入数据流名称是否与实际发布的一致
2. 确认拟合初始值在合理范围内
3. 使用图像监视器查看原始数据和 ROI 设置
4. 检查是否有数据流名称冲突（两个模块发布同名流）

内存不足

症状：长时间运行后系统内存占用持续增长

解决方案：

1. 检查是否有未关闭的数据客户端订阅
2. 使用 DataManager 而非手动管理 HDF5 写入
3. 定期清理不再需要的数据流订阅
4. 考虑使用 numpy.float32 替代 float64 减小内存占用

性能优化

实验时序抖动

症状：实际时序与设定值存在不稳定偏差

排查步骤：

1. 减少 realtime() 上下文中的 Python 代码
2. 关闭不必要的后台进程（如数据分析、数据记录）
3. 检查 FPGA 进程文件是否过大
4. 使用 priority 参数设置实验进程优先级

图像采集延迟

症状：相机触发与预期时间存在延迟

解决方案：

1. 减小相机 ROI 以提高帧率
2. 使用硬件触发而非软件轮询
3. 在 realtime() 前配置相机参数，而非在时序内部

Web 远程控制问题

浏览器打不开 Web 控制台

症状：访问 http://<实验PC>:8000 无响应

排查步骤：

1. 确认实验 PC 上 Web Hub 服务已启动（进程管理器中显示绿色）；
2. 检查端口是否被占用（日志提示 “端口可能已被占用”），可改用 --port 换端口；
3. 若用旧版本安装，可能缺少 quatm.web 子包：重新 pip install -e .；
4. 防火墙放行对应端口（局域网访问）。

页面改动不生效

症状：前端界面行为异常或新功能未出现

解决：强制刷新浏览器（Ctrl+Shift+R / 清缓存）：静态文件带 Cache-Control: no-cache，但个别浏览器或代理可能仍使用旧缓存。

实时数据面板无数据

症状：Web「数据」页实时追踪只有 X 轴、Y 轴无数据

排查步骤：

1. 确认实验正在运行且数据通道已发布（分析脚本运行的拟合结果）；
2. 分析脚本发布的消息需带 timestamp 字段（与桌面 DataSummary 相同契约）；
3. 若 Y 下拉没有任何字段，先确认监控页能看到数据通道：Hub 网络不通时 Web 与桌面均无法收到数据。