PyNMEA GPS

https://www.semuconsulting.com/pynmeagps/
Admin
PyNMEA GPS is a Python library for parsing, reading, and handling NMEA GPS/GNSS messages with...
Tokens:33,357
Snippets:273
Trust Score:5.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Get Quectel QTMCFGUART Payload Dictionary

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeamessage.html

Determines the specific payload dictionary key for Quectel QTMCFGUART messages based on message mode, payload length, and keyword arguments.

```python
def _get_dict_qtmcfguart(self, key: str, mode: int, **kwargs) -> str:
        """
        Get payload dictionary for proprietary Quectel QTMCFGUART
        command and query variants.

        :param str key: msgid
        :param int mode: msgmode 1/2
        :return: key of payload definition
        :rtype: str
        """

        lp = len(self._payload)
        py = self._streaming
        pt = "portid" in kwargs
        if mode == nmt.SET:
            bd = "baudrate" in kwargs
            db = "databit" in kwargs
            if (py and lp == 2) or (not py and not pt and bd and not db):
                key += "_CURRBAUD"
            elif (py and lp == 3) or (not py and pt and bd and not db):
                pass
```

--------------------------------

### Get Proprietary NMEA Payload Dictionary

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeamessage.html

Retrieves the payload definition dictionary for proprietary NMEA message types, with specific handling for various Quectel commands.

```python
def _get_dict_prop(self, key: str, **kwargs) -> dict:
        """
        Get payload dictionary for proprietary message types.

        :param str key: msgid
        :return: dictionary representing payload definition
        :rtype: dict
        """

        if key == "QTMCFGGEOFENCE":
            key = self._get_dict_qtmcfggeofence(key, self._mode, **kwargs)
        elif key == "QTMCFGMSGRATE":
            key = self._get_dict_qtmcfgmsgrate(key, self._mode, **kwargs)
        elif key == "QTMCFGPPS":
            key = self._get_dict_qtmcfgpps(key, self._mode, **kwargs)
        elif key == "QTMCFGSAT":
            key = self._get_dict_qtmcfgsat(key, self._mode, **kwargs)
        elif key == "QTMCFGUART":
            key = self._get_dict_qtmcfguart(key, self._mode, **kwargs)
        elif key == "QTMSN":
            key = self._get_dict_qtmsn(key, self._mode, **kwargs)
        elif key == "STMDRSENMSG":
            key = self._get_dict_stmdrsenmsg(key, self._mode, **kwargs)
        elif key[0:3] == "QTM":
            key = self._get_dict_qtmacknak(key, self._mode)

        if self._mode == nmt.POLL:
            return nmpp.NMEA_PAYLOADS_POLL_PROP[key]
        if self._mode == nmt.SET:
            return nmsp.NMEA_PAYLOADS_SET_PROP[key]
        return nmgp.NMEA_PAYLOADS_GET_PROP[key]
```

--------------------------------

### Get Data Stream Property

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeareader.html

Provides read-only access to the underlying data stream object.

```python
@property
def datastream(self) -> object:
        """
        Getter for stream.

        :return: data stream
        :rtype: object
        """

        return self._stream
```

--------------------------------

### utc2wnotow

Source: https://www.semuconsulting.com/pynmeagps/pynmeagps.html

Gets the week number, time of week in milliseconds, and leap second offset for a given GNSS UTC epoch.

```APIDOC
## utc2wnotow

### Description
Get Week number (wno), Time of Week (tow) in milliseconds and leapsecond offset for given GNSS UTC epoch and time system.
G = GPS, E = Galileo, C = Beidou, J = QZSS, I = IRNSS (NavIC)
Note: GLONASS does not use GPS-style wno or tow.
If utc is None, will default to current UTC datetime.

### Parameters
* **utc** (_datetime_ | _NoneType_) – UTC epoch
* **gnss** (_Literal_ _[__"G"__,__"E"__,__"C"__,__"J"__,__"I"__]__= GPS_ _)_) – GNSS time system (GPS)
* **modwno** (_bool_) – True = modular wno, False = continuous wno

### Returns
wno, tow, leapsecond

### Return type
tuple[int, int, int]
```

--------------------------------

### Initialize NMEAReader

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeareader.html

Instantiate the NMEAReader with a stream and configuration options. Supports both socket and other stream types.

