pygnssutils

https://semuconsulting.com/pygnssutils
Admin
pygnssutils is a Python library providing comprehensive utilities for GNSS data handling, including...
Tokens:76,531
Snippets:543
Trust Score:5.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Setup Serial or File Input Stream

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssstreamer_cli.html

Configures the input stream, either a serial port or a binary file, and starts a reader thread. Handles potential errors during stream setup.

```python
def _setup_input(**kwargs):
    """
    Set up serial stream as input data source.

    :param app: calling application (i.e. gnssstreamer)
    :param int datatype: "SERIAL" or "FILE"
    :returns: reference to stream
    :rtype: stream
    :raises: ParameterError if input stream descriptor invalid or not found
    """

    # pylint: disable=unused-argument

    def runreader(stream: object, output: Queue):
        """
        THREADED
        Serial stream reader. Parses data from
        serial stream and passes it to receiver
        input queue.

        :param object stream: input stream
        :param Queue output: queue to receiver
        """

        try:
            ubr = GNSSReader(stream, msgmode=SETPOLL, quitonerror=ERR_LOG)
            for raw, _ in ubr:
                if raw is not None:
                    output.put(raw)
                else:
                    break  # EOF
        except ValueError:
            pass  # null buffer, treat as EOF

    def startreader(stream: object, output: Queue):
        """
        Start serial reader thread.

        :param object stream: input stream
        :param Queue output: queue to receiver
        """

        Thread(
            target=runreader,
            args=(stream, output),
            daemon=True,
        ).start()

    instream = kwargs.get("input", "")
    output = kwargs["inqueue"]
    try:
        if datatype == "SERIAL":  # serial port
            port, baudrate = instream.split("@")
            with Serial(port, baudrate, timeout=5) as stream:
                startreader(stream, output)
        else:  # binary file
            with open(instream, "rb") as stream:
                startreader(stream, output)
    except (FileNotFoundError, SerialException, ValueError) as err:
        raise ParameterError(
            f"Invalid input stream descriptor '{instream}' {err}"
        ) from err

```

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

### ClientHandler Setup and Finish

Source: https://semuconsulting.com/pygnssutils/pygnssutils.html

The setup() method allocates the message queue to a client upon connection, and the finish() method de-allocates it upon disconnection. These are overridden from the base StreamRequestHandler class.

```python
setup(_* args_, _** kwargs_)[source]
    Overridden client handler setup routine. Allocates available message queue to client.

finish(_* args_, _** kwargs_)[source]
    Overridden client handler finish routine. De-allocates message queue from client.

```

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

### GNSSMQTTClient.start()

Source: https://semuconsulting.com/pygnssutils/genindex.html

Starts the GNSSMQTTClient.

```APIDOC
## start()

### Description
Starts the GNSSMQTTClient.

### Method
(Method details not provided in source)

### Endpoint
(Endpoint details not provided in source)

### Parameters
(Parameter details not provided in source)

### Request Example
(Request example not provided in source)

### Response
(Response details not provided in source)

### Response Example
(Response example not provided in source)
```

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

### Setup GNSS Datastream

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssserver_cli.html

Processes CLI arguments to configure and initialize the input datastream (serial, socket, or UBXSimulator). It then starts the streamer with the configured stream and any additional keyword arguments.

```python
def _setup_datastream(**kwargs):
    """
    Process CLI arguments to setup specified
    input datastream (serial, socket, file, other),
    and then run streamer using this stream.

    :param dict kwargs: parsed CLI arguments
    :raises: ParameterError if args are invalid
    """

    port = kwargs.pop("inport", None)
    sock = kwargs.pop("socket", None)
    baudrate = int(kwargs.pop("baudrate", 9600))
    timeout = int(kwargs.pop("timeout", 3))
    encoding = kwargs.pop("encoding", ENCODE_NONE)

    if port is None and sock is None:
        raise ParameterError(
            "Either stream, port, socket or filename keyword argument "
            "must be provided.\nType gnsssteamer -h for help.",
        )

    if port is not None:  # serial
        if port.upper() == UBXSIMULATOR:
            with UBXSimulator() as stream:
                _run_streamer(stream, **kwargs)
        else:
            with Serial(port, baudrate, timeout=timeout) as stream:
                _run_streamer(stream, **kwargs)
    elif sock is not None:  # socket
        hostport = sock.split(":")
        if len(hostport) != 2:
            raise ParameterError("socket argument must be in the format host:port")
        hostname = hostport[0]
        port = int(hostport[1])
        ip = gethostbyname(hostname)
        with create_connection((ip, port), timeout) as sock:
            # wrap socket to allow processing as normal stream
            stream = SocketWrapper(sock, encoding)
            _run_streamer(stream, **kwargs)
```

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

### Initialize and Start MQTT Client

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssmqttclient.html

Initializes and starts the MQTT client thread with provided settings. Handles potential parameter errors during initialization. Use this to begin the MQTT client's operation.

