pynmeagps package

Submodules

pynmeagps.exceptions module

NMEA Custom Exception Types

Created on 04 Mar 2021

author:: semuadmin
copyright:: SEMU Consulting © 2020
license:: BSD 3-Clause

exception pynmeagps.exceptions.NMEAParseError[source]

Bases: Exception

NMEA Parsing error.

exception pynmeagps.exceptions.NMEAStreamError[source]

Bases: Exception

NMEA Streaming error.

exception pynmeagps.exceptions.NMEAMessageError[source]

Bases: Exception

NMEA Undefined message class/id. Essentially a prompt to add missing payload types to UBX_PAYLOADS.

exception pynmeagps.exceptions.NMEATypeError[source]

Bases: Exception

NMEA Undefined payload attribute type. Essentially a prompt to fix incorrect payload definitions to UBX_PAYLOADS.

pynmeagps.nmeahelpers module

Collection of NMEA helper methods which can be used outside the NMEAMessage or NMEAReader classes

Created on 04 Mar 2021

author:: semuadmin
copyright:: SEMU Consulting © 2021
license:: BSD 3-Clause

pynmeagps.nmeahelpers.get_parts(message: object) → tuple[source]

Get content, talker, msgid, payload and checksum of raw NMEA message.

Parameters:: message (object) – entire message as bytes or string
Returns:: tuple of (content, talker, msgID, payload as list, checksum)
Return type:: tuple
Raises:: NMEAMessageError (if message is badly formed)

pynmeagps.nmeahelpers.calc_checksum(content: object) → str[source]

Calculate checksum for raw NMEA message.

Parameters:: content (object) – NMEA message content (everything except checksum)
Returns:: checksum as hex string
Return type:: str

pynmeagps.nmeahelpers.generate_checksum(talker: str, msgID: str, payload: list) → str[source]

Generate checksum for new NMEA message.

Parameters:

talker (str) – talker e.g. “GN”
msgID (str) – msgID e.g. “GLL”
payload (list) – payload as list

Returns:

checksum as hex string

Return type:

str

pynmeagps.nmeahelpers.dmm2ddd(pos: str) → float[source]

Convert NMEA lat/lon string to (unsigned) decimal degrees.

Parameters:: pos (str) – (d)ddmm.mmmmm
Returns:: pos as decimal degrees
Return type:: float or str if invalid

pynmeagps.nmeahelpers.ddd2dmm(degrees: float, att: str, hpmode: bool = False) → str[source]

Convert decimal degrees to native NMEA degrees decimal minutes string (NB: standard NMEA only supports 5dp minutes precision - a high precision mode offers 7dp precision but this may not be accepted by all NMEA parsers).

Parameters:

degrees (float) – degrees
att (str) – ‘LA’ (lat) or ‘LN’ (lon)
hpmode (bool) – high precision mode (7dp rather than 5dp)

Returns:

degrees as (d)ddmm.mmmmm(mm) formatted string

Return type:

str

pynmeagps.nmeahelpers.date2utc(dates: str, form: str = 'DT') → date[source]

Convert NMEA Date to UTC datetime.

Parameters:

dates (str) – NMEA date
form (str) – date format DT = ddmmyy, DM = mmddyy (DT)

Returns:

UTC date YYyy:mm:dd

Return type:

datetime.date

pynmeagps.nmeahelpers.time2utc(times: str) → time[source]

Convert NMEA Time to UTC datetime.

Parameters:: times (str) – NMEA time hhmmss.ss
Returns:: UTC time hh:mm:ss.ss
Return type:: datetime.time

pynmeagps.nmeahelpers.time2str(tim: ~.datetime.time) → str[source]

Convert datetime.time to NMEA formatted string.

Parameters:: tim (datetime.time) – time
Returns:: NMEA formatted time string hhmmss.ss
Return type:: str

pynmeagps.nmeahelpers.date2str(dat: ~.datetime.date, form: str = 'DT') → str[source]

Convert datetime.date to NMEA formatted string.

Parameters:

dat (datetime.date) – date
form (str) – date format DT = ddmmyy, DM = mmddyy (DT)

Returns:

NMEA formatted date string

Return type:

str

pynmeagps.nmeahelpers.knots2spd(knots: float, unit: str = 'MS') → float[source]

Convert speed in knots to speed in specified units.

Parameters:

knots (float) – knots
str (unit) – ‘MS’ (default), ‘FS’, MPH’, ‘KMPH’

Returns:

speed in m/s, feet/s, mph or kmph

Return type:

float

pynmeagps.nmeahelpers.msgdesc(msgID: str) → str[source]

Return descriptive string for NMEA msgId.

Parameters:: str (msgID) – message ID e.g. ‘GGA’
Returns:: description of message
Return type:: str

