PGNSS 集成与问题处理

PGNSS 集成

功能概述

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

PGNSS服务提供联网一次下载PGNSS数据，后续可以离线预测未来的星历数据功能，可免除自主解星历时间，缩短首次定位时间；预测时间较长，可提供1~28天预测数据，但预测天数越长数据下载量越大，且离线预测的精度会随时间增长变差。

服务架构

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

图 1 PGNSS服务架构

**图 1** PGNSS服务架构

须知： 对接数据源服务所需的账号、密钥信息，请联系FAE获取。

集成步骤

整体流程

PGNSS整体流程如图1所示。

须知：

PGNSS星历存在有效期，比如1天、3天、7天、14天、28天，需要用户周期性访问数据源服务器获取最新的星历数据。

用户可通过“PGNSS扩展库接口”查询当前星历有效期，确保星历在到期前完成更新。

数据源服务器通常每3小时更新一套PGNSS星历，建议用户每3小时左右请求一次数据。

图 1 PGNSS整体流程

**图 1** PGNSS整体流程

服务端数据下载

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

图 1 PGNSS服务请求过程

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

构造请求消息

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

GET /higeo/v1/xgnss/pgnss?period=28 HTTP/1.1
HOST: geo-drcn.platform.dbankcloud.cn
Authorization: HMAC-SHA256 appid=abc123, timestamp=1672545600000, signature=CwshITD1LgX2tIQ1/W7xF5vq21hyjGMiV6UsN+7+ABE=
X-Request-ID: ABCDEFG

URL

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

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

请求消息头

表 1 PGNSS请求消息头

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

说明： 举例：假设设备出厂UUID是ABCDEFG，请求参数period=28，参考“签名认证”进行签名后，构造消息头如下： Authorization: HMAC-SHA256 appid=abc123, timestamp=1672545600000, signature=CwshITD1LgX2tIQ1/W7xF5vq21hyjGMiV6UsN+7+ABE= X-Request-ID: ABCDEFG

请求参数

如果不带任何请求参数，使用默认参数，将发送7天的PGNSS数据。

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

举例：如url?period=28，将发送28天的PGNSS数据。

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

表 2 PGNSS请求参数

参数	类型	可选	参数范围	参数说明
period	Int	可选，默认7	仅可选择以下数值：1、3、7、14、28。	用户可以根据自身设备需求一次性请求X天的数据，单位：天。

签名认证

PGNSS签名认证流程同AGNSS，请参考“签名认证”。

处理响应消息

HTTP返回状态码

表 1 HTTP状态码

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

响应消息头

表 2 PGNSS响应消息头

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

响应消息体

用户单次下载全量PGNSS数据，常规7天数据量约500KB，最大值28天约为2MB。

响应数据类型是二进制码流，实际下载的是PGNSS种子数据，需使用SDK中发布的PGNSS数据扩展库扩展成星历文件后，再分发给设备端使用。

服务端数据扩展

用户服务器下载到原始PGNSS种子文件后，需使用SDK中发布的PGNSS星历扩展库进行扩展，得到可以分发给设备的星历文件。扩展库名称为 libpgnss_decoder.so，位于 /src/tools/pkg/bin/3322/gnss/pgnss/pgnss_decoder/pgnss_decoder_interface.h，需部署在Linux环境中。

PGNSS扩展库接口

表 1 查询PGNSS下载数据文件时效

查询PGNSS下载数据文件时效
函数原型	int32_t GetPgnssDataValidTime(const char filePath, uint32_t startTimestamp, uint32_t *endTimestamp)
函数功能	查询PGNSS下载的数据文件中，数据的有效起始时间。
返回值	0：成功。其他：错误码。
入参	filePath：PGNSS下载数据的文件路径。
出参	startTimestamp：种子有效开始时间对应的unix时间戳（unix时间戳是从1970年1月1日（UTC/GMT的午夜）开始所经过的秒数，不考虑闰秒）。 endTimestamp：种子有效结束时间对应的unix时间戳。

