42 libgnss-GNSS定位

作者：李源龙　|　最后修改：2026-10-29

一、概述

当前使用libgnss核心库去实现gnss应用会比较麻烦，需要自己先去设置串口号，然后打开gnss电源，然后设置绑定串口2，再然后需要打开debug功能，还要去自己调用agps的接口，自己设置步骤太繁琐，而且有些指令不知道到底要不要去操作，所以LuatOS新增了exgnss扩展库，简化了gnss的使用。exgnss扩展库是对libgnss核心库的封装，使用起来更加简单。

libgnss核心库和exgnss扩展库的区别如下：

区别项	libgnss核心库	exgnss扩展库
打开方式	需要自己先去设置串口号，然后打开gnss电源，然后设置绑定串口2，再然后需要打开debug功能，还要去自己调用agps的接口	用exgnss.setup设置，然后用exgnss.open操作
应用场景	需要自己去用定时器开启，定时器关闭，或者定位成功再去手动调用关闭电源去操作	提供三种比较经典的应用场景

本篇文章仅介绍libgnss核心库，如果需要了解exgnss扩展库，请 点击此处

二、核心示例

function gnss_open()
    --打开gnss电源
    pm.power(pm.GPS, true)
    --设置串口号和波特率
    uart.setup(2, 115200)
    --绑定串口2
    libgnss.bind(2)
    --打开debug功能，输出日志到luatools
    libgnss.debug(true)
end

sys.taskInit(gnss_open)

-- 可选调试模式
-- libgnss.debug(true)


--GNSS定位状态的消息处理函数：
local function gnss_state(event, ticks)
    -- event取值有
    -- "FIXED"：string类型 定位成功
    -- "LOSE"： string类型 定位丢失
    -- ticks number类型 是事件发生的时间,一般可以忽略
    log.info("exgnss", "state", event)
    if event=="FIXED" then
        --获取rmc数据
        --json.encode默认输出"7f"格式保留7位小数，可以根据自己需要的格式调整小数位，本示例保留5位小数
        log.info("nmea", "rmc0", json.encode(libgnss.getRmc(0),"5f"))
    end
end
sys.subscribe("GNSS_STATE",gnss_state)

三、常量详解

libgnss库没有常量

四、函数详解

libgnss.isFix()

功能

gnss是否定位成功

注意事项

暂无

参数

无

返回值

local result = libgnss.isFix()

result

参数含义：是否定位成功；
数据类型：boolean；
取值范围：true/false；
注意事项：true表示定位成功，false表示定位失败；

示例

local result = libgnss.isFix()
log.info("nmea", "isfix", result)

libgnss.getIntLocation(speed_type)

功能

获取number类型的位置和速度信息

注意事项

暂无

参数

speed_type

参数含义：速度单位；
数据类型：number；
取值范围：0 - m/h 米/小时，1 - m/s 米/秒，2 - km/h 千米/小时,3 - kn/h 英里/小时；
是否必选：否；
注意事项：默认0；
示例代码：libgnss.getIntLocation(speed_type)

返回值

local lat,lng,speed=libgnss.getIntLocation(0)

lat

参数含义：纬度数据；
数据类型：number；
取值范围：格式为 DDDDDDDDD，示例：343482649，DDDDDDDDD格式是由ddmm.mmmmm*100000转换而来，目的是作为整数，方便某些场景使用；
注意事项：无；

lng

参数含义：经度数据；
数据类型：number；
取值范围：格式为 DDDDDDDDD，示例：1135039700，DDDDDDDDD格式是由ddmm.mmmmm*100000转换而来，目的是作为整数，方便某些场景使用；
注意事项：无；

speed

参数含义：速度数据；
数据类型：number；
取值范围：单位根据speed_type决定，m/h, m/s, km/h, kn/h；
注意事项：无；

示例

--DDDDDDDDD格式是由ddmm.mmmmm*100000转换而来，目的是作为整数，方便某些场景使用，示例：343482649对应的原始值是3434.82649
-- 该数据是通过RMC转换的，如果想获取更详细的可以用libgnss.getRmc(1)
-- speed数据默认 米/小时，返回值例如：343482649   1135039700  390m/h
log.info("nmea", "loc", libgnss.getIntLocation())
-- speed数据米/秒，返回值例如：343482649   1135039700  0.1085478m/s
log.info("nmea", "loc", libgnss.getIntLocation(1))
-- speed数据千米/小时，返回值例如：343482649 1135039700  0.3907720km/h
log.info("nmea", "loc", libgnss.getIntLocation(2))
-- speed数据英里/小时，返回值例如：343482649 1135039700  0.2110000kn/h
log.info("nmea", "loc", libgnss.getIntLocation(3))