pynmeagps.nmeahelpers.latlon2dms(lat: float, lon: float) → tuple[source]

Converts decimal lat/lon tuple to degrees minutes seconds.

Parameters:

lat (float) – lat
lon (float) – lon

Returns:

(lat,lon) in d.m.s. format

Return type:

tuple

pynmeagps.nmeahelpers.latlon2dmm(lat: float, lon: float) → tuple[source]

Converts decimal lat/lon tuple to degrees decimal minutes.

Parameters:

lat (float) – lat
lon (float) – lon

Returns:

(lat,lon) in d.mm.m format

Return type:

tuple

pynmeagps.nmeahelpers.deg2dms(degrees: float, att: str) → str[source]

Convert decimal degrees to degrees minutes seconds string e.g. ‘51°20′45.6″N’

Parameters:

degrees (float) – degrees
att (str) – ‘LA’ (lat) or ‘LN’ (lon)

Returns:

degrees as d.m.s formatted string

Return type:

str

pynmeagps.nmeahelpers.deg2dmm(degrees: float, att: str) → str[source]

Convert decimal degrees to degrees decimal minutes string e.g. ‘51°20.76′S’.

Parameters:

degrees (float) – degrees
att (str) – ‘LA’ (lat) or ‘LN’ (lon)

Returns:

degrees as dm.m formatted string

Return type:

str

pynmeagps.nmeahelpers.llh2iso6709(lat: float, lon: float, alt: float, crs: str = 'WGS_84') → str[source]

Convert decimal degrees and alt to ISO6709 format e.g. “+27.5916+086.5640+8850CRSWGS_84/”.

Parameters:

lat (float) – latitude
lon (float) – longitude
alt (float) – altitude (hMSL)
crs (float) – coordinate reference system (default = WGS_84)

Returns:

position in ISO6709 format

Return type:

str

pynmeagps.nmeahelpers.ecef2llh(x: float, y: float, z: float, a: float = 6378137.0, f: float = 298.257223563) → tuple[source]

Convert ECEF coordinates to geodetic (LLH) using Olson algorithm.

Olson, D. K. (1996). Converting Earth-Centered, Earth-Fixed Coordinates to Geodetic Coordinates. IEEE Transactions on Aerospace and Electronic Systems, 32(1), 473-476. https://doi.org/10.1109/7.481290

Parameters:

x (float) – X coordinate
y (float) – Y coordinate
z (float) – Z coordinate
a (float) – semi-major axis (6378137.0 for WGS84)
f (float) – flattening (298.257223563 for WGS84)

Returns:

tuple of (lat, lon, ellipsoidal height in m) as floats

Return type:

tuple

pynmeagps.nmeahelpers.llh2ecef(lat: float, lon: float, height: float, a: float = 6378137.0, f: float = 298.257223563) → tuple[source]

Convert geodetic coordinates (LLH) to ECEF.

Parameters:

lat (float) – lat in degrees
lon (float) – lon on degrees
height (float) – ellipsoidal height in metres
a (float) – semi-major axis (6378137.0 for WGS84)
f (float) – flattening (298.257223563 for WGS84)

Returns:

tuple of ECEF (X, Y, Z) as floats

Return type:

tuple

pynmeagps.nmeahelpers.haversine(lat1: float, lon1: float, lat2: float, lon2: float, radius: int = 6378.137) → float[source]

Calculate spherical distance in km between two coordinates using haversine formula.

NB suitable for coordinates greater than around 50m apart. For smaller separations, use the planar approximation formula.

Parameters:

lat1 (float) – lat1
lon1 (float) – lon1
lat2 (float) – lat2
lon2 (float) – lon2
radius (float) – radius in km (Earth = 6378.137 km)

Returns:

spherical distance in km

Return type:

float

pynmeagps.nmeahelpers.planar(lat1: float, lon1: float, lat2: float, lon2: float, radius: int = 6378137.0) → float[source]

Calculate planar distance between two coordinates using planar approximation formula.

NB suitable for coordinates less than around 50m apart. For larger separations, use the haversine great circle formula.

Parameters:

lat1 (float) – lat1
lon1 (float) – lon1
lat2 (float) – lat2
lon2 (float) – lon2
radius (float) – radius in m (Earth = 6378137 m)

Returns:

planar distance in m

Return type:

float

pynmeagps.nmeahelpers.bearing(lat1: float, lon1: float, lat2: float, lon2: float) → float[source]

Calculate bearing between two coordinates.

Parameters:

lat1 (float) – lat1
lon1 (float) – lon1
lat2 (float) – lat2
lon2 (float) – lon2

Returns:

bearing in degrees

Return type:

float

