pygpsclient 说明翻译

pygpsclient · PyPI

PyGPSClient 是一个免费的开源、跨平台的图形化 GNSS/GPS 测试、诊断和配置应用程序，完全由志愿者使用 Python 和 tkinter 编写。

运行在任何支持 Python 3 解释器（>=3.10）和 tkinter（>=8.6）GUI 框架的平台上，包括 Windows、MacOS、Linux 和树莓派操作系统。

支持 NMEA、UBX、SBF、QGC、RTCM3、NTRIP、SPARTN、MQTT 和 TTY (ASCII) 协议。

能够读取各种 GNSS 数据流：串行（USB / UART）、套接字（TCP / UDP）、二进制数据流（终端或文件捕获）和二进制记录（例如 u-center *.ubx）。

提供 NTRIP 和 SPARTN 客户端功能。

可以作为 NTRIP 基站，配合 RTK 兼容接收机使用（例如 u-blox ZED-F9P/ZED-X20P、Quectel LG290P/LG580P/LC29H 和 Septentrio Mosaic G5/X5）。

通过专有 UBX、NMEA 和 ASCII TTY 协议支持 GNSS（及相关）设备配置，包括大多数 u-blox、Quectel、Septentrio 和 Feyman GNSS 设备。

可以使用标准的 Python 包管理器进行安装 - 请参阅下面的安装说明。

这是一个独立项目，我们与任何 GNSS 制造商或分销商没有任何关联。

Current Status

略

Installation

略，参考以下文章

https://blog.csdn.net/LJX_wantAC/article/details/154918235

Instructions

注：部分超链接未标注，对这方面的功能感兴趣的话仍需阅读原文

1. 通过 USB 或 UART 端口连接 GNSS 接收器：从列表框中选择设备，设置合适的串口连接参数，然后点击图标 。应用会尝试自动预选已识别的 GNSS/GPS 设备，但这取决于平台和设备。点击刷新按钮  可更新已连接设备列表。（波特率）通常是唯一可能需要调整的参数，不过微调该设置可能会提升部分平台的性能。参数默认为向接收设备周期性或轮询响应消息。若需解析接收设备的命令流或轮询消息流，将设置为或 。还可设置可选的串口 / 套接字流闲置超时（单位：秒；0 = 无超时）。

2. 自定义串口可通过 JSON 配置文件设置、环境变量或命令行参数来指定自定义串口。若将 “userport” 值设为 “ubxsimulator”，会调用实验性工具，用于模拟 GNSS 的 NMEA/UBX 串口数据流。

3. 连接 TCP 或 UDP 套接字：输入服务器 URL 和端口，选择协议（默认是 TCP），然后点击图标。若为加密 TLS 连接，勾选 “TLS” 复选框；若要适配自签名 TLS 证书（通常用于测试或演示服务），勾选 “Self Sign” 复选框。

4. 从已保存的二进制数据日志文件流读取：点击图标，选择文件类型与路径。PyGPSClient 的数据日志文件命名示例如，但任何 GNSS 接收器输出的二进制转储文件均支持（包括 u-center 生成的 .log、 .ubx等文件）。

5. 断开数据流连接：点击。

第1~5条介绍的是右上角的界面

6. 退出应用：点击 ，或按下快捷键 Ctrl+Q，或点击应用窗口的关闭按钮。

7. 强制终止：按下快捷键 Ctrl+K（“终止开关”），可立即断开连接并终止所有运行中的线程。

8. 协议显示：选择需要展示的协议（包括 NMEA、UBX、SBF、QGC、RTCM3、SPARTN 或 TTY）。

注意：此操作仅改变显示的协议；若需修改接收器实际输出的协议，需使用 “UBX 配置对话框”。

补充说明：切换至 TTY（终端）协议或从该协议切换前，必须停止串口连接。补充说明：启用 TTY（终端）模式后，其他所有协议都会被禁用。

9. 控制台显示格式：选择控制台的显示格式（包括Parsed[解析后文本]、Binary[二进制]、Hex Tabular[十六进制表格]、Hex String[十六进制字符串]、Parsed+Hex Tabular[解析后文本 + 十六进制表格]，具体可参考下方的控制台组件）。

10. 最大行数：选择控制台中保留的可滚动显示行数。

11. 文件读取延迟：选择从二进制文件流读取时，单次读取之间的延迟（单位：毫秒，默认 20 毫秒）。

12. 颜色标签：启用控制台中的颜色标签（详情见下方控制台组件）。

13. 位置格式与单位：修改位置的显示格式（包括十进制度 D.DD、度分秒 D.M.S、度分分 D.M.MM、地心地固坐标系 ECEF），以及单位格式（公制metric / 英制imperial）。

14. 显示未使用卫星：在图表与天空视图面板中，包含或排除未用于导航解算的卫星（例如信号强度过低的卫星）。

15. 数据日志：开启或关闭选定格式的数据日志功能。首次选择时，会提示选择保存带时间戳日志文件的目录。

