XGNSS 基础与 AGNSS 集成

概述

本指南介绍 XGNSS 辅助定位中的 AGNSS 与 PGNSS 方案，覆盖服务端数据下载和扩展、终端数据分发与注入、SDK 接口与示例接入以及结果验证和问题处理。

架构与准备

方案选择

方案	数据特征	典型使用方式	主要取舍
AGNSS	在线获取实时辅助数据，广播星历通常可使用约 2 h	用户服务器定期下载并向在线终端分发	数据实时性高，但需要较稳定的网络连接和较短的更新周期
PGNSS	下载 1～28 天种子数据，经扩展库生成预测星历	用户服务器周期性下载、扩展并向终端分发，终端可离线使用	离线可用时间长，但预测天数越长，下载量越大，预测精度会随时间增长而下降

无论选择哪种方案，均建议通过用户自建服务器连接数据源服务，再由用户服务器向终端设备分发数据，避免终端设备直接连接数据源服务。

方案架构

两种方案均包含数据源服务、用户服务器和终端设备三部分：

用户服务器通过 HTTPS 请求 XGNSS 数据源服务，并完成 HMAC-SHA256 签名认证。
AGNSS 响应可直接按 AGNSS 数据结构分发；PGNSS 响应是种子数据，需要先通过 PGNSS 扩展库生成可注入的辅助数据文件。
终端设备保存辅助数据，先注入可靠的参考时间，再按协议逐条注入辅助数据，最后启动定位。

详细架构分别见 AGNSS 服务架构和 PGNSS 服务架构。GNSS 内层消息的封装、ACK 和辅助数据消息定义见 GNSS 接口协议开发指南的 GNBIN 内层协议框架。

服务端准备

准备可访问数据源服务的联网服务器。数据源服务使用 HTTPS 和 443 端口。
联系销售代表或技术支持渠道获取与产品匹配的 APP_ID 和 APP_SECRET；为每台设备准备唯一的 UUID。
运行下载示例需要 Python 3 及 requests 模块。
运行 PGNSS 扩展示例需要 Linux 环境、GCC、动态库加载支持，以及 SDK 中的 libpgnss_decoder.so。
生产环境应妥善保管 APP_SECRET，不要将密钥写入日志、固件或可公开访问的仓库。

设备端准备

按 GNSS 集成开发指南完成供电、天线、串口、固件和 GNSS 示例配置。
当前 diting-community 目标配置包含 CONFIG_ENABLE_DITING_GNSS_SAMPLE，构建系统据此引入 src/application/samples/gnss/gnss_at_samples。
AGNSS 示例从 /user/gnss/xgnss/AGNSS.dat 读取辅助数据；PGNSS 少文件注入示例从 /user/gnss/xgnss/ 读取 AssistInfo.dat、NonGlo_*.eph 和 GLO_*.eph 等扩展结果。部署前应创建目录并保证应用具有读权限。
注入辅助数据前应完成 GNSS 初始化，并准备误差不超过 10 s 的可靠 UTC 时间源。

快速集成

AGNSS 快速流程

打开 AGNSS 下载示例，填写 APP_ID、APP_SECRET 和设备 UUID。按需填写 CONSTELLATION 和 DATATYPE；留空时使用服务端默认值。
在示例目录运行：
```
python server_agnss_download_demo.py
```
请求成功后确认当前目录生成 AGNSS.dat，再将文件安全分发到设备的 /user/gnss/xgnss/AGNSS.dat。
完成设备端 GNSS 初始化后，依次执行 AT^GNSSSAMPLE=3 和 AT^GNSSSTART。当前设备端示例会先注入 UTC 时间，再校验并注入 AGNSS.dat 中的各条 TLV 数据。
观察注入日志和 NMEA 输出；RMC 语句的位置有效标志为 A 时表示定位有效。完整运行时序和日志确认方法见 GNSS 集成开发指南的 AGNSS 辅助定位。

PGNSS 快速流程