libgnss.getRmc(lnglat_mode)

功能

获取RMC的信息，经纬度，时间，速度，航向，定位是否有效，磁偏角

注意事项

暂无

参数

lnglat_mode

参数含义：经纬度数据的格式；
数据类型：number；
取值范围：0-ddmm.mmmmm格式, 1-DDDDDDDDD格式, 2-DD.DDDDDDD格式, 3-原始RMC字符串；
是否必选：是；
注意事项：无；
示例代码：libgnss.getRmc(0)

返回值

table类型，返回RMC信息，格式如下：

local rmc=libgnss.getRmc(lnglat_mode)

rmc

{
    -- 参数含义：地面航向；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：地面航向，单位为度，从北向起顺时针计算；
    course=344.9920044,     

    -- 参数含义：是否定位成功；
    -- 数据类型：boolean；
    -- 取值范围：true/false；
    -- 注意事项：true定位成功,false定位丢失；
    valid=true,   

    -- 参数含义：纬度；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：纬度, 正数为北纬, 负数为南纬；
    lat=34.5804405,  

    -- 参数含义：经度；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：经度, 正数为东经, 负数为西经；
    lng=113.8399506,  

    -- 参数含义：磁偏角；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：磁偏角，固定为0；
    variation=0,  

    -- 参数含义：地面速度；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：单位为"节"；
    speed=0.2110000,  

    -- 参数含义：年份；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：无；
    year=2025,   

    -- 参数含义：月份；
    -- 数据类型：number；
    -- 取值范围：1-12；
    -- 注意事项：无；
    month=1,     

    -- 参数含义：天；
    -- 数据类型：number；
    -- 取值范围：1-31；
    -- 注意事项：无；
    day=5,

    -- 参数含义：小时；
    -- 数据类型：number；
    -- 取值范围：0-23；
    -- 注意事项：无；
    hour=7, 

    -- 参数含义：分钟；
    -- 数据类型：number；
    -- 取值范围：0-59；
    -- 注意事项：无；
    min=23,

    -- 参数含义：秒；
    -- 数据类型：number；
    -- 取值范围：0-59；
    -- 注意事项：无；
    sec=20,
}

示例

--模式0示例：
--json.encode默认输出"7f"格式保留7位小数，可以根据自己需要的格式调整小数位，本示例保留5位小数
log.info("nmea", "rmc0", json.encode(libgnss.getRmc(0),"5f"))
--日志输出内容：{"variation":0,"lat":3434.82666,"min":54,"valid":true,"day":17,"lng":11350.39746,"speed":0.21100,"year":2025,"month":7,"sec":30,"hour":11,"course":344.99200}
--模式1示例：
--DDDDDDDDD格式是由DD.DDDDDDD*10000000转换而来，目的是作为整数，方便某些场景使用
log.info("nmea", "rmc1", json.encode(libgnss.getRmc(1)))
--日志输出内容：{"variation":0,"lat":345804414,"min":54,"valid":true,"day":17,"lng":1138399500,"speed":0.2110000,"year":2025,"month":7,"sec":30,"hour":11,"course":344.9920044}
--模式2示例：
--json.encode默认输出"7f"格式保留7位小数，可以根据自己需要的格式调整小数位
log.info("nmea", "rmc2", json.encode(libgnss.getRmc(2)))
--日志输出内容：{"variation":0,"lat":34.5804405,"min":54,"valid":true,"day":17,"lng":113.8399506,"speed":0.2110000,"year":2025,"month":7,"sec":30,"hour":11,"course":344.9920044}
--模式3示例：
log.info("nmea", "rmc3", libgnss.getRmc(3))
--日志输出内容：$GNRMC,115430.000,A,3434.82649,N,11350.39700,E,0.211,344.992,170725,,,A,S*02\r

libgnss.getGsv()

功能*

获取原始GSV信息