```python
from logging import getLogger
from socket import socket
from types import FunctionType, NoneType
from typing import Literal

import pynmeagps.exceptions as nme
from pynmeagps.nmeahelpers import calc_checksum, get_parts
from pynmeagps.nmeamessage import NMEAMessage
from pynmeagps.nmeatypes_core import (
    DEFAULT_BUFSIZE,
    ENCODE_NONE,
    ERR_LOG,
    ERR_RAISE,
    GET,
    NMEA_HDR,
    VALCKSUM,
    VALMSGID,
)
from pynmeagps.socketwrapper import SocketWrapper




[docs]
class NMEAReader:
    """
    NMEAReader class.
    """



    [docs]
    def __init__(
        self,
        stream,
        msgmode: Literal[0, 1, 2] = GET,
        validate: int = VALCKSUM,
        nmeaonly: bool = False,
        quitonerror: Literal[0, 1, 2] = ERR_LOG,
        bufsize: int = DEFAULT_BUFSIZE,
        errorhandler: FunctionType | NoneType = None,
        userdefined: dict | NoneType = None,
        encoding: int = ENCODE_NONE,
    ):
        """Constructor.

        :param stream stream: input data stream (e.g. Serial or binary File)
        :param Literal[0,1,2] msgmode: 0=GET, 1=SET, 2=POLL (0)
        :param int validate: VALNONE (0), VALCKSUM (1), VALMSGID (2),
            (can be OR'd) (1)
        :param bool nmeaonly: True = error on non-NMEA data, False = ignore non-NMEA data
        :param Literal[0,1,2] quitonerror: ERR_IGNORE (0) = ignore errors,  
            ERR_LOG (1) = log continue, ERR_RAISE (2) = (re)raise (1)
        :param int bufsize: socket recv buffer size (4096)
        :param FunctionType | NoneType errorhandler: error handling callback function (None)
        :param dict | NoneType userdefined: user-defined payload definition dictionary (None)
        :param int encoding: encoding for socket stream 
            (0 = none, 1 = chunk, 2 = gzip, 4 = compress, 8 = deflate (can be OR'd)) (0)
        :raises: NMEAParseError (if mode is invalid)
        """
        # pylint: disable=too-many-arguments

        if isinstance(stream, socket):
            self._stream = SocketWrapper(stream, encoding=encoding, bufsize=bufsize)
        else:
            self._stream = stream
        if msgmode not in (0, 1, 2):
            raise nme.NMEAParseError(
                f"Invalid stream mode {msgmode} - must be 0, 1 or 2."
            )
        self._quitonerror = quitonerror
        self._errorhandler = errorhandler
        self._nmea_only = nmeaonly
        self._validate = validate
        self._mode = msgmode
        self._userdefined = userdefined
        self._logger = getLogger(__name__)

```

--------------------------------

### pynmeagps.nmeahelpers.deg2dms

Source: https://www.semuconsulting.com/pynmeagps/pynmeagps.html

Converts decimal degrees to a degrees minutes seconds string. Example: '51°20′45.6″N'.

```APIDOC
## pynmeagps.nmeahelpers.deg2dms

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

### Parameters
* **degrees** (float) - The decimal degrees to convert.
* **att** (Literal['LA', 'LN']) - Specifies whether the value is Latitude ('LA') or Longitude ('LN').

### Returns
* str - The degrees formatted as d.m.s.
```

--------------------------------

### NMEAReader Constructor

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeareader.html

Initializes the NMEAReader with a data stream and configuration options for parsing NMEA messages.

```APIDOC
## NMEAReader.__init__

### Description
Initializes the NMEAReader with a data stream and configuration options for parsing NMEA messages.

### Parameters
#### Path Parameters
- **stream** (stream): input data stream (e.g. Serial or binary File)
- **msgmode** (Literal[0, 1, 2]): 0=GET, 1=SET, 2=POLL (default: 0)
- **validate** (int): VALNONE (0), VALCKSUM (1), VALMSGID (2), (can be OR'd) (default: 1)
- **nmeaonly** (bool): True = error on non-NMEA data, False = ignore non-NMEA data (default: False)
- **quitonerror** (Literal[0, 1, 2]): ERR_IGNORE (0) = ignore errors, ERR_LOG (1) = log continue, ERR_RAISE (2) = (re)raise (default: 1)
- **bufsize** (int): socket recv buffer size (default: 4096)
- **errorhandler** (FunctionType | NoneType): error handling callback function (default: None)
- **userdefined** (dict | NoneType): user-defined payload definition dictionary (default: None)
- **encoding** (int): encoding for socket stream (0 = none, 1 = chunk, 2 = gzip, 4 = compress, 8 = deflate (can be OR'd)) (default: 0)

### Raises
- NMEAParseError: if mode is invalid
```

--------------------------------

### pynmeagps.nmeahelpers.deg2dmm

Source: https://www.semuconsulting.com/pynmeagps/pynmeagps.html

Converts decimal degrees to a degrees decimal minutes string, suitable for display or NMEA compatibility. Example: '51°20.76′S'.

```APIDOC
## pynmeagps.nmeahelpers.deg2dmm

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

### Parameters
* **degrees** (float) - The decimal degrees to convert.
* **att** (Literal['LA', 'LN']) - Specifies whether the value is Latitude ('LA') or Longitude ('LN').

### Returns
* str - The degrees formatted as dm.m.
```

--------------------------------

### NMEAReader Methods and Properties

Source: https://www.semuconsulting.com/pynmeagps/genindex.html

Details on methods and properties available for the NMEAReader class.

```APIDOC
## NMEAReader

### Methods
*   `__init__()`

### Properties
*   `datastream`
```

--------------------------------

### Initialize SocketWrapper

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/socketwrapper.html

Constructor for the SocketWrapper class. Configures the wrapper with a socket object, transfer encoding type, and internal buffer size.