打开 PGNSS 下载示例，填写 APP_ID、APP_SECRET 和设备 UUID，按需将 PERIOD 设置为 1、3、7、14 或 28；留空时默认请求 7 天数据。
运行下载脚本，成功后确认生成 EE.dat：
```
python server_pgnss_download_demo.py
```
进入 src/tools/pkg/bin/3322/gnss/pgnss/server_pgnss_decode_demo，将下载文件放入 demo_data/EE_7days.dat，并将 ../pgnss_decoder/libpgnss_decoder.so 复制到当前目录。示例中的文件路径和预测小时数由 server_pgnss_decode_demo.c 顶部宏定义控制。
在 Linux 环境编译并运行扩展示例：
```
bash build_and_run.sh
```
脚本使用 gcc 和 -ldl 生成 decode_demo。output1 保存合并文件输出，output2 保存多文件输出。 5. 将 output1 中的少文件扩展结果分发到设备 /user/gnss/xgnss/，完成 GNSS 初始化后依次执行 AT^GNSSSAMPLE=4 和 AT^GNSSSTART。 6. 设备端示例按当前 UTC 时间选择有效星历，先注入时间，再注入非 GLONASS 星历、GLONASS 星历和其他辅助信息。定位结果的确认方法见 GNSS 集成开发指南的 PGNSS 辅助定位。

下载示例当前通过 verify=False 关闭 TLS 证书校验，适合说明请求流程。产品部署时应配置受信任 CA 并启用服务器证书校验，避免凭据或辅助数据在传输过程中被篡改。

AGNSS 集成

功能概述

接收机在无任何辅助信息的情况下冷启动定位，受限于自主解调广播星历耗时，一般需要约30s。

AGNSS服务提供在线实时请求广播星历等辅助数据功能，可免除自主解星历时间，缩短首次定位时间；实时广播星历有效期较短，一般可以使用约2h。

服务架构

用户需自行搭建服务器，采用云云对接方式，由用户服务器对接AGNSS数据服务，从AGNSS服务器获取数据后，向用户的终端设备进行分发。

图 1 AGNSS服务架构

**图 1** AGNSS服务架构

须知： 对接数据源服务所需的账号、密钥信息，请联系销售代表或技术支持渠道获取。

集成步骤

整体流程

AGNSS整体流程如图1所示。

须知： AGNSS星历有效期仅有2小时，建议用户自建服务器每1小时或更短时间请求1次数据，以保持自建服务器上的星历处在有效期内。

图 1 AGNSS整体流程

**图 1** AGNSS整体流程

服务端数据下载

用户自建服务器，采用HTTPS协议，向AGNSS数据源服务器请求AGNSS数据。请求流程如图1所示。

图 1 AGNSS服务请求过程

**图 1** AGNSS服务请求过程

构造请求消息

使用HTTPS协议，请求方法为GET，构造的HTTP报文格式示例如下：

GET /higeo/v1/xgnss/agnss?constellation=5&datatype=1 HTTP/1.1
HOST: geo-drcn.platform.dbankcloud.cn
Authorization: HMAC-SHA256 appid=abc123, timestamp=1672545600000, signature=oZg+Uo+TEnQ75NHweWAKfy/+xOn5jAFa7r93gj/muGk=
X-Request-ID: ABCDEFG

URL

中国：https://geo-drcn.platform.dbankcloud.cn/higeo/v1/xgnss/agnss

数据源服务不支持海外直接访问。

请求消息头

表 1 AGNSS请求消息头

参数	类型	可选	参数范围	参数说明
Authorization	String	必选	-	参考“签名认证-组装请求消息头”章节。
X-Request-ID	String	可选	-	设备UUID，一般设备出厂时会分配一个唯一的UUID。

说明： 举例：假设设备出厂UUID是ABCDEFG，签名参考“签名认证”章节的例子，构造消息头如下： Authorization: HMAC-SHA256 appid=abc123, timestamp=1672545600000, signature=oZg+Uo+TEnQ75NHweWAKfy/+xOn5jAFa7r93gj/muGk= X-Request-ID: ABCDEFG

请求参数

如果不带任何请求参数，全部使用默认参数，将注入GPS、GLO、BDS、GAL四模卫星的参考时间、星历、UTC模型、电离层参数、实时完好性信息、频点对应关系的数据。

请求参数跟在域名网址后，用“?”分隔，可以带多个参数，参数之间用“&”隔开，参数名和值之间用“=”隔开。

举例：如url?constellation=7&datatype=1，将注入gps、glo、bds三模卫星的参考时间和星历的RawData格式数据。

具体参数说明如表2所示。

表 2 AGNSS请求参数

参数	类型	可选	参数范围	参数说明
constellation	Int	可选，默认15	掩码如表3所示。	掩码表示卫星模式，传输时传10进制数。可组合使用，如constellation=15，对应掩码为0xF：GPS+GLO+BDS+GAL。
datatype	Int	可选，默认31	掩码如表4所示。	掩码表示请求的数据类型，传输时传10进制数。请求任意类型默认下发参考时间。可选数据类型有：星历、UTC模型、电离层参数、实时完好性信息、频点对应关系，各卫星模式支持数据类型情况见表4。按需配置，可组合使用，如datatype=31，对应掩码为0x1F：rtc(默认下发)+eph+utc+ion+rti+aux。