```python
self._settings["tlskey"] = kwargs.get("tlskey", self._settings["tlskey"])
self._settings["spartndecode"] = int(
    kwargs.get("spartndecode", self._settings["spartndecode"])
)
self._settings["spartnkey"] = kwargs.get(
    "spartnkey", self._settings["spartnkey"]
)
self._settings["spartnbasedate"] = kwargs.get(
    "spartnbasedate", self._settings["spartnbasedate"]
)
self._settings["output"] = kwargs.get("output", self._settings["output"])

        except (ParameterError, ValueError, TypeError) as err:
            self.logger.critical(
                f"Invalid input arguments {kwargs}\n{err}\nType gnssntripclient -h for help."
            )
            self._validargs = False
            return 0

        self.logger.info(f"Starting MQTT client with arguments {self._settings}.")
        self._stopevent.clear()
        self._mqtt_thread = Thread(
            target=self._run,
            args=(
                self.__app,
                self._settings,
                self._timeout,
                self._stopevent,
            ),
            daemon=True,
        )
        self._mqtt_thread.start()
        return 1
```

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

### Setup MQTT SPARTN Client for GNSS Data Input

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssstreamer_cli.html

Initializes and starts a GNSSMQTTClient for receiving SPARTN data via MQTT. It parses the MQTT server URL and configures the client with connection details and authentication.

```python
def _setup_input_mqtt(app: object, datatype: str, **kwargs) -> object:
    """
    Set up MQTT SPARTN client as input data source.

    :param app: calling application (i.e. gnssstreamer)
    :param datatype: "MQTT"
    :returns: reference to MQTT client
    :rtype: GNSSMQTTClient
    """

    # pylint: disable=unused-argument

    prot, hostname, port, path = parse_url(kwargs["input"])
    prot = 1 if prot == "https" else 0

    gmq = GNSSMQTTClient(app)
    gmq.start(
        server=hostname,
        port=port,
        clientid=kwargs.get("rtkuser", "anon"),
        region=path.lower(),  # e.g. "eu"
        mode=0,  # IP (as opposed to 1 = L-Band)
        output=kwargs["inqueue"],  # send SPARTN data to receiver
    )

    return gmq
```

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

### ClientHandler Setup Method

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/socket_server.html

Sets up the client handler by allocating a message queue.

```APIDOC
## setup

### Description
Overridden client handler setup routine. Allocates an available message queue to the client.

### Parameters
- **args**: Positional arguments.
- **kwargs**: Keyword arguments.

### Method Signature
`def setup(self, *args, **kwargs):`
```

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

### GNSSMQTTClient Start

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssmqttclient.html

Starts the MQTT client's operation by initiating the handler thread and configuring connection parameters.

```APIDOC
## GNSSMQTTClient.start

### Description
Starts the MQTT handler thread. This method configures the client's connection parameters, potentially overriding the default settings, and prepares it to connect to the MQTT broker.

### Method Signature
```python
def start(self, **kwargs) -> int
```

### Parameters
- **
**kwargs**: Arbitrary keyword arguments to override default settings. Supported arguments include:
    - **server** (str): MQTT broker server address.
    - **port** (int): MQTT broker port number.
    - **clientid** (str): MQTT client identifier.
    - **region** (str): MQTT connection region.
    - **mode** (int): Connection mode.
    - **topic_ip** (int): Topic setting for IP data.
    - **topic_mga** (int): Topic setting for MGA data.
    - **topic_key** (int): Topic setting for key data.
    - **topic_freq** (int): Topic setting for frequency data.
    - **tlscrt** (str): Path to the TLS certificate file.

### Returns
- **int**: Return code indicating the success or failure of starting the handler thread.
```

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

### GNSSSocketServer.run

Source: https://semuconsulting.com/pygnssutils/pygnssutils.html

Starts the GNSS socket server to begin broadcasting data.

```APIDOC
## GNSSSocketServer.run()

### Description
Run server.

### Returns
- **rc** (int) - 0 = fail, 1 = ok
```

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

### Setup Output Channel

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssstreamer_cli.html

Processes CLI arguments to set up the specified output channel (serial, socket, file, or custom handler).

```python
def _setup_output(**kwargs):
    """
    Process CLI arguments to setup specified
    output channel (serial, socket, file). The
    different output channels will be handled via
    the customer outputhandler `do_cli_output`.

    :param dict kwargs: parsed CLI arguments
    """

    cliout = int(kwargs.pop("clioutput", OUTPUT_NONE))
    output = kwargs.pop("output", None)
    if cliout == OUTPUT_FILE:
        filename = output
        with open(filename, "wb") as output:
            kwargs["output"] = output
            _setup_datastream(**kwargs)
    elif cliout == OUTPUT_TEXT_FILE:
        filename = output
        with open(filename, "w", encoding="utf-8") as output:
            kwargs["output"] = output
            _setup_datastream(**kwargs)
    elif cliout == OUTPUT_SERIAL:
        port, baud = output.split("@")
        with Serial(port, int(baud), timeout=3) as output:
            kwargs["output"] = output
            _setup_datastream(**kwargs)
    elif cliout in (OUTPUT_SOCKET, OUTPUT_SOCKET_TLS):
        host, port = output.split(":")
        tls = cliout == OUTPUT_SOCKET_TLS
        output = Queue()
        # socket server runs as background thread, piping
        # output from gnssstreamer via a message queue
        Thread(
            target=runserver,
            args=(host, int(port), output, 0, MAXCONNECTION, tls, NTRIP2),
            daemon=True,
        ).start()
        kwargs["output"] = output
        _setup_datastream(**kwargs)
    elif cliout == OUTPUT_HANDLER:
        output = eval(output)  # pylint: disable=eval-used
        kwargs["output"] = output
        _setup_datastream(**kwargs)
    else:
        kwargs["output"] = None
        _setup_datastream(**kwargs)

```

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