```python
def __init__(
        self,
        sock: socket.socket,
        encoding=ENCODE_NONE,
        bufsize=DEFAULT_BUFSIZE
    ):
        """
        Constructor.

        :param socket.socket sock: socket object
        :param int encoding: transfer-encoding values 
            (0 = none, 1 = chunk, 2 = gzip, 4 = compress, 8 = deflate (can be OR'd) (0)
        :param int bufsize: internal buffer size
        """

        # configure logger with name "pygnssutils" in calling module
        self.logger = getLogger(__name__)
        self._socket = sock
        self._bufsize = bufsize
        self._encoding = encoding
        self._buffer = bytearray()
        self._partial = b""  # partial chunk
        self._recv()  # populate initial buffer
```

--------------------------------

### Get NMEA Payload Dictionary

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeamessage.html

Retrieves the payload definition dictionary for a given NMEA message ID, handling standard, proprietary, and user-defined messages.

```python
def _get_dict(self, **kwargs) -> dict | NoneType:
        """
        Get payload dictionary.

        :return: dictionary representing payload definition
        :rtype: dict | NoneType
        """

        dic = None
        key = self.msgID

        try:
            if key in nmt.NMEA_PREFIX_PROP:  # proprietary, first element is msgId
                if self._streaming:
                    if key == "ASHR" and self._payload[0][1].isdigit():
                        pass  # exception for PASHR pitch and roll sentence without msgId
                    else:
                        key += self._payload[0]
                elif "msgId" in kwargs:
                    key += kwargs["msgId"]
                else:
                    raise nme.NMEAMessageError(
                        f"P{key} message definitions must "
                        "include payload or msgId keyword arguments."
                    )
            key = key.upper()

            if self._defsource == nmt.DEF_PROP:  # proprietary
                dic = self._get_dict_prop(key, **kwargs)
            elif self._defsource == nmt.DEF_USER:  # user defined
                dic = self._userdefined[key]
            else:  # standard
                if self._mode == nmt.POLL:
                    dic = nmp.NMEA_PAYLOADS_POLL[key]
                elif self._mode == nmt.SET:  # pragma: no cover
                    dic = nms.NMEA_PAYLOADS_SET[key]
                else:
                    dic = nmg.NMEA_PAYLOADS_GET[key]
        except KeyError as err:  # unknown msgid
            erm = f"Unknown msgID {key} msgmode {('GET', 'SET', 'POLL')[self._mode]}.".
            if self._validate & nmt.VALMSGID:
                raise nme.NMEAMessageError(erm) from err

        return dic
```

--------------------------------

### SocketWrapper Methods and Properties

Source: https://www.semuconsulting.com/pynmeagps/genindex.html

Details on methods and properties available for the SocketWrapper class.

```APIDOC
## SocketWrapper

### Methods
*   `__init__()`
*   `dechunk()`
*   `in_waiting()`

### Properties
*   `buffer`
```

--------------------------------

### NMEAMessage Initialization

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeamessage.html

Initializes an NMEAMessage object. It handles validation of message parameters and populates attributes based on keyword arguments. Supports user-defined message formats.

```python
def __init__(
        self,
        talker: str,
        msgID: str,
        msgmode: Literal[0, 1, 2],
        hpnmeamode: bool = False,
        validate: int = nmt.VALCKSUM,
        userdefined: dict | NoneType = None,
        checksum: str | NoneType = None,
        **kwargs,
    ):
        """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.

        :param str talker: message talker e.g. "GP" or "P"
        :param str msgID: message ID e.g. "GGA"
        :param int msgmode: mode (0=GET, 1=SET, 2=POLL)
        :param bool hpnmeamode: high precision lat/lon mode (7dp rather than 5dp) (False)
        :param int validate: VALNONE (0), VALCKSUM (1), VALMSGID (2),
            (can be OR'd) (1)
        :param dict userdefined: user-defined payload definition dictionary (None)
        :param str | NoneType checksum: checksum from incoming message or
            None if creating new message (None)
        :param kwargs: keyword arg(s) representing all or some payload attributes
        :raises: NMEAMessageError
        """

        # object is mutable during initialisation only
        super().__setattr__("_immutable", False)
        self._logger = getLogger(__name__)
        self._validate = validate
        self._userdefined = {} if userdefined is None else userdefined

        if msgmode not in (0, 1, 2):
            raise nme.NMEAMessageError(
                f"Invalid msgmode {msgmode} - must be 0, 1 or 2."
            )
        if talker not in nmt.NMEA_TALKERS:
            if self._validate & nmt.VALMSGID:
                raise nme.NMEAMessageError(f"Unknown talker {talker}.")
        if msgID in nmt.NMEA_MSGIDS:
            self._defsource = nmt.DEF_STND  # standard
        elif msgID in nmt.NMEA_MSGIDS_PROP or msgID in nmt.NMEA_PREFIX_PROP:
            self._defsource = nmt.DEF_PROP  # proprietary
        elif msgID in self._userdefined:
            self._defsource = nmt.DEF_USER  # user-defined
        else:
            self._defsource = nmt.DEF_UNKN  # unrecognised
            if self._validate & nmt.VALMSGID:
                raise nme.NMEAMessageError(
                    f"Unknown msgID {talker}{msgID}, msgmode {('GET','SET','POLL')[msgmode]}.")

        self._mode = msgmode
        # high precision NMEA mode returns NMEA lat/lon to 7dp rather than 5dp
        self._hpnmeamode = hpnmeamode
        self._talker = talker
        self._msgID = msgID
        self._checksum = checksum
        # flag to show message is being streamed rather than generated
        self._streaming = "payload" in kwargs
        self._do_attributes(**kwargs)
        self._immutable = True  # once initialised, object is immutable

```

