Main Content

nmeaParser

Parse data from standard and manufacturer-specific NMEA sentences sent from marine electronic devices

Since R2020b

Description

The nmeaParser System object™ parses data from any NMEA (National Marine Electronics Association) sentences. The sentences that need parsing of data can be any standard sentences compliant with the NMEA 0183® specifications (which are sent from a GNSS (Global Navigation Satellite System) receiver), or other manufacturer-specific sentences approved by the NMEA (which are sent from other marine electronic devices).

The nmeaParser System object provides:

  • Built-in support to parse data sent from GNSS receivers and identified by these nine NMEA message types: RMC, GGA, GSA, VTG, GLL, GST, ZDA, GSV, and HDT

  • Additional configuration using the CustomSentence name-value pair to parse NMEA data from multiple device categories, including manufacturer-specific sentences from different hardware manufacturers

To parse data from NMEA sentences:

  1. Create the nmeaParser object and set its properties.

  2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

The nmeaParser System object outputs an array of structures corresponding to the values extracted from the specified NMEA sentences.

Creation

Description

pnmea = nmeaParser returns a nmeaParser System object, pnmea, with default properties, that extracts data from these standard NMEA messages: RMC, GGA, and GSA. The order of structure arrays in the extracted output data is also: RMC, GGA, and GSA.

example

pnmea = nmeaParser("MessageIDs", 'msgID') returns a nmeaParser System object, pnmea, that extracts data from one of the nine standard NMEA messages with built-in support, specified using the Message IDs. Specify msgID as "RMC", "GGA", "GSA", "GSV", "VTG", "GLL", "GST", "ZDA", and "HDT", or a combination of these IDs (for example: ["VTG","GLL","HDT"]). The order in which you specify the Message IDs determines the order of the structure arrays in the extracted output data. The default value is ["RMC","GGA","GSA"].

example

pnmea = nmeaParser("CustomSentence", {['CustomMessageId1','parserFunctionName1'],['CustomMessageId2','parserFunctionName2']}) sets properties using the CustomSentence name-value pair and returns a nmeaParser System object, pnmea, that extracts data from any custom NMEA message (either standard NMEA message or manufacturer-specific NMEA message), specified using the message IDs.

The CustomSentence name-value pair accepts a nested cell array where each element is a pair of message ID name (either standard NMEA message ID name or manufacturer-specific message ID) and the corresponding user-defined parser function, which is created by including the extractNMEASentence function in a function file. The order in which you specify the message IDs determines the order of the structure arrays in the extracted output data.

example

pnmea = nmeaParser("MessageIDs", {'msgID1','msgID2'},"CustomSentence", {['CustomMessageId1','parserFunctionName1'],['CustomMessageId2','parserFunctionName2']}) returns a nmeaParser System object, pnmea, that extracts data from two of the nine standard NMEA messages with built-in support and also from custom NMEA messages that you specified using the CustomSentence name-value pair.

Input Arguments

expand all

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: pnmea = nmeaParser("CustomSentence", {['CustomMessageId1','parserFunctionName1'],['CustomMessageId2','parserFunctionName2']});

Specify the message ID of any NMEA sentence from which you want to extract data and the name of the parser function. You can specify multiple message IDs and parser functions as a cell array of character vectors. The parser function is defined in a function file, which can optionally include the extractNMEASentence function.

Note

The function file for the parser function must be present in the current directory or on MATLAB path.