### ClientHandler Setup

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/socket_server.html

Allocates an available message queue to the client upon connection. If no queues are available, the connection is not allowed.

```python
def setup(self, *args, **kwargs):
        """
        Overridden client handler setup routine.
        Allocates available message queue to client.
        """

        # find next unused client queue in pool...
        for i, clq in enumerate(self.server.clientqueues):
            if clq["client"] is None:
                self._allowed = True
                self.server.clientqueues[i]["client"] = self.client_address
                self._msgqueue = clq["queue"]
                while not self._msgqueue.empty():  # flush queue
                    self._msgqueue.get()
                self._qidx = i
                self.server.notify(self.client_address, CONNECTED)
                break
        if self._qidx is None:  # no available client queues in pool
            return

        super().setup(*args, **kwargs)
```

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

### Setup Data Stream

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssstreamer_cli.html

Configures the input data stream (serial, socket, file, or other generic stream) and initiates the streamer process. Raises an error if no input source is specified.

```python
def _setup_datastream(**kwargs):
    """
    Process CLI arguments to setup specified
    input datastream (serial, socket, file, other),
    and then run streamer using this stream.

    :param dict kwargs: parsed CLI arguments
    :raises: ParameterError if args are invalid
    """

    datastream = kwargs.pop("datastream", None)
    port = kwargs.pop("port", None)
    sock = kwargs.pop("socket", None)
    baudrate = int(kwargs.pop("baudrate", 9600))
    timeout = int(kwargs.pop("timeout", 3))
    filename = kwargs.pop("filename", None)
    encoding = kwargs.pop("encoding", ENCODE_NONE)

    if datastream is None and port is None and sock is None and filename is None:
        raise ParameterError(
            "Either stream, port, socket or filename keyword argument "
            "must be provided.\nType gnsssteamer -h for help.",
        )

    if datastream is not None:  # generic stream
        with datastream as stream:
            _run_streamer(stream, **kwargs)
    elif port is not None:  # serial
        if port.upper() == UBXSIMULATOR:
            with UBXSimulator() as stream:
                _run_streamer(stream, **kwargs)
        else:
            with Serial(port, baudrate, timeout=timeout) as stream:
                _run_streamer(stream, **kwargs)
    elif sock is not None:  # socket
        hostport = sock.split(":")

```

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

### run

Source: https://semuconsulting.com/pygnssutils/pygnssutils.html

Starts the GNSS reader/writer process to process data from the datastream.

```APIDOC
## run()

### Description
Run GNSS reader/writer.

### Method
Call

### Endpoint
run()
```

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

### GNSSSocketServer Run Method

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssserver.html

Starts the GNSSSocketServer, initiating the input and output threads for data processing.

```APIDOC
## run

### Description

Starts the GNSSSocketServer, initiating the input and output threads for data processing.

### Returns

- **rc** (int) - 0 for failure, 1 for success.
```

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

### run()

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssstreamer.html

Starts the GNSS reader/writer thread to process the data stream.

```APIDOC
## run()

### Description
Starts the GNSS reader/writer thread to process the data stream. It sets the connected status and initiates the read loop.

### Method
`run()`

### Usage
Call this method to begin processing GNSS data from the configured stream.
```

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

### Start GNSSMQTTClient Thread

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssmqttclient.html

Initiates the MQTT client's operation by starting its handler thread. This method allows overriding default connection parameters like server, port, and client ID.

```python
def start(self, **kwargs) -> int:
        """
        Start MQTT handler thread.

        :returns: return code
        :rtype: int
        """

        try:
            self._settings["server"] = kwargs.get("server", self._settings["server"])
            self._settings["port"] = int(kwargs.get("port", self._settings["port"]))
            self._settings["clientid"] = kwargs.get(
                "clientid", self._settings["clientid"]
            )
            self._settings["region"] = kwargs.get("region", self._settings["region"])
            self._settings["mode"] = int(kwargs.get("mode", self._settings["mode"]))
            self._settings["topic_ip"] = int(
                kwargs.get("topic_ip", self._settings["topic_ip"])
            )
            self._settings["topic_mga"] = int(
                kwargs.get("topic_mga", self._settings["topic_mga"])
            )
            self._settings["topic_key"] = int(
                kwargs.get("topic_key", self._settings["topic_key"])
            )
            self._settings["topic_freq"] = int(
                kwargs.get("topic_freq", self._settings["topic_freq"])
            )
            self._settings["tlscrt"] = kwargs.get("tlscrt", self._settings["tlscrt"])
```

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

### Context Manager Enter

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssstreamer.html

