Merge pull request #155 from semuconsulting/RC-1.2.44

Rc 1.2.44

.vscode/settings.json

@@ -4,5 +4,5 @@
     "editor.formatOnSave": true,
     "modulename": "${workspaceFolderBasename}",
     "distname": "${workspaceFolderBasename}",
-    "moduleversion": "1.2.43",
+    "moduleversion": "1.2.44",
 }

README.md

@@ -103,7 +103,7 @@ class pyubx2.ubxreader.UBXReader(stream, *args, **kwargs)
 
 You can create a `UBXReader` object by calling the constructor with an active stream object. 
 The stream object can be any viable data stream which supports a `read(n) -> bytes` method (e.g. File or Serial, with 
-or without a buffer wrapper). `pyubx2` implements an internal `SocketStream` class to allow sockets to be read in the same way as other streams (see example below).
+or without a buffer wrapper). `pyubx2` implements an internal `SocketWrapper` class to allow sockets to be read in the same way as other streams (see example below).
 
 Individual input UBX, NMEA or RTCM3 messages can then be read using the `UBXReader.read()` function, which returns both the raw binary data (as bytes) and the parsed data (as a `UBXMessage`, `NMEAMessage` or `RTCMMessage` object, via the `parse()` method). The function is thread-safe in so far as the incoming data stream object is thread-safe. `UBXReader` also implements an iterator.
 

RELEASE_NOTES.md

@@ -1,5 +1,13 @@
 # pyubx2 Release Notes
 
+### RELEASE 1.2.44
+
+CHANGES:
+
+1. Add `process_monver()` helper method to extract dictionary of hardware, firmware and software version identifiers from parsed MON-VER message.
+1. Sphinx documentation and docstrings enhanced to include global constants and decodes.
+1. `socket_stream.SocketStream` class renamed to `socket_wrapper.SocketWrapper` class for clarity.
+
 ### RELEASE 1.2.43
 
 FIXES:

docs/pyubx2.rst

@@ -12,10 +12,10 @@ pyubx2.exceptions module
    :undoc-members:
    :show-inheritance:
 
-pyubx2.socket\_stream module
-----------------------------
+pyubx2.socket\_wrapper module
+-----------------------------
 
-.. automodule:: pyubx2.socket_stream
+.. automodule:: pyubx2.socket_wrapper
    :members:
    :undoc-members:
    :show-inheritance:

pyproject.toml

@@ -7,7 +7,7 @@ name = "pyubx2"
 authors = [{ name = "semuadmin", email = "[email protected]" }]
 maintainers = [{ name = "semuadmin", email = "[email protected]" }]
 description = "UBX protocol parser and generator"
-version = "1.2.43"
+version = "1.2.44"
 license = { file = "LICENSE" }
 readme = "README.md"
 requires-python = ">=3.8"

src/pyubx2/__init__.py

@@ -26,7 +26,7 @@
     UBXStreamError,
     UBXTypeError,
 )
-from pyubx2.socket_stream import SocketStream
+from pyubx2.socket_wrapper import SocketWrapper
 from pyubx2.ubxhelpers import *
 from pyubx2.ubxmessage import UBXMessage
 from pyubx2.ubxreader import UBXReader

src/pyubx2/_version.py

@@ -8,4 +8,4 @@
 :license: BSD 3-Clause
 """
 
-__version__ = "1.2.43"
+__version__ = "1.2.44"

src/pyubx2/exceptions.py

@@ -1,5 +1,5 @@
 """
-UBX Custom Exception Types
+UBX Custom Exception Types.
 
 Created on 27 Sep 2020
 

src/pyubx2/socket_stream.py → src/pyubx2/socket_wrapper.py

@@ -1,5 +1,5 @@
 """
-socket_stream class.
+socket_wrapper class.
 
 A skeleton socket wrapper which provides basic stream-like
 read(bytes) and readline() methods.
@@ -19,9 +19,9 @@
 from socket import socket
 
 
-class SocketStream:
+class SocketWrapper:
     """
-    socket stream class.
+    Socket wrapper class.
     """
 
     def __init__(self, sock: socket, **kwargs):

src/pyubx2/ubxhelpers.py

@@ -1,6 +1,6 @@
 """
 Collection of UBX helper methods which can be used
-outside the UBXMessage or UBXReader classes
+outside the UBXMessage or UBXReader classes.
 
 Created on 15 Dec 2020
 
@@ -564,3 +564,61 @@ def getinputmode(data: bytes) -> int:
     ):
         return POLL
     return SET