16. GPX 轨迹：开启或关闭 GPX 格式的轨迹记录功能。首次选择时，会提示选择保存带时间戳 GPX 轨迹文件的目录。

17. 数据库：开启或关闭 SpatiaLite 数据库记录功能（若可用）。首次选择时，会提示选择数据库的保存目录。注意：数据库首次创建时，其空间元数据初始化需要几秒时间（在树莓派及类似单板计算机上最长可能需要 1 分钟）。此功能依赖 Python 环境支持所需的pygpsclient.sqlite、sqlite3 extension、mod_spatialite（详情见INSTALLATION.md）若环境不支持，该选项会呈灰色不可用状态。可通过 “Menu→Help→About” 对话框查看当前 SpatiaLite 的支持状态。

补充：提供了从该数据库检索数据的辅助方法，详情见Sphinx documentation 及retrieve_data.py示例。

18. 保存配置：要将当前配置保存到文件，可通过 “File→Save Configuration” 操作。

19. 加载配置文件：要加载已保存的配置文件，可通过 “File→Load Configuration” 操作。默认配置文件路径为 $HOME/pygpsclient.json。

注意：加载新配置前，必须停止当前活跃的串口或 RTK 连接。

20. 套接字服务器 / NTRIP 播发器：该功能包含两种运行模式：(a) 开放、无认证的套接字服务器；(b) NTRIP 播发器（挂载点由pygnsutils定义）。

21. UBX 配置对话框：可向 u-blox GNSS 设备发送各类 UBX CFG 配置指令，支持添加自定义指令或指令序列（详情见下方 “自定义预设” 说明）。仅当通过串口连接至 UBX GNSS 设备时，该对话框才可使用；可通过点击，或 “Menu→Options→UBX Configuration Dialog” 打开。

22. NMEA 配置对话框：可向 GNSS 设备（如移远 LG290P）发送各类 NMEA 配置指令，支持添加自定义指令或指令序列（详情见下方 “自定义预设” 说明）。仅当通过串口连接至兼容的 GNSS 设备时，该对话框才可使用；可通过点击，或 “Menu→Options→NMEA  Configuration” 打开。

23. TTY 配置对话框：可向 GNSS 及相关设备（如 Septentrio X5、Feyman IM19）发送各类 TTY（ASCII）配置指令，支持添加自定义指令或指令序列（详情见下方 “自定义预设” 说明）。仅当通过串口连接至兼容的 GNSS 设备时，该对话框才可使用；可通过点击，或 “Menu→Options→TTY Comands” 打开。

24. NTRIP 客户端：可连接至指定 NTRIP 播发器，解析传入的 RTCM3 或 SPARTN 数据并将其馈送至兼容的 GNSS 接收器（需联网、有权访问 NTRIP 播发器及本地挂载点）。可通过点击对应图标，或 “Menu→Options→NTRIP Configuration” 打开 NTRIP 客户端配置界面。

25. SPARTN 客户端：可配置 IP 或 L 波段 SPARTN 校正源，以及 SPARTN 兼容的 GNSS 接收器（如 ZED-F9P），并将传入的校正数据传递至 GNSS 接收器（需联网、有权访问 SPARTN 定位服务）。可通过 “Menu→Options→SPARTN Configuration Dialog” 打开 SPARTN 客户端配置界面。

26. GPX 轨迹查看器：该工具可展示轨迹的海拔、速度曲线及元数据。要打开 GPX 轨迹查看器，可通过 “Menu→Options→GPX Track Viewer” 操作。

Configuration settings

PyGPSClient 的配置设置可通过 “Menu→File→Save Configuration” 和 “Menu→File→Load Configuration options” 选项进行保存与调用。默认情况下，PyGPSClient 会在用户主目录中查找名为 pygpsclient.json 的文件。部分配置（如自定义预设的 UBX、NMEA、TTY 指令及标签配色方案）需手动编辑，详情见下文说明。

Checking for the latest version

“About” 对话框（Menu→help→About）包含检查 PyGPSClient 及其附属模块最新版本的功能，并可触发自动更新。勾选 “Check on stratup” 框，可在应用启动时执行版本检查（注意：此功能需联网，在低带宽 / 高延迟网络环境的设备上可能会延长启动时间）。受技术限制，该功能在部分通过 Homebrew 安装的 Python 环境中可能无法使用。

GUI refresh rate setting

PyGPSClient 会 “实时” 处理所有传入的 GNSS 数据，但默认情况下，GUI 每 0.5 秒刷新一次。可通过 JSON 配置文件中的 guiupdateinterval_f 设置调整刷新频率。注意：在性能较低的设备（如树莓派）上，若 GUI 更新间隔小于 0.1 秒，且数据消息频率较高时，PyGPSClient 可能会出现无响应的情况；而在性能更强的设备上，可支持≤0.1 秒的更新间隔。

Transient dialog setting