Enters the runtime context and starts the GNSS reader/writer. Returns the instance of the streamer.

```python
def __enter__(self):
        """
        Context manager enter routine.
        """

        self.run()
        return self

```

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

### Initialize GnssNtripClient

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssntripclient.html

Initializes the GnssNtripClient with various configuration parameters. Raises ParameterError for invalid inputs. Starts a background thread for reading data if a mountpoint is specified.

```python
        # pylint: disable=unused-variable

        try:
            self._stopevent = kwargs.get("stopevent", self._stopevent)
            self._last_gga = datetime.fromordinal(1)
            self.settings = kwargs
            self._output = kwargs.get("output", None)
            if self._settings["server"] == "":
                raise ParameterError(f"Invalid server URL {self._settings['server']}")
            if not 1 < self._settings["port"] < MAXPORT:
                raise ParameterError(f"Invalid port {self._settings['port']}")

        except (ParameterError, ValueError, TypeError) as err:
            msg = f"Invalid input arguments - {err}"
            self._app_update_status(False, (str(err), ERRCOL))
            raise ParameterError(msg + "\nType gnssntripclient -h for help.") from err

        self._connected = True
        self._stopevent.clear()
        self._sleepevent.clear()
        Thread(
            target=self._read_thread,
            args=(
                self._settings,
                self._stopevent,
                self._output,
            ),
            daemon=True,
        ).start()
        if self.settings["mountpoint"] != "":
            return 1
        return 0

```

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

### GNSSMQTTClient CLI Functions

Source: https://semuconsulting.com/pygnssutils/pygnssutils.html

Provides command-line interface functions for the GNSSMQTTClient, allowing users to start the client with specified parameters.

```APIDOC
## pygnssutils.gnssmqttclient_cli module

### Functions
runclient(**kwargs)
  Start MQTT client with CLI parameters.

main()
  CLI Entry point.

  Parameters:
    **waittime** (_int_) – response wait time in seconds (3)

  Param:
    as per GNSSSPARTNClient constructor and run() method.

  Raises:
    ParameterError if parameters are invalid
```

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

### GNSSNTRIPClient CLI Argument Parser Setup

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssntripclient_cli.html

Sets up the argument parser for the GNSSNTRIPClient CLI. This includes defining all available command-line options for server connection, authentication, data types, and protocol versions.

```python
from argparse import ArgumentDefaultsHelpFormatter, ArgumentParser
from datetime import datetime, timezone
from os import getenv
from queue import Queue
from threading import Thread
from time import sleep

from serial import Serial

from pygnssutils._version import __version__ as VERSION
from pygnssutils.globals import (
    CLIAPP,
    ENV_MQTT_KEY,
    ENV_NTRIP_PASSWORD,
    ENV_NTRIP_USER,
    EPILOG,
    MAXCONNECTION,
    NTRIP1,
    NTRIP2,
    OUTPUT_FILE,
    OUTPUT_NONE,
    OUTPUT_SERIAL,
    OUTPUT_SOCKET,
    OUTPUT_SOCKET_TLS,
    PYGNSSUTILS_CRT,
    PYGNSSUTILS_CRTPATH,
)
from pygnssutils.gnssntripclient import (
    GGAFIXED,
    INACTIVITY_TIMEOUT,
    MAX_RETRY,
    RETRY_INTERVAL,
    RTCM,
    SPARTN,
    WAITTIME,
    GNSSNTRIPClient,
)
from pygnssutils.helpers import set_common_args
from pygnssutils.socket_server import runserver


def main():
    """
    CLI Entry point.

    :param: as per GNSSNTRIPClient constructor and run() method.
    :raises: ParameterError if parameters are invalid
    """
    # pylint: disable=raise-missing-from, too-many-statements

    ap = ArgumentParser(
        epilog=EPILOG,
        formatter_class=ArgumentDefaultsHelpFormatter,
    )
    ap.add_argument("-V", "--version", action="version", version="%(prog)s " + VERSION)
    ap.add_argument(
        "-S", "--server", required=False, help="NTRIP server (caster) URL", default=""
    )
    ap.add_argument(
        "-P", "--port", required=False, help="NTRIP port", type=int, default=2101
    )
    ap.add_argument(
        "-M",
        "--mountpoint",
        required=False,
        help="NTRIP mountpoint (leave blank to get sourcetable)",
        default="",
    )
    ap.add_argument(
        "-H",
        "--https",
        required=False,
        help=("HTTPS (TLS) connection? 0 = HTTP, 1 = HTTPS"),
        type=int,
        choices=[0, 1],
        default=0,
    )
    ap.add_argument(
        "--selfsign",
        required=False,
        help=("Allow self-signed TLS certificate? - set tlscrtpath"),
        type=int,
        choices=[0, 1],
        default=0,
    )
    ap.add_argument(
        "--tlscrtpath",
        required=False,
        help=(
            ""
            "Fully qualified path to self-signed TLS CRT (certificate) file "
            "(required if --selfsign=1)"
        ),
        type=str,
        default=getenv(PYGNSSUTILS_CRTPATH, PYGNSSUTILS_CRT),
    )
    ap.add_argument(
        "-I",
        "--ipprot",
        required=False,
        help="IP protocol",
        choices=["IPv4", "IPv6"],
        default="IPv4",
    )
    ap.add_argument(
        "--flowinfo", required=False, help="Flow info for IPv6", type=int, default=0
    )
    ap.add_argument(
        "--scopeid", required=False, help="Scope ID for IPv6", type=int, default=0
    )
    ap.add_argument(
        "--retries",
        required=False,
        help="Maximum failed connection retries",
        type=int,
        default=MAX_RETRY,
    )
    ap.add_argument(
        "--retryinterval",
        required=False,
        help="Retry backoff (interval = retryinterval * (2**retries))",
        type=int,
        default=RETRY_INTERVAL,
    )
    ap.add_argument(
        "--timeout",
        required=False,
        help="Inactivity timeout in seconds",
        type=int,
        default=INACTIVITY_TIMEOUT,
    )
    ap.add_argument(
        "--ntripversion",
        required=False,
        dest="version",
        help="NTRIP protocol version",
        choices=(NTRIP1, NTRIP2),
        default=NTRIP2,
    )
    ap.add_argument(
        "--datatype",
        required=False,
        help="Data type (RTCM or SPARTN)",
        choices=[RTCM, RTCM.upper(), SPARTN, SPARTN.upper()],
        default=RTCM,
    )
    ap.add_argument(
        "--ntripuser",
        required=False,
        help="NTRIP authentication user",
        default=getenv(ENV_NTRIP_USER, "anon"),
    )
    ap.add_argument(
        "--ntrippassword",
        required=False,
        help="NTRIP authentication password",
        default=getenv(ENV_NTRIP_PASSWORD, "password"),
    )
    ap.add_argument(
        "--ggainterval",
        required=False,
        help="GGA NMEA sentence transmission interval (-1 = None)",
        type=int,
        default=-1,
    )
    ap.add_argument(
        "--reflat", required=False, help="reference latitude", type=float, default=0.0
    )
    ap.add_argument(

```

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