+
+
+def process_monver(msg: object) -> dict:
+    """
+    Process parsed MON-VER sentence into dictionary of
+    hardware, firmware and software version identifiers.
+
+    :param UBXMessage msg: UBX MON-VER config message
+    :return: dict of version information
+    :rtype: dict
+    """
+
+    exts = []
+    fw_version = "N/A"
+    rom_version = "N/A"
+    gnss_supported = ""
+    model = ""
+    sw_version = getattr(msg, "swVersion", b"N/A")
+    sw_version = sw_version.replace(b"\x00", b"").decode()
+    sw_version = sw_version.replace("ROM CORE", "ROM")
+    sw_version = sw_version.replace("EXT CORE", "Flash")
+    hw_version = getattr(msg, "hwVersion", b"N/A")
+    hw_version = hw_version.replace(b"\x00", b"").decode()
+
+    for i in range(9):
+        ext = getattr(msg, f"extension_{i+1:02d}", b"")
+        ext = ext.replace(b"\x00", b"").decode()
+        exts.append(ext)
+        if "FWVER=" in exts[i]:
+            fw_version = exts[i].replace("FWVER=", "")
+        if "PROTVER=" in exts[i]:
+            rom_version = exts[i].replace("PROTVER=", "")
+        if "PROTVER " in exts[i]:
+            rom_version = exts[i].replace("PROTVER ", "")
+        if "MOD=" in exts[i]:
+            model = exts[i].replace("MOD=", "")
+            hw_version = f"{model} {hw_version}"
+        for gnss in (
+            "GPS",
+            "GLO",
+            "GAL",
+            "BDS",
+            "SBAS",
+            "IMES",
+            "QZSS",
+            "NAVIC",
+        ):
+            if gnss in exts[i]:
+                gnss_supported = gnss_supported + gnss + " "
+
+    verdata = {}
+    verdata["swversion"] = sw_version
+    verdata["hwversion"] = hw_version
+    verdata["fwversion"] = fw_version
+    verdata["romversion"] = rom_version
+    verdata["gnss"] = gnss_supported
+
+    return verdata

src/pyubx2/ubxreader.py

@@ -33,7 +33,7 @@
     UBXStreamError,
     UBXTypeError,
 )
-from pyubx2.socket_stream import SocketStream
+from pyubx2.socket_wrapper import SocketWrapper
 from pyubx2.ubxhelpers import bytes2val, calc_checksum, getinputmode, val2bytes
 from pyubx2.ubxmessage import UBXMessage
 from pyubx2.ubxtypes_core import (
@@ -90,7 +90,7 @@ def __init__(
         # pylint: disable=too-many-arguments
 
         if isinstance(datastream, socket):
-            self._stream = SocketStream(datastream, bufsize=bufsize)
+            self._stream = SocketWrapper(datastream, bufsize=bufsize)
         else:
             self._stream = datastream
         self._protfilter = protfilter

src/pyubx2/ubxtypes_configdb.py

@@ -1,10 +1,10 @@
 """
-UBX Protocol Configuration Database Keys
+UBX Protocol Configuration Database Keys.
 
-Used by CFG_VALGET, CFG_VALSET and CFG_VALDEL message types
+Used by CFG_VALGET, CFG_VALSET and CFG_VALDEL message types.
 
 Format:
-"keyname": (keyID, "type")
+ "keyname": (keyID, "type")
 
 Created on 30 Nov 2020
 
@@ -35,20 +35,31 @@
 
 # memory layer designators for CFG_VALSET & CFG_VALDEL
 SET_LAYER_RAM = 1
+"""Set RAM (volatile) memory layer in UBX-CFG-VALSET, UBX-CFG-VALDEL"""
 SET_LAYER_BBR = 2
+"""Set Battery-backed RAM memory layer in UBX-CFG-VALSET, UBX-CFG-VALDEL"""
 SET_LAYER_FLASH = 4
+"""Set Flash memory layer in UBX-CFG-VALSET, UBX-CFG-VALDEL"""
 
 # memory layer designators for CFG_VALGET
 POLL_LAYER_RAM = 0
+"""Poll RAM (volatile) memory layer in UBX-CFG-VALGET"""
 POLL_LAYER_BBR = 1
+"""Poll Battery-backed RAM memory layer in UBX-CFG-VALGET"""
 POLL_LAYER_FLASH = 2
+"""Poll Flash memory layer in UBX-CFG-VALGET"""
 POLL_LAYER_DEFAULT = 7
+"""Poll factory default (immutable) memory layer in UBX-CFG-VALGET"""
 
 # transaction state designators for CFG_VALSET & CFG_VALDEL
 TXN_NONE = 0
+"""Transaction none in UBX-CFG-VALSET, UBX-CFG-VALDEL"""
 TXN_START = 1
+"""Transaction start in UBX-CFG-VALSET, UBX-CFG-VALDEL"""
 TXN_ONGOING = 2
+"""Transaction ongoing in UBX-CFG-VALSET, UBX-CFG-VALDEL"""
 TXN_COMMIT = 3
+"""Transaction commit in UBX-CFG-VALSET, UBX-CFG-VALDEL"""
 
 # bits 28..30 of Configuration KeyID represent
 # storage length of Configuration Value in bytes

src/pyubx2/ubxtypes_core.py

@@ -1,5 +1,5 @@
 """
-UBX Protocol core globals and constants
+UBX Protocol core globals, constants, datatypes and message identifiers.
 
 Created on 27 Sep 2020
 
@@ -9,18 +9,31 @@
 """
 
 UBX_HDR = b"\xb5\x62"
+"""UBX message header"""
 GET = 0
+"""GET (receive, response) message types"""
 SET = 1
+"""SET (command) message types"""
 POLL = 2
+"""POLL (query) message types"""
 SETPOLL = 3
+"""SETPOLL (SET or POLL) message types"""
 VALNONE = 0
+"""Do not validate checksum"""
 VALCKSUM = 1
+"""Validate checksum"""
 NMEA_PROTOCOL = 1
+"""NMEA Protocol"""
 UBX_PROTOCOL = 2
+"""UBX Protocol"""
 RTCM3_PROTOCOL = 4
+"""RTCM3 Protocol"""
 ERR_RAISE = 2
+"""Raise error and quit"""
 ERR_LOG = 1
+"""Log errors"""
 ERR_IGNORE = 0
+"""Ignore errors"""
 
 # scaling factor constants
 SCAL9 = 1e-9  # 0.000000001