一项布尔型配置设置用于控制弹出对话框是否为 “临时模式”（即始终显示在主应用对话框的顶层）。默认设置允许弹出对话框独立于主应用窗口最小化，但需注意部分对话框可能会被其他窗口遮挡（例如 “Open file / folder” 对话框）。若 “打开文件” 按钮看似无响应，请检查 ““Open file / folder”面板是否已打开但被遮挡。

对应配置项：transient_dialog_b（默认值为 0）

User-selectable'widgets' 用户可选择的部件

显示或隐藏部件，在“Menu→View”点击相关的hide/show按钮

1. 导航状态横幅

可展开的横幅，基于接收器接收的消息展示关键导航状态信息。点击▼/▲按钮可展开 / 折叠该横幅或串口配置组件。注意：部分字段（如 hdop/vdop、hacc/vacc）仅能从专有 NMEA 或 UBX 消息中获取，默认可能不输出。填充所有字段所需的最小消息集：- NMEA：GGA、GSA、GSV、RMC、UBX0（专有）- UBX：NAV-DOP、NAV-PVT、NAV_SAT

2. Console 串口控制台

可配置的串口控制台组件，支持以解析后文本、二进制或十六进制表格格式显示传入的 GNSS 数据流。右键双击可将控制台内容复制到剪贴板。控制台的滚动行为与保留行数可通过设置面板配置，支持自定义颜色标签标记指定字符串以方便识别。颜色标签从 JSON 配置文件的 colortag_b（0 = 禁用，1 = 启用）和 colortags_l（[字符串，颜色] 对列表）加载。若颜色设为 “HALT”，匹配到对应内容时数据流会暂停并显示警告。注意：颜色标签会带来轻微性能开销，在高事务速率场景下，关闭该功能可提升控制台响应速度。

3. Satellites 天空视图

展示当前卫星可见性与位置（仰角 / 方位角）的组件，卫星图标边框通过颜色区分不同 GNSS 星座。为保持 NMEA 与 UBX 数据源的一致性，GLONASS 会显示 NMEA 卫星编号（65-96）而非时隙号（1-24）。

4. Levels 卫星信号视图

展示各 GNSS 星座当前卫星载噪比（CNo）的组件，双击可切换图例显示状态。

5. Map 基础地图（含离线 “world” 模式）

支持多显示模式的地图组件：可选择 “map”/“sat”（在线）或 “world”/“custom”（离线）模式，缩放级别可选 1-20。双击缩放级别标签可重置缩放至 10；右键双击缩放标签可最大化缩放至 20；勾选 “Track” 可显示轨迹（仅勾选期间会记录轨迹）；右键双击地图可清空内容。当地图类型为 “world” 时，显示静态离线墨卡托世界地图，用于展示当前全球位置。

6. 在线地图（“map”/“sat”/“hyb” 模式）

地图类型为 “map”（地图）、“sat”（卫星）或 “hyb”（混合）时，通过 MapQuest API 加载动态在线网络地图或卫星影像（需联网及免费 MapQuest API 密钥）。默认每 60 秒自动刷新（左上角会显示小型计时器图标），刷新频率可通过 JSON 配置文件中的 mapupdateinterval_n修改。注意：此功能不用于实时导航；双击地图任意位置可立即刷新。

7. 自定义离线地图（“custom” 模式）

可通过 “菜单→选项→导入自定义地图” 功能，或手动修改 JSON 配置文件导入一个或多个带地理参考的离线地图。配置格式为 ["地图图片路径", [最小纬度, 最小经度, 最大纬度, 最大经度]]，详情见示例配置文件。地图图片需为支持的格式，并采用标准 WGS84 Web 墨卡托投影（如 EPSG:4326）。PyGPSClient 会根据地图在配置中的顺序，自动选择范围包含当前位置的首张图片。注意：可用缩放级别的上下限取决于导入图片的分辨率、范围及用户显示器；若缩放范围超出图片范围，缩放选择框会高亮提示。

8. 导入自定义地图对话框

点击对应图标可打开自定义地图图片路径选择界面（默认文件后缀为 .tif，选择 “显示选项” 可选择任意后缀）。若已安装对应库且图片已地理配准（如通过 QGIS 处理），地图范围会自动提取；否则需手动输入。点击箭头按钮可导入自定义地图的路径与范围设置。默认情况下，导入的地图会追加到现有列表中；点击 “First” 可将其插入列表顶部。关于如何创建适配的地理配准地图图片，可参考《为 PyGPSClient 创建自定义地图》文档。

9. Spectrum 频谱分析组件

展示频谱分析图表的组件（需 GNSS 接收器支持输出 UBX MON-SPAN 消息）。点击图表任意位置可显示该点的频率与分贝值；双击图表可切换 GNSS 频段标记（L1、G2 等）的显示 / 隐藏；右键点击图表可捕获频谱数据快照并叠加在实时数据上；右键双击可清除快照。注意：部分接收器（如 NEO-F10N）需将端口波特率至少设为 57600，才会输出所需的 MON-SPAN 消息。