### runserver

Source: https://semuconsulting.com/pygnssutils/pygnssutils.html

Starts a threaded socket server. It can function as a basic socket server or an NTRIP caster, handling multiple client connections and optionally supporting TLS.

```APIDOC
## runserver

### Description
THREADED Socket server function to be run as thread.

### Parameters
#### Parameters
- **host** (str) – host IP
- **port** (int) – port
- **mq** (Queue) – output message queue
- **ntripmode** (int) – 0 = basic, 1 = ntrip caster (default: 0)
- **maxclients** (int) – max concurrent clients (default: 5)
- **tls** (bool) – Enable TLS (HTTPS) (default: False) (remember to set PYGNSSUTILS_PEMPATH)
- **ntripversion** (str) – NTRIP version 1.0 or 2.0 (default: '2.0')
```

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

### Output Thread Logic

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssserver.html

Handles the setup and execution of the output socket server thread. It configures the server based on provided network parameters, including TLS and NTRIP settings, and logs critical errors during startup.

```python
requesthandler = ClientHandlerTLS if tls else ClientHandler
try:
    conn = format_conn(ipprot2int(ipprot), hostip, outport)
    with SocketServer(
        self,
        ntripmode,
        maxclients,
        output,
        conn,
        requesthandler,
        ntripversion=ntripversion,
        ntripuser=ntripuser,
        ntrippassword=ntrippassword,
        ipprot=ipprot,
        tlspempath=tlspempath,
        ntriprtcmstr=ntriprtcmstr,
    ) as self._socket_server:
        self._socket_server.serve_forever()
except OSError as err:
    self.logger.critical(f"Error starting socket server {err}")
```

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

### Run GNSSSocketServer

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssserver.html

Starts the GNSS server by initializing the input and output threads. This method should be called after the server has been configured. It returns an integer status code indicating success (1) or failure (0).

```python
def run(self) -> int:
        """
        Run server.

        :returns: rc 0 = fail, 1 = ok
        :rtype: int
        """

        if self._validargs:
            self.logger.info("Starting server (type CTRL-C to stop)...")
            self._in_thread = self._start_input_thread(**self._kwargs)
            sleep(0.5)
            if self._in_thread.is_alive():
                self._out_thread = self._start_output_thread()
                sleep(0.5)
                if self._out_thread.is_alive():
                    return 1
        return 0
```

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

### Start Output Thread

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssserver.html

Launches a background thread responsible for broadcasting GNSS data over a network socket. It configures the server with various network and NTRIP parameters.

```python
self.logger.info(
    f"Starting output thread, broadcasting on {self._hostip}:{self._outport}..."
)
thread = Thread(
    target=self._output_thread,
    args=(
        self._ipprot,
        self._hostip,
        self._outport,
        self._tls,
        self._ntripmode,
        self._maxclients,
        self._output,
        self._ntripversion,
        self._ntripuser,
        self._ntrippassword,
        self._tlspempath,
        self._ntriprtcmstr,
    ),
    daemon=True,
)
thread.start()
return thread
```

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

### Run MQTT Client Thread

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssmqttclient.html

