OpenFlight连接高尔夫模拟器:实时把球速数据流式推送到GSPro、OpenGolfSim和PAR-TEE
OpenFlight连接高尔夫模拟器:实时把球速数据流式推送到GSPro、OpenGolfSim和PAR-TEE
OpenFlight 是一款开源的 DIY 高尔夫击球监测器,基于 OPS243-A 多普勒雷达测量球速。除了自带的 Web 界面,它还能通过 OpenConnect V1 协议,把每一杆的球速、发射角、旋转等数据实时流式推送到 GSPro、OpenGolfSim 和 PAR-TEE 三款高尔夫模拟器,让 DIY 雷达和模拟器画面同步起飞。
1 分钟看懂连接原理
OpenFlight 的模拟器连接器是可选且可叠加的:你可以同时开启 0 个、1 个或多个目标,例如 GSPro 和 OpenGolfSim 同时接收。检测击球的管线完全不被修改——连接器只是挂在每杆结果上的"监听者"。
整条数据流大致如下:
OPS243 + 可选角度雷达 ──► 击球管线 ──► on_shot_detected()
▼
解析 + 兜底填充 (sim/resolver.py)
▼
OpenConnect V1 编码 ──TCP──► GSPro :921 / OpenGolfSim :3111 / PAR-TEE :921
核心设计是把"所有模拟器共用的部分"和"某个协议专属的部分"拆开:
| 层 | 文件 | 职责 |
|---|---|---|
| 传输层 | sim/transport.py | TCP 连接、自动重连/退避、JSON 帧、心跳 |
| 解析层 | sim/resolver.py | 把 Shot 解析为带"实测/估算"来源标记的完整字段,缺失值按球杆模型兜底 |
| 协议编码 | gspro/codec.py 等 | 把字段序列化为各家线上格式、解析模拟器回传消息 |
也就是说:球速缺失才会丢杆,其余字段都有模型兜底,推送永远尽量完整。
一键开启:--sim 参数与 sim.json
连接器默认关闭,开启只需两步:
- 复制示例配置(三个连接器都在里面,全部
enabled: false):
cp config/sim.example.json config/sim.json
- 把你要用的连接器改为
"enabled": true并填上目标 IP,然后用--sim启动:
scripts/start-kiosk.sh --sim
没有 --sim 时,无论文件里怎么配置连接器都不会启动。启动后,界面顶部会为每个连接器显示一个状态胶囊:绿色 = 已连接,琥珀色 = 连接中/重连中,红色 = 出错,灰色 = 未启用。开启调试模式后,每杆还有一个 "Sent to <模拟器>" 面板,逐项展示发送的值并标注 M(实测)/ E(估算)。
三个连接器共用同一套 OpenConnect V1 编解码,区别只在名称和默认端口:GSPro 921、OpenGolfSim 的 Developer API 3111、PAR-TEE 921。
连接 GSPro 的完整步骤
前提:GSPro 需为 OpenAPI / OpenConnect 许可证类型(用 GSPro 官方的许可证转换工具一次性转换),且 OpenFlight 所在的树莓派与 GSPro 电脑在同一局域网。
- 用
ipconfig记下 GSPro 电脑的 IP(如192.168.1.50),并在 Windows 防火墙放行 入站 TCP 921(GSPro 安装程序通常会自动加规则)。 - 配置 sim.json:
{
"connectors": [
{
"type": "gspro",
"enabled": true,
"host": "192.168.1.50",
"port": 921,
"device_id": "OpenFlight",
"units": "Yards",
"heartbeat_interval_s": 5
}
]
}
scripts/start-kiosk.sh --sim启动,打开 GSPro 并开始一场球局,进入 GSPro Connect 窗口——它应显示"等待连接"。- 顶部 GSPro 胶囊变绿即表示已连接,此时开一杆,几毫秒内就会出现在 GSPro 里。
连接 OpenGolfSim
OpenGolfSim 自带 Developer API 设备(TCP 3111),说的就是 OpenConnect V1,所以复用 GSPro 那套共享编码:
- 在 OpenGolfSim 中选择 Developer API 击球监测设备,记下其电脑 IP(如
192.168.1.60); - 配置:
{ "type": "opengolfsim", "enabled": true, "host": "192.168.1.60", "port": 3111 }; --sim启动,胶囊变绿后即可开杆。
球杆同步小技巧:OGS 的 Developer API 回传的 201 Player 消息里原本写死了 Club: "DR"。仓库自带 scripts/setup/opengolfsim/ 补丁,打上后 OGS 会在切换球杆时把真实球杆推给 OpenFlight,其落点/旋转模型随之更新。不打补丁也能正常推送击球,只是需要手动在 OpenFlight 端选杆。
连接 PAR-TEE(iPhone / iPad)
PAR-TEE 是 iOS 端的高尔夫模拟器,监听手机自身的 Wi-Fi 地址(默认 TCP 921):
- 在 PAR-TEE 中进入 Settings → MONITOR → DEVICE → OPENFLIGHT(需要 1.2+),记下显示的地址如
192.168.1.70:921; - 配置:
{ "type": "partee", "enabled": true, "host": "192.168.1.70", "port": 921 }; - 确保树莓派与手机在同一 Wi-Fi,PAR-TEE 保持在前台,然后
--sim启动。
注意 PAR-TEE 只在"可击球"界面(练习场或静止球的球洞)才会播放击球,其他界面会确认收到但直接丢弃。PAR-TEE 没有推杆选择器,球杆在 OpenFlight 端照常设置即可。
到底推了哪些数据?
以 GSPro 为例(PAR-TEE 基本相同):
| 字段 | 来源 |
|---|---|
BallData.Speed |
实测球速(必填,缺失即丢杆) |
BallData.VLA / HLA |
实测发射角,否则按模型兜底 |
BallData.TotalSpin |
高置信度时用实测旋转,否则用当前球杆模型值 |
BallData.SpinAxis |
实测旋转轴,否则 0 |
BallData.CarryDistance |
OpenFlight 弹道模型估算 |
ClubData.Speed / Path |
有实测则发送 |
值得强调的是"来源诚实":每个字段都被标记为 measured 或 estimated,UI 端渲染统一的 M/E 徽章,你能清楚知道模拟器里的每个数来自雷达还是模型。
状态胶囊与常见排错
- 胶囊一直琥珀色:连不上
host:port。检查 IP、端口是否放行(GSPro 921 / OGS 3111)、--sim是否加了。OpenFlight 会按 1→2→4→…→30 秒指数退避自动重连。 - 杆被确认但不播放:目标模拟器不在可击球界面(OGS/PAR-TEE 都如此),检查会话日志里的
sim_send条目确认 OpenFlight 确实发出了。 - GSPro 无法选择 OpenAPI:许可证类型未转换,转换后清除 GSPro Connect 设置再重启。
- OGS 球杆一直显示 DR:球杆同步补丁未生效,重新执行补丁脚本。
每个连接器还会向会话日志(JSONL)写入 sim_send(发送了哪些字段及来源)、sim_status(连接状态变化)、sim_player(模拟器回传的球杆更新),方便回溯排查。
延伸阅读
- 连接器架构总览:docs/using/simulator/index.md
- GSPro 专页:docs/using/simulator/gspro.md
- OpenGolfSim 专页:docs/using/simulator/opengolfsim.md
- PAR-TEE 专页:docs/using/simulator/partee.md
- 示例配置:config/sim.example.json
- 模拟器连接器源码:src/openflight/sim/