--------------------------------

### NMEAMessage Methods and Properties

Source: https://www.semuconsulting.com/pynmeagps/genindex.html

Details on methods and properties available for the NMEAMessage class.

```APIDOC
## NMEAMessage

### Methods
*   `__init__()`
*   `nomval()` (static method)

### Properties
*   `checksum`
*   `identity`
*   `msgID`
*   `msgmode`
```

--------------------------------

### Get Bytes in Buffer

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/socketwrapper.html

Returns the number of bytes currently held in the internal buffer, indicating how much data is available for immediate reading without needing to fetch from the socket.

```python
def in_waiting(self) -> int:
        """
        Return number of bytes in buffer.

        :returns: length of buffer
        :rtype: int
        """

        return len(self._buffer)
```

--------------------------------

### NMEAMessage Constructor

Source: https://www.semuconsulting.com/pynmeagps/pynmeagps.html

Initializes an NMEAMessage object. It can be constructed with individual parameters or by passing a 'payload' keyword argument containing the entire message content. Other keyword arguments are ignored if 'payload' is provided.

```APIDOC
## NMEAMessage.__init__

### Description
Constructor for the NMEAMessage class.

### Parameters
- **talker** (str) - Required - Message talker identifier (e.g., "GP" or "P").
- **msgID** (str) - Required - Message identifier (e.g., "GGA").
- **msgmode** (Literal[0, 1, 2]) - Required - Message mode (0=GET, 1=SET, 2=POLL).
- **hpnmeamode** (bool) - Optional - High precision latitude/longitude mode (defaults to False).
- **validate** (int) - Optional - Validation level (defaults to 1, which is VALCKSUM).
- **userdefined** (dict | None) - Optional - User-defined payload definition dictionary (defaults to None).
- **checksum** (str | None) - Optional - Checksum from an incoming message or None if creating a new message (defaults to None).
- **kwargs** - Optional - Keyword arguments representing payload attributes.

### Raises
- NMEAMessageError
```

--------------------------------

### Convert Decimal Lat/Lon to Degrees Minutes Seconds

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeahelpers.html

Converts latitude and longitude from decimal degrees to degrees, minutes, and seconds format.

```python
def latlon2dms(lat: float, lon: float) -> tuple[str, str]:
    """
    Converts decimal lat/lon tuple to degrees minutes seconds.

    
```

--------------------------------

### Get Nominal Value for NMEA Attribute

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeamessage.html

Retrieves the nominal (default) value for a specified NMEA attribute type. Supports different values based on message mode for certain attributes like Quectel status.

```python
        if att in (nmt.CH, nmt.ST, nmt.LA, nmt.LN):
            val = ""
        elif att == nmt.LAD:  # pragma: no cover
            val = "N"
        elif att == nmt.LND:  # pragma: no cover
            val = "E"
        elif att == nmt.HX:
            val = "0"
        elif att == nmt.DE:
            val = 0.0
        elif att == nmt.IN:
            val = 0
        elif att == nmt.TM:
            val = datetime.now(timezone.utc).time()
        elif att in (nmt.DT, nmt.DTL, nmt.DM):
            val = datetime.now(timezone.utc).date()
        elif att == nmt.QS:  # Quectel status attribute
            if msgmode == nmt.POLL:
                val = "R"  # read
            elif msgmode == nmt.SET:
                val = "W"  # write
            else:
                val = "OK"  # acknowledgement
        else:
            raise nme.NMEATypeError(f"Unknown attribute type {att}.")
        return val
```

--------------------------------

### NMEAMessage Static Utility Methods

Source: https://www.semuconsulting.com/pynmeagps/pynmeagps.html

Provides static methods for converting NMEA string values to typed Python objects and vice versa, as well as retrieving nominal values for attribute types.

```APIDOC
## NMEAMessage Static Utility Methods

### Description
Utility methods for value conversion and retrieval.

### Methods
- **str2val(_vals: str, _att: str)**
  Converts an NMEA string value to a typed Python object.
  Parameters:
    - **vals** (str) - Attribute value in NMEA protocol format.
    - **att** (str) - Attribute type (e.g., 'DE').
  Returns:
    - Any: The typed attribute value.
  Raises:
    - MMEATypeError

- **val2str(_val_, _att: str, _hpmode: bool = False)**
  Converts a typed Python value to its NMEA string representation.
  Parameters:
    - **val** (object) - Typed attribute value.
    - **att** (str) - Attribute type (e.g., 'IN').
    - **hpmode** (bool) - Optional - High precision lat/lon mode (defaults to False).
  Returns:
    - str: The attribute value in NMEA protocol format.
  Raises:
    - NMEATypeError

- **nomval(_att: str, _msgmode: int = 0)**
  Returns the nominal value for a specified attribute type.
  Parameters:
    - **att** (str) - Attribute type (e.g., 'DE').
    - **msgmode** (int) - Optional - Message mode GET/SET/POLL (defaults to 0).
  Returns:
    - Any: The nominal value for the attribute type.
  Raises:
    - NMEATypeError
```