The core function executed in a separate thread to manage the MQTT client connection and message handling. It sets up topics, user data, and the client instance, then attempts to connect and starts the client loop. Handles connection errors and SSL issues.

```python
def _run(
        self,
        app: object,
        settings: dict,
        timeout: int,
        stopevent: Event,
    ):
        """
        THREADED Run MQTT client thread.

        :param object app: calling application
        :param dict settings: dict of settings
        :param int timeout: connection timeout in seconds
        :param event stopevent: stop event
        """

        # these pylint exclusions are necessary to accommodate old and new versions
        # of the paho.mqtt api...
        # pylint: disable=redundant-keyword-arg, no-member, no-value-for-parameter

        topics = []
        mode = "Lb" if settings.get("mode", 0) else "ip"
        if settings["topic_ip"]:
            topics.append((TOPIC_DATA.format(mode, settings["region"])), 0))
        if settings["topic_mga"]:
            topics.append((TOPIC_ASSIST, 0))
        if settings["topic_key"]:
            topics.append((TOPIC_KEY.format(mode), 0))
        if settings["topic_freq"]:
            topics.append((TOPIC_FREQ, 0))
        userdata = {
            "output": settings["output"],
            "topics": topics,
            "app": app,
            "decode": settings["spartndecode"],
            "key": settings["spartnkey"],
            "basedate": settings["spartnbasedate"],
            "logger": self.logger,
        }

        try:
            if PAHO_MQTT_VERSION < "2.0.0":
                client = mqtt.Client(
                    client_id=settings["clientid"],
                    userdata=userdata,
                )
            else:
                client = mqtt.Client(
                    mqtt.CallbackAPIVersion.VERSION1,
                    client_id=settings["clientid"],
                    userdata=userdata,
                )
            client.on_connect = self.on_connect
            client.on_disconnect = self.on_disconnect
            client.on_message = self.on_message
            client.tls_set(certfile=settings["tlscrt"], keyfile=settings["tlskey"])
            i = 1
            while not stopevent.is_set():
                try:
                    client.connect(settings["server"], port=settings["port"])
                    break
                except Exception as err:  # pylint: disable=broad-exception-caught
                    if i > 4:
                        raise TimeoutError(
                            f"Unable to connect to {settings['server']}"
                            + f":{settings['port']} in {timeout} seconds. {err}"
                        ) from err
                    self.logger.info(f"Trying to connect {i} ...")
                    sleep(timeout / 4)
                    i += 1

            client.loop_start()
            while not stopevent.is_set():
                # run the client loop in the same thread, as callback access gnss
                # client.loop(timeout=0.1)
                sleep(0.1)
        except (FileNotFoundError, TimeoutError, SSLError) as err:
            if "[SSL] PEM lib" in str(err):
                err = f"Invalid Certificate or Key File {err}"
            self.logger.critical(f"ERROR! {err}")
            GNSSMQTTClient.on_error(userdata, err)
            self.stop()
            self.errevent.set()

        finally:
            client.loop_stop()
```

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

### Run GNSS MQTT Client

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssmqttclient_cli.html

Starts the GNSS MQTT client with specified parameters. The client runs in a loop, processing data until an error event is set or streaming stops. Adjust 'waittime' for responsiveness.

```python
def runclient(**kwargs):
    """
    Start MQTT client with CLI parameters.
    """

    waittime = float(kwargs["waittime"])
    with GNSSMQTTClient(CLIAPP, **kwargs) as gsc:
        streaming = gsc.start(**kwargs)
        while streaming and not kwargs["errevent"].is_set():
            sleep(waittime)
        sleep(waittime)
```

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

### ClientHandler.setup()

Source: https://semuconsulting.com/pygnssutils/genindex.html

Sets up the ClientHandler.

```APIDOC
## setup()

### Description
Sets up the ClientHandler.

### Method
(Method details not provided in source)

### Endpoint
(Endpoint details not provided in source)

### Parameters
(Parameter details not provided in source)

### Request Example
(Request example not provided in source)

### Response
(Response details not provided in source)

### Response Example
(Response example not provided in source)
```

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

### SocketServer Start Read Thread

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/socket_server.html

Starts the GNSS message reader thread. It first flushes the message queue and then initializes and starts a new thread targeting the _read_thread method.

```python
def _start_read_thread(self):
        """
        Start GNSS message reader thread.
        """

        while not self._msgqueue.empty():  # flush queue
            self._msgqueue.get()

        self._stopmqread.clear()
        self._stream_thread = Thread(
            target=self._read_thread,
            args=(self._stopmqread, self._msgqueue, self.clientqueues),
            daemon=True,
        )
        self._stream_thread.start()
```

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

### Start Input Thread

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssserver.html

Internal method to start the input thread responsible for reading data. It initializes and starts a new Thread object, passing any additional keyword arguments to the GNSSStreamer.

```python
def _start_input_thread(self, **kwargs) -> Thread:
        """
        Start input (read) thread.

        :param dict kwargs: optional keyword arguments to pass to GNSSStreamer
        :returns: thread
        :rtype: Thread
        """

```

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

