gnss

GNSS（Global Navigation Satellite System）模块提供卫星定位功能接口，支持GNSS芯片的初始化、配置、启停控制及数据回调等功能。

头文件清单

#include "middleware/services/gnss/gnss_device.h"

接口清单

接口名称	功能简述
uapi_gnss_register_callback	注册GNSS消息回调函数
uapi_gnss_init	GNSS初始化，创建任务线程
uapi_gnss_open	GNSS加载，打开设备节点并加载固件
uapi_gnss_config	GNSS配置接口
uapi_gnss_start	GNSS启动，开始上报定位信息
uapi_gnss_stop	GNSS停止，停止上报定位信息
uapi_gnss_close	GNSS卸载，关闭设备节点
uapi_gnss_deinit	GNSS去初始化，退出任务线程
uapi_gnss_register_power_callback	注册GNSS上下电回调函数
uapi_gnss_set_xgnss_type	配置辅助GNSS数据类型
uapi_gnss_register_xgnss_req_callback	注册请求xgnss回调函数
uapi_notify_xgnss_updated	通知xgnss更新完成
uapi_gnss_register_log_callback	注册GNSS日志回调函数
uapi_gnss_set_pos_type	配置GNSS定位类型
uapi_gnss_set_file_path	配置GNSS文件存储路径
uapi_gnss_power_on	GNSS上电
uapi_gnss_power_off	GNSS下电

Functions

uapi_gnss_register_callback

gnss_register_callback uapi gnss register callback uapi_gnss_register_callback

errcode_t uapi_gnss_register_callback(uint32_t callback_type, gnss_callback_func callback_func)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• 注册GNSS消息回调函数
• 根据回调类型注册对应的消息处理回调
• 支持二进制消息和NMEA数据两种回调类型

前置条件

• 调用时序约束：需在uapi_gnss_init()成功返回后调用
• 依赖关系：依赖GNSS模块已完成初始化

入参

名称	参数类型	详细说明	约束取值范围
callback_type	uint32_t	回调消息类型	- GNSS_CALLBACK_MSG(0) - GNSS_CALLBACK_NMEA(1)
callback_func	gnss_callback_func	回调函数地址	非NULL

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	注册成功
ERRCODE_GNSS_CALLBACK_TYPE_ERROR(0x8000A003)	回调类型错误	callback_type不在有效范围内
ERRCODE_GNSS_CALLBACK_FUNC_ERROR(0x8000A004)	回调函数地址错误	callback_func为NULL
ERRCODE_GNSS_CALLBACK_EXISTED(0x8000A005)	回调函数已注册	该类型回调已被注册
Other	其他错误码，参考errcode_t	执行失败

参考案例

• src/application/samples/gnss/gnss_at_samples/gnss_common_proc.c

uapi_gnss_init

gnss_init uapi gnss init uapi_gnss_init

errcode_t uapi_gnss_init(void)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• GNSS初始化接口
• 创建GNSS任务线程
• 创建消息队列

前置条件

• 调用时序约束：需在其他GNSS接口之前调用
• 依赖关系：依赖系统消息队列和线程创建能力

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	初始化成功或已初始化
ERRCODE_FAIL(0xFFFFFFFF)	执行失败	消息队列创建失败或tiot服务初始化失败
ERRCODE_GNSS_CREATE_THREAD_FAILED(0x8000A000)	创建线程失败	GNSS任务线程创建失败
Other	其他错误码，参考errcode_t	执行失败

参考案例

• src/application/samples/gnss/gnss_at_samples/gnss_common_proc.c

uapi_gnss_open

gnss_open uapi gnss open uapi_gnss_open

errcode_t uapi_gnss_open(void)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• GNSS加载接口
• 打开GNSS设备节点
• 加载GNSS固件

前置条件

• 调用时序约束：需在uapi_gnss_init()成功返回后调用
• 依赖关系：需确保板级已给GNSS芯片上电

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	设备打开成功
ERRCODE_FAIL(0xFFFFFFFF)	执行失败	设备已打开或内存分配失败
ERRCODE_GNSS_OPEN_GNSS_FAILED(0x8000A001)	打开GNSS设备失败	tiot服务打开失败
Other	其他错误码，参考errcode_t	执行失败

参考案例

• src/application/samples/gnss/gnss_at_samples/gnss_common_proc.c

uapi_gnss_config