--------------------------------

### NMEA Helper Functions

Source: https://www.semuconsulting.com/pynmeagps/genindex.html

A collection of utility functions for NMEA data processing and conversion.

```APIDOC
## pynmeagps.nmeahelpers Module Functions

*   `area()`
*   `bearing()`
*   `calc_checksum()`
*   `date2str()`
*   `date2utc()`
*   `ddd2dmm()`
*   `deg2dmm()`
*   `deg2dms()`
*   `dmm2ddd()`
*   `dms2deg()`
*   `ecef2llh()`
*   `generate_checksum()`
*   `get_parts()`
*   `groupsize()`
*   `haversine()`
*   `hex2str()`
*   `knots2spd()`
*   `latlon2dmm()`
*   `latlon2dms()`
*   `leapsecond()`
*   `llh2ecef()`
*   `llh2iso6709()`
*   `msgdesc()`
```

--------------------------------

### Handle Errors Based on Configuration

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeareader.html

Handles exceptions based on the 'quitonerror' setting. Raises the exception if set to ERR_RAISE, logs it or passes to an error handler otherwise.

```python
def _do_error(self, err: Exception):
        """
        Handle error.

        :param Exception err: error message
        :raises: Exception if quitonerror = 2
        """

        if self._quitonerror == ERR_RAISE:
            raise err from err
        if self._quitonerror == ERR_LOG:
            # pass to error handler if there is one
            if self._errorhandler is None:
                self._logger.error(err)
            else:
                self._errorhandler(err)
```

--------------------------------

### NMEAMessage Constructor

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeamessage.html

Initializes an NMEAMessage object. It can be used to create new messages or parse existing ones. It handles message validation, talker ID, message ID, and payload attributes.

```APIDOC
## NMEAMessage.__init__

### Description
Constructor for the NMEAMessage class.

### Parameters
- **talker** (str) - Message talker ID (e.g., "GP", "P").
- **msgID** (str) - Message ID (e.g., "GGA").
- **msgmode** (Literal[0, 1, 2]) - Message mode: 0 for GET, 1 for SET, 2 for POLL.
- **hpnmeamode** (bool, optional) - High precision latitude/longitude mode (7dp). Defaults to False.
- **validate** (int, optional) - Validation level (VALNONE, VALCKSUM, VALMSGID). Defaults to nmt.VALCKSUM.
- **userdefined** (dict | NoneType, optional) - User-defined payload definition dictionary. Defaults to None.
- **checksum** (str | NoneType, optional) - Checksum from an incoming message. Defaults to None.
- **kwargs** - Keyword arguments representing payload attributes or 'payload' list.

### Raises
- **NMEAMessageError**: If msgmode is invalid, or if talker/msgID are unknown and validation is enabled.
```

--------------------------------

### Convert Decimal Degrees to Degrees Minutes Seconds String

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeahelpers.html

Converts decimal degrees to a formatted degrees minutes seconds string (e.g., '51°20′45.6″N'). Supports latitude and longitude with directional suffixes.

```python
def deg2dms(degrees: float, att: Literal["LA", "LN"]) -> str:
    """
    Convert decimal degrees to degrees minutes seconds string
    e.g. '51°20′45.6″N'

    :param float degrees: degrees
    :param Literal["LA","LN"] att: 'LA' (lat) or 'LN' (lon)
    :return: degrees as d.m.s formatted string
    :rtype: str

    """

    try:
        negative = degrees < 0
        degrees = abs(degrees)
        minutes, seconds = divmod(degrees * 3600, 60)
        degrees, minutes = divmod(minutes, 60)
        if negative:
            sfx = "S" if att == LA else "W"
        else:
            sfx = "N" if att == LA else "E"
        return f"{int(degrees)}\u00b0{int(minutes)}\u2032{round(seconds,5)}\u2033{sfx}"
    except (TypeError, ValueError):
        return ""
```

--------------------------------

### Calculate Bearing - Python

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeahelpers.html

Calculates the initial bearing between two geographical coordinates. The result is returned in degrees, ranging from 0 to 360.

```python
def bearing(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
    """
    Calculate bearing between two coordinates.

    :param float lat1: lat1
    :param float lon1: lon1
    :param float lat2: lat2
    :param float lon2: lon2
    :return: bearing in degrees
    :rtype: float
    """

    phi1, lambda1, phi2, lambda2 = [c * pi / 180 for c in (lat1, lon1, lat2, lon2)]
    y = sin(lambda2 - lambda1) * cos(phi2)
    x = cos(phi1) * sin(phi2) - sin(phi1) * cos(phi2) * cos(lambda2 - lambda1)
    theta = atan2(y, x)
    brng = (theta * 180 / pi + 360) % 360

    return brng
```