### Run GNSS Streamer

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssstreamer.html

Starts the GNSS reader/writer process. It sets the connected status, clears the stop event, and starts a background thread for reading data from the stream.

```python
def run(self):
        """
        Run GNSS reader/writer.
        """

        self.logger.info(f"Starting GNSS reader/writer using {self._stream}...")
        self.connected = CONNECTED
        self._stopevent.clear()

        self._read_thread = Thread(
            target=self._read_loop,
            args=(
                self._stream,
                self._stopevent,
                self._outqueue,
                self._inqueue,
                self._protfilter,
                self._kwargs,
            ),
            daemon=True,
        )
        self._read_thread.start()

```

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

### helpers.set_logging()

Source: https://semuconsulting.com/pygnssutils/genindex.html

Sets up logging.

```APIDOC
## set_logging()

### Description
Sets up logging.

### Method
(Method details not provided in source)

### Endpoint
(Endpoint details not provided in source)

### Parameters
(Parameter details not provided in source)

### Request Example
(Request example not provided in source)

### Response
(Response details not provided in source)

### Response Example
(Response example not provided in source)
```

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

### main (gnssmqttclient_cli)

Source: https://semuconsulting.com/pygnssutils/modules.html

Main entry point for the GNSS MQTT client CLI.

```APIDOC
## main (gnssmqttclient_cli)

### Description
Main entry point for the GNSS MQTT client CLI.

### Usage
```python
main()
```
```

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

### Construct HTTP(S) GET Request Headers

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssntripclient.html

Builds the necessary HTTP headers for an NTRIP GET request, including authentication and version information. Handles different NTRIP versions and GGA data inclusion.

```python
def _set_headers(self, settings: dict) -> str:
        """
        Construct HTTP(S) GET request headers.

        :param dict settings: settings as dictionary
        :returns: request headers as string
        :rtype: str
        """

        headers = ""
        path = settings["mountpoint"]
        hostname = settings["server"]
        port = settings["port"]
        user = settings["ntripuser"]
        password = settings["ntrippassword"]
        ntrip_version = settings["version"]
        ggainterval = settings["ggainterval"]
        if ggainterval == NOGGA:
            gga = ""
        else:
            gga, _ = self._format_gga()

        cred = b64encode(f"{user}:{password}".encode()).decode()
        headers += f"Authorization: Basic {cred}\r\n"
        httpver = "1.1"
        gga_as_data = ""
        if ntrip_version == NTRIP2:
            headers += "Ntrip-Version: Ntrip/2.0\r\n"
            if ggainterval != NOGGA:
                headers += f"Ntrip-GGA: {gga.decode()}"  # includes \r\n
        else:
            httpver = "1.0"
            if ggainterval != NOGGA:
                gga_as_data = gga.decode()

        return (
            f"GET /{path} HTTP/{httpver}\r\n"
            f"Host: {hostname}:{port}\r\n"
            f"User-Agent: NTRIP pygnssutils/{VERSION}\r\n"
            f"{headers}"
            "Accept: */*\r\n"
            "Connection: close\r\n"
            "\r\n"
            f"{gga_as_data}"
        )
```

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

### GNSSMQTTClient Initialization

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssmqttclient.html

Initializes the GNSSMQTTClient with optional application reference and configuration parameters. It sets up logging and default MQTT settings.

```APIDOC
## GNSSMQTTClient.__init__

### Description
Constructor for the GNSSMQTTClient class. Initializes the client with application context, logging configuration, and default MQTT settings. Allows overriding settings via keyword arguments.

### Method Signature
```python
def __init__(self, app=None, **kwargs)
```

### Parameters
- **app** (object, optional): Reference to the calling application class. Defaults to None.
- ****kwargs**: Arbitrary keyword arguments. Supported arguments include:
    - **verbosity** (int): Logging verbosity level. Defaults to VERBOSITY_MEDIUM.
    - **logtofile** (str): Path to a log file. Defaults to empty string.
    - **timeout** (int): Connection timeout in seconds. Defaults to TIMEOUT (8).
    - **errevent** (Event): An event object for error signaling. Defaults to a new Event().
    - **logpath** (str): Directory for log files. Defaults to '.'.
```

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

### main (gnssserver_cli)

Source: https://semuconsulting.com/pygnssutils/modules.html

Main entry point for the GNSS server CLI.

```APIDOC
## main (gnssserver_cli)

### Description
Main entry point for the GNSS server CLI.

### Usage
```python
main()
```
```

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

### Initialize GNSSMQTTClient

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssmqttclient.html

Initializes the GNSSMQTTClient with optional application reference and configuration parameters. Logging is set up based on verbosity and log file settings.