gnss_config uapi gnss config uapi_gnss_config

errcode_t uapi_gnss_config(gnss_message_t *msg)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• GNSS配置接口
• 向GNSS芯片发送配置消息
• 支持查询和设置两种配置模式

前置条件

• 调用时序约束：需在uapi_gnss_open()成功返回后调用
• 依赖关系：部分配置项需在uapi_gnss_start()之前调用，请参考GNSS芯片手册

入参

名称	参数类型	详细说明	约束取值范围
msg	gnss_message_t *	配置项消息指针	非NULL

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	配置成功
ERRCODE_FAIL(0xFFFFFFFF)	执行失败	msg为NULL或写入设备失败或等待ACK超时
ERRCODE_GNSS_CONFIG_ITEM_LEN_ERROR(0x8000A00C)	配置项长度错误	ACK返回长度错误
ERRCODE_GNSS_CONFIG_ITEM_PARA_ERROR(0x8000A00D)	配置项参数错误	ACK返回参数错误
ERRCODE_GNSS_CONFIG_ITEM_TYPE_ERROR(0x8000A00B)	配置项类型错误	ACK返回类型错误
ERRCODE_GNSS_CONFIG_ITEM_PROC_ERROR(0x8000A00E)	配置项处理错误	ACK返回处理错误
Other	其他错误码，参考errcode_t	执行失败

参考案例

• src/application/samples/gnss/gnss_at_samples/gnss_common_proc.c
• src/application/samples/gnss/gnss_at_samples/gnss_normal.c
• src/application/samples/gnss/gnss_at_samples/gnss_factory_test.c

uapi_gnss_start

gnss_start uapi gnss start uapi_gnss_start

errcode_t uapi_gnss_start(void)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• GNSS启动接口
• 查询GNSS芯片版本信息
• 启动GNSS定位功能，开始上报定位信息

前置条件

• 调用时序约束：需在uapi_gnss_open()成功返回后调用
• 依赖关系：依赖GNSS设备已打开且固件已加载

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	启动成功
Other	其他错误码，参考errcode_t	执行失败

参考案例

• src/application/samples/gnss/gnss_at_samples/gnss_common_proc.c

uapi_gnss_stop

gnss_stop uapi gnss stop uapi_gnss_stop

errcode_t uapi_gnss_stop(void)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• GNSS停止接口
• 停止GNSS定位功能，停止上报定位信息

前置条件

• 调用时序约束：需在uapi_gnss_start()成功返回后调用
• 依赖关系：依赖GNSS已在运行状态

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	停止成功
Other	其他错误码，参考errcode_t	执行失败

参考案例

• src/application/samples/gnss/gnss_at_samples/gnss_common_proc.c

uapi_gnss_close

gnss_close uapi gnss close uapi_gnss_close

errcode_t uapi_gnss_close(void)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• GNSS卸载接口
• 关闭GNSS设备节点
• 释放回调函数资源

前置条件

• 调用时序约束：需在uapi_gnss_stop()成功返回后调用
• 依赖关系：依赖GNSS设备已打开

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	关闭成功
ERRCODE_FAIL(0xFFFFFFFF)	执行失败	设备未打开
Other	其他错误码，参考errcode_t	执行失败

参考案例

• src/application/samples/gnss/gnss_at_samples/gnss_common_proc.c

uapi_gnss_deinit

gnss_deinit uapi gnss deinit uapi_gnss_deinit

errcode_t uapi_gnss_deinit(void)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• GNSS去初始化接口
• 销毁GNSS任务线程
• 删除消息队列

前置条件

• 调用时序约束：需在uapi_gnss_close()成功返回后调用
• 依赖关系：依赖GNSS模块已完成初始化

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	去初始化成功
Other	其他错误码，参考errcode_t	执行失败

参考案例

• src/application/samples/gnss/gnss_at_samples/gnss_common_proc.c

uapi_gnss_register_power_callback

gnss_register_power_callback uapi gnss register power callback uapi_gnss_register_power_callback

errcode_t uapi_gnss_register_power_callback(power_callback_func power_on_callback, power_callback_func power_off_callback)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• 注册GNSS上下电回调函数
• 支持分别注册上电和下电回调
• 用于GNSS芯片板级电源管理

前置条件

• 调用时序约束：需在uapi_gnss_power_on/off()之前调用
• 依赖关系：依赖GNSS模块已完成初始化