表 2 查询跳秒时间

查询跳秒时间
函数原型	int32_t GetLeapSecond(const char *filePath)
函数功能	查询跳秒时间。
返回值	LeapSecond跳秒。
入参	filePath：PGNSS下载数据的文件路径。
出参	无。

表 3 PGNSS数据解析1（多文件输出）

PGNSS数据解析
函数原型	int32_t ParsePgnssData(const char filePath, const char outputDir, uint32_t timestamp, uint32_t hours)
函数功能	读取PGNSS种子文件，解析PGNSS辅助数据，扩展星历，保存星历文件。每一份星历文件可使用前后两小时，两份星历文件间隔两小时，支持一次扩展多份星历文件。
返回值	0：成功。其他：错误码。
入参	filePath：PGNSS下载数据的文件路径。 outputDir：扩展的辅助数据存放路径。 timestamp：开始预测时间对应的unix时间戳，可取用当前时间，也可自行设置时间，单位：s。 hours：解析X小时星历，调用者需保证种子文件中从timestamp开始有X小时的有效星历，可先调用查询时效接口来保障。
出参	无。

表 4 PGNSS数据解析2（合并文件输出）

PGNSS数据解析
函数原型	int32_t ParsePgnssDataByLessFiles(const char filePath, const char outputDir, uint32_t timestamp, uint32_t hours)
函数功能	读取PGNSS种子文件，解析PGNSS辅助数据，扩展星历，保存星历文件。与PGNSS数据解析1不同的是，每次解析仅生成三种文件，分别为GLONASS星历、除GLONASS外其余星历以及其余辅助信息。每一份星历文件可使用前后两小时，两份星历文件间隔两小时，支持一次扩展多份星历文件。其余辅助信息每次仅生成一份文件，与时间无关。
返回值	0：成功。其他：错误码。
入参	与PGNSS数据解析1一致。 filePath：PGNSS下载数据的文件路径。 outputDir：扩展的辅助数据存放路径。 timestamp：开始预测时间对应的unix时间戳，可取用当前时间，也可自行设置时间，单位：s。 hours：解析X小时星历，调用者需保证种子文件中从timestamp开始有X小时的有效星历，可先调用查询时效接口来保障。
出参	无。

PGNSS扩展库输出

调用表3接口后，将在用户入参给出的路径下生成解析出的辅助数据二进制文件。文件内容对应 GNSS接口协议开发指南中CTR-PX-XXX消息类型内容，设备端需按内层协议框架组装后注入GNSS芯片。设备端操作可参考 GNSS集成开发指南的 PGNSS 辅助定位。

扩展星历命名规范如表1所示。

表 1 扩展库输出数据文件1（多文件输出）