表 3 AGNSSID掩码

constel	GNSSID掩码
GPS	0x01
GLO	0x02
BDS	0x04
GAL	0x08

表 4 AGNSS辅助数据掩码及各模支持辅助数据情况

数据类型	描述	datatype值	gps	glo	bds	gal
rtc	参考时间	默认下发	O	X	X	X
eph	星历	0x01	O	O	O	O
utc	UTC模型	0x02	O	X	X	X
ion	电离层参数	0x04	O	X	O	X
rti	实时完好性信息	0x08	O	O	O	O
aux	频点对应关系	0x10	X	O	X	X

签名认证

生成请求签名的流程如图1所示。

图 1 请求签名生成流程图

**图 1** 请求签名生成流程图

签名认证-构造规范化请求字符串

按照参数名称的字典顺序对请求中所有的请求参数进行排序。
对每个请求参数的名称和值进行编码，名称和值要使用UTF-8字符集进行URL编码（例如：java.net.URLEncoder）。
对排序后的参数名称和值使用英文等号（=）进行连接。
英文等号连接得到的字符串按参数名称的字典顺序依次使用（&）符号连接，即得到规范化请求字符串。

说明： 举例：假设请求卫星模式是5，辅助数据类型是1，构造请求字符串如下： constellation=5&datatype=1 注意因为需按字典顺序排序，所以constellation在前。

签名认证-构造待签名字符串

请求字符串构造方法如下所示：

StringToSign = ${http_method} +"&"+ ${http_url_path} +"&"+ ${canonical_query_string} +"&"+ ${http_payload}+"&appid="+ ${appid} +"&timestamp=" + ${current_timestamp}

参数列表说明如下：

http_method：固定设置为GET。
http_url_path：请求URL路径，不包含host和请求参数部分，如AGNSS固定为“/higeo/v1/xgnss/agnss”。
canonical_query_string：为“签名认证-构造规范化请求字符串”生成的规范化请求字符串。
http_payload：http请求消息体。
appid：设备商ID，通过注册得到。
current_timestamp：当前时间（单位为：ms），取值1970-01-01 00:00:00.000到当前的毫秒数，比如使用JAVA System.currentTimeMillis()获取。

说明： 举例：例如北京时间2023-01-01 12:00:00，转换unix时间戳为1672545600000；例如appid=abc123，再使用上一章例子中请求参数，构造待签名字串如下： GET&/higeo/v1/xgnss/agnss&constellation=5&datatype=1&&appid=abc123&timestamp=1672545600000

签名认证-计算签名HMAC值

使用“签名认证-构造待签名字符串”生成的待签名请求字符串使用HMAC-SHA256算法计算签名HMAC值（使用SecretKey作为HMAC-SHA256算法的Key），按照Base64编码规则对HMAC值编码成字符串，即得到签名值。

说明： 举例：使用“签名认证-构造待签名字符串”中待签名字串，计算出签名HMAC值如下： oZg+Uo+TEnQ75NHweWAKfy/+xOn5jAFa7r93gj/muGk= SecretKey（密钥）请联系销售代表或技术支持渠道获取。

签名认证-组装请求消息头

将得到的签名值作为Signature参数添加到请求Authorization头，参考如下：

Authorization: HMAC-SHA256 appid=${appid}, timestamp=${current_timestamp}, signature=${signature_value}

参数列表说明如下：

appid为“签名认证-构造待签名字符串”中使用的APPID参数。

current_timestamp为“签名认证-构造待签名字符串”使用的current_timestamp参数。

signature_value为“签名认证-计算签名HMAC值”获得的签名HMAC值。
将Authorization头附加到请求消息头中，作为请求认证信息。

说明： 举例：使用“签名认证-构造待签名字符串”中时间戳和签名值，组装消息头如下： Authorization: HMAC-SHA256 appid=abc123, timestamp=1672545600000, signature=oZg+Uo+TEnQ75NHweWAKfy/+xOn5jAFa7r93gj/muGk=

处理响应消息

HTTP返回状态码

表 1 HTTP状态码

状态码	说明
200	辅助数据请求成功，可以开始解析数据。
400	请求参数错误。
401	用户认证失败。
503	超过访问次数限制，服务不可用。

响应消息头

表 2 AGNSS响应消息头

参数	类型	参数范围	参数说明
Content-Type	String	固定值： "application/octet-stream"	响应数据类型是二进制码流。
X-Auth-Timestamp	Int	-	服务器unix时间戳。