入参

名称	参数类型	详细说明	约束取值范围
power_on_callback	power_callback_func	上电回调函数地址	非NULL
power_off_callback	power_callback_func	下电回调函数地址	非NULL

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	注册成功
Other	其他错误码，参考errcode_t	执行失败

uapi_gnss_set_xgnss_type

gnss_set_xgnss_type uapi gnss set xgnss type uapi_gnss_set_xgnss_type

errcode_t uapi_gnss_set_xgnss_type(uint8_t xgnss_type)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• 配置辅助GNSS数据类型
• 支持PGNSS和AGNSS两种辅助类型
• 默认类型为PGNSS

前置条件

• 调用时序约束：需在uapi_gnss_start()之前调用
• 依赖关系：依赖GNSS模块已完成初始化

入参

名称	参数类型	详细说明	约束取值范围
xgnss_type	uint8_t	辅助GNSS数据类型	- PGNSS_TYPE(0) - AGNSS_TYPE(1)

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	设置成功
Other	其他错误码，参考errcode_t	执行失败

uapi_gnss_register_xgnss_req_callback

gnss_register_xgnss_req_callback uapi gnss register xgnss req callback uapi_gnss_register_xgnss_req_callback

errcode_t uapi_gnss_register_xgnss_req_callback(xgnss_request_func callback_func)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• 注册请求xgnss回调函数
• 当GNSS芯片请求辅助数据时触发回调
• 用于辅助数据注入流程

前置条件

• 调用时序约束：需在uapi_gnss_start()之前调用
• 依赖关系：依赖GNSS模块已完成初始化

入参

名称	参数类型	详细说明	约束取值范围
callback_func	xgnss_request_func	请求xgnss回调函数地址	非NULL

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	注册成功
Other	其他错误码，参考errcode_t	执行失败

uapi_notify_xgnss_updated

notify_xgnss_updated uapi notify xgnss updated uapi_notify_xgnss_updated

errcode_t uapi_notify_xgnss_updated(void)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• 通知xgnss更新完成
• 触发GNSS芯片读取辅助数据

前置条件

• 调用时序约束：需在用户将xgnss辅助数据保存到文件后调用
• 依赖关系：依赖xgnss辅助数据文件已写入完成

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	通知成功
Other	其他错误码，参考errcode_t	执行失败

uapi_gnss_register_log_callback

gnss_register_log_callback uapi gnss register log callback uapi_gnss_register_log_callback

errcode_t uapi_gnss_register_log_callback(gnss_log_callback callback_func)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• 注册GNSS日志回调函数
• 用于接收GNSS模块的日志输出
• 用户不需要日志时可跳过注册

入参

名称	参数类型	详细说明	约束取值范围
callback_func	gnss_log_callback	日志回调函数地址	非NULL

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	注册成功
Other	其他错误码，参考errcode_t	执行失败

uapi_gnss_set_pos_type

gnss_set_pos_type uapi gnss set pos type uapi_gnss_set_pos_type

errcode_t uapi_gnss_set_pos_type(uint8_t pos_type)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• 配置GNSS定位类型
• 默认类型为PVT

前置条件

• 调用时序约束：需在uapi_gnss_start()之前调用
• 依赖关系：依赖GNSS模块已完成初始化

入参

名称	参数类型	详细说明	约束取值范围
pos_type	uint8_t	定位类型	- GNSS_PVT_TYPE(0)

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	设置成功
Other	其他错误码，参考errcode_t	执行失败

uapi_gnss_set_file_path

gnss_set_file_path uapi gnss set file path uapi_gnss_set_file_path

errcode_t uapi_gnss_set_file_path(char *path)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• 配置GNSS文件存储路径
• 日志、xgnss辅助数据和历史文件将保存到该路径
• 默认路径为/user/gnss/

前置条件

• 调用时序约束：需在uapi_gnss_start()之前调用
• 依赖关系：依赖GNSS模块已完成初始化

入参

名称	参数类型	详细说明	约束取值范围
path	char *	文件存储路径	非NULL，有效文件路径

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	设置成功
Other	其他错误码，参考errcode_t	执行失败

uapi_gnss_power_on

gnss_power_on uapi gnss power on uapi_gnss_power_on