pynmeagps.nmeahelpers.get_gpswnotow(dat: datetime) → tuple[source]

Get GPS Week number (Wno) and Time of Week (Tow) for midnight on given date.

GPS Epoch 0 = 6th Jan 1980

Parameters:: dat (datetime) – calendar date
Returns:: tuple of (Wno, Tow)
Return type:: tuple

pynmeagps.nmeamessage module

Main NMEA GNSS/GPS Message Protocol Class.

Created on 04 Mar 2021

author:: semuadmin
copyright:: SEMU Consulting © 2021
license:: BSD 3-Clause

class pynmeagps.nmeamessage.NMEAMessage(talker: str, msgID: str, msgmode: int, hpnmeamode: bool = False, **kwargs)[source]

Bases: object

NMEA GNSS/GPS Message Class.

__init__(talker: str, msgID: str, msgmode: int, hpnmeamode: bool = False, **kwargs)[source]

Constructor.

If ‘payload’ is passed as a keyword arg, this is taken to contain the entire message content as a list of string values; any other keyword args are ignored.

Otherwise, any individual attributes passed as keyword args will be set to the value provided, all others will be assigned a nominal value according to type.

Parameters:

talker (str) – message talker e.g. “GP” or “P”
msgID (str) – message ID e.g. “GGA”
msgmode (int) – mode (0=GET, 1=SET, 2=POLL)
hpnmeamode (bool) – high precision lat/lon mode (7dp rather than 5dp) (False)
kwargs – keyword arg(s) representing all or some payload attributes

Raises:

NMEAMessageError

serialize() → bytes[source]

Serialize message.

Returns:: serialized output
Return type:: bytes

property identity: str

Identity getter.

Returns:: message identity e.g. GNGSA
Return type:: str

property talker: str

Talker getter.

Returns:: talker e.g. GN
Return type:: str

property msgID: str

Message id getter.

Returns:: message id e.g. GSA
Return type:: str

property msgmode: int

Message mode getter.

Returns:: message mode
Return type:: int

property payload: list

Payload getter.

Returns:: raw payload as list of strings
Return type:: list

property checksum: str

Checksum getter.

Returns:: checksum as hex string
Return type:: str

static str2val(vals: str, att: str) → object[source]

Convert NMEA string to typed value (this is the format that will be available to end users).

Parameters:

vals (str) – attribute value in NMEA protocol format
att (str) – attribute type e.g. ‘DE’

Returns:

attribute value

Return type:

object

Raises:

MMEATypeError

static val2str(val, att: str, hpmode: bool = False) → str[source]

Convert typed value to NMEA string (this is the format used internally by the NMEA protocol).

Parameters:

val (object) – typed attribute value
att (str) – attribute type e.g. ‘IN’
hpmode (bool) – high precision lat/lon mode (7dp rather than 5dp)

Returns:

attribute value in NMEA protocol format

Return type:

str

Raises:

NMEATypeError

static nomval(att: str) → object[source]

Return nominal value for specified attribute type

Parameters:: att (str) – attribute type e.g. ‘DE’
Returns:: nominal value for type
Return type:: object
Raises:: NMEATypeError

pynmeagps.nmeareader module

NMEAReader class.

Reads and parses individual NMEA GNSS/GPS messages from any stream which supports a read(n) -> bytes method.

Can also read from socket via SocketStream wrapper.

Returns both the raw binary data (as bytes) and the parsed data (as a NMEAMessage object).

If the ‘nmeaonly’ kwarg is set to ‘True’, the reader will raise a NMEAParseError if it encounters any non-NMEA data. Otherwise, it will ignore the non-NMEA data and attempt to carry on.

Created on 4 Mar 2021

author:: semuadmin
license:: BSD 3-Clause

class pynmeagps.nmeareader.NMEAReader(stream, msgmode: int = 0, validate: int = 1, nmeaonly: bool = False, quitonerror: int = 1, bufsize: int = 4096, errorhandler: object = None)[source]

Bases: object

NMEAReader class.

__init__(stream, msgmode: int = 0, validate: int = 1, nmeaonly: bool = False, quitonerror: int = 1, bufsize: int = 4096, errorhandler: object = None)[source]

Constructor.

Parameters:

stream (stream) – input data stream (e.g. Serial or binary File)
msgmode (int) – 0 = GET (default), 1 = SET, 2 = POLL
validate (int) – bitfield validation flags - VALCKSUM (default), VALMSGID
nmeaonly (bool) – True = error on non-NMEA data, False = ignore non-NMEA data
quitonerror (int) – 0 = ignore, 1 = log and continue, 2 = (re)raise (1)
bufsize (int) – socket recv buffer size (4096)
errorhandler (object) – error handling object or function (None)