10. System Monitor 系统监控组件

展示设备 CPU、内存与 I/O 使用率的组件（需 GNSS 接收器支持输出 UBX MON-SYS/MON-COMM 或 SBF ReceiverStatus 消息）。勾选复选框可在实际（累计）I/O 状态与待处理 I/O 之间切换。该组件主要适配 u-blox 模块，对其他设备仅能显示有限的系统信息。

11. Scatter Plot 散点图组件

展示位置报告随时间变化波动性的组件。可（可选）输入固定参考位置：选择 “Average” 可将图表中心设为动态平均位置（显示在左上方）；选择 “Fixed” 可将中心设为已输入的固定参考位置。勾选 “Autorange” 可自动设置图表范围；设置更新间隔（如 4 = 每 4 次导航解算更新一次）；通过范围滑块或鼠标滚轮调整图表范围；右键点击可将固定参考点设为当前鼠标光标位置；双击可清除现有数据。

12. Rover Plot 移动站组件

用于绘制动态移动站在 “固定 / 移动基准站 - 移动站”RTK 配置下的相对二维位置、轨迹与状态信息；也可在静态 RTK 配置中展示 NTRIP 挂载点与接收器的相对位置。双击可清除现有绘图内容。

13. Chart Plot 图表组件

作为多通道 “绘图工具”，支持从任意解析后的 GNSS 数据源中，绘制一系列命名数值数据属性，可配置 Y 轴（数值）与 X 轴（时间）。默认通道数为 4，用户可通过 JSON 配置文件的 chartsettings_d（含 numchn_n项）手动修改。每个通道可配置：（可选）消息源标识（如 NAV-PVT）、属性名称（如 hAcc）、缩放因子（除数，如 1000）、Y 轴范围（如 0-5）。属性组支持通配符： *（组值平均值）、 +（组值最大值）、 -（组值最小值），例如 cno*可绘制卫星组的载噪比平均值。操作：双击可清除现有数据；右键双击可将当前图表数据以 CSV 格式保存至剪贴板，可直接粘贴到电子表格应用中。

14. IMU Monitor IMU 监控组件

展示 IMU（惯性测量单元）当前姿态（横滚、俯仰、偏航）与状态的组件，数据来自任意 IMU / 航位推算消息源。支持选择角度范围（±1 至 ±180 度）。

UBX Configuration Facilities

Pre-Requisites

u-blox GNSS 接收器需通过 USB 或 UART 端口连接至工作站。注意：u-blox 在第 9 代设备（ROM 协议≥23.01）中引入了新配置机制。部分 UBX 配置指令（如CFG-PRT、CFG-RATE）仅适用于旧设备（如 NEO-M6S、NEO-M8P）；其他指令（如CFG-MSG、CFG-VALSET、CFG-VALDEL）仅适用于新设备（如 NEO-M9、ZED-F9P、ZED-X20P）。注意：UBX 协议不支持同步指令确认或唯一确认 ID。在高消息传输速率下，异步指令、轮询的确认与响应可能需要数秒，若设备发送缓冲区已满（txbuff-alloc error），响应甚至会被直接丢弃。如需及时响应，可尝试提高波特率，或通过配置指令临时降低消息传输速率。警告图标（通常伴随 ACK-NAK 响应）通常表示接收器不支持所发送的一条或多条指令（如协议不匹配）。

补充说明：

配置指令可通过 TCP 套接字发送，但接收端需配备第三方或定制的 TCP-UART 转换器。不直接支持 I2C（QWIIC），但可通过第三方 I2C-UART 适配器实现兼容。

Instructions

UBX 配置对话框当前提供以下 UBX 配置面板：

1. 版本面板：通过 MON-VER 和 MON-HW 轮询，显示设备当前的硬件 / 固件版本。

2. CFG 配置加载Load / 保存Save / 记录功Record能：支持记录一系列 UBX CFG 配置指令，并将记录保存为文件（以二进制 CFG-* 消息格式）。已保存的文件可重新加载，且配置指令可回放。该功能可快速复现特定配置指令序列，或在兼容设备间复制已保存的配置。配置加载 / 保存 / 记录功能支持二进制 UBX 格式（*.ubx）或 u-center 文本格式（*.txt）的配置文件；通过pygnssutils库安装的ubxsave命令行工具保存的文件，也可加载和回放。

提示：二进制配置文件的内容可通过 PyGPSClient 的文件流功能查看，但需在设置面板中将消息模式设为 “GET” 而非默认的 “SET”。

3. 协议配置面板（CFG-PRT）：设置所有可用端口的波特率及入站 / 出站协议（仅支持旧协议）。

4. 解算速率面板（CFG-RATE）：设置导航解算间隔（单位：毫秒，如 1000=1 次 / 秒）与测量比值（测量次数与导航解算次数的比例，如 5 = 每次解算对应 5 次测量）（仅支持旧协议）。

