硬件连接问题

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() 前配置相机参数，而非在时序内部