--------------------------------

### NMEAMessageError

Source: https://www.semuconsulting.com/pynmeagps/pynmeagps.html

Custom exception raised for undefined NMEA message classes or IDs.

```APIDOC
## Exception: NMEAMessageError

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

### Inheritance
Bases: `Exception`
```

--------------------------------

### Calculate GNSS Week Number, Time of Week, and Leap Second Offset

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeahelpers.html

Derives the GPS-style week number (wno), time of week (tow) in milliseconds, and leap second offset for a given GNSS UTC epoch. Supports GPS, Galileo, Beidou, QZSS, and NavIC. GLONASS is excluded as it does not use GPS-style wno or tow. Defaults to current UTC if no datetime is provided.

```python
def utc2wnotow(utc: datetime | NoneType = None, gnss: Literal["G", "E", "C", "J", "I"] = GPS, modwno: bool = True) -> tuple[int, int, int]:
    """
    Get Week number (wno), Time of Week (tow) in milliseconds
    and leapsecond offset for given GNSS UTC epoch and time system.

    G = GPS, E = Galileo, C = Beidou, J = QZSS, I = IRNSS (NavIC)
    
    Note: GLONASS does not use GPS-style wno or tow.

    If `utc` is None, will default to current UTC datetime.

    :param datetime | NoneType utc: UTC epoch
    :param Literal["G","E","C","J","I"] = GPS) gnss: \ 
        GNSS time system (GPS)
    :param bool modwno: True = modular wno, False = continuous wno
    :return: wno, tow, leapsecond
    :rtype: tuple[int, int, int]
    """

    if utc is None:
        utc = datetime.now(tz=timezone.utc)
    if utc.tzinfo is None:
        utc = utc.replace(tzinfo=timezone.utc)

    if gnss == BDS:
        ep0 = EPOCH0_BEIDOU
        rollover = 8192
    elif gnss == GAL:
        ep0 = EPOCH0_GAL
        rollover = 4096
    elif gnss == IRN:
        ep0 = EPOCH0_IRN
        rollover = 1024
    else:
        ep0 = EPOCH0_GPS
        rollover = 1024

    ls = 0 if gnss == GLO else leapsecond(utc, gnss)
    ts = ((utc - ep0).total_seconds() + ls) * 1000
    wno = floor((utc - ep0).days / 7)
    wnom = wno % rollover
    tow = int(ts - wno * 604800000)
    return wnom if modwno else wno, tow, ls






```

--------------------------------

### NMEAReader.__next__

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeareader.html

Returns the next item from the iterator. Raises StopIteration if there are no more items.

```APIDOC
## NMEAReader.__next__

### Description
Returns the next item from the iterator. Raises StopIteration if there are no more items.

### Returns
- tuple[bytes | NoneType, NMEAMessage | NoneType]: A tuple containing the raw NMEA data as bytes and the parsed NMEA message object.

### Raises
- StopIteration: If there are no more items to read from the stream.
```

--------------------------------

### Convert Decimal Lat/Lon to Degrees Decimal Minutes

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeahelpers.html

Converts latitude and longitude from decimal degrees to degrees and decimal minutes format.

```python
def latlon2dmm(lat: float, lon: float) -> tuple[str, str]:
    """
    Converts decimal lat/lon tuple to degrees decimal minutes.

    :param float lat: lat
    :param float lon: lon
    :return: (lat,lon) in d.mm.m format
    :rtype: tuple[str, str]
    """

    latd = deg2dmm(lat, LA)
    lond = deg2dmm(lon, LN)
    return latd,lond
```

--------------------------------

### SocketWrapper.readline()

Source: https://www.semuconsulting.com/pynmeagps/genindex.html

Reads a line of data from the socket wrapper.

```APIDOC
## SocketWrapper.readline()

### Description
Reads a line of data from the socket wrapper.

### Method
method

### Class
pynmeagps.socketwrapper.SocketWrapper
```

--------------------------------

### wnotow2utc

Source: https://www.semuconsulting.com/pynmeagps/pynmeagps.html

Converts GNSS week number and time of week to UTC datetime.

```APIDOC
## wnotow2utc

### Description
Convert week number and seconds of week (expressed as milliseconds) for given GNSS epoch to UTC time.
G = GPS, E = Galileo, C = Beidou, J = QZSS, I = IRNSS (NavIC)
Note: GLONASS does not use GPS-style wno or tow.
If ls is None (the default), leapsecond offset will be automatically derived from NTC reference table.
If autoroll is True, rolls over modular wno to LATEST date less than current date.
e.g. if current date is 2026-04-17:
wno=366, tow=381600000, gnss=GPS gives…
  * autoroll on: 2026-04-16 09:59:42+00:00
  * autoroll off: 1987-01-15 09:59:56+00:00

wno=368, tow=610000000, gnss=GPS gives…
  * autoroll on: 2006-09-17 01:26:26+00:00
  * autoroll off: 1987-02-01 01:26:36+00:00


### Parameters
* **wno** (_int_) – week number (modular or mon-modular)
* **tow** (_int_) – time of week in milliseconds (mod 604,800,000)
* **ls** (_int_ | _NoneType_) – leapsecond offset (will be derived if None) (None)
* **gnss** (_Literal_ _[__"G"__,__"E"__,__"C"__,__"J"__,__"I"__]__= GPS_ _)_) – GNSS time system (GPS)
* **autoroll** (_bool_) – automatic rollover (False)
* **modwno** (_bool_) – True = modular wno, False = continuous wno

### Returns
GNSS epoch as UTC datetime

### Return type
datetime
```