5. 对于上述所有面板，点击面板背景任意位置，可刷新显示当前配置信息。

6. 消息速率面板（CFG-MSG）：设置各端口的 UBX 与 NMEA 消息速率（仅支持旧协议）。

消息速率与导航解算频率相关，例如速率 “4” 表示 “每 4 次导航解算发送一次消息”（数值越大，频率越低）。

7. 配置接口组件（CFG-VALSET，CFG-VALDEL和CFG-VALGET）：仅支持现代协议的查询与设置配置。

8. UBX 传统指令配置面板 为一系列传统 CFG-* 配置指令提供结构化更新功能（仅支持旧协议）。注意：“X”（字节）类型的属性可输入整数或十六进制字符串（如 522125312 或 0x1f1f0000）。选择指令后，系统会轮询当前配置并显示数值；用户可按需修改数值后发送更新后的配置。部分轮询需要输入参数（如 portID）—— 这些参数会高亮显示，初始设为默认值（如 portID=0），用户可修改后点击重新轮询。

9. 预设指令组件支持各类用户自定义的 UBX 指令与查询，详情见 “自定义预设”。

指令确认状态标识每个 “发送” 按钮右侧的图标用于指示配置指令的确认状态：待确认（等待响应），已确认，警告

NEMA Configuration Facilities

Pre-Requisites

接收器需支持通过专有 NMEA 语句进行配置，并通过 USB 或 UART 端口连接至工作站。该功能支持多款移远（Quectel）LG 与 LC 系列接收器，适配 PQTM*、PSTM*、PAIR * 语句。底层 NMEA 解析库pynmeagps的后续版本可能支持更多接收器类型（欢迎社区贡献）。

Instructions

NMEA 配置对话框目前提供以下 NMEA 配置面板：

版本面板显示当前设备的硬件 / 固件版本（通过 PQTMVERNO 轮询实现）。动态配置面板为受支持的接收器提供结构化更新，例如：移远通信 LG290P 通过 PQTM语句，或 LC29H 通过 PAIR语句。选择命令后，系统会轮询配置并显示当前值；用户可按需修改这些值并发送更新后的配置。部分轮询需要输入参数（如 portid 或 msgname）—— 这些参数会被高亮显示，初始时设为默认值（如 portid=1），但用户可修改参数并通过 “” 按钮重新轮询。预设命令组件支持多种用户自定义的 NMEA 命令与查询 —— 详见用户自定义预设。

每个 “SEND”按钮右侧的图标用于指示配置命令的确认状态：（待确认，已确认或警告）。

注意：部分移远通信 LG 和 LC 系列命令需执行热重启（PQT MHOT）才能生效，包括 PQTM CFGCNST（启用 / 禁用星座）、PQTM CFG FIX（配置定位频率）、PQTM CFGSAT（配置卫星掩码）和 PQTM CFGSIGNAL（配置信号掩码）。这是移远通信协议的限制，并非 PyGPSClient 的问题。

TTY Configuration Facilities

TTY Commands 对话框提供了向已连接的串口设备发送用户自定义 ASCII TTY 配置命令（例如 AT 指令）的功能。命令可手动输入，也可从用户自定义的预设列表中选择。可通过 TTY Config 按钮或 “Menu→Options→TTY Commands” 打开该对话框。

CRLF 复选框：若勾选，会在命令字符串后添加 CRLF 终止符（对应 b"x0dx0a"）。Echo 复选框：若勾选，发出的 TTY 命令会在控制台回显，并带有 "TTY<<"标记。Delay 复选框：若勾选，每条发出的命令之间会添加短暂延迟，以便接收设备处理命令。

预设命令可通过在 JSON 配置文件的列表中，添加适当的、以分号分隔的消息描述与负载定义来设置。详情见上文的 “用户自定义预设” 及提供的示例，对应配置项为 "ttypresets_l"。

注意：部分 GNSS 设备（如 Septentrio X5）会将配置端口与导航 / 监控端口分离为不同的 UART 端口 —— 发送 TTY 命令时请确保使用对应的 UART 端口。Septentrio 设备在接收 TTY 命令前，还需先发送 “初始化命令模式” 序列。

以下示例展示了向 Septentrio Mosaic X5 接收器发送一系列 ASCII 配置命令，以及对应的成功确认响应：

NTRIP Client Facilities

NTRIP 配置工具允许用户从 NTRIP 播发器接收并处理 NTRIP RTK 校正数据，以实现厘米级的定位精度。可通过点击对应图标，或选择 “Menu→Options→NTRIP Configuration” 来使用该功能。

Pre-Requisites

兼容 NTRIP 的 GNSS 接收器（例如 u-blox ZED-F9P）互联网连接NTRIP 播发器的 URLNTRIP 播发器的登录凭据（如需）本地挂载点名称（若不使用 PyGPSClient 的自动挂载点定位功能）数据类型（通常为 RTCM，但部分服务会以 SPARTN 格式输出数据）

