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/SASS/QSZZ, 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	Format of coordinate data, 0-DDMM.MMM format, 1-DDDDDDD format, 2-DD.DDDDD format

Return Value

return value type	explanation
table	Raw GSA Data

Examples

-- Get
log.info("nmea", "gsa", json.encode(libgnss.getGsa(), "11g"))
-- Sample data
--[[
{
    "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
}
]]

---

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
}
]]

---

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)

---