--------------------------------

### get_wno_tow_ls

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeahelpers.html

Calculates the GPS week number (wno), time of week (tow) in milliseconds, and leap second offset for a given GNSS UTC epoch.

```APIDOC
## get_wno_tow_ls

### Description
Get Week number (wno), Time of Week (tow) in milliseconds and leapsecond offset for given GNSS UTC epoch and time system.

G = GPS, E = Galileo, C = Beidou, J = QZSS, I = IRNSS (NavIC)

Note: GLONASS does not use GPS-style wno or tow.

If `utc` is None, will default to current UTC datetime.

### Parameters
- **utc** (datetime | NoneType) - UTC epoch
- **gnss** (Literal["G","E","C","J","I"] = GPS) - GNSS time system (GPS)
- **modwno** (bool) - True = modular wno, False = continuous wno

### Returns
- **tuple[int, int, int]** - wno, tow, leapsecond
```

--------------------------------

### Decompressing NMEA Data

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/socketwrapper.html

Handles decompression of NMEA data chunks, supporting different compression methods like GZIP and ZLIB. Includes error handling for decompression failures.

```python
chunk = decompress(chunk, wbits=MAX_WBITS | 16)
                    if self._encoding & ENCODE_COMPRESS:
                        chunk = decompress(chunk, wbits=MAX_WBITS)
                    if self._encoding & ENCODE_DEFLATE:
                        chunk = decompress(chunk, wbits=-MAX_WBITS)
                except zlibError as err:  # pragma: no cover
                    self.logger.error(f"Error decompressing data: {err}")
                    # parser will discard data
                chunks += chunk
```

--------------------------------

### SocketWrapper.read()

Source: https://www.semuconsulting.com/pynmeagps/genindex.html

Reads data from the socket wrapper.

```APIDOC
## SocketWrapper.read()

### Description
Reads data from the socket wrapper.

### Method
method

### Class
pynmeagps.socketwrapper.SocketWrapper
```

--------------------------------

### NMEAParseError

Source: https://www.semuconsulting.com/pynmeagps/pynmeagps.html

Custom exception raised for NMEA parsing errors.

```APIDOC
## Exception: NMEAParseError

### Description
NMEA Parsing error.

### Inheritance
Bases: `Exception`
```

--------------------------------

### get_parts

Source: https://www.semuconsulting.com/pynmeagps/pynmeagps.html

Parses a raw NMEA message to extract its content, talker, message ID, payload, and checksum.

```APIDOC
## pynmeagps.nmeahelpers.get_parts

### Description
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)
```

--------------------------------

### msgdesc

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeahelpers.html

Returns a descriptive string for a given NMEA message ID.

```APIDOC
## msgdesc

### Description
Return descriptive string for NMEA msgId.

### Parameters
* `msgID` (str): message ID e.g. 'GGA'

### Returns
* `str`: description of message
```

--------------------------------

### utc2wnotow

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeahelpers.html

Converts UTC time to Week Number and TOW (Time of Week).

```APIDOC
## utc2wnotow

### Description
Convert UTC to Week Number and TOW (Time of Week).

### Parameters
* `utc` (datetime | NoneType): UTC datetime object. If None, current UTC time is used.
* `gnss` (Literal["G", "E", "C", "J", "I"]): GNSS time system (default: GPS).
* `modwno` (bool): If True, modifies week number for GPS week rollover.

### Returns
* `tuple[int, int, int]`: A tuple containing (week number, TOW, day of week).
```

--------------------------------

### NMEAReader.read

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeareader.html

Reads binary data from the stream buffer, parses it into an NMEA message, and returns the raw data and parsed message.

```APIDOC
## NMEAReader.read

### Description
Reads binary data from the stream buffer, parses it into an NMEA message, and returns the raw data and parsed message.

### Returns
- tuple[bytes | NoneType, NMEAMessage | NoneType]: A tuple containing the raw NMEA data as bytes and the parsed NMEA message object. Returns (None, None) if EOF is reached.

### Raises
- NMEAStreamError: If `nmeaonly` is True and the stream contains non-NMEA data.
```

--------------------------------

### NMEAReader.__iter__

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeareader.html

Returns the iterator object itself.

```APIDOC
## NMEAReader.__iter__

### Description
Returns the iterator object itself.

### Returns
- self (NMEAReader): The iterator object.
```

--------------------------------

### Convert Decimal Degrees to NMEA Degrees Minutes - Python

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeahelpers.html