Instructions

输入所需的 NTRIP 服务器 URL（或 IP 地址）与端口（默认 2101）。对于 SSL/TLS（HTTPS）连接（通常使用 443 或 2102 端口），勾选 “TLS” 复选框；若要兼容自签名 TLS 证书（通常用于测试或演示服务），勾选 “Self-Sign” 复选框。若服务需要授权，输入分配的登录用户名与密码。选择数据类型（默认 RTCM，也可设为 SPARTN）。若要获取源列表，保持挂载点字段为空并点击 “连接”（响应可能需要几秒）。随后可从列表中选择所需挂载点，或手动输入。在条件允许时，PyGPSClient 会自动识别距离当前位置最近的挂载点。对于要求通过 NMEA GGA 语句传输客户端位置数据的 NTRIP 服务，选择合适的语句传输间隔（秒）。默认值为 “无”（不发送 GGA 语句），常用值为 10 或 60 秒。若启用 GGA 语句传输，GGA 语句的数据源可选择：①实时导航数据（需接收器已连接并输出有效位置数据）；②NTRIP 配置面板中输入的固定参考设置（需填写纬度、经度、高程、大地水准面差距这四项参数）。点击按钮连接 NTRIP 服务器；点击按钮断开连接。若 NTRIP 数据接收成功，“dgps:” 状态指示器会变为 “YES”，并显示修正数据的时长与参考站信息（若可用），。注意：修正信号丢失后，DGPS 状态通常会维持至多 60 秒。部分 NTRIP 服务可能会高频输出 RTCM3 或 SPARTN 修正消息，导致 GUI 控制台显示过载。若要在控制台中隐藏这些消息，可在 “显示的协议” 中取消勾选 “RTCM” 或 “SPARTN” 选项 —— 这些消息仍会在后台继续处理。

以下是一个示例 NTRIP 差分全球定位系统（DGPS）数据日志，包含以下内容：

发出的 NMEA GPGGA 语句（客户端位置）。传入的 RTCM3 校正消息：本示例中包括 1006（参考站 ARP，DF003=2690，含天线高度）、1008（天线描述）、1033（接收器描述）、1075（GPS MSM5）、1085（GLONASS MSM5）、1095（Galileo MSM5）、1125（北斗 MSM5）和 1230（GLONASS 码相位偏差）。u-blox ZED-F9P 接收器生成的对应 UBX RXM-RTCM 确认消息：包含消息类型、校验和有效（crcFailed=0）、使用成功（msgUsed=2）及参考站 ARP（refStation=2690）的确认信息。

注意：使用本功能对接远程 NTRIP 服务时，请遵守该服务的条款与条件。若用于测试或评估，可考虑部署本地的 SNIP LITE 服务器。不当使用 NTRIP 服务可能导致你的账号被封禁。

SPARTN Client Facilities

注意：截至 2025 年 10 月，u-blox 已停用其 L 波段与 MQTT 加密的 SPARTN 校正服务，因此 SPARTN 客户端功能实际已冗余，可能在 PyGPSClient 后续版本中被移除。

SPARTN MQTT 与 L 波段配置面板目前默认处于禁用状态；不过理论上 L 波段面板仍可用于其他通用 L 波段调制解调器的配置场景，可通过将 JSON 配置参数lband_enabled_b设为 1 来重新启用。

详情请参考SPARTN.md文档。

Socket Server / NTRIP Caster Facilities

套接字服务器 / NTRIP 播发器功能支持两种运行模式：

SOCKET SERVER(套接字服务器模式)：这是一个开放、无认证的 TCP 套接字服务器，可供任意套接字客户端连接（例如另一实例的 PyGPSClient 或 gnssstreamer命令行工具）。此模式下，服务器会广播主机当前连接的 GNSS 数据流，默认端口为 5001。NTRIP(NTRIP 播发器模式)：这是一个带认证的简易 NTRIP 播发器实现，可供任意 NTRIP 客户端连接（例如 PyGPSClient 的 NTRIP 客户端功能、gnssntripclient或 BKG 的 NTRIP 客户端（BNC））。NTRIP 播发器的登录凭据可通过 JSON 配置文件中的 ntripcasteruser_s和 ntripcasterpassword_s设置，也可通过 PyGPSClient 的命令行参数（ --ntripcasteruser、 --ntripcasterpassword）或环境变量（ NTRIPCASTER_USER、 NTRIPCASTER_PASSWORD）配置。默认设置如下：绑定地址：0.0.0.0，端口：2101，挂载点：pygnssutils，用户：anon，密码：password。

默认情况下，服务器 / 播发器会绑定到主机地址 “0.0.0.0”（IPv4）或 “::”（IPv6），即主机上所有可用的 IP 地址。这一设置可通过设置面板或主机环境变量 PYGPSCLIENT_BINDADDRESS覆盖。

