libgnss - NMEA Data processing#

Adapted Air780E/Air700E Air780EP Air601 Air101/Air103 Air105 ESP32C3 ESP32S3

Note

This page document is automatically generated by this file. If there is any error, please submit issue or help modify pr, thank you!

Tip

This library has its own demo,click this link to view libgnss demo examples

Example

-- Reminder: the coordinates output by this library are all WGS84 coordinate system
-- If it needs to be used in domestic maps, it should be converted into the coordinate system of the corresponding map, for example GCJ02 BD09
-- Related Links: https://lbsyun.baidu.com/index.php?title=coordinate
-- Related Links: https://www.openluat.com/GPS-Offset.html

-- Reminder: GPS function, GNSS function, NMEA analysis function, are sub-functions of the current library
-- The main function of this library is to parse the NMEA protocol and support both built-in GNSS and external GNSS.GNSS

-- The following is sample code using this libgnss
-- Scheme 1, data transfer through lua layer
uart.setup(2, 115200)
uart.on(2, "recv", function(id, len)
    while 1 do
        local data = uart.read(id, 1024)
        if data and #data > 1 then
            libgnss.parse(data)
        else
            break
        end
    end
end)
-- Scheme 2 is suitable for compiling firmware after 2022.12.26, which is more efficient.
uart.setup(2, 115200)
libgnss.bind(2)

-- Optional debug mode
-- libgnss.debug(true)

sys.subscribe("GNSS_STATE", function(event, ticks)
    -- event Values are
    -- FIXED Positioning success
    -- LOSE  LOST POSITIONING
    -- ticks is the time of the event and can generally be ignored
    log.info("gnss", "state", event, ticks)
end)

libgnss.parse(str)#

Processing nmea data

Parameters

Incoming Value Type

Explanation

string

raw nmea data

Return Value

None

Examples

-- Parsing nmea data
libgnss.parse(indata)
log.info("nmea", json.encode(libgnss.getRmc(), "11g"))

libgnss.isFix()#

Whether the current location has been successful

Parameters

None

Return Value

return value type

explanation

boolean

Positioning success or not

Examples

log.info("nmea", "isFix", libgnss.isFix())

libgnss.getIntLocation(speed_type)#

Get location information

Parameters

Incoming Value Type

Explanation

int

Speed unit, default is m/h

Return Value

return value type

explanation

int

lat Data in the format ddddddddd

int

lng Data in the format ddddddddd

int

speed Data in metres. As amended on 2023.9.26

Examples

-- It is recommended to use libgnss.getRmc(1)
log.info("nmea", "loc", libgnss.getIntLocation())

-- 2023.12.11 Added speed_type parameters
--[[
Speed unit selectable value
0 - m/h meter/hour, default, integer
1 - m/s m/s, floating point number
2 - km/h km/hour, floating point number
3 - kn/h Miles per hour, float
]]
-- Default meter/hour
log.info("nmea", "loc", libgnss.getIntLocation())
-- m/s
log.info("nmea", "loc", libgnss.getIntLocation(1))
-- km/hour
log.info("nmea", "loc", libgnss.getIntLocation(2))
-- mile/hour
log.info("nmea", "loc", libgnss.getIntLocation(3))

libgnss.getRmc(data_mode)#

Get Raw RMC Location Information

Parameters

Incoming Value Type

Explanation

int

Format of coordinate data, 0-DDMM.MMM format, 1-DDDDDDD format, 2-DD.DDDDD format

Return Value

return value type

explanation

table

raw rmc data

Examples

-- Parsing nmea
log.info("nmea", "rmc", json.encode(libgnss.getRmc(2)))
-- Instance output
--[[
{
    "course":0,
    "valid":true,   // true Positioning successful, false positioning lost
    "lat":23.4067,  // Latitude, positive number is north latitude, negative number is south latitude
    "lng":113.231,  // Longitude, the positive number is east longitude, the negative number is west longitude
    "variation":0,  // Ground heading, in degrees, clockwise from the north
    "speed":0       // Ground speed in "knots""
    "year":2023,    // Year
    "month":1,      // Months, 1-12
    "day":5,        // Month Day, 1-31
    "hour":7,       // Hours,0-23
    "min":23,       // Minutes,0-59
    "sec":20,       // Seconds,0-59
}
]]

libgnss.getGsv()#

Get original GSV information

Parameters

None

Return Value

return value type

explanation

table

Raw GSV data

Examples

