gps

machine Module

Class GPS

A satellite navigation or satnav system is a system that uses satellites to provide autonomous geo-spatial positioning. It allows small electronic receivers to determine their location (longitude, latitude, and altitude/elevation) to high precision (within a few metres) using time signals transmitted along a line of sight by radio from satellites. The system can be used for providing position, navigation or for tracking the position of something fitted with a receiver (satellite tracking). The signals also allow the electronic receiver to calculate the current local time to high precision, which allows time synchronisation. Satnav systems operate independently of any telephonic or internet reception, though these technologies can enhance the usefulness of the positioning information generated.

---

Using this class you can read and parse NMEA sentences from the GPS receiver connected to the UART port.

Reading and parsing NMEA sentences can be performed in a service task, the GPS data are analyzed in background and you can acces the collected data at any time.

The collected data are returned as 9-item tuple:

(time_tuple, latitude, longitude, altitude, n_satelites, quality, speed_kmh, course, dop)

If not using the GPS service, GPS data (NMEA sentences) can be read and parsed directly, using the provided methods.

The parsed data are returned as tuple containing items depending on NMEA sentence type:

RMC sentence type:
('RMC', valid, time_tuple, latitude, longitude, speed_kn, course)
If not valid, only ('RMC', False) is returned.

GGA sentence type:
('GGA', time_tuple, latitude, longitude, altitude, n_satellites, quality, dop)
If n_satelites=0 or quality=0, only ('GGA', n_satellites, quality) is returned.
Note: for this sentence type, only the time in the time_tuple is valid.

GLL sentence type:
('GLL', valid, time_tuple, latitude, longitude)
If not valid, only ('GLL', False) is returned.

VTG sentence type:
('VTG', speed_kmh, speed_kn, course)

GST sentence type:
('GST', time_tuple, rmssd, sdmaj, sdmin, ori, latsd, lonsd, altsd)

Parsing more NMEA types will be added in the future.

---

Create gps instance

gps = machine.GPS(uart_obj, [,args])

Creates the GPS instance.
uart_obj is mandatory, the UART instance object used to comunicate with the GPS receiver
Other arguments are optional and have the same meaning as in gps.init() method.

>>> import machine
>>> uart = machine.UART(2, rx=27, tx=21, baudrate=9600, bits=8, parity=None, stop=1, timeout=1500, buffer_size=1024, lineend='\r\n')
>>> gps = machine.GPS(uart)
>>> gps
GPS(default_timeout=1500, use_crc=True, task_running=False, read_sentences=0)

Methods

gps.init([args])

All arguments are optional and must be entered as kw arguments (arg=value)

Argument	Description
timeout	Default timeout for gps operations in ms; default: 1500
crc	boolean, check or not the checksum in nmea sentences; default: True
service	boolean, start or stop the GPS service task; default: False

gps.parse(nmea_sent)

Parses the given nmea sentence string (nmea_sent), returns the gps response tuple (see above).
The sentence string must end with '\r\n'

>>> ss="$GPRMC,130255.00,A,4548.79997,N,01601.46621,E,0.496,,010518,,,A*73\r\n"
>>> gps.parse(ss)
('RMC', True, (2018, 5, 1, 13, 2, 55, 3, 121), 45.8133316040039, 16.0244369506836, 0.918591984987259, 0.0)

gps.read([timeout [,type]])

Reads the nmea sentence (as string) from the GPS receiver.
Without arguments returns the first sentence from the UART buffer (if any). If the timeout argument is given, waits for maximum of timeout ms for data from GPS receiver
If the type (string) argument is given, waits for and returns the first sentence of specified type.

>>> gps.read()
'$GPGGA,120417.834,4548.7973,N,01601.4726,E,0,00,,172.2,M,42.4,M,,0000*7F\r\n'
>>> gps.read(1500, 'GPRMC')
'$GPRMC,130649.836,V,4548.7973,N,01601.4726,E,,,170518,,,N*7E\r\n'
>>> 

gps.read_parse(type [,timeout])

Reads the sentence from the GPS receiver and parses it to the response tuple which is returned.
The type (string) argument defines the sentence type to be read.
You can use the type 'GP' to read any sentence type.
If the timeout argument is given, waits for maximum of timeout ms for data from GPS receiver

>>> float_precision(6)
6
>>> gps.read_parse('GP')
('VTG', 0.41, 0.222, 0.0)
>>> gps.read_parse('GPRMC')
('RMC', True, (2018, 5, 17, 13, 21, 27, 5, 137), 45.8134, 16.0247, 0.031484, 0.0)
>>> gps.read_parse('GPGGA')
('GGA', (1900, 1, 0, 13, 21, 27, 1, 1), 45.8134, 16.0247, 138.7, 4, 1, 4.26)
>>> 

gps.service()

Returns the state of the background service task (True or False).

gps.startservice()

Start the background service task.
Returns True if started, False if not.

Note: While the gps service task is running gps.read() and gps.read_parse() cannot be used.

gps.stopservice()

Stop the background service task.
Returns True if stopped, False if not.

gps.get_data()

Get the data collected by the background GPS task.

>>> gps.startservice()
True
>>> gps.service()
True
>>> gps.getdata()
((2018, 5, 17, 13, 34, 51, 5, 137), 45.8132, 16.0249, 186.5, 6, 1, 0.156, 0.0, 1.7)
>>> gps.getdata()
((2018, 5, 17, 13, 35, 30, 5, 137), 45.8133, 16.0249, 174.4, 6, 1, 0.613, 0.0, 1.7)
>>> 
>>> 
>>> gps
GPS(default_timeout=1500, use_crc=True, task_running=True, read_sentences=6276)

gps.distance(lat_from, lon_from, lat_to. lon_to)

Calcutates the distance (in km) between two coordinates.

>>> gps.distance(45.8133, 16.0249, 46.8133, 17.0249)
135.139
>>>