设置面板上的标签会显示已连接的客户端数量，服务器 / 播发器的状态会在顶部横幅中展示：无客户端连接时运行：，有客户端连接时运行：。

Pre-Requisites

以 NTRIP CASTER 模式运行的前提是：主机已连接一台工作在基准站模式下的 RTK 兼容型 GNSS 接收器（支持 “FIXED” 或 “SURVEY_IN” 模式），且该接收器能输出所需的 RTCM3 消息类型（如 1005/6、1077、1087、1097 等）。可能需要在主机或路由器上添加防火墙规则、启用端口转发，以允许指定地址：端口的远程流量访问。服务器支持加密的 TLS（HTTPS）连接。TLS 证书 / 密钥的路径可通过环境变量设置，默认路径为空。用于测试和演示的自签名 pem 文件可通过以下交互式命令创建：

PYGNSUTILS_PEMPATH $HOME/pygnsutils.pem

对应的 OpenSSL 命令：

openssl req -x509 -newkey rsa:4096 -keyout pygnssutils.pem -out pygnssutils.pem -sha256 -days 3650 -nodes

Instructions

SOCKET SERVER MODE

选择 “SOCKET SERVER” 模式，（如有需要）输入主机 IP 地址与端口。选择 “TLS” 以启用加密的 TLS（HTTPS）连接。勾选 “Socket Server/NTRIP” 复选框以激活服务器。要停止服务器，取消勾选该复选框。

NTRIP CASTER MODE

选择 “NTRIP 播发器” 模式，（如有需要）输入主机 IP 地址与端口。选择 “TLS” 以启用加密的 TLS（HTTPS）连接。会显示一个额外的可展开面板，允许用户将已连接的 RTK 兼容接收器配置为 “FIXED SURVEY-IN” 或 “Base Station” 模式（注意：仅当播发器处于停止状态时，才能修改参数）。选择接收器类型（当前支持 u-blox ZED-F9*, u-blox ZED-X20*, Quectel LG290P, Quectel LC29HBA 和 Septentrio Mosaic X5），点击 “Send” 按钮向接收器发送对应的配置指令。注意（Septentrio Mosaic X5）：这些接收器通过 ASCII TTY 指令配置 —— 若要监控指令响应，需将控制台协议设为 “TTY”（监控 RTCM3 输出时请记得改回 RTCM）。同时注意，输入（ASCII 指令）UART 端口可能与输出（RTCM3）UART 端口不同 —— 配置设备与监控 RTCM3 输出时，请确保选择对应的端口。勾选 “Disable NMEA” 可屏蔽 NMEA 消息。NTRIP 客户端的登录凭据通过 “用户” 与 “密码” 字段设置。勾选 “Socket Server/NTRIP Caster” 复选框以激活播发器。要停止播发器，取消勾选该复选框。

Base Station Configuration

1. FIXED

在此模式下，已知的基准站坐标（天线参考点，即 ARP）可通过 LLH 或 ECEF（X,Y,Z）格式指定。坐标会预填充接收器当前的导航解算结果（若可用），但通常应替换为精确测量的数值。若坐标被确认，定位状态会变为 “TIME ONLY”，接收器会开始输出包含 ECEF（X,Y,Z）格式基准站位置的 RTCM 1005 或 1006 消息。

2. SURVEY-IN

在此模式下，基准站坐标由接收器当前的导航解算结果生成，前提是在指定的测量时长内达到预设的精度要求。若测量成功，定位状态会变为 “TIME ONLY”，接收器会开始输出包含 ECEF（X,Y,Z）格式基准站位置的 RTCM 1005 或 1006 消息。基准站的测量位置会根据这些 RTCM 消息提供的位置进行更新。

3. DISABLED

禁用基准站功能。

注意：要让设备有效充当 RTK 基准站，天线的定位至关重要。可参考以下链接获取相关建议：

u-blox GNSS 天线文档Ardusimple GNSS 天线安装指南

GPX Track Viewer

GPX 轨迹查看器可显示包含轨迹点（trkpt）、路线点（rtept）或航点（wpt）元素的任意有效 GPX 文件，背景地图可选择 “custom” 离线地图图片，或在线的 MapQuest “map”（地图）、“sat”（卫星）、“hyb”（混合）视图。其中 “map”“sat”“hyb” 选项需要免费的 MapQuest API key 。Y 轴的刻度会匹配当前选择的单位（公制或英制）。若 GPX 轨迹缺少时间元素，时间轴与速度轴会标记为 “标称值”。GPX 轨迹的元数据（包括海拔与速度的最小值、最大值、平均值、中位数）会以所选单位显示。在进行任何更改（如调整尺寸、缩放或切换单位）后，点击刷新图标可更新显示内容。位置标记会指示轨迹的标称中心点。

MapQuest API Key

Pre-Requisites

若要使用可选的动态网络地图视图或 GPX 轨迹查看器功能，需申请并配置 MapQuest API 密钥。