Raises:

NMEAParseError (if mode is invalid)

read() → tuple[source]

Read the binary data from the stream buffer.

Returns:: tuple of (raw_data as bytes, parsed_data as NMEAMessage)
Return type:: tuple
Raises:: NMEAStreamError (if nmeaonly=True and stream includes non-NMEA data)

property datastream: object

Getter for stream.

Returns:: data stream
Return type:: object

static parse(message: bytes, msgmode: int = 0, validate: int = 1) → object[source]

Parse NMEA byte stream to NMEAMessage object.

Parameters:

message (bytes) – bytes message to parse
msgmode (int) – 0 = GET (default), 1 = SET, 2 = POLL
validate (int) – 1 VALCKSUM (default), 2 VALMSGID (can be OR’d)

Returns:

NMEAMessage object (or None if unknown message and VALMSGID is not set)

Return type:

NMEAMessage

Raises:

NMEAParseError (if data stream contains invalid data or unknown message type)

pynmeagps.nmeatypes_core module

NMEA Protocol core globals and constants

Created on 4 Mar 2021

author:: semuadmin

pynmeagps.nmeatypes_get module

NMEA Protocol Output payload definitions

THESE ARE THE PAYLOAD DEFINITIONS FOR _GET_ MESSAGES _FROM_ THE RECEIVER (e.g. Periodic Navigation Data; Poll Responses; Info messages).

NB: Attribute names must be unique within each message id. NB: Avoid reserved names ‘msgID’, ‘talker’, ‘payload’, ‘checksum’.

NB: Repeating groups must be defined as a tuple thus

‘group’: (‘numr’, {dict}) where - ‘numr’ is either:

an integer representing a fixed number of repeats e.g 32

a string representing the name of a preceding attribute containing the number of repeats e.g. ‘numCh’

‘None’ for an indeterminate repeating group (only one such group is permitted per message type)

{dict} is the nested dictionary containing the repeating attributes

Created on 4 Mar Sep 2021

author:: semuadmin

pynmeagps.nmeatypes_poll module

NMEA Protocol Poll payload definitions

THESE ARE THE PAYLOAD DEFINITIONS FOR _POLL_ MESSAGES _TO_ THE RECEIVER (e.g. Message Poll requests).

NB: Attribute names must be unique within each message id. NB: Avoid reserved names ‘msgID’, ‘talker’, ‘payload’, ‘checksum’.

Created on 4 Mar Sep 2021

author:: semuadmin

pynmeagps.nmeatypes_set module

NMEA Protocol Set payload definitions

THESE ARE THE PAYLOAD DEFINITIONS FOR _SET_ MESSAGES _TO_ THE RECEIVER (e.g. Configuration commands).

NB: Attribute names must be unique within each message id. NB: Avoid reserved names ‘msgID’, ‘talker’, ‘payload’, ‘checksum’.

NB: Repeating groups must be defined as a tuple thus

‘group’: (‘numr’, {dict}) where - ‘numr’ is either:

an integer representing a fixed number of repeats e.g 32

a string representing the name of a preceding attribute containing the number of repeats e.g. ‘numCh’

‘None’ for an indeterminate repeating group (only one such group is permitted per message type)

{dict} is the nested dictionary containing the repeating attributes

Created on 4 Mar Sep 2021

author:: semuadmin

pynmeagps.socket_stream module

socket_stream class.

A skeleton socket wrapper which provides basic stream-like read(bytes) and readline() methods.

NB: this will read from a socket indefinitely. It is the responsibility of the calling application to monitor data returned and implement appropriate socket error, timeout or inactivity procedures.

Created on 4 Apr 2022

author:: semuadmin
license:: BSD 3-Clause

class pynmeagps.socket_stream.SocketStream(sock: socket, **kwargs)[source]

Bases: object

socket stream class.

__init__(sock: socket, **kwargs)[source]

Constructor.

Parameters:

socket (sock) – socket object
bufsize (int) – (kwarg) internal buffer size (4096)

property buffer: bytearray

Getter for buffer.

Returns:: buffer
Return type:: bytearray

read(num: int) → bytes[source]

Read specified number of bytes from buffer. NB: always check length of return data.

Parameters:: num (int) – number of bytes to read
Returns:: bytes read (which may be less than num)
Return type:: bytes

readline() → bytes[source]

Read bytes from buffer until LF reached. NB: always check that return data terminator is LF.

Returns:: bytes
Return type:: bytes

write(data: bytes, **kwargs)[source]

Write bytes to socket.

Parameters:: data (bytes) – data
Returns:: None if successful
Return type:: Nonetype

Module contents

Created on 4 Mar 2021

author:: semuadmin
license:: BSD 3-Clause