errcode_t uapi_gnss_power_on(void)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• GNSS上电接口
• 使能GNSS芯片32K时钟输出
• 需配合上下电回调使用

前置条件

• 调用时序约束：需在uapi_gnss_register_power_callback()注册回调后调用
• 依赖关系：依赖上下电回调已注册

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	上电成功

参考案例

• src/application/samples/gnss/gnss_at_samples/gnss_common_proc.c

uapi_gnss_power_off

gnss_power_off uapi gnss power off uapi_gnss_power_off

errcode_t uapi_gnss_power_off(void)

头文件清单

#include "middleware/services/gnss/gnss_device.h"

功能说明

• GNSS下电接口
• 关闭GNSS芯片32K时钟输出
• 需配合上下电回调使用

前置条件

• 调用时序约束：需在uapi_gnss_register_power_callback()注册回调后调用
• 依赖关系：依赖上下电回调已注册

返回值

返回值	文字含义	触发场景
ERRCODE_SUCC(0x00)	执行成功	下电成功

参考案例

• src/application/samples/gnss/gnss_at_samples/gnss_common_proc.c

Type definitions

errcode_t

errcode t errcode_t

typedef uint32_t errcode_t;

使用说明

本模块所有对外接口的返回值类型 [SDK公共基础类型]

gnss_callback_func

typedef void (*gnss_callback_func)(uint8_t *buff, uint32_t len);

使用说明

uapi_gnss_register_callback接口的回调函数类型

调用时机

当GNSS芯片上报二进制消息或NMEA数据时，已注册的回调函数将被调用，buff为数据缓冲区指针，len为数据长度

power_callback_func

typedef void (*power_callback_func)(void);

使用说明

uapi_gnss_register_power_callback接口的回调函数类型

调用时机

当调用uapi_gnss_power_on()时触发上电回调，调用uapi_gnss_power_off()时触发下电回调，用于板级电源控制

xgnss_request_func

typedef void (*xgnss_request_func)(void);

使用说明

uapi_gnss_register_xgnss_req_callback接口的回调函数类型

调用时机

当GNSS芯片请求辅助数据（PGNSS或AGNSS）时触发该回调，用户应在回调中准备辅助数据并调用uapi_notify_xgnss_updated()通知更新完成

gnss_log_callback

typedef void (*gnss_log_callback)(const char* log_level, const char* fmt, ...);

使用说明

uapi_gnss_register_log_callback接口的回调函数类型

调用时机

当GNSS模块产生日志输出时触发该回调，log_level为日志级别，fmt为格式化字符串

Enumerations

gnss_callback_enum_t

typedef enum {
    GNSS_CALLBACK_MSG = 0,
    GNSS_CALLBACK_NMEA = 1,
} gnss_callback_enum_t;

枚举成员	取值	描述
GNSS_CALLBACK_MSG	0	二进制数据类型
GNSS_CALLBACK_NMEA	1	NMEA数据类型

gnss_pos_type_t

typedef enum {
    GNSS_PVT_TYPE = 0,
    GNSS_POS_TYPE_BUTT = 2,
} gnss_pos_type_t;

枚举成员	取值	描述
GNSS_PVT_TYPE	0	PVT定位模式
GNSS_POS_TYPE_BUTT	2	定位类型边界值

gnss_xgnss_type_t

typedef enum {
    PGNSS_TYPE = 0,
    AGNSS_TYPE = 1,
    XGNSS_TYPE_BUTT = 2,
} gnss_xgnss_type_t;

枚举成员	取值	描述
PGNSS_TYPE	0	PGNSS辅助类型
AGNSS_TYPE	1	AGNSS辅助类型
XGNSS_TYPE_BUTT	2	辅助类型边界值

Structures

gnss_message_t

#pragma pack(1)
typedef struct gnss_message {
    uint16_t  message_type;
    uint16_t  message_chksum;
    uint16_t  message_sequence;
    uint16_t  payload_length;
    uint8_t   payload[0];
} gnss_message_t;
#pragma pack()

成员说明

成员名称	数据类型	描述
message_type	uint16_t	消息类型，请参考芯片手册
message_chksum	uint16_t	消息载荷的校验和，不包括消息头8字节
message_sequence	uint16_t	消息序号，默认为0
payload_length	uint16_t	消息载荷长度，不包括消息头8字节
payload	uint8_t[0]	消息载荷

Macros

ERRCODE_SUCC