-- Parsing nmea
log.info("nmea", "gsv", json.encode(libgnss.getGsv()))
--[[Instance output
{
    "total_sats":24,      // Total number of visible satellites
    "sats":[
        {
            "snr":27,     // signal-to-noise ratio
            "azimuth":278, // Direction angle
            "elevation":59, // elevation angle
            "tp":0,        // 0 - GPS, 1 - BD
            "nr":4         // Satellite Number
        },
        // Information from 22 satellites is ignored here
        {
            "snr":0,
            "azimuth":107,
            "elevation":19,
            "tp":1,
            "nr":31
        }
    ]
}
]]

libgnss.getGsa(data_mode)#

Get Raw GSA Information

Parameters

Incoming Value Type

Explanation

int

Mode

Return Value

return value type

explanation

table

Raw GSA Data

Examples

-- Get
log.info("nmea", "gsa", json.encode(libgnss.getGsa(), "11g"))
-- Sample data (mode 0, which is the default mode)
--[[
{
    "sats":[ // Satellite number in use
        9,
        6,
        16,
        16,
        26,
        21,
        27,
        27,
        4,
        36,
        3,
        7,
        8,
        194
    ],
    "vdop":0.03083333, // Vertical precision factor, 0.00 - 99.99, with a value 99.99
    "pdop":0.0455,     // Horizontal accuracy factor, 0.00 - 99.99, with a value 99.99
    "fix_type":3,      // Positioning mode, 1-unpositioned, 2-2D positioning, 3-3D positioning
    "hdop":0.0335      // Position accuracy factor, 0.00 - 99.99, with a value 99.99
}
]]

-- Sample data (Mode 1), 2024.5.26 New
[
    {"pdop":7.8299999,"sats":[13,15,18,23],"vdop":3.2400000,"hdop":7.1300001,"fix_type":3},
    {"pdop":7.8299999,"sats":[20,35,8,13],"vdop":3.2400000,"hdop":7.1300001,"fix_type":3}
]

libgnss.getVtg(data_mode)#

Get VTA speed information

Parameters

Incoming Value Type

Explanation

int

Optional, 3-original string, do not pass or pass other values, then return floating-point value

Return Value

return value type

explanation

table

Original VTA Data

Examples

-- Parsing nmea
log.info("nmea", "vtg", json.encode(libgnss.getVtg()))
-- Example
--[[
{
    "speed_knots":0,        // Speed, miles per hour
    "true_track_degrees":0,  // True North Angle
    "magnetic_track_degrees":0, // Magnetic north direction angle
    "speed_kph":0           // Speed, km/h
}
-- Reminder: Air780EG and Air510U will not return to the direction angle when the speed is <5 km/h
]]

libgnss.getZda()#

Get raw ZDA time and date information

Parameters

None

Return Value

return value type

explanation

table

raw zda data

Examples

log.info("nmea", "zda", json.encode(libgnss.getZda()))
-- Instance output
--[[
{
    "minute_offset":0,   // Local time zone minutes, general fixed output 0
    "hour_offset":0,     // Hour of the local time zone, generally fixed output 0
    "year":2023         // UTC Year, four digits
    "month":1,          // UTC Month, two.,01 ~ 12
    "day":5,            // UTC Day, two digits,01 ~ 31
    "hour":7,           // Hours
    "min":50,           // Points
    "sec":14,           // Seconds
}
]]

libgnss.debug(mode)#

Set Debug Mode

Parameters

Incoming Value Type

Explanation

bool

true Turn on debugging, false to turn off debugging, the default is false

Return Value

None

Examples

-- When debugging is enabled, raw GNSS data is output to the log.
libgnss.debug(true)
-- Close Debugging
libgnss.debug(false)

libgnss.getGga(data_mode)#

Get GGA data

Parameters

Incoming Value Type

Explanation

int

Format of coordinate data, 0-DDMM.MMM format, 1-DDDDDDD format, 2-DD.DDDDD format, 3-original string

Return Value

return value type

explanation

table

GGA Data, if it does not exist, it will be returned.nil

Examples

local gga = libgnss.getGga(2)
if gga then
    log.info("GGA", json.encode(gga, "11g"))
end
--Instance output
--[[
{
    "dgps_age":0,             // Differential correction delay, in seconds
    "fix_quality":1,          // Positioning Status Identifier 0-Invalid, 1-Single Point Positioning, 2-Differential Positioning
    "satellites_tracked":14,  // Number of satellites involved in positioning
    "altitude":0.255,         // Sea level separation, or becomes elevation, in meters,
    "hdop":0.0335,            // Horizontal accuracy factor, 0.00 - 99.99, with a value 99.99
    "longitude":113.231,      // Longitude, the positive number is east longitude, the negative number is west longitude
    "latitude":23.4067,       // Latitude, positive number is north latitude, negative number is south latitude
    "height":0                // Ellipsoid high, fixed output 1 decimal
}
]]