CustomSentence accepts function name or function handle. For example, both these formats are valid:

  • pnmea = nmeaParser('CustomSentence', {['standardnmeaMessageId1','parserFunctionName1']}
  • parserFunctionHandle=@parserFunctionName1
    pnmea = nmeaParser('CustomSentence', {['standardnmeaMessageId1',parserFunctionHandle]}

Note

Using CustomSentence name-value pair to parse data instead of the built-in parser function results in override of the default fields when data is parsed. For example, nmeaParser('CustomSentence',{["RMC","parserRMC"]}) overrides the default format of parsed data as RMC is one of the nine sentences with built-in support for parsing data.

Data Types: char | string

Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

Message IDs of nine NMEA sentences with built-in support, which are compliant with the NMEA 0183 Standard, from which you want to extract data. You can specify multiple message IDs as an array of strings to extract data from NMEA sentences.

Data Types: char | string

Usage

Description

example

[rmcData,ggaData,gsaData,vtgData,gllData,gstData,gsvData,zdaData,hdtData] = pnmea(rawData) parses data from nine standard NMEA sentences with built-in support, and returns an array of structures, where each structure corresponds to a single Message ID. The sequence that you specify for the output arguments must be the same sequence that you specified for the Message IDs when creating the nmeaParser System object.

example

[customNmeaData1,customNmeaData2] = pnmea(rawData) parses data from two custom NMEA sentences (either standard NMEA sentence or manufacturer-specific NMEA sentence), and returns an array of structures, where each structure corresponds to a single Message ID. The sequence that you specify for the output arguments must be the same sequence that you specified in the CustomSentence name-value pair when creating the nmeaParser System object.

Input Arguments

expand all

NMEA data, which is compliant with NMEA standard, as obtained from a marine electronic device.

Data Types: string | char

Output Arguments

expand all

Data extracted from an RMC sentence. The output structure contains the information parsed from an RMC sentence along with the parsing status. If multiple RMC sentences are found in the input data, then an array of structures is returned. For more details, see RMC Sentences.

Data extracted from a GGA sentence. The output structure contains the information parsed from a GGA sentence along with the parsing status. If multiple GGA sentences are found in the input data, then an array of structures is returned. For more details, see GGA Sentences.

Data extracted from a GSA sentence. The output structure contains the information parsed from a GSA sentence along with the parsing status. If multiple GSA sentences are found in the input data, then an array of structures is returned. For more details, see GSA Sentences.

Data extracted from a VTG sentence. The output structure contains the information parsed from a VTG sentence along with the parsing status. If multiple VTG sentences are found in the input data, then an array of structures is returned. For more details, see VTG Sentences.

Data extracted from a GLL sentence. The output structure contains the information parsed from a GLL sentence along with the parsing status. If multiple GLL sentences are found in the input data, then an array of structures is returned. For more details, see GLL Sentences.

Data extracted from a GST sentence. The output structure contains the information parsed from a GST sentence along with the parsing status. If multiple GST sentences are found in the input data, then an array of structures is returned. For more details, see GST Sentences.

Data extracted from a GSV sentence. The output structure contains the information parsed from a GSV sentence along with the parsing status. The complete satellite information is available in multiple gsvData structures. Each gsvData structure can have a maximum of four satellite information. For more details, see GSV Sentences.

Data extracted from a ZDA sentence. The output structure contains the information parsed from a ZDA sentence along with the parsing status. If multiple ZDA sentences are found in the input data, then an array of structures is returned. For more details, see ZDA Sentences.

Data extracted from an HDT sentence. The output structure contains the information parsed from an HDT sentence along with the parsing status. If multiple HDT sentences are found in the input data, then an array of structures is returned. For more details, see HDT Sentences.

Data extracted from any standard or manufacturer-specific NMEA sentence. The output structure contains the information parsed from the custom sentence along with the parsing status. If multiple sentences of the same NMEA message type are found in the input data, then an array of structures is returned.

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

Examples

collapse all

Extract data from any of the nine standard NMEA sentences as part of the built-in support using the MessageID property. The NMEA data is obtained from a GNSS receiver.

Extract Data from RMC Sentence

Create an nmeaParser System Object by specifying the Message ID as "RMC".

pnmea = nmeaParser("MessageID","RMC");

Provide the RMC sentence obtained from the GNSS receiver as the input and extract data.

unparsedRMCLine='$GNRMC,143909.00,A,5107.0020216,N,11402.3294835,W,0.036,348.3,210307,0.0,E,A*31';
rmcData = pnmea(unparsedRMCLine)
rmcData = struct with fields:
             TalkerID: "GN"
            MessageID: "RMC"
            FixStatus: 'A'
             Latitude: 51.1167
            Longitude: -114.0388
          GroundSpeed: 0.0185
      TrueCourseAngle: 348.3000
          UTCDateTime: 21-Mar-2007 14:39:09.000
    MagneticVariation: 0
        ModeIndicator: 'A'
     NavigationStatus: "NA"
               Status: 0

Extract Data from Multiple NMEA Message Types

Provide GGA, GSA, and RMC sentences as the input.

unparsedGGALine = ['$GPGGA,111357.771,5231.364,N,01324.240,E,1,12,1.0,0.0,M,0.0,M,,*69'];
unparsedGSALine = ['$GPGSA,A,3,01,02,03,04,05,06,07,08,09,10,11,12,1.0,1.0,1.0*30'];
unparsedRMCLine = ['$GPRMC,111357.771,A,5231.364,N,01324.240,E,10903,221.5,020620,000.0,W*44'];

Create a string array to include the three sentences

rawNMEAData = [unparsedGGALine ,newline,  unparsedGSALine ,newline,  unparsedRMCLine]
rawNMEAData = 
    '$GPGGA,111357.771,5231.364,N,01324.240,E,1,12,1.0,0.0,M,0.0,M,,*69
     $GPGSA,A,3,01,02,03,04,05,06,07,08,09,10,11,12,1.0,1.0,1.0*30
     $GPRMC,111357.771,A,5231.364,N,01324.240,E,10903,221.5,020620,000.0,W*44'

However, consider that you need to extract data only from GGA and GSA sentences. So create the nmeaParser System Object 'pnmea', and specify the 'GGA' and 'GSA' Message IDs as a string array.

pnmea=nmeaParser("MessageIDs",["GGA","GSA"]); 

Specify the output arguments for all the three sentences to extract the data as structures.

[ggaData,gsaData] =  pnmea(rawNMEAData)
ggaData = struct with fields:
                          TalkerID: "GP"
                         MessageID: "GGA"
                           UTCTime: 11:13:57.771
                          Latitude: 52.5227
                         Longitude: 13.4040
                  QualityIndicator: 1
                NumSatellitesInUse: 12
                              HDOP: 1
                          Altitude: 0
                   GeoidSeparation: 0
             AgeOfDifferentialData: NaN
    DifferentialReferenceStationID: NaN
                            Status: 0

gsaData = struct with fields:
              TalkerID: "GP"
             MessageID: "GSA"
                  Mode: "A"
               FixType: 3
    SatellitesIDNumber: [1 2 3 4 5 6 7 8 9 10 11 12]
                  PDOP: 1
                  VDOP: 1
                  HDOP: 1
              SystemID: NaN
                Status: 0

The above output shows that only GGA and GSA sentences are extracted based on the Message IDs specified as input.

Provide another GGA sentence as an additional input, and extract data. In this case, you need not modify the System object as the Message ID has not changed.

unparsedGGALine1='$GNGGA,001043.00,4404.14036,N,12118.85961,W,1,12,0.98,1113.0,M,-21.3,M,,*47'
unparsedGGALine1 = 
'$GNGGA,001043.00,4404.14036,N,12118.85961,W,1,12,0.98,1113.0,M,-21.3,M,,*47'
rawNMEAData = [unparsedGGALine ,newline,  unparsedGSALine ,newline,  unparsedGGALine1]
rawNMEAData = 
    '$GPGGA,111357.771,5231.364,N,01324.240,E,1,12,1.0,0.0,M,0.0,M,,*69
     $GPGSA,A,3,01,02,03,04,05,06,07,08,09,10,11,12,1.0,1.0,1.0*30
     $GNGGA,001043.00,4404.14036,N,12118.85961,W,1,12,0.98,1113.0,M,-21.3,M,,*47'

[ggaData,gsaData] =  pnmea(rawNMEAData)
ggaData=2×1 struct array with fields:
    TalkerID
    MessageID
    UTCTime
    Latitude
    Longitude
    QualityIndicator
    NumSatellitesInUse
    HDOP
    Altitude
    GeoidSeparation
    AgeOfDifferentialData
    DifferentialReferenceStationID
    Status

gsaData = struct with fields:
              TalkerID: "GP"
             MessageID: "GSA"
                  Mode: "A"
               FixType: 3
    SatellitesIDNumber: [1 2 3 4 5 6 7 8 9 10 11 12]
                  PDOP: 1
                  VDOP: 1
                  HDOP: 1
              SystemID: NaN
                Status: 0

A status of 0 indicates that the data was parsed successfully.

Extract Data from GSV Sentence

Create an nmeaParser System Object by specifying the Message ID as "GSV".

pnmea = nmeaParser("MessageID","GSV");

Provide the GSV sentence obtained from the GNSS receiver as the input and extract data.

unparsedGSVLine='$GPGSV,3,3,10,32,69,205,41,46,47,215,39*79';
gsvData = pnmea(unparsedGSVLine)
gsvData = struct with fields:
            TalkerID: "GP"
           MessageID: "GSV"
        NumSentences: 3
      SentenceNumber: 3
    SatellitesInView: 10
         SatelliteID: [32 46]
           Elevation: [69 47]
             Azimuth: [205 215]
                 SNR: [41 39]
            SignalID: NaN
              Status: 0

Extract Data from Multiple GSV Sentences

Provide multiple GSV sentences as the input.

unparsedGSVLine1 = '$GPGSV,3,1,10,01,,,31,03,28,325,40,10,,,33,12,20,047,30*70';
unparsedGSVLine2 = '$GPGSV,3,2,10,14,88,028,42,22,39,299,48,25,,,25,31,79,289,46*49';
unparsedGSVLine3 = '$GPGSV,3,3,10,32,69,205,41,46,47,215,39*79';

Create a string array to include the three sentences.

CRLF = [char(13),newline];
unparsedGSVLines = [unparsedGSVLine1,CRLF, unparsedGSVLine2, CRLF, unparsedGSVLine3];

Create the nmeaParser System Object 'pnmea', specify the 'GSV' Message ID, and extract data.

pnmea = nmeaParser("MessageIDs","GSV");
gsvData = pnmea(unparsedGSVLines)
gsvData=3×1 struct array with fields:
    TalkerID
    MessageID
    NumSentences
    SentenceNumber
    SatellitesInView
    SatelliteID
    Elevation
    Azimuth
    SNR
    SignalID
    Status

Read Data from NMEA Log

Read data from a sample NMEA log, so that the data can be parsed using the nmeaParser System Object.

The sample log file is nmeaLog.nmea, which is included in this example.

f = fopen('nmeaLog.nmea');
unParsedNMEAdata = fread(f);
pnmea = nmeaParser("MessageIDs",["RMC","GGA"]);
[rmcStruct, ggaStruct] = pnmea(unParsedNMEAdata)
rmcStruct=9×1 struct array with fields:
    TalkerID
    MessageID
    FixStatus
    Latitude
    Longitude
    GroundSpeed
    TrueCourseAngle
    UTCDateTime
    MagneticVariation
    ModeIndicator
    NavigationStatus
    Status

ggaStruct=9×1 struct array with fields:
    TalkerID
    MessageID
    UTCTime
    Latitude
    Longitude
    QualityIndicator
    NumSatellitesInUse
    HDOP
    Altitude
    GeoidSeparation
    AgeOfDifferentialData
    DifferentialReferenceStationID
    Status

You can extract data from any NMEA sentence using the CustomSentence name-value pair. The NMEA data to be parsed is obtained from marine electronic devices.

Identify the Structure of NMEA Sentence and Create the Parser Function

You need to identify the structure of the NMEA sentence, as defined in the specification, and use that information to define the structure of output data to be used in the nmeaParser System object.

For example, let us consider an example sentence with Message ID, SSS.

sss-sample1.png

After identifying the structure, you create a function file that defines the parser function, fsssParser. In the function file, you define the output data as a structure array with its fields matching the sequence as it appears in the specification.

The Navigation Toolbox™ provides an optional pre-configured function, extractNMEASentence, that checks if the sentence is valid and convert the fields in the sentence into string array. You can call extractNMEASentence inside the function file. You can also use any other function instead (which outputs a string array from unparsed data), and then call it inside the function file.

The below image shows the function file with the code, with the assumption that the fields available in SSS sentence are TalkerID, MessageID, UTC, and LatitudeError. Refer the additional comments for details.

fsssparser-example1.png

In the above sample file, you define the mapping between the fields in the structure array and the elements of string array. For certain fields (for example, UTC time), you may need to define a character array to map the fields.

After you include the MATLAB code as mentioned above, save the function file (fsssParser.m) in the MATLAB path, so that you can call it to obtain parsed data using the CustomSentence name-value pair of nmeaParser System object.

To download another sample function file parserRMB.m that is used this example, click Open Live Script. This is a function file specific to the fields of an RMB sentence (mentioned in NMEA Standard, Version 4.1).

Extract Data from RMB Sentence

Create an nmeaParser System Object by using the CustomSentence name-value pair and specifying the message ID as "RMB" and the function as "parserRMB" (downloaded in the previous step).

pnmea = nmeaParser("CustomSentence",{["RMB","parserRMB"]});

Provide the RMB sentence obtained from the GNSS receiver as the input and extract data.

unparsedRMBLine='$GPRMB,A,4.08,L,EGLL,EGLM,5130.02,N,00046.34,W,004.6,213.9,122.9,A*3D';
rmbData = pnmea(unparsedRMBLine)
rmbData = struct with fields:
                        TalkerID: "GP"
                       MessageID: "RMB"
                      DataStatus: 'A'
                 CrossTrackError: 4.0800
                DirectionToSteer: NaN
                OriginWaypointID: NaN
           DestinationWaypointID: NaN
     DestinationWaypointLatitude: '5130.02 N'
    DestinationWaypointLongitude: '00046.34 W'
              RangeToDestination: 4.6000
            BearingToDestination: 213.9000
      DestinationClosingVelocity: 122.9000
                   ArrivalStatus: 'A'
                   ModeIndicator: "NA"
                          Status: 0

Extract Data from Multiple RMB Sentences

Provide multiple RMB sentences as the input.

unparsedRMBLine1 = ['$GPRMB,A,0.66,L,003,004,4917.24,N,12309.57,W,001.3,052.5,000.5,V*20'];
unparsedRMBLine2 = ['$GPRMB,A,4.08,L,EGLL,EGLM,5130.02,N,00046.34,W,004.6,213.9,122.9,A*3D'];

Create a character array to include the two sentences

rawNMEAData = [unparsedRMBLine1 ,newline,  unparsedRMBLine2]
rawNMEAData = 
    '$GPRMB,A,0.66,L,003,004,4917.24,N,12309.57,W,001.3,052.5,000.5,V*20
     $GPRMB,A,4.08,L,EGLL,EGLM,5130.02,N,00046.34,W,004.6,213.9,122.9,A*3D'

Specify the output argument for the RMB sentence to extract the data.

[rmbData] =  pnmea(rawNMEAData)
rmbData=2×1 struct array with fields:
    TalkerID
    MessageID
    DataStatus
    CrossTrackError
    DirectionToSteer
    OriginWaypointID
    DestinationWaypointID
    DestinationWaypointLatitude
    DestinationWaypointLongitude
    RangeToDestination
    BearingToDestination
    DestinationClosingVelocity
    ArrivalStatus
    ModeIndicator
    Status

Extract Data from a Sentence with Built-in Support (RMC) and RMB Sentence

Create an nmeaParser System Object by using the MessageID property (to parse a sentence with built-in support - RMC) and also using the CustomSentence name-value pair (specifying the message ID as "RMB" and the function as "parserRMB" (created in a previous step)).

pnmea = nmeaParser("MessageID","RMC","CustomSentence",{["RMB","parserRMB"]});

Provide RMC and RMB sentences as the input.

unparsedRMCLine1 = ['$GNRMC,143909.00,A,5107.0020216,N,11402.3294835,W,0.036,348.3,210307,0.0,E,A*31'];
unparsedRMBLine2 = ['$GPRMB,A,4.08,L,EGLL,EGLM,5130.02,N,00046.34,W,004.6,213.9,122.9,A*3D'];

Create a string array to include the two sentences

rawNMEAData = [unparsedRMCLine1 ,newline,  unparsedRMBLine2]
rawNMEAData = 
    '$GNRMC,143909.00,A,5107.0020216,N,11402.3294835,W,0.036,348.3,210307,0.0,E,A*31
     $GPRMB,A,4.08,L,EGLL,EGLM,5130.02,N,00046.34,W,004.6,213.9,122.9,A*3D'

Specify the output argument for the RMB sentence to extract the data.

[rmcdata,rmbData] =  pnmea(rawNMEAData)
rmcdata = struct with fields:
             TalkerID: "GN"
            MessageID: "RMC"
            FixStatus: 'A'
             Latitude: 51.1167
            Longitude: -114.0388
          GroundSpeed: 0.0185
      TrueCourseAngle: 348.3000
          UTCDateTime: 21-Mar-2007 14:39:09.000
    MagneticVariation: 0
        ModeIndicator: 'A'
     NavigationStatus: "NA"
               Status: 0

rmbData = struct with fields:
                        TalkerID: "GP"
                       MessageID: "RMB"
                      DataStatus: 'A'
                 CrossTrackError: 4.0800
                DirectionToSteer: NaN
                OriginWaypointID: NaN
           DestinationWaypointID: NaN
     DestinationWaypointLatitude: '5130.02 N'
    DestinationWaypointLongitude: '00046.34 W'
              RangeToDestination: 4.6000
            BearingToDestination: 213.9000
      DestinationClosingVelocity: 122.9000
                   ArrivalStatus: 'A'
                   ModeIndicator: "NA"
                          Status: 0

  1. Identify Structure of Manufacturer-specific Sentence and Create Function File with Parser Function

    The structure of NMEA sentence to be parsed is available in the specification of the device from the manufacturer. You need to identify the structure and use the information to define the structure of output data to be used in the nmeaParser System object.

    For example, the structure of the NMEA sentence from a hardware manufacturer may look like this:

    $PMMCZ,hhmmss.ss,Latitude,N,Longitude,E,NavSatellite,DR*hh<CR><LF>

    Here, P denotes that the sentence is manufacturer-specific, MMC is the manufacturer mnemonic code, and Z is the sentence type. Each field thereafter indicates a specific data (position, velocity, time, and so on). Some manufacturers use two characters for the sentence type, followed by the data fields.

    After identifying the structure, create the parser function, parserMMCZ, using the optional extractNMEASentence function, as shown below (you can also use other functions to extract the unparsed data to strings, instead of extractNMEASentence).

    function OutputData = parserMMCZ(unparsedData, MessageID)
     
      OutputData = struct("MessageID",MessageID,...
      "UTC","NA",...
      "Latitude",NaN,...
      "Longitude",NaN,...
      "NavigationSatellites",NaN,...
      "Status",uint8(1));
     
      [isValid, splitString] = extractNMEASentence(unparsedData, MessageID);
      
    if(isValid)
        OutputData.MessageID = splitString(1);
        temp = char(splitString(2));
        utcOutput = [temp(1:2), ':', temp(3:4), ':', temp(5:6)];
        OutputData.UTC = utcOutput;
        OutputData.Latitude = str2double(splitString{3});
        OutputData.Longitude = str2double(splitString{5});
        OutputData.NavigationSatellites = str2double(splitString{7});
        OutputData.Status = uint8(0);
      end
    end

    Save parserMMCZ.m in the MATLAB path.

  2. Extract Data from Manufacturer-specific Sentence

    Create an nmeaParser System Object by using the CustomSentence name-value pair and specifying the message ID as "MMCZ" and the function as "parserMMCZ" (created in the previous step).

    pnmea = nmeaParser("CustomSentence",{["MMCZ","parserMMCZ"]});

    Provide an MMC sentence obtained from the device as the input and extract data:

    unparsedMMCLine='$PMMCZ,225444,4917.24,N,00046.34,E,3,DR*7C';
    mmcData = pnmea(unparsedMMCLine)
    mmcData = 
    
      struct with fields:
    
                   MessageID: "MMCZ"
                         UTC: '22:54:44'
                    Latitude: 4.9172e+03
                   Longitude: 46.3400
        NavigationSatellites: 3
                      Status: 0

More About

expand all

Version History

Introduced in R2020b