辅助数据类型	命名规范	举例	对应HiDiTing GNSS消息类型
GPS星历	以“GPS_”开头，紧接着是unix时间戳，再以“.eph”结尾。预测星历在unix时间戳前后2小时有效。	GPS_1689839982.eph 星历有效期：2023/7/20 15:59:42±2小时	CTR-PX-EPHG(0x203)
GLONASS星历	以“GLO_”开头，紧接着是unix时间戳，再以“.eph”结尾。预测星历在unix时间戳前后15分钟有效。	GLO_1689839982.eph 星历有效期：2023/7/20 15:59:42±15分钟	CTR-PX-EPHA(0x204)
Beidou星历	以“BDS_”开头，紧接着是unix时间戳，再以“.eph”结尾。预测星历在unix时间戳前后2小时有效。	BDS_1689839982.eph 星历有效期：2023/7/20 15:59:42±2小时	CTR-PX-EPHA(0x204)
Galileo星历	以“GAL_”开头，紧接着是unix时间戳，再以“.eph”结尾。预测星历在unix时间戳前后2小时有效。	GAL_1689839982.eph 星历有效期：2023/7/20 15:59:42±2小时	CTR-PX-EPHA(0x204)
QZSS星历	以“QZS_”开头，紧接着是unix时间戳，再以“.eph”结尾。预测星历在unix时间戳前后2小时有效。	QZS_1689839982.eph 星历有效期：2023/7/20 15:59:42±2小时	CTR-PX-EPHA(0x204)
GPS UTC模型	固定名“GPS_UTC.dat”	-	CTR-PX-UTCG(0x205)
GPS电离层参数	固定名“GPS_ION.dat”	-	CTR-PX-IONG(0x208)
GPS完好性信息	固定名“GPS_RTI.dat”	-	CTR-PX-RTIG(0x206)
GLONASS完好性信息	固定名“GLO_RTI.dat”	-	CTR-PX-RTIA(0x207)
GLONASS频点转换关系	固定名“GLO_AUX.dat”	-	CTR-PX-AUXA(0x209)
Beidou完好性信息	固定名“BDS_RTI.dat”	-	CTR-PX-RTIA(0x207)
Galileo完好性信息	固定名“GAL_RTI.dat”	-	CTR-PX-RTIA(0x207)

调用表4接口后，将在用户入参给出的路径底下生成解析出的辅助数据二进制文件，与PGNSS数据解析1不同的是，PGNSS数据解析2每次解析仅生成三种文件，分别为GLONASS星历、除GLONASS外其余星历以及其余辅助信息。两份星历文件间隔两小时，支持一次扩展多份星历文件。其余辅助信息每次仅生成一份文件，与时间无关。输出数据文件具体如表2所示。

表 2 扩展库输出数据文件（合并文件输出）

辅助数据类型

命名规范

举例

数据组成

对应HiDiTing GNSS消息类型

除GLONASS外全模星历

以“NonGlo_”开头，紧接着是unix时间戳，再以“.eph”结尾。

预测星历在unix时间戳前后2小时有效。