注意事项

暂无

参数

无

返回值

table类型，返回GSV信息，格式如下：

local gsv=libgnss.getGsv()

gsv

{
    -- 参数含义：总可见卫星数量；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：无；
    total_sats=24, 

    -- 参数含义：卫星信息数组，每个元素为一个table；
    -- 数据类型：table；
    -- 取值范围：无特别限制；
    -- 注意事项：无；
    sats=[
            {
            -- 参数含义：信噪比；
            -- 数据类型：number；
            -- 取值范围：无特别限制；
            -- 注意事项：无；
            snr=27,     

            -- 参数含义：方向角；
            -- 数据类型：number；
            -- 取值范围：无特别限制；
            -- 注意事项：无；
            azimuth=278, 

            -- 参数含义：仰角；
            -- 数据类型：number；
            -- 取值范围：无特别限制；
            -- 注意事项：无；
            elevation=59, 

            -- 参数含义：卫星类型；
            -- 数据类型：number；
            -- 取值范围：0 - GPS, 1 - BD, 2 - GLONASS, 3 - Galileo, 4 - QZSS；
            -- 注意事项：无；
            tp=0,     

            -- 参数含义：卫星编号；
            -- 数据类型：number；
            -- 取值范围：无特别限制；
            -- 注意事项：无；
            nr=4
            },
            // 这里忽略了22个卫星的信息
            {
            snr=0,
            azimuth=107,
            elevation=19,
            tp=1,
            nr=31
            }
        ]   
}

示例

log.info("nmea", "gsv", json.encode(libgnss.getGsv()))
-- 实例输出
-- {
--     "total_sats":24,      // 总可见卫星数量
--     "sats":[
--         {
--             "snr":27,     // 信噪比
--             "azimuth":278, // 方向角
--             "elevation":59, // 仰角
--             "tp":0,        // 0 - GPS, 1 - BD, 2 - GLONASS, 3 - Galileo, 4 - QZSS
--             "nr":4         // 卫星编号
--         },
--         // 这里忽略了22个卫星的信息
--         {
--             "snr":0,
--             "azimuth":107,
--             "elevation":19,
--             "tp":1,
--             "nr":31
--         }
--     ]
-- }

libgnss.getGsa(data_mode)

功能

获取原始GSA信息

注意事项

暂无

参数

data_mode

参数含义：输出模式；
数据类型：number；
取值范围：默认为0 -所有卫星系统全部输出在一起，1 - 每个卫星系统单独分开输出；
是否必选：否；
注意事项：无；
示例代码：libgnss.getGsa(0)

返回值

table类型，返回GSA信息，格式如下：

local gsa=libgnss.getGsa(data_mode)

gsa

-- 示例数据(模式0, 也就是默认模式)

{
    -- 参数含义：位置精度因子；
    -- 数据类型：number；
    -- 取值范围：0.00 - 99.99，不定位时值为 99.99；
    -- 注意事项：暂无；
    pdop=1.1770000,

    -- 参数含义：正在使用的卫星编号；
    -- 数据类型：table；
    -- 取值范围：无特别限制；
    -- 注意事项：暂无；
    sats=[15,13,5,18,23,20,24,30,24,13,33,38,8,14,28,41,6,39,25,16,32,27],

    -- 参数含义：垂直精度因子；
    -- 数据类型：number；
    -- 取值范围：垂直精度因子，0.00 - 99.99，不定位时值为 99.99；
    -- 注意事项：暂无；
    vdop=1.0160000, 

    -- 参数含义：水平精度因子；
    -- 数据类型：number；
    -- 取值范围：水平精度因子，0.00 - 99.99，不定位时值为 99.99；
    -- 注意事项：暂无；
    hdop=0.5940000,

    -- 参数含义：卫星系统编号；
    -- 数据类型：number；
    -- 取值范围：1为GPS，4为北斗，2为GLONASS，3为Galileo；
    -- 注意事项：暂无；
    sysid=1, 

    -- 参数含义：定位模式；
    -- 数据类型：number；
    -- 取值范围：1-未定位, 2-2D定位, 3-3D定位；
    -- 注意事项：暂无；
    fix_type=3
}

示例