请注意：自 2024 年 1 月 15 日起，MapQuest 要求提供支付卡信息才能使用该 API，但每月前 15000 次调用仍免费；超出 15000 次的部分，每次调用收费 0.0045 美元。更多信息请参考 FAQ。

因此，地图刷新频率被刻意限制为 1 次 / 分钟 *，以避免正常使用时超出免费调用限额。注意：此功能不用于实时导航场景。

Instructions

获取 API 密钥（32 位字母数字字符串）后，可按以下优先级顺序配置：

将密钥填写到 JSON 配置文件的 "mqapikey_s"字段中（参考提供的示例）。创建名为 MQAPIKEY的环境变量（全大写），并将其值设为 API 密钥。建议使用用户变量而非系统 / 全局变量。通过命令行参数 --mqapikey传入密钥。

* 若需修改网络地图的刷新频率，可调整 JSON 配置文件中的mapupdateinterval_n字段。

User Defined Presets

UBX、NMEA 与 TTY 配置对话框支持向兼容的接收器发送用户自定义的配置消息或消息序列。可通过在 JSON 配置文件的"ubxpresets_l" "nmeapresets_l" "ttypresets_l"设置中，添加以逗号或分号分隔的消息描述与负载定义来配置（参考提供的示例）。消息定义包含一个自由格式的文本描述（避免嵌入逗号或分号），后跟一个或多个 pyubx2（UBX）、pynmeagps（NMEA）或 tty（ASCII）消息构造器，格式示例如下：

 

若命令描述中包含CONFIRM关键词，执行命令前会弹出确认框。

PyGPSClient 首次启动时，这些设置会预填充初始预设命令集，可保存到 JSON 配置文件中，之后用户可根据需求手动删除、修改或补充。若后续需恢复初始预设集，可在对应的"ubxpresets_l" "nmeapresets_l" "ttypresets_l"配置项顶部添加"INIT_PRESETS"。

pygpsclient.ubx2preset()与pygpsclient.nmea2preset()辅助函数可将UBXMessage或NMEAMessage对象转换为预设字符串，便于复制粘贴到"ubxpresets_l"或"nmeapresets_l"的JSON配置部分。

from pygpsclient import ubx2preset, nmea2preset
from pyubx2 import UBXMessage
from pynmeagps import NMEAMessage, SET
 
ubx = UBXMessage("CFG", "CFG-MSG", SET, msgClass=0x01, msgID=0x03, rateUART1=1)
print(ubx2preset(ubx, "Configure NAV-STATUS Message Rate on ZED-F9P"))
 
nmea = NMEAMessage("P", "QTMCFGUART", SET, baudrate=460800)
print(nmea2preset(nmea, "Configure UART baud rate on LG290P")

输出结果：

Configure NAV-STATUS Message Rate on ZED-F9P, CFG, CFG-MSG, 0103000100000000, 1
Configure UART baud rate on LG290P; P; QTMCFGUART; W,460800; 1

多条命令可拼接在同一行中。示例可参考pygpsclient.json示例文件

Command Line Utilities

支撑 PyGPSClient 多数功能的pygnssutils与pyubxutils库，也包含这些功能的命令行版本。更多详情请参考对应主页：

pygnssutils:https://github.com/semuconsulting/pygnssutils，pyubxutils:https://github.com/semuconsulting/pyubxutils。

Known Issues

1. 多数经济型 USB-UART 适配器（如 FT232、CH345、CP2102）的带宽限制约为 3MB/s，即便接收器支持更高波特率，波特率超过 115200 时可能无法稳定工作。若使用适配器时出现大量消息损坏，可尝试将波特率降至最高 115200。

2. 截至 2025 年 10 月，u-blox 已停用其 PointPerfect SPARTN L 波段与 MQTT 服务。因此 PyGPSClient 的 SPARTN 配置面板基本冗余，在版本≥1.5.17 中默认禁用；但可通过手动将配置项 lband_enabled_b设为 1 来重新启用。

3. MacOS 上部分通过 Homebrew 安装的 Python 环境，因权限实现方式问题，在调用 Shell 子进程时可能出现严重的段错误（非法内存访问）。例如，这可能影响 “关于→更新” 功能；解决方法是通过标准命令行指令 pip install --upgrade进行更新。

4. 在部分 Python 3.14 环境（如 MacOS）中安装可选包 rasterio，可能出现构建依赖问题。这是因为这些平台暂未提供 Python 3.14 的预编译二进制（wheel）分发包；目前 rasterio的 Python 3.14 二进制分发包正在开发中。（错误提示：必须指定 GDAL API 版本。可通过 GDAL_CONFIG环境变量提供 gdal-config 的路径，或使用 GDAL_VERSION环境变量）

5. 在部分 32 位 Linux 平台（如树莓派 OS 32 位）上安装可选包 cryptography，可能需要 Rust 编译器支持及额外的构建依赖（详情见 pyspartn加密安装说明）。