NonGlo_1689839982.eph，时间戳1689839982对应时间2023/7/20 15:59:42，星历有效期：(2023/7/20 13:59:42，2023/7/20 17:59:42）。

如表3所示

GPS星历：CTR-PX-EPHG(0x203)
其余星历：CTR-PX-EPHA(0x204)

GLONASS星历

以“GLO_”开头，紧接着是unix时间戳，再以“.eph”结尾。

预测星历在unix时间戳前15分钟，后2小时有效。

GLO_1689839982.eph，时间戳1689839982对应时间2023/7/20 15:59:42，对应第一份15分钟有效期GLONASS星历的时间戳，整体星历有效期：(2023/7/20 15:44:42，2023/7/20 17:59:42）。

如表4所示

CTR-PX-EPHA(0x204)

其余辅助信息

固定名“AssistInfo.dat”

-

如表5所示

GPS 完好性信息：CTR-PX-RTIG(0x206)
其余完好性信息：CTR-PX-RTIA(0x207)
GPS UTC模型：CTR-PX-UTCG(0x205)
GPS电离层参数：CTR-PX-IONG(0x208)
GLONASS 频点转换关系：CTR-PX-AUXA(0x209)

表 3 除GLONASS外全模星历内容组成

字节偏移	数据类型	字段名	说明
0	U4	time1	GPS星历对应unix时间戳
4	U2	cmd1	GPS星历对应的HiDiTing GNSS消息类型CTR-PX-EPHG(0x203)
6	U4	len1	GPS星历对应的消息长度
10	U1	content1	GPS星历对应的消息内容
10+len1	U4	time2	BDS星历对应unix时间戳
14+len1	U2	cmd2	BDS星历对应的HiDiTing GNSS消息类型CTR-PX-EPHA(0x204)
16+len1	U4	len2	BDS星历对应的消息长度
20+len1	U1	content2	BDS星历对应的消息内容
20+len1+len2	U4	time2	GALILEO星历对应unix时间戳
24+len1+len2	U2	cmd2	GALILEO星历对应的HiDiTing GNSS消息类型CTR-PX-EPHA(0x204)
26+len1+len2	U4	len2	GALILEO星历对应的消息长度
30+len1+len2	U1	content3	GALILEO星历对应的消息内容
30+len1+len2+len3	U4	time2	QZSS星历对应unix时间戳
34+len1+len2+len3	U2	cmd2	QZSS星历对应的HiDiTing GNSS消息类型CTR-PX-EPHA(0x204)
36+len1+len2+len3	U4	len2	QZSS星历对应的消息长度
40+len1+len2+len3	U1	content4	QZSS星历对应的消息内容

表 4 GLONASS星历内容组成

字节偏移	数据类型	字段名	说明
0	U4	time1	第1份15分钟有效期GLONASS星历对应unix时间戳
4	U2	cmd1	第1份15分钟有效期GLONASS星历对应的HiDiTing GNSS消息类型CTR-PX-EPHA(0x204)
6	U4	len1	第1份15分钟有效期GLONASS星历对应的消息长度
10	U1	content1	第1份15分钟有效期GLONASS星历对应的消息内容
10+len1	U4	time2	第2份15分钟有效期GLONASS星历对应unix时间戳
14+len1	U2	cmd2	第2份15分钟有效期GLONASS星历对应的HiDiTing GNSS消息类型CTR-PX-EPHA(0x204)
16+len1	U4	len2	第2份15分钟有效期GLONASS星历对应的消息长度
20+len1	U1	content2	第2份15分钟有效期GLONASS星历对应的消息内容
20+len1+len2	U4	time2	第3份15分钟有效期GLONASS星历对应unix时间戳
24+len1+len2	U2	cmd2	第3份15分钟有效期GLONASS星历对应的HiDiTing GNSS消息类型CTR-PX-EPHA(0x204)
26+len1+len2	U4	len2	第3份15分钟有效期GLONASS星历对应的消息长度
30+len1+len2	U1	content3	第3份15分钟有效期GLONASS星历对应的消息内容
30+len1+len2+len3	U4	time2	第4份15分钟有效期GLONASS星历对应unix时间戳
34+len1+len2+len3	U2	cmd2	第4份15分钟有效期GLONASS星历对应的HiDiTing GNSS消息类型CTR-PX-EPHA(0x204)
36+len1+len2+len3	U4	len2	第4份15分钟有效期GLONASS星历对应的消息长度
40+len1+len2+len3	U1	content4	第4份15分钟有效期GLONASS星历对应的消息内容
40+len1+len2+len3+len4	U4	time5	第5份15分钟有效期GLONASS星历对应unix时间戳
44+len1+len2+len3+len4	U2	cmd5	第5份15分钟有效期GLONASS星历对应的HiDiTing GNSS消息类型CTR-PX-EPHA(0x204)
46+len1+len2+len3+len4	U4	len5	第5份15分钟有效期GLONASS星历对应的消息长度
50+len1+len2+len3+len4	U1	content5	第5份15分钟有效期GLONASS星历对应的消息内容
50+len1+len2+len3+len4+len5	U4	time6	第6份15分钟有效期GLONASS星历对应unix时间戳
54+len1+len2+len3+len4+len5	U2	cmd6	第6份15分钟有效期GLONASS星历对应的HiDiTing GNSS消息类型CTR-PX-EPHA(0x204)
56+len1+len2+len3+len4+len5	U4	len6	第6份15分钟有效期GLONASS星历对应的消息长度
60+len1+len2+len3+len4+len5	U1	content6	第6份15分钟有效期GLONASS星历对应的消息内容
60+len1+len2+len3+len4+len5+len6	U4	time7	第7份15分钟有效期GLONASS星历对应unix时间戳
64+len1+len2+len3+len4+len5+len6	U2	cmd7	第7份15分钟有效期GLONASS星历对应的HiDiTing GNSS消息类型CTR-PX-EPHA(0x204)
66+len1+len2+len3+len4+len5+len6	U4	len7	第7份15分钟有效期GLONASS星历对应的消息长度
70+len1+len2+len3+len4+len5+len6	U1	content7	第7份15分钟有效期GLONASS星历对应的消息内容
70+len1+len2+len3+len4+len5+len6+len7	U4	time8	第8份15分钟有效期GLONASS星历对应unix时间戳
74+len1+len2+len3+len4+len5+len6+len7	U2	cmd8	第8份15分钟有效期GLONASS星历对应的HiDiTing GNSS消息类型CTR-PX-EPHA(0x204)
76+len1+len2+len3+len4+len5+len6+len7	U4	len8	第8份15分钟有效期GLONASS星历对应的消息长度
80+len1+len2+len3+len4+len5+len6+len7	U1	content8	第8份15分钟有效期GLONASS星历对应的消息内容

表 5 其余辅助信息内容组成

字节偏移	数据类型	字段名	说明
0	U2	cmd1	GPS完好性信息对应的HiDiTing GNSS消息类型CTR-PX-RTIG(0x206)
2	U4	len1	GPS完好性信息对应的消息长度
6	U1	content1	GPS完好性信息对应的消息内容
6+len1	U2	cmd2	GLONASS完好性信息对应的HiDiTing GNSS消息类型CTR-PX-RTIA(0x207)
8+len1	U4	len2	GLONASS完好性信息对应的消息长度
12+len1	U1	content2	GLONASS完好性信息对应的消息内容
12+len1+len2	U2	cmd2	BDS完好性信息对应的HiDiTing GNSS消息类型CTR-PX-RTIA(0x207)
14+len1+len2	U4	len2	BDS完好性信息对应的消息长度
18+len1+len2	U1	content3	BDS完好性信息对应的消息内容
18+len1+len2+len3	U2	cmd2	GALILEO完好性信息对应的HiDiTing GNSS消息类型CTR-PX-RTIA(0x207)
20+len1+len2+len3	U4	len2	GALILEO完好性信息对应的消息长度
24+len1+len2+len3	U1	content4	GALILEO完好性信息对应的消息内容
24+len1+len2+len3+len4	U2	cmd5	GPS UTC模型对应的HiDiTing GNSS消息类型CTR-PX-UTCG(0x205)
26+len1+len2+len3+len4	U4	len5	GPS UTC模型对应的消息长度
30+len1+len2+len3+len4	U1	content5	GPS UTC模型对应的消息内容
30+len1+len2+len3+len4+len5	U2	cmd6	GPS电离层参数对应的HiDiTing GNSS消息类型CTR-PX-IONG(0x208)
32+len1+len2+len3+len4+len5	U4	len6	GPS 电离层参数对应的消息长度
36+len1+len2+len3+len4+len5	U1	content6	GPS 电离层参数对应的消息内容
36+len1+len2+len3+len4+len5+len6	U2	cmd7	GLONASS 频点转换关系对应的HiDiTing GNSS消息类型CTR-PX-AUXA(0x209)
38+len1+len2+len3+len4+len5+len6	U4	len7	GLONASS 频点转换关系对应的消息长度
42+len1+len2+len3+len4+len5+len6	U1	content7	GLONASS 频点转换关系对应的消息内容

PGNSS扩展库部署

内存使用

表 1 PGNSS扩展库常规内存使用

ITCM	DTCM（静态）	STACK峰值
5K	40K	12K

HEAP峰值与PGNSS数据有效期相关，对应关系如表2所示。

表 2 PGNSS动态内存使用

PGNSS数据有效期	HEAP峰值
1天	500K
3天	700K
7天	1000K
14天	1800K
28天	3200K

运行耗时

运行耗时主要与解析星历文件个数以及其中包含的卫星个数相关，每份星历文件每颗卫星耗时约3s，解析1份全模完整星历（GPS、BDS、GALILEO、QZSS、GLONASS各一个星历文件）典型耗时约为250s。

服务端数据分发

当用户自建服务器收到设备端的请求后，需将最新的一整套扩展后的PGNSS星历数据发送给设备端，比如将扩展出的7天的星历文件，全部发送给设备端，以实现设备端离线后仍能在有效期内长期使用离线星历完成快速定位。

此处详细设计需用户自行实现。

设备端数据注入

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

须知：

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

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

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

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

设备端遍历到最接近当前时间的一份有效星历后，需根据PGNSS消息协议，按照 GNSS接口协议开发指南的内层协议框架封装成GNSS芯片所需的消息并注入GNSS芯片。

集成示例

服务端数据下载示例

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

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

示例位置：/src/tools/pkg/bin/3322/gnss/pgnss/server_pgnss_download_demo/server_pgnss_download_demo.py。

服务端数据扩展示例

HiDiTing SDK中提供了PGNSS星历扩展示例：server_pgnss_decode_demo。

用户可参考demo，利用下载到的PGNSS辅助数据扩展出PGNSS星历文件。

示例位置：/src/tools/pkg/bin/3322/gnss/pgnss/server_pgnss_decode_demo/server_pgnss_decode_demo.c。

设备端数据注入示例

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

示例与结果验证

示例文件结构

路径	作用
`/src/tools/pkg/bin/3322/gnss/agnss/server_agnss_download_demo/server_agnss_download_demo.py`	构造 AGNSS 查询参数和 HMAC-SHA256 鉴权头，发送 HTTPS GET 请求并保存 `AGNSS.dat`
`/src/tools/pkg/bin/3322/gnss/pgnss/server_pgnss_download_demo/server_pgnss_download_demo.py`	请求指定有效期的 PGNSS 种子数据并保存 `EE.dat`
`/src/tools/pkg/bin/3322/gnss/pgnss/pgnss_decoder/pgnss_decoder_interface.h`	声明种子有效期查询、跳秒查询和两种星历扩展接口
`/src/tools/pkg/bin/3322/gnss/pgnss/server_pgnss_decode_demo/server_pgnss_decode_demo.c`	动态加载扩展库、检查种子有效期并演示合并文件与多文件输出
`/src/tools/pkg/bin/3322/gnss/pgnss/server_pgnss_decode_demo/build_and_run.sh`	使用 GCC 编译扩展示例并运行 `decode_demo`
`/src/application/samples/gnss/gnss_at_samples/gnss_agnss.c`	读取并校验 `AGNSS.dat`，映射辅助数据类型并注入 GNSS
`/src/application/samples/gnss/gnss_at_samples/gnss_pgnss.c`	按当前时间选择有效 PGNSS 文件并注入星历和其他辅助信息
`/src/application/samples/gnss/gnss_at_samples/gnss_process.c`	将 `AT^GNSSSAMPLE=3` 和 `AT^GNSSSAMPLE=4` 分派到 AGNSS、PGNSS 示例
`/src/application/samples/gnss/gnss_at_samples/CMakeLists.txt`	将 GNSS AT 示例源码编入 `gnss_at_samples` 组件

代码走读

AGNSS 与 PGNSS 下载脚本采用相同的请求链路：先构造规范化查询字符串，再用 APP_SECRET 对 GET&URI&查询字符串&&appid=...&timestamp=... 计算 HMAC-SHA256，进行 Base64 编码后写入 Authorization 请求头。服务返回 HTTP 200 时，AGNSS 脚本保存 AGNSS.dat，PGNSS 脚本保存 EE.dat。

PGNSS 扩展示例通过 dlopen 加载 libpgnss_decoder.so，通过 dlsym 获取 GetPgnssDataValidTime 以及选定的解析接口。示例先校验预测起止时间，再分别调用 ParsePgnssDataByLessFiles 和 ParsePgnssData 演示两种输出方式；单次示例解析 24 h 星历。

设备端 AGNSS 示例先调用 gnss_inject_time 注入 UTC 时间，再读取 AGNSS.dat。代码逐条检查 TLV 长度和模 256 校验和，将 AGNSS 数据类型映射为 GNSS 内层命令，最终通过 uapi_gnss_config 下发。PGNSS 示例先将 UTC 转为 UNIX 时间戳，然后选择时间最接近且仍在有效窗口内的 NonGlo_*.eph 和 GLO_*.eph，再注入 AssistInfo.dat 中的其他辅助信息。

固件构建与运行

说明：本文示例命令以一站式 CLI 为主。实际开发可从以下三种环境中选择，推荐使用一站式 CLI。

开发环境	适用场景	使用指南
一站式 CLI（推荐）	快速完成目标选择、构建、烧录和串口监视	一站式 CLI 开发环境使用指南
HiSpark Studio for VS Code	图形化编辑、编译、烧录和调试	HiSpark Studio for VS Code 开发环境使用指南
WSL 与 Docker	在 Windows 上使用一致的 Linux 容器构建环境	WSL 与 Docker 环境使用指南

diting-community 目标已在目标配置中启用 CONFIG_ENABLE_DITING_GNSS_SAMPLE。需要重新生成包含设备端示例的固件时，请参见开发环境快速入门，建议优先使用一站式 CLI 开发环境。

烧录和串口连接方法见 GNSS集成开发指南的快速跑通流程。辅助文件部署完成后，可按以下顺序验证：

AT^GNSSINIT=1,1,0,0
AT^GNSSSAMPLE=3
AT^GNSSSTART

验证 PGNSS 时，将第 2 条命令改为 AT^GNSSSAMPLE=4。测试结束后依次执行 AT^GNSSSTOP 和 AT^GNSSDEINIT。

预期结果

AGNSS 下载成功时，脚本打印 HTTP 状态码 200、响应长度和“辅助数据请求成功”，并生成非空的 AGNSS.dat。
PGNSS 下载成功时，脚本打印 HTTP 状态码 200 和“EE.dat下载成功”，并生成非空的 EE.dat。
PGNSS 扩展成功时，示例打印动态库加载成功、种子有效起止时间以及 Parse Pgnss Data succeed.，同时在 demo_data/output1 和 demo_data/output2 生成扩展结果。
设备端注入成功时，日志中可看到对应命令的注入成功信息；注入后的有效星历数量应增加。RMC 语句的位置有效标志为 A 时表示定位有效。

调试方法

服务请求失败时，先记录 HTTP 状态码和状态消息，再核对 URI、查询参数、APP_ID、时间戳单位、签名字符串和设备 UUID。
扩展库加载失败时，确认 libpgnss_decoder.so 位于 server_pgnss_decode_demo.c 中 XGNSS_LIB_PATH 指定的位置，并确认运行环境支持 dlopen。
PGNSS 解析返回错误时，先通过 GetPgnssDataValidTime 检查 timestamp 和 hours 是否落在种子有效期内；当前示例每次最多解析 24 h，需要更长时段时应拆分调用。
AGNSS 注入失败时，检查 /user/gnss/xgnss/AGNSS.dat 是否存在、文件是否非空以及 TLV 长度和校验和是否正确。
PGNSS 注入失败时，确认少文件输出已完整复制到 /user/gnss/xgnss/，并检查当前时间是否能匹配有效的 NonGlo_*.eph、GLO_*.eph 和 AssistInfo.dat。
已完成注入但定位仍失败时，检查天线连接、卫星信号环境、NMEA 输出和 GNSS 生命周期顺序，具体方法见 GNSS集成开发指南的常见错误。

问题处理与注意事项

时间校验失败

表 1 时间校验失败

现象	HTTP状态码401，状态消息“TimestampMoreEarlierOrLater”。
排查方法	检查服务器下发的响应消息头中“X-Auth-Timestamp”与请求消息头的“Authorization”中的“timestamp”是否相差很大。检查此处要填充的是从1970年1月1日（UTC/GMT的午夜）开始所经过的毫秒数，不考虑闰秒的unix时间戳，是否取错时间。时间戳单位是毫秒，是否单位出错。是否客户端本身不支持获取unix时间戳，未填充正确的timestamp。
解决方法	如果自建服务器本身支持获取unix时间戳，请填充正确的数值。如果自建服务器本身不支持获取unix时间戳，可不带时间戳先执行一次请求，再按带时间戳执行请求。

签名校验失败

表 1 未填写鉴权校验字段

现象	HTTP状态码401，状态消息“authorization is missed”。
排查方法	确定请求消息头已填写“Authorization”字段。
解决方法	参考签名认证章节进行填写。

表 2 未填写APPID字段

现象	HTTP状态码401，状态消息“appid is missed”。
排查方法	确定请求消息头的“Authorization”中已填写“appid”字段。
解决方法	参考签名认证章节进行填写。

表 3 未填写timestamp字段

现象	HTTP状态码401，状态消息“timestamp is invalid”。
排查方法	确定请求消息头的“Authorization”中已填写“timestamp”字段。
解决方法	参考签名认证章节进行填写。

表 4 未填写signature字段

现象	HTTP状态码401，状态消息“signature is invalid”。
排查方法	确定请求消息头的“Authorization”中已填写“signature”字段。
解决方法	参考签名认证章节进行填写。

表 5 非法的APPID

现象

HTTP状态码401，状态消息“Can't get the keys of appid”。

排查方法

确定请求消息头的“Authorization”中的“appid”已正确填写。

确定APPID的合法性，联系销售代表获取合法的APPID。

解决方法

联系销售代表获取合法的APPID。

表 6 鉴权校验失败

现象	HTTP状态码401，状态消息“SignatureInvalid”。
排查方法	确定请求消息头的“Authorization”中的“signature”已正确填写。确定加密算法中使用的预共享密钥是与APPID匹配的。确定数据组装及加密算法使用是否正确。
解决方法	联系销售代表获取合法的APPID及对应的密钥。检查数据组装及加密算法使用是否正确，参考签名认证章节。

超过访问次数

表 1 超过访问次数

现象	HTTP状态码503。
排查方法	确认请求是否过于频繁，是否已经超出使用限制。
解决方法	避免设备直连数据源服务，使用自建服务器访问数据源服务。

注意事项

AGNSS 广播星历有效期通常约为 2 h，建议用户服务器每 1 h 或更短时间更新一次，终端侧应避免注入已过期数据。
PGNSS 的 period 仅支持 1、3、7、14、28，默认值为 7。选择更长周期时，应同时评估下载量、服务器内存和预测精度。
注入 AGNSS 或 PGNSS 数据前必须先注入参考时间，时间误差应控制在 10 s 内。PGNSS 还必须确认当前时间位于种子及扩展星历的有效窗口内。
每条辅助数据注入后应等待并校验 ACK；若采用固定间隔，建议按 data_size * 10 / current_bps 估算传输时间，避免连续数据覆盖。
APP_ID 必须与 APP_SECRET 匹配，UUID 应保持设备唯一。签名使用毫秒级 UNIX 时间戳，PGNSS 扩展接口中的 timestamp 使用秒级 UNIX 时间戳，不能混用。
下载脚本输出的二进制文件不应按文本修改。分发和存储时应保证文件完整性，并限制辅助数据目录的写权限。
下载示例为便于展示请求流程而关闭了 TLS 证书校验；实际产品应配置可信 CA、启用证书校验并安全存储凭据。