log.info("nmea", "gsa", json.encode(libgnss.getGsa()))
--日志打印输出：
--[{"pdop":1.1770000,"sats":[15,13,5,18,23,20,24],"vdop":1.0160000,"hdop":0.5940000,"sysid":1,"fix_type":3},
--{"pdop":1.1770000,"sats":[30,24,13,33,38,8,14,28,41,6,39,25],"vdop":1.0160000,"hdop":0.5940000,"sysid":4,"fix_type":3},
--{"pdop":1.1770000,"sats":[16,32,27],"vdop":1.0160000,"hdop":0.5940000,"sysid":4,"fix_type":3},
--{"pdop":1.1770000,"sats":{},"vdop":1.0160000,"hdop":0.5940000,"sysid":2,"fix_type":3},
--{"pdop":1.1770000,"sats":{},"vdop":1.0160000,"hdop":0.5940000,"sysid":3,"fix_type":3}]

libgnss.getVtg(data_mode)

功能

获取VTG速度信息

注意事项

暂无

参数

data_mode

参数含义：输出模式；
数据类型：number/nil；
取值范围：3-原始字符串, 不传或者传其他值, 则返回浮点值；
是否必选：否；
注意事项：不传或者传其他值, 则返回浮点值；
示例代码：libgnss.getVtg()

返回值

table类型，返回VTG信息，格式如下：

local vtg=libgnss.getVtg(data_mode)

vtg

{
    -- 参数含义：速度；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：英里/小时；
    speed_knots=0,

    -- 参数含义：真北方向角；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：无；
    true_track_degrees=0,

        -- 参数含义：磁北方向角；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：无；
    magnetic_track_degrees=0, 

        -- 参数含义：速度；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：千米/小时；
    speed_kph=0 
}

示例

log.info("nmea", "vtg", json.encode(libgnss.getVtg()))
-- 输出内容：
-- {
--     "speed_knots":0,        // 速度, 英里/小时
--     "true_track_degrees":0,  // 真北方向角
--     "magnetic_track_degrees":0, // 磁北方向角
--     "speed_kph":0           // 速度, 千米/小时
-- }

--模式3
log.info("nmea", "vtg", libgnss.getVtg(3))
-- 返回值：$GNVTG,0.000,T,,M,0.000,N,0.000,K,A*13\r
-- 提醒: 在速度<5km/h时, 不会返回方向角

libgnss.getZda()

功能

获取原始ZDA时间和日期信息

注意事项

暂无

参数

无

返回值

table类型，返回VTG信息，格式如下：

local zda=libgnss.getZda()

zda

{
    -- 参数含义：本地时区的分钟；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：本地时区的分钟, 一般固定输出0；
    minute_offset=0, 

    -- 参数含义：本地时区的小时；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：本地时区的小时, 一般固定输出0；
    hour_offset=0, 

    -- 参数含义：年份；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：UTC 年，四位数字；
    year=2025,   

    -- 参数含义：月份；
    -- 数据类型：number；
    -- 取值范围：1-12；
    -- 注意事项：UTC 月；
    month=1,     

    -- 参数含义：天；
    -- 数据类型：number；
    -- 取值范围：1-31；
    -- 注意事项：UTC 日；
    day=5,

    -- 参数含义：小时；
    -- 数据类型：number；
    -- 取值范围：0-23；
    -- 注意事项：无；
    hour=7, 

    -- 参数含义：分钟；
    -- 数据类型：number；
    -- 取值范围：0-59；
    -- 注意事项：无；
    min=23,

    -- 参数含义：秒；
    -- 数据类型：number；
    -- 取值范围：0-59；
    -- 注意事项：无；
    sec=20,
}

示例

log.info("nmea", "zda", json.encode(libgnss.getZda()))
-- 实例输出
-- {
--     "minute_offset":0,   // 本地时区的分钟, 一般固定输出0
--     "hour_offset":0,     // 本地时区的小时, 一般固定输出0
--     "year":2023         // UTC 年，四位数字
--     "month":1,          // UTC 月，两位，01 ~ 12
--     "day":5,            // UTC 日，两位数字，01 ~ 31
--     "hour":7,           // 小时
--     "min":50,           // 分
--     "sec":14,           // 秒
-- }

libgnss.debug(mode)

功能

设置调试模式，是否输出GNSS原始数据到luatools日志中

注意事项

暂无