errcode succ errcode_succ

#define ERRCODE_SUCC                                        0UL

ERRCODE_FAIL

errcode fail errcode_fail

#define ERRCODE_FAIL                                        0xFFFFFFFF

ERRCODE_GNSS_CREATE_THREAD_FAILED

errcode gnss create thread failed errcode_gnss_create_thread_failed gnss_create_thread_failed

#define ERRCODE_GNSS_CREATE_THREAD_FAILED                   0x8000A000

ERRCODE_GNSS_OPEN_GNSS_FAILED

errcode gnss open gnss failed errcode_gnss_open_gnss_failed gnss_open_gnss_failed

#define ERRCODE_GNSS_OPEN_GNSS_FAILED                       0x8000A001

ERRCODE_GNSS_CLOSE_GNSS_FAILED

errcode gnss close gnss failed errcode_gnss_close_gnss_failed gnss_close_gnss_failed

#define ERRCODE_GNSS_CLOSE_GNSS_FAILED                      0x8000A002

ERRCODE_GNSS_CALLBACK_TYPE_ERROR

errcode gnss callback type error errcode_gnss_callback_type_error gnss_callback_type_error

#define ERRCODE_GNSS_CALLBACK_TYPE_ERROR                    0x8000A003

ERRCODE_GNSS_CALLBACK_FUNC_ERROR

errcode gnss callback func error errcode_gnss_callback_func_error gnss_callback_func_error

#define ERRCODE_GNSS_CALLBACK_FUNC_ERROR                    0x8000A004

ERRCODE_GNSS_CALLBACK_EXISTED

errcode gnss callback existed errcode_gnss_callback_existed gnss_callback_existed

#define ERRCODE_GNSS_CALLBACK_EXISTED                       0x8000A005

ERRCODE_GNSS_MESSAGE_TYPE_ERROR

errcode gnss message type error errcode_gnss_message_type_error gnss_message_type_error

#define ERRCODE_GNSS_MESSAGE_TYPE_ERROR                     0x8000A006

ERRCODE_GNSS_MESSAGE_LEN_ERROR

errcode gnss message len error errcode_gnss_message_len_error gnss_message_len_error

#define ERRCODE_GNSS_MESSAGE_LEN_ERROR                      0x8000A007

ERRCODE_GNSS_MESSAGE_CHKSUM_ERROR

errcode gnss message chksum error errcode_gnss_message_chksum_error gnss_message_chksum_error

#define ERRCODE_GNSS_MESSAGE_CHKSUM_ERROR                   0x8000A008

ERRCODE_GNSS_MESSAGE_SEND_TO_DEVICE_FAILED

errcode gnss message send to device failed errcode_gnss_message_send_to_device_failed gnss_message_send_to_device_failed

#define ERRCODE_GNSS_MESSAGE_SEND_TO_DEVICE_FAILED          0x8000A009

ERRCODE_GNSS_MESSAGE_WAIT_FOR_ACK_FAILED

errcode gnss message wait for ack failed errcode_gnss_message_wait_for_ack_failed gnss_message_wait_for_ack_failed

#define ERRCODE_GNSS_MESSAGE_WAIT_FOR_ACK_FAILED            0x8000A00A

ERRCODE_GNSS_CONFIG_ITEM_TYPE_ERROR

errcode gnss config item type error errcode_gnss_config_item_type_error gnss_config_item_type_error

#define ERRCODE_GNSS_CONFIG_ITEM_TYPE_ERROR                 0x8000A00B

ERRCODE_GNSS_CONFIG_ITEM_LEN_ERROR

errcode gnss config item len error errcode_gnss_config_item_len_error gnss_config_item_len_error

#define ERRCODE_GNSS_CONFIG_ITEM_LEN_ERROR                  0x8000A00C

ERRCODE_GNSS_CONFIG_ITEM_PARA_ERROR

errcode gnss config item para error errcode_gnss_config_item_para_error gnss_config_item_para_error

#define ERRCODE_GNSS_CONFIG_ITEM_PARA_ERROR                 0x8000A00D

ERRCODE_GNSS_CONFIG_ITEM_PROC_ERROR

errcode gnss config item proc error errcode_gnss_config_item_proc_error gnss_config_item_proc_error

#define ERRCODE_GNSS_CONFIG_ITEM_PROC_ERROR                 0x8000A00E