read

Read data from GPS receiver

collapse all in page

Syntax

[tt,overrun] = read(gpsObj)
[lla,groundSpeed,course, dops,gpsReceiverTime,timestamp, overrun] = read(gpsObj)

Description

example

[tt,overrun] = read(gpsObj) returns the GPS readings in timetable format. This is a non blocking read which returns N datapoints in timetable format where N is specified by SamplesPerRead and timetable is specified using OutputFormat property of gpsdev object.

example

[lla,groundSpeed,course, dops,gpsReceiverTime,timestamp, overrun] = read(gpsObj) returns matrices of measurements from the GPS. This is a non blocking read which returns N data points in matrix format where N is specified by SamplesPerRead and matrix is specified using OutputFormat property of the gpsdev object.

Examples

Read Data from GPS as a timetable

Create GPS object with properties available.

g = gpsdev('COM4','OutputFormat','timetable','SamplesPerRead',2)

Read samples of GPS.

[tt,overruns] = read(g)

tt =

 2×5 timetable

              Time                         LLA                GroundSpeed    Course            DOPs                GPSReceiverTime     
    ________________________    __________________________    ___________    ______    ____________________    ________________________

    31-Jan-2020 11:32:49.459    12.944    77.692     806.8       0.0463      258.87    1.31    0.99    0.85    31-Jan-2020 06:02:49.000
    31-Jan-2020 11:32:50.416    12.944    77.692     806.9      0.12861       262.7    1.31    0.99    0.85    31-Jan-2020 06:02:50.000


overrun =

     0

Display the time at which GPS data is read, in duration format.

g.TimeFormat = “duration”;
[tt,overruns] = read(g)
tt =

  2×5 timetable

       Time                  LLA                GroundSpeed    Course            DOPs                GPSReceiverTime     
    __________    __________________________    ___________    ______    ____________________    ________________________

    9.4257 sec    12.944    77.692     808.4     0.030867       4.93     1.51    0.78    1.29    31-Jan-2020 06:15:24.000
    10.404 sec    12.944    77.692     808.4     0.051444      41.26      1.1    0.76    0.79    31-Jan-2020 06:15:25.000

overrun =

     0

Read Data from GPS as a Matrix

Create GPS object with properties available.

g = gpsdev('COM4', "OutputFormat","matrix",'SamplesPerRead',2);

Read samples of GPS data.

[lla,speed,course,dops,gpsReceiverTime,timestamp,overruns] = read(g)

lla =

   12.9437   77.6916  807.4000
   12.9437   77.6916  807.4000


speed =

    0.0154
    0.0463


course =

  346.0100
  270.2100


dops =

    1.2400    0.9200    0.8300
    1.7700    0.9900    1.4700


gpsReceiverTime = 

  2×1 datetime array

   31-Jan-2020 06:07:01.000
   31-Jan-2020 06:07:02.000


timestamp = 

  2×1 datetime array

   31-Jan-2020 11:37:01.734
   31-Jan-2020 11:37:02.436


overruns =

    0

Input Arguments

collapse all

The GPS object with the default or specified properties.

Output Arguments

collapse all

Data read from the GPS receiver when the output format is set to timetable. The timetable returned has the following fields:

  • LLA (Latitude, Longitude, Altitude)

  • Ground Speed

  • Course over ground

  • Dilution of Precisions(DOPs), VDOP,HDOP,PDOP,

  • GPS Receiver Time

  • Time — System time when the data is read, in datetime or duration format

Data Types: timetable

Position of the GPS receiver in the geodetic latitude, longitude, and altitude (LLA), returned as a real finite N-by-3 array. Latitude and longitude are in degrees with North and East being positive. Altitude is in meters.

Data Types: double

Speed over ground, returned as a real finite N-by-1 column vector.

Data Types: double

Course over ground relative to true north,returned as a real finite N-by-1 column of values between 0 and 2pi radians.

Data Types: double

Dilution of precisions, returned as a real finite N-by-3 array. The order of the output is [PDOP,HDOP,VDOP].

Data Types: double

UTC time returned by the GPS module.

Data Types: datetime

Time at which GPS data is read, returned as a real finite N-by-1 column vector. This is the system time. If the TimeFormat is datetime, the timestamp will be datetime. If the TimeFormat is a duration, the timestamp will be duration

  • datetime — Displays the date and time at which the data is read.

  • duration — Displays the time elapsed in seconds after the first call of the read function or the last execution of the release function.

Note

If the SamplesPerRead is greater than 1, an extrapolation is done on the time value. Hence it might not be precise.

Data Types: datetime | duration

The number of samples lost between consecutive calls to read. The overrun is zero when ReadMode is set to oldest.

Data Types: double

More About

collapse all

read Output

The gpsdev object expects GPRMC, GPGGA, and GPGSA sentences as outputs from the GPS receiver to get the required values. The read function errors out if these sentences are not available.

The read function outputs NaN and NaT in the following situations:

  • If the GPS module does not receive valid data because there is no satellite lock or when GPS does not give a particular value.

  • If there is a checksum failure, corresponding data points will be NaN for numeric outputs (lla, speed, course, dops) and NaT for gpsRecieverTime. lla is taken from GPGGA sentence, speed,course, and gpsRecieverTime is taken GPRMC sentence and dops are taken from GPGSA sentence.

Because read function is non blocking, the following is expected:

  • If no new data is available, the output of read is the previous data. For example, if the delay between subsequent reads is less than the UpdateRate of the GPS receiver.

Because GPS data is validated in the first read operation, it might take more time compared to the subsequent read operations.

Introduced in R2020b

Navigation Toolbox Documentation

Support