libgnss - NMEA数据处理
作者:李源龙
一、概述
当前使用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格式是由DD.DDDDDDD*10000000转换而来,目的是作为整数,方便某些场景使用;
注意事项:无;
lng
参数含义:经度数据;
数据类型:number;
取值范围:格式为 DDDDDDDDD,示例:1135039700,DDDDDDDDD格式是由DD.DDDDDDD*10000000转换而来,目的是作为整数,方便某些场景使用;
注意事项:无;
speed
参数含义:速度数据;
数据类型:number;
取值范围:单位根据speed_type决定,m/h, m/s, km/h, kn/h;
注意事项:无;
示例
--DDDDDDDDD格式是由DD.DDDDDDD*10000000转换而来,目的是作为整数,方便某些场景使用,示例:343482649对应的原始值是34.3482649
-- 该数据是通过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)