Main Content

read

Read data from GPS

Since R2020a

collapse all in page

Add-On Required: This feature requires the MATLAB Support Package for Arduino Hardware add-on.

Syntax

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

Description

tt = read(gpsObj) returns the one frame of GPS data in timetable format.

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.

example

Examples

Read Data from GPS

Create an Arduino object and include the Serial library.

a = arduino('COM4', 'Mega2560', 'Libraries', 'Serial');

Create GPS object.

gpsObj = gpsdev(a);

Read samples of GPS data.

tt = read(gpsObj)

tt =

  1×5 timetable

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

    31-Jan-2020 11:41:42.475    12.944    77.692     807.7      0.0463       266.6     1.72    0.94    1.44    31-Jan-2020 06:11:42.000

Read Data from GPS as a timetable

Create an Arduino object and include the Serial library.

a = arduino('COM4', 'Mega2560', 'Libraries', 'Serial');

Create GPS object with additional properties.

gpsObj = gpsdev(a, "OutputFormat","timetable",'SamplesPerRead',2);

Read samples of GPS data.

[tt,overruns] = read(gpsObj)

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 =

     3

Display the time at which GPS data is read from the Arduino hardware in duration format.

gpsObj.TimeFormat = “duration”;
[tt,overruns] = read(gpsObj)
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 =

     755

Read Data from GPS as a Matrix

Create an Arduino object and include the Serial library.

a = arduino('COM4', 'Mega2560', 'Libraries', 'Serial');

Create GPS object with additional properties.

gpsObj = gpsdev(a, "OutputFormat","matrix",'SamplesPerRead',2);

Read samples of GPS data.

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

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 =

    75

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 — Time stamps read from the Arduino hardware 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 from the hardware, returned as a real finite N-by-1 column vector. 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.

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 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.

Since read is non blocking, the following is expected:

The first read after GPS object creation gives NaN for numeric values and NaT for time values since acquiring data from GPS takes time.

  • 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.

Version History

Introduced in R2020a