```python
def __init__(self, app=None, **kwargs):
        """
        Constructor.

        :param object app: application from which this class is invoked (None)
        """

        self.__app = app  # Reference to calling application class (if applicable)
        # configure logger with name "pygnssutils" in calling module
        verbosity = int(kwargs.pop("verbosity", VERBOSITY_MEDIUM))
        logtofile = kwargs.pop("logtofile", "")
        self.logger = getLogger(__name__)
        set_logging(getLogger("pyspartn"), verbosity, logtofile)
        self._validargs = True
        clientid = getenv(ENV_MQTT_CLIENTID, default="enter-client-id")

        self._settings = {
            "server": SPARTN_PPSERVER,
            "port": OUTPORT_SPARTN,
            "clientid": clientid,
            "region": "eu",
            "mode": 0,
            "topic_ip": 1,
            "topic_mga": 1,
            "topic_key": 1,
            "topic_freq": 0,
            "tlscrt": getenv(
                "MQTTCRT",
                default=path.join(Path.home(), f"device-{clientid}-pp-cert.crt"),
            ),
            "tlskey": getenv(
                "MQTTPEM",
                default=path.join(Path.home(), f"device-{clientid}-pp-key.pem"),
            ),
            "spartndecode": 0,
            "spartnkey": getenv(ENV_MQTT_KEY, default=None),
            "spartnbasedate": None,
            "output": None,
        }

        self._timeout = kwargs.get("timeout", TIMEOUT)
        self.errevent = kwargs.get("errevent", Event())
        self._logpath = kwargs.get("logpath", ".")
        self._loglines = 0
        self._socket = None
        self._connected = False
        self._stopevent = Event()
        self._mqtt_thread = None
        self._logfile = ""
```

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

### Content Type

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssntripclient.html

Gets the content type of the response from the NTRIP server.

```APIDOC
## content_type

### Description
Get content type e.g. "text/html" or "gnss/data".

### Returns
- **content_type** (str) - The content type of the response.
```

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

### ClientHandler Initialization

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/socket_server.html

Initializes the ClientHandler with request, client address, and server details. Sets up internal queue and message handling flags.

```python
def __init__(self, request, client_address, server):
        """
        Overridden constructor.
        """

        self._qidx = None
        self._msgqueue = None
        self._allowed = False

        super().__init__(request, client_address, server)
```

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

### Get GNSS Datastream

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssstreamer.html

Returns the GNSS datastream object associated with the streamer.

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

        :returns: GNSS datastream
        :rtype: object
        """

        return self._stream
```

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

### Initialize GNSSSocketServer

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssserver.html

Instantiate the GNSSSocketServer with various configuration options for network, NTRIP, and TLS settings. The constructor accepts parameters to define the host IP, port, client limits, NTRIP mode and credentials, and TLS certificate path. It also allows passing keyword arguments to the underlying GNSSStreamer.

```python
gnssserver inport=COM3 hostip=192.168.0.20 outport=50010 ntripmode=0
```

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

### Get Data Stream

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssreader.html

Provides access to the underlying data stream object.

```APIDOC
## datastream

### Description
Provides read-only access to the underlying data stream object used by the GNSS reader.

### Parameters
None

### Returns
- **object**: The data stream object.

### Example
```python
# Assuming 'reader' is an instance of the GNSSReader class
data_stream = reader.datastream
# You can now interact with the data_stream object as needed
```
```

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

### Get Client Connections Count

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/socket_server.html

Retrieves the current number of active client connections to the server.

```python
@property
def connections(self):
        """
        Getter for client connections.
        """

        return self._connections
```

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

### runclient (gnssmqttclient_cli)

Source: https://semuconsulting.com/pygnssutils/modules.html

Runs the GNSS MQTT client from the command line.

```APIDOC
## runclient (gnssmqttclient_cli)

### Description
Runs the GNSS MQTT client from the command line.

### Usage
```python
runclient()
```
```

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

### Get GNSSMQTTClient Settings

Source: https://semuconsulting.com/pygnssutils/_modules/pygnssutils/gnssmqttclient.html

Provides read-only access to the SPARTN IP settings configured for the MQTT client.

```python
@property
def settings(self):
        """
        Getter for SPARTN IP settings.
        """

        return self._settings
```

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

### GNSSMQTTClient

Source: https://semuconsulting.com/pygnssutils/modules.html

Client for handling MQTT communication for GNSS data. Supports starting, stopping, and managing connection events.

```APIDOC
## GNSSMQTTClient

### Description
Client for handling MQTT communication for GNSS data. Supports starting, stopping, and managing connection events.

### Methods
- `__init__()`: Initializes the GNSSMQTTClient.
- `start()`: Starts the MQTT client connection.
- `stop()`: Stops the MQTT client connection.
- `on_connect()`: Callback for successful connection.
- `on_connect_fail()`: Callback for connection failure.
- `on_disconnect()`: Callback for disconnection.
- `on_message()`: Callback for received messages.
- `on_error()`: Callback for errors.

### Properties
- `settings`: Configuration settings for the client.
- `connected`: Boolean indicating if the client is connected.
```

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

### helpers.parse_config()

Source: https://semuconsulting.com/pygnssutils/genindex.html

Parses configuration settings.

```APIDOC
## parse_config()

### Description
Parses configuration settings.

### Method
(Method details not provided in source)

### Endpoint
(Endpoint details not provided in source)

### Parameters
(Parameter details not provided in source)

### Request Example
(Request example not provided in source)

### Response
(Response details not provided in source)

### Response Example
(Response example not provided in source)
```
Tokens:
Raw