响应消息体

AGNSS服务用户单次下载全量数据常规约在15KB～20KB，理论最大值不超过30KB，消息体数据结构如图1。

图 1 AGNSS辅助数据结构

**图 1** AGNSS辅助数据结构

消息体中的Data字段，对应 GNSS接口协议开发指南中CTR-AX-XXX消息类型的载荷内容。

服务端数据分发

用户自建服务器在收到来自设备的请求后，将最新保存的AGNSS数据，返回给设备。此部分具体过程需用户自行设计。

设备端数据注入

设备端数据注入过程如图1所示。

须知：

在注入AGNSS辅助数据前，必须先注入参考时间。客户端可以自行寻找可靠的时间源，时间精度在10秒内即可，请参照 GNSS接口协议开发指南的 GNBIN 协议中的CTR-AST-TIME进行组装后注入。

依次注入每条AGNSS辅助数据，每条辅助数据注入完，需要参考接口协议，验证ACK后，再发下一条。或者连续两条辅助数据之间，设置时延，避免数据流覆盖，建议按data_size * 10 / current_bps来评估时延。

图 1 AGNSS设备端数据注入流程

**图 1** AGNSS设备端数据注入流程

设备端收到AGNSS原始数据后，需根据AGNSS的消息协议，参考表1，将AGNSS原始消息类型转换为HiDiTing GNSS消息类型，然后按照 GNSS接口协议开发指南的内层协议框架封装成GNSS芯片所需的消息并注入GNSS芯片。

表 1 AGNSS响应辅助数据类型

星座	Data Type	数据类型	数据量（单位：Byte）	对应HiDiTing GNSS接口类型
GPS	0x0001	参考时间	最大211	CTR-AX-TIME(0x0301)
	0x0002	星历	最大2244	CTR-AX-EPHG(0x0303)
	0x0003	UTC模型	20	CTR-AX-UTCG(0x0305)
	0x0004	电离层参数	8	CTR-AX-IONG(0x0304)
	0x0005	实时完好性信息	最大20	CTR-AX-RTIG(0x0306)
GLONASS	0x0022	星历	最大3343	CTR-AX-EPHA(0x0309)
	0x0025	实时完好性信息	最大197	CTR-AX-RTIA(0x030A)
	0x0026	频点对应关系	最大265	CTR-AX-AUXA(0x030C)
Beidou	0x0042	星历	最大8903	CTR-AX-EPHA(0x0309)
	0x0044	电离层参数	9	CTR-AX-IONA(0x0308)
	0x0045	实时完好性信息	最大197	CTR-AX-RTIA(0x030A)
Galileo	0x0062	星历	最大5011	CTR-AX-EPHA(0x0309)
Galileo	0x0065	实时完好性信息	最大197	CTR-AX-RTIA(0x030A)

集成示例

服务端数据下载示例

HiDiTing SDK中提供了数据下载示例：server_agnss_download_demo。

用户在联网环境下，填充APP_ID和APP_SECRET后，执行脚本，即可获取到AGNSS辅助数据。

示例位置：/src/tools/pkg/bin/3322/gnss/agnss/server_agnss_download_demo/server_agnss_download_demo.py。

设备端数据注入示例

设备端注入代码见 /src/application/samples/gnss/gnss_at_samples/gnss_agnss.c，完整操作时序见 GNSS集成开发指南的 AGNSS 辅助定位。

接口	用途	详细说明
`uapi_gnss_init`	初始化 GNSS 服务	API 参考
`uapi_gnss_open`	打开设备并加载固件	API 参考
`uapi_gnss_config`	向 GNSS 芯片发送时间和辅助数据消息	API 参考
`uapi_gnss_start`	启动定位	API 参考
`uapi_gnss_stop`	停止定位	API 参考
`uapi_gnss_close`	关闭 GNSS 设备	API 参考
`uapi_gnss_deinit`	去初始化 GNSS 服务	API 参考
`uapi_gnss_set_xgnss_type`	在启动定位前选择 AGNSS 或 PGNSS 类型	API 参考
`uapi_gnss_register_xgnss_req_callback`	注册辅助数据请求回调	API 参考
`uapi_notify_xgnss_updated`	辅助数据文件写入完成后通知 GNSS 服务	API 参考
`GetPgnssDataValidTime`、`GetLeapSecond`、`ParsePgnssData`、`ParsePgnssDataByLessFiles`	查询 PGNSS 种子有效期、跳秒并生成扩展星历	接口声明