libgnss.getGll(data_mode)#

Obtaining GLL data

Parameters

Incoming Value Type

Explanation

int

Format of coordinate data, 0-DDMM.MMM format, 1-DDDDDDD format, 2-DD.DDDDD format

Return Value

return value type

explanation

table

GLL Data, if it does not exist, it will be returned.nil

Examples

local gll = libgnss.getGll(2)
if gll then
    log.info("GLL", json.encode(gll, "11g"))
end
-- Instance data
--[[
{
    "status":"A",        // Positioning status, A is valid, B is invalid
    "mode":"A",          // Positioning mode, V invalid, A single point solution, D difference decomposition
    "sec":20,            // Seconds, UTC time
    "min":23,            // Minutes, UTC time
    "hour":7,            // Hours, UTC time shall prevail
    "longitude":113.231, // Longitude, the positive number is east longitude, the negative number is west longitude
    "latitude":23.4067,  // Latitude, positive number is north latitude, negative number is south latitude
    "us":0               // A subtle number, usually 0
}
]]

libgnss.clear()#

Clear historical positioning data

Parameters

None

Return Value

return value type

explanation

nil

No return value

Examples

-- This operation clears all positioning data

libgnss.bind(id, next_id)#

bind uart port to read GNSS data

Parameters

Incoming Value Type

Explanation

int

uart Port number

int

the id forwarded to uart, such as virtual uart.VUART_0

Return Value

None

Examples

-- Configure serial port information, typically 115200 8N1
uart.setup(2, 115200)
-- bind uart and immediately start parsing GNSS data
libgnss.bind(2)
-- There is no need to call uart.on and then call libgnss.parse
-- Debug log can be opened during development
libgnss.debug(true)

-- 2023-01-02 Firmware compiled afterwards is valid
-- Read and parse from uart2 and forward to virtual serial port 0
libgnss.bind(2, uart.VUART_0)

libgnss.locStr(mode)#

Get Location String

Parameters

Incoming Value Type

Explanation

int

String Pattern. 0- Air780EG the desired format

return

String that specifies the pattern

Return Value

None

Examples

-- Called only recommend after successful targeting

libgnss.rtcAuto(enable)#

Automatically set after successful positioning RTC

Parameters

Incoming Value Type

Explanation

bool

On or off, the default is false

Return Value

None

Examples

-- Turn on automatic settings RTC
libgnss.rtcAuto(true)

libgnss.on(tp, fn)#

underlying event callback

Parameters

Incoming Value Type

Explanation

string

Event types, currently supported”raw”

Return Value

None

Examples

-- This function is generally used for debugging and is used to obtain the data actually received by the bottom layer.
libgnss.on("raw", function(data)
    log.info("GNSS", data)
end)

libgnss.getTxt()#

Obtain non-standard GPTXT data

Parameters

Incoming Value Type

Explanation

return

GPTXT The string carried

Return Value

None

Examples

-- This function was added on 2023.6.6
log.info("gnss", "txt", libgnss.getTxt())

-- test statement
libgnss.parse("$GPTXT,01,01,01,ANTENNA SHORT*63\r\n")
log.info("GNSS", libgnss.getTxt())
libgnss.parse("$GPTXT,01,01,01,ANTENNA OPEN*25\r\n")
log.info("GNSS", libgnss.getTxt())
libgnss.parse("$GPTXT,01,01,01,ANTENNA OK*35\r\n")
log.info("GNSS", libgnss.getTxt())

libgnss.casic_aid(dt, loc)#

Auxiliary positioning data required for synthetic Air530Z

Parameters

Incoming Value Type

Explanation

table

Time information

table

Latitude and longitude and altitude

Return Value

return value type

explanation

string

Auxiliary Positioning Data

Examples

-- This function is suitable for the synthesis of auxiliary positioning information of GNSS module of CASIC series
-- This function 2023.11.14 New

-- The first is the time information, note the UTC time
-- There are many sources of time. It is generally recommended that the system time after socket.sntp() time synchronization
local dt = os.date("!*t")

-- Then the auxiliary positioning coordinates
-- There are many ways to source:
-- 1. It is obtained from historical positioning data, for example, it is saved to the local file system after successful positioning.
-- 2. obtained through base station positioning or wifi positioning
-- 3. Obtain approximate coordinates through IP positioning
-- The coordinate system is WGS84, but in view of the auxiliary positioning, accuracy is not the key factor
local lla = {
    lat = 23.12,
    lng = 114.12
}

local aid = libgnss.casic_aid(dt, lla)