参数

mode

参数含义：设置调试模式；
数据类型：boolean；
取值范围：true/false 默认flase；
是否必选：是；
注意事项：无；
示例代码：libgnss.debug(true)

返回值

无

示例

-- 开启调试, 会输出GNSS原始数据到日志中
libgnss.debug(true)
-- 关闭调试,默认是false
libgnss.debug(false)

libgnss.getGga(data_mode)

功能

获取GGA数据

注意事项

没定位成功时，返回nil

参数

lnglat_mode

参数含义：经纬度数据的格式；
数据类型：number；
取值范围：0-ddmm.mmmmm格式, 1-DDDDDDDDD格式, 2-DD.DDDDDDD格式, 3-原始RMC字符串；
是否必选：是；
注意事项：无；
示例代码：libgnss.getGga(0)

返回值

table类型，GGA数据, 若如不存在会返回nil，格式如下：

local gga2 =libgnss.getGga(data_mode)

gga2

{
    -- 参数含义：经度；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：正数为东经, 负数为西经；
    longitude=114.3199081,

    -- 参数含义：差分校正时延；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：单位为秒；
    dgps_age=0, 

    -- 参数含义：海平面分离度, 或者为海拔；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：单位是米；
    altitude=86.4000015,

    -- 参数含义：水平精度因子；
    -- 数据类型：number；
    -- 取值范围：0.00 - 99.99，不定位时值为 99.99；
    -- 注意事项：无；
    hdop=0.5940000,

    -- 参数含义：椭球高；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：无；
    height=-13.6999998,

    -- 参数含义：定位状态标识；
    -- 数据类型：number；
    -- 取值范围：0 - 无效,1 - 单点定位,2 - 差分定位；
    -- 注意事项：无；
    fix_quality=1,

    -- 参数含义：参与定位的卫星数量；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：无；
    satellites_tracked=22,

    -- 参数含义：纬度；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：正数为北纬, 负数为南纬；
    latitude=34.7978172
}

示例

--模式0示例：
--json.encode默认输出"7f"格式保留7位小数，可以根据自己需要的格式调整小数位，本示例保留5位小数
local gga =libgnss.getGga(0)
if gga then
    log.info("GGA0", json.encode(gga, "5f"))
end
--{"longitude":11419.19531,"dgps_age":0,"altitude":86.40000,"hdop":0.59400,"height":-13.70000,"fix_quality":1,"satellites_tracked":22,"latitude":3447.86914}
--模式1示例：
--DDDDDDDDD格式是由DD.DDDDDDD*10000000转换而来，目的是作为整数，方便某些场景使用
local gga1 =libgnss.getGga(1)
if gga1 then
    log.info("GGA1", json.encode(gga1))
end
--{"longitude":1143199103,"dgps_age":0,"altitude":86.4000015,"hdop":0.5940000,"height":-13.6999998,"fix_quality":1,"satellites_tracked":22,"latitude":347978178}
--模式2示例：
--json.encode默认输出"7f"格式保留7位小数，可以根据自己需要的格式调整小数位
local gga2 =libgnss.getGga(2)
if gga2 then
    log.info("GGA2", json.encode(gga2))
end
--{"longitude":114.3199081,"dgps_age":0,"altitude":86.4000015,"hdop":0.5940000,"height":-13.6999998,"fix_quality":1,"satellites_tracked":22,"latitude":34.7978172}
--模式3示例：
local gga3 =libgnss.getGga(3)
if gga3 then
    log.info("GGA3", gga3)
end
--$GNGGA,131241.000,3434.81372,N,11350.39930,E,1,05,4.924,165.5,M,-15.2,M,,*6D\r

libgnss.getGll(data_mode)

功能

获取GLL数据

注意事项

没定位成功时，返回nil

参数

data_mode

参数含义：经纬度数据的格式；
数据类型：number；
取值范围：0-ddmm.mmmmm格式, 1-DDDDDDDDD格式, 2-DD.DDDDDDD格式；
是否必选：是；
注意事项：无；
示例代码：libgnss.getGll(0)

返回值

table类型，GLL数据, 若如不存在会返回nil，格式如下：

local gll2 = libgnss.getGll(data_mode)

gll2