Converts decimal degrees to the NMEA standard degrees decimal minutes format. Supports latitude ('LA') and longitude ('LN') and an optional high-precision mode.

```python
def ddd2dmm(degrees: float, att: Literal["LA", "LN"], hpmode: bool = False) -> str:
    """
    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).

```

--------------------------------

### SocketWrapper.write()

Source: https://www.semuconsulting.com/pynmeagps/genindex.html

Writes data to the socket wrapper.

```APIDOC
## SocketWrapper.write()

### Description
Writes data to the socket wrapper.

### Method
method

### Class
pynmeagps.socketwrapper.SocketWrapper
```

--------------------------------

### NMEATypeError

Source: https://www.semuconsulting.com/pynmeagps/pynmeagps.html

Custom exception raised for undefined NMEA payload attribute types.

```APIDOC
## Exception: NMEATypeError

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

### Inheritance
Bases: `Exception`
```

--------------------------------

### SocketWrapper Class

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/socketwrapper.html

The SocketWrapper class provides methods for reading and writing data from a socket, handling transfer encodings, and managing internal buffers.

```APIDOC
## SocketWrapper

### Description
Socket stream wrapper providing read(n) and readline() methods. Supports chunked transfer-encoded datastreams.

### Methods

#### `__init__(self, sock: socket.socket, encoding=ENCODE_NONE, bufsize=DEFAULT_BUFSIZE)`

Constructor for the SocketWrapper.

*   **Parameters**:
    *   `sock` (socket.socket): The socket object to wrap.
    *   `encoding` (int): Transfer-encoding values (0 = none, 1 = chunk, 2 = gzip, 4 = compress, 8 = deflate). Defaults to `ENCODE_NONE`.
    *   `bufsize` (int): Internal buffer size. Defaults to `DEFAULT_BUFSIZE`.

#### `read(self, num: int) -> bytes`

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

*   **Parameters**:
    *   `num` (int): Number of bytes to read.
*   **Returns**:
    *   `bytes`: Bytes read (which may be less than num).

#### `readline(self) -> bytes`

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

*   **Returns**:
    *   `bytes`: Bytes read up to CRLF.

#### `write(self, data: bytes, **kwargs)`

Write bytes to socket.

*   **Parameters**:
    *   `data` (bytes): Data to write.
    *   `kwargs`: Additional keyword arguments for the socket send method.

#### `in_waiting(self) -> int`

Return number of bytes currently in the internal buffer.

*   **Returns**:
    *   `int`: Length of the buffer.

#### `dechunk(self, segment: bytes) -> tuple`

Parse segment of chunked transfer-encoded byte stream. Returns complete chunks in this segment and any partial chunk, which should be prepended to next segment read.

*   **Parameters**:
    *   `segment` (bytes): Segment of byte stream to parse.
*   **Returns**:
    *   `tuple`: A tuple containing (complete_chunks, partial_chunk).
```

--------------------------------

### wnotow2utc

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeahelpers.html

Converts GNSS week number and time of week (in milliseconds) to a UTC datetime object.

```APIDOC
## wnotow2utc

### Description
Convert week number and seconds of week (expressed as milliseconds) for given GNSS epoch to UTC time.

G = GPS, E = Galileo, C = Beidou, J = QZSS, I = IRNSS (NavIC)

Note: GLONASS does not use GPS-style wno or tow.

If `ls` is None (the default), leapsecond offset will be automatically derived from NTC reference table.

If `autoroll` is True, rolls over modular wno to LATEST date less than current date.

### Parameters
- **wno** (int) - week number (modular or mon-modular)
- **tow** (int) - time of week in milliseconds (mod 604,800,000)
- **ls** (int | NoneType, optional) - leapsecond offset (will be derived if None). Defaults to None.
- **gnss** (Literal["G", "E", "C", "J", "I"], optional) - GNSS time system (GPS). Defaults to GPS.
- **autoroll** (bool, optional) - automatic rollover. Defaults to False.
- **modwno** (bool, optional) - True = modular wno, False = continuous wno. Defaults to True.

### Returns
- **datetime** - GNSS epoch as UTC datetime
```

--------------------------------

### Convert Degrees Decimal Minutes String to Decimal Degrees

Source: https://www.semuconsulting.com/pynmeagps/_modules/pynmeagps/nmeahelpers.html

Converts a NMEA latitude or longitude string in (d)ddmm.mmmmm format to unsigned decimal degrees. Returns an empty string for invalid input.

```python
def dmm2ddd(pos: str) -> float | str:
    """
    Convert NMEA lat/lon string to (unsigned) decimal degrees.

    :param str pos: (d)ddmm.mmmmm
    :return: pos as decimal degrees, or "" if invalid
    :rtype: float | str

    """

    try:
        dp = pos.find(".")
        if dp < 4:
            raise ValueError()
        posdeg = abs(float(pos[0 : dp - 2]))
        posmin = float(pos[dp - 2 :])
        return round((posdeg + posmin / 60), 10)
    except (TypeError, ValueError):
        return ""
```
Tokens:
Raw