{
    -- 参数含义：经度；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：正数为东经, 负数为西经；
    longitude=114.3199081,

    -- 参数含义：秒；
    -- 数据类型：number；
    -- 取值范围：0-59；
    -- 注意事项：无；
    sec=14,

    -- 参数含义：分钟；
    -- 数据类型：number；
    -- 取值范围：0-59；
    -- 注意事项：无；
    min=32,

    -- 参数含义：定位模式；
    -- 数据类型：string；
    -- 取值范围：V无效, A单点解, D差分解；
    -- 注意事项：无；
    mode="A",

    -- 参数含义：小时；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：UTC时间为准；
    hour=6,

    -- 参数含义：微妙数；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：通常为0；
    us=0,

    -- 参数含义：定位状态；
    -- 数据类型：string；
    -- 取值范围：定位状态, A有效, B无效；
    -- 注意事项：无；
    status="A",

    -- 参数含义：纬度；
    -- 数据类型：number；
    -- 取值范围：无特别限制；
    -- 注意事项：正数为北纬, 负数为南纬；
    latitude=34.7978172
}

libgnss.clear()

功能

清除历史定位数据

注意事项

暂无

参数

无

返回值

无

示例

-- 清除历史定位数据，如果在关闭gnss之后不清除的话，获取的数据是最后一次的定位数据
libgnss.clear()

libgnss.bind(id, next_id)

功能

绑定uart端口进行GNSS数据读取

注意事项

暂无

参数

id

参数含义：gnss绑定的串口id号；
数据类型：number；
取值范围：1,2,3；
是否必选：是；
注意事项：作为必需参数，若不提供会导致获取不到gnss的数据；
示例代码：libgnss.bind(2)

next_id

参数含义：转发原始NMEA数据到uart的id, 例如虚拟uart.VUART_0；
数据类型：number；
取值范围：1,2,3,uart.VUART_0；
是否必选：否；
注意事项：不能id参数一个串口；
示例代码：libgnss.bind(2, uart.VUART_0)

返回值

无

示例

-- 绑定uart2, 马上开始解析GNSS数据
libgnss.bind(2)

-- 从uart2读取并解析, 同时转发到虚拟串口0
libgnss.bind(2, uart.VUART_0)

libgnss.rtcAuto(enable)

功能

定位成功后自动设置RTC

注意事项

暂无

参数

enable

参数含义：定位成功后自动设置RTC；
数据类型：olean；
取值范围：true/false，默认false；
是否必选：是；
注意事项：无；
示例代码：libgnss.rtcAuto(true)

返回值

无

示例

-- 开启自动设置RTC
libgnss.rtcAuto(true)

libgnss.parse(str)

功能

手动把一段原始 NMEA 数据交给 libgnss 解析，解析结果与串口自动收到数据时完全一致，随后可用 getRmc、getGga、getVtg 等接口读出。

注意事项

1. 正常定位时不需要调用本接口，数据由 libgnss.bind 绑定的串口自动送入并解析；
2. 主要用于离线回放、自测，或者从网络/文件里拿到 NMEA 日志后做验证；
3. 一次传一条完整语句（以 $ 开头、以 CRLF 结尾）；校验和错误或语句不完整的会被丢弃，getRmc 不会更新；
4. 与 libgnss.getTxt() 配合，可以验证模块上报的 GPTXT 提示。

参数

str

参数含义：原始NMEA数据
数据类型：string
取值范围：单条完整NMEA语句，例如 "$GNRMC,...*hh\r\n"
是否必选：是
示例代码：libgnss.parse("$GPTXT,01,01,01,ANTENNA OK*35\r\n")

返回值

无

示例

-- 解析一条NMEA数据, 然后读取解析结果
libgnss.parse(indata)
log.info("nmea", json.encode(libgnss.getRmc(), "11g"))

libgnss.getTxt()

功能

获取最近一条 GPTXT 语句携带的文字内容。GPTXT 是模块自己上报的提示信息，最常见的是天线状态，例如 ANTENNA OK、ANTENNA OPEN、ANTENNA SHORT。

注意事项

1. 只保留最近一条 GPTXT，之前的内容会被覆盖；
2. 不是所有模块、所有固件都会输出 GPTXT，取到空字符串说明当前没有上报，并不代表定位异常；
3. 2023.6.6 新增本接口。

参数

无

返回值

GPTXT 所携带的字符串；没有收到过 GPTXT 时返回空字符串 ""。

示例

log.info("gnss", "txt", libgnss.getTxt())

-- 也可以用 parse 直接灌一条测试
libgnss.parse("$GPTXT,01,01,01,ANTENNA SHORT*63\r\n")
log.info("GNSS", libgnss.getTxt())   -- ANTENNA SHORT
libgnss.parse("$GPTXT,01,01,01,ANTENNA OK*35\r\n")
log.info("GNSS", libgnss.getTxt())   -- ANTENNA OK

libgnss.locStr(mode)

功能

把最近一次定位结果（RMC 帧）拼装成字符串，便于直接上报到平台或做日志记录。

注意事项

1. 数据来自最近解析到的 RMC，只建议在定位成功（libgnss.isFix() 为 true）之后调用，否则拼出来的内容没有实际意义；
2. mode 只实现了 0 和 1，传其它值会返回空字符串；
3. mode 1 返回的是模块原始整数表示，需要自己按经纬度换算规则还原，一般业务直接用 0。

参数

mode

参数含义：字符串模式
数据类型：number
取值范围：
         0 - 默认值，纬度,南北,经度,东西,1.0，即 "23.1234567,N,113.1234567,E,1.0"
         1 - 原始整数值，即 "纬度原值,经度原值"
是否必选：否，默认0
示例代码：local s = libgnss.locStr(0)

返回值

指定模式的定位字符串；mode 非法时为空字符串。

示例

if libgnss.isFix() then
    log.info("loc", libgnss.locStr(0))   -- 23.1234567,N,113.1234567,E,1.0
end

libgnss.casic_aid(dt, loc)

功能

合成 CASIC 系列 GNSS 模块所需的辅助定位数据（AGNSS AID）。把“大概的时间 + 大概的位置”预先交给模块，可以明显缩短首次定位时间。

注意事项

1. 只适用于 CASIC 系列 GNSS 模块，其它方案（如 ublox）不认这组数据；
2. 时间必须是 UTC，一般用 socket.sntp() 同步之后取 os.date("!*t")；
3. 位置坐标系是 WGS84，因为是辅助定位，精度不要求很高，基站定位、WiFi 定位、IP 定位得到的粗略坐标都可以用；
4. 年份大于 2022 时才认为时间有效；经纬度都接近 0 时认为位置无效，这两种情况合成的数据不会起作用；
5. 2023.11.14 新增本接口。

参数

dt

参数含义：时间信息表
数据类型：table
取值范围：字段 day、month（或 mon）、year、hour、min、sec，缺省按 0 处理
是否必选：是
注意事项：必须是UTC时间；os.date("!*t") 用 month 字段，rtc.get() 用 mon 字段，两种写法都兼容
示例代码：local dt = os.date("!*t")

loc

参数含义：经纬度及海拔
数据类型：table
取值范围：lat、lng 必填（number，或可转成数字的字符串），alt 可选
是否必选：是
注意事项：WGS84 坐标系，东经北纬为正
示例代码：local lla = { lat = 23.12, lng = 114.12 }

返回值

string，定长 66 字节的二进制辅助定位数据，直接发给模块即可。

示例

-- 时间来自SNTP同步后的系统时间(UTC)
local dt = os.date("!*t")
-- 位置可以来自上一次定位、基站定位或WiFi定位
local lla = { lat = 23.12, lng = 114.12 }
local aid = libgnss.casic_aid(dt, lla)

五、产品支持说明

不同产品的LuatOS固件，对libgnss核心库的支持情况如下：

1、Air780EX2/Air700ECP/Air780EPM/Air780EGP 103号、104号、105号固件支持；

2、Air700ECH/Air780EHM/EHV/EGH/EGG/EHU/EHN/Air8000系列 所有固件支持；

3、Air8101系列 不支持；

4、Air1601 / Air1602 都不支持；

各产品固件支持核心库列表详细说明参考下面链接：

Air780EX2/Air700ECP/Air780EPM/Air780EGP固件支持列表

Air700ECH/Air780EHM/EHV/EGH/EGG/EHU/EHN固件支持列表

Air8000系列所有型号固件支持列表

Air8101系列所有型号固件支持列表

Air1601/Air1602固件支持列表