### Get configuration key name

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxhelpers.html

Retrieves the name and data type for a configuration database key ID.

```python
def cfgkey2name(keyid: int) -> tuple:
    """
    Return key name and data type for given
    configuration database hexadecimal key.

    :param int keyID: config key as integer e.g. 0x20930001
    :return: tuple of (keyname, type)
    :rtype: tuple: (str, str)
    :raises: UBXMessageError

    """

    try:
        val = None
        for key, val in ubcdb.UBX_CONFIG_DATABASE.items():
            kid, typ = val
            if keyid == kid:
                return (key, typ)

        # undocumented configuration database key
```

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

### Boot Type Decode

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

Maps numerical values to boot types (Unknown, Cold Start, Watchdog, etc.) as found in UBX-MON-SYS messages.

```APIDOC
## Boot Type Decode

### Description
Maps numerical values to boot types.

### Source
UBX-MON-SYS

### Decode Mapping
- **0**: Unknown
- **1**: Cold Start
- **2**: Watchdog
- **3**: Hardware reset
- **4**: Hardware backup
- **5**: Software backup
- **6**: Software reset
- **7**: VIO fail
- **8**: VDD_X fail
- **9**: VDD_RF fail
- **10**: V_CORE_HIGH fail
```

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

### Get Configuration Key Name and Type - pyubx2.ubxhelpers.cfgkey2name

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

Retrieves the human-readable key name and data type for a given hexadecimal configuration database key ID. Raises UBXMessageError if the keyID is invalid.

```python
pyubx2.ubxhelpers.cfgkey2name(0x20930001)
```

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

### Get Configuration Key ID and Type - pyubx2.ubxhelpers.cfgname2key

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

Converts a configuration database key name (e.g., 'CFG_NMEA_PROTVER') into its hexadecimal key ID and data type. Note that underscores are used in key names, unlike some documentation which may use hyphens.

```python
pyubx2.ubxhelpers.cfgname2key('CFG_NMEA_PROTVER')
```

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

### AID-ALPSRV GET Payload Selection

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxvariants.html

Selects the appropriate AID-ALPSRV GET payload definition by checking the 'type' attribute, which is the second byte of the payload.

```APIDOC
## AID-ALPSRV GET Payload Selection

### Description
Selects the appropriate AID-ALPSRV GET payload definition by checking the value of the 'type' attribute (2nd byte of payload).

### Method
GET (Implicit)

### Endpoint
N/A (Function-based selection)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **type** (int/bytes) - Optional - The type attribute.
- **payload** (bytes) - Optional - The payload of the message.
- **kwargs** (dict) - Optional - Additional keyword arguments.

### Request Example
```json
{
  "type": 255
}
```
```json
{
  "payload": "...\xff..."
}
```

### Response
#### Success Response (dict)
- Returns a dictionary representing the payload definition.

#### Response Example
```json
{
  "example": "payload definition dictionary"
}
```

### Error Handling
- **UBXMessageError**: Raised if neither the type nor payload keyword is provided.
```

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

### Select SEC-SIG Payload by Version

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxvariants.html

Selects the SEC-SIG GET payload definition based on the 'version' attribute, which is the first byte of the payload. Requires 'version' or 'payload' keyword argument.

```python
def get_secsig_dict(**kwargs) -> dict:
    """
    Select appropriate SEC-SIG GET payload definition by checking
    value of 'version' attribute (1st byte of payload).

    :param kwargs: optional payload key/value pairs
    :return: dictionary representing payload definition
    :rtype: dict

    """

    if "version" in kwargs:
        ver = val2bytes(kwargs["version"], U1)
    elif "payload" in kwargs:
        ver = kwargs["payload"][0:1]
    else:
        raise UBXMessageError(
            "SEC-SIG message definitions must include version or payload keyword"
        )
    if ver == b"\x01":
        return UBX_PAYLOADS_GET["SEC-SIG-V1"]
    return UBX_PAYLOADS_GET["SEC-SIG-V2"]
```

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

### pyubx2.ubxvariants.get_secsig_dict

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

Selects the appropriate SEC-SIG GET payload definition by checking the value of the 'version' attribute (1st byte of payload).

```APIDOC
## get_secsig_dict

### Description
Select appropriate SEC-SIG GET payload definition by checking value of ‘version’ attribute (1st byte of payload).

### Method
GET

### Endpoint
/websites/semuconsulting_pyubx2/pyubx2/ubxvariants

### Parameters
#### Query Parameters
- **kwargs** (dict) - Optional - optional payload key/value pairs

### Response
#### Success Response (200)
- **dict** - dictionary representing payload definition

### Raises
- **UBXMessageError**

### Response Example
```json
{
  "example": "response body"
}
```
```

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

### Select AID-ALPSRV Payload by Type

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxvariants.html

Selects the AID-ALPSRV GET payload definition by checking the 'type' attribute, which is the second byte of the payload. Requires 'type' or 'payload' keyword argument.

```python
def get_alpsrv_dict(**kwargs) -> dict:
    """
    Select appropriate AID-ALPSRV GET payload definition by checking
    value of 'type' attribute (2nd byte of payload).

    :param kwargs: optional payload key/value pairs
    :return: dictionary representing payload definition
    :rtype: dict

    """

    if "type" in kwargs:
        typ = val2bytes(kwargs["type"], U1)
    elif "payload" in kwargs:
        typ = kwargs["payload"][1:2]
    else:
        raise UBXMessageError(
            "AID-ALPSRV GET message definitions must include type or payload keyword"
        )
    if typ == b"\xff":
        return UBX_PAYLOADS_GET["AID-ALPSRV-SEND"]
    return UBX_PAYLOADS_GET["AID-ALPSRV-REQ"]
```

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

### Helper Functions

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

Documentation for helper functions within the `pyubx2.ubxhelpers` module.

```APIDOC
## Helper Functions (`pyubx2.ubxhelpers`)

### `process_monver()`

#### Description
Processes MONVER data.

### `protocol()`

#### Description
Determines the protocol of a message.

### `sigid2str()`

#### Description
Converts a signal ID to its string representation.

### `utc2itow()`

#### Description
Converts UTC time to TOW (Time of Week).

### `val2bytes()`

#### Description
Converts a value to bytes.

### `val2signmag()`

#### Description
Converts a value to sign-magnitude format.

### `val2sphp()`

#### Description
Converts a value to SPHP format.

### `val2twoscomp()`

#### Description
Converts a value to two's complement format.
```

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

### UBXMessage Configuration Set (CFG-VALSET)

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxmessage.html

Constructs a CFG-VALSET message from a list of configuration key-value tuples. Keys can be integers (keyID) or strings (keyname). Supports up to 64 tuples and specifies memory layers and transaction types.

```python
@staticmethod
def config_set(
        layers: int,
        transaction: int,
        cfgData: list[tuple[int | str, object]]
    ) -> bytes:
        """
        Construct CFG-VALSET message from an array of
        configuration database (key, value) tuples. Keys
        can be in int (keyID) or str (keyname) format.

        :param int layers: memory layer(s) SET_LAYER_RAM (1) = RAM,
            SET_LAYER_BBR (2) = Battery Backed RAM, SETLAYER_FLASH (4) = Flash
        :param int transaction: TXN_NONE (0) = no txn, TXN _START (1) = start txn,
            TXN_ONGOING (2) = continue txn, TXT_COMMIT (3) = apply txn
        :param list[tuple[int| str,object]] cfgData: list of up to 64 tuples (key, value)
        :return: UBXMessage CFG-VALSET
        :rtype: UBXMessage
        :raises: UBXMessageError

        """

        num = len(cfgData)
        if num > 64:
            raise UBXMessageError(
                f"Number of configuration tuples {num} exceeds maximum of 64"
            )

        version = val2bytes(0 if transaction == 0 else 1, U1)
        layersb = val2bytes(layers, U1)
        transactionb = val2bytes(transaction, U1)
        payload = version + layersb + transactionb + b"\x00"
        lis = b""

        for cfgItem in cfgData:
            att = ""
            key, val = cfgItem
            if isinstance(key, str):  # if key is a string (keyname)
                kid, att = cfgname2key(key)  # lookup keyID & attribute type
            else:
                kid = key
                key, att = cfgkey2name(key)  # lookup attribute type
```

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

### SEC-SIG GET Payload Selection

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxvariants.html

Selects the appropriate SEC-SIG GET payload definition by checking the 'version' attribute, which is the first byte of the payload.

```APIDOC
## SEC-SIG GET Payload Selection

### Description
Selects the appropriate SEC-SIG GET payload definition by checking the value of the 'version' attribute (1st byte of payload).

### Method
GET (Implicit)

### Endpoint
N/A (Function-based selection)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **version** (int/bytes) - Optional - The version attribute.
- **payload** (bytes) - Optional - The payload of the message.
- **kwargs** (dict) - Optional - Additional keyword arguments.

### Request Example
```json
{
  "version": 1
}
```
```json
{
  "payload": "\x01..."
}
```

### Response
#### Success Response (dict)
- Returns a dictionary representing the payload definition.

#### Response Example
```json
{
  "example": "payload definition dictionary"
}
```

### Error Handling
- **UBXMessageError**: Raised if neither the version nor payload keyword is provided.
```

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

### Get Payload Dictionary

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxmessage.html

Retrieves the dictionary defining the payload structure for a given message mode (GET, SET, POLL), handling special variants and default definitions.

```APIDOC
## Get Payload Dictionary

### Description
Retrieves the dictionary corresponding to the message mode (GET/SET/POLL). Handles specific message types that require alternate payload variants.

### Parameters
* `**kwargs**` (dict) - Optional payload key/value pairs.

### Returns
* `dict` - A dictionary representing the payload definition.

### Raises
* `UBXMessageError` - If an unknown message type or inappropriate mode is encountered.
```

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

### Static Configuration Methods

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

Static methods for constructing specific configuration messages like CFG-VALSET, CFG-VALDEL, and CFG-VALGET.

```APIDOC
## config_set

### Description
Constructs a CFG-VALSET message from a list of (key, value) tuples.

### Parameters
- **layers** (int) - Required - Memory layer (RAM, BBR, FLASH)
- **transaction** (int) - Required - Transaction state
- **cfgData** (list[tuple[int | str, object]]) - Required - List of up to 64 (key, value) tuples

## config_del

### Description
Constructs a CFG-VALDEL message to delete configuration keys.

### Parameters
- **layers** (int) - Required - Memory layer (BBR, FLASH)
- **transaction** (int) - Required - Transaction state
- **keys** (list[int | str]) - Required - List of up to 64 keys

## config_poll

### Description
Constructs a CFG-VALGET message to poll configuration keys.

### Parameters
- **layer** (int) - Required - Memory layer (RAM, BBR, FLASH, DEFAULT)
- **position** (int) - Required - Number of keys to skip
- **keys** (list[int | str]) - Required - List of up to 64 keys
```

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

### Get attribute type

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxhelpers.html

Extracts the type character from a UBX attribute string.

```python
def atttyp(att: str) -> str:
    """
    Helper function to return attribute type as string.

    :param str: attribute type e.g. 'U002'
    :return: type of attribute as string e.g. 'U'
    :rtype: str

    """

    return att[0:1]
```

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

### process_monver - Process MON-VER message

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

Parses a MON-VER UBX message and returns a dictionary containing hardware, firmware, and software version information.

```APIDOC
## process_monver

### Description
Process parsed MON-VER sentence into dictionary of hardware, firmware and software version identifiers.

### Parameters
* **_msg** (_UBXMessage_) – UBX MON-VER config message

### Returns
* **dict** – dict of version information
```

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

### Get Data Stream Property

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxreader.html

Provides a getter for the data stream object.

```python
return self._stream
```

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

### Configuration Key Handling

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

Functions for converting between configuration key IDs and names.

```APIDOC
## pyubx2.ubxhelpers.cfgkey2name

### Description
Return key name and data type for a given configuration database hexadecimal key.

### Method
N/A (Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

## pyubx2.ubxhelpers.cfgname2key

### Description
Return hexadecimal key and data type for a given configuration database key name.

### Method
N/A (Function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### protocol - Get protocol of raw message

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

Determines the protocol type of a raw binary message.

```APIDOC
## protocol

### Description
Gets protocol of raw message.

### Parameters
* **_raw** (_bytes_) – raw (binary) message

### Returns
* **int** – protocol type (1 = NMEA, 2 = UBX, 4 = RTCM3, 0 = unknown)
```

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

### UBXMessage Initialization

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxmessage.html

Details the constructor for the UBXMessage class, including parameter types and initialization logic.

```APIDOC
## UBXMessage Constructor

### Description
Initializes a UBXMessage object. It can be constructed with a payload provided as keyword arguments or as a byte sequence. If no keyword arguments are provided, the payload is assumed to be empty. The message mode and parsing behavior for bitfields can also be specified.

### Parameters
- **ubxClass** (str | int | bytes) - The message class, can be a string (e.g., 'CFG'), an integer, or bytes.
- **ubxID** (str | int | bytes) - The message ID, can be a string (e.g., 'PRT'), an integer, or bytes.
- **msgmode** (Literal[0, 1, 2]) - The message mode: 0 for GET, 1 for SET, 2 for POLL.
- **parsebitfield** (Literal[0, 1, 2]) - Controls how bitfields are parsed: 0 for bytes, 1 for individual bits, 2 for both bytes and bits. Defaults to 1.
- **kwargs** - Optional keyword arguments representing payload attributes or the complete 'payload' as bytes.

### Raises
- **UBXMessageError**: If an invalid `msgmode` is provided.
- **UBXTypeError**: If there's an incorrect type for an attribute or an overflow error during attribute processing.
```

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

### pyubx2.ubxhelpers Module Functions

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

This section lists and describes the various helper functions available in the pyubx2.ubxhelpers module, which provide utility for data conversion, validation, and manipulation.

```APIDOC
## pyubx2.ubxhelpers Module Functions

### Description
Utility functions for data conversion, validation, and manipulation within the pyubx2 package.

### Functions

- **att2idx()**: Converts attribute name to index.
- **att2name()**: Converts attribute index to name.
- **attsiz()**: Returns the size of an attribute.
- **atttyp()**: Returns the type of an attribute.
- **bytes2val()**: Converts bytes to a value.
- **calc_checksum()**: Calculates the checksum for UBX data.
- **cel2cart()**: Converts celestial coordinates to Cartesian coordinates.
- **cfgkey2name()**: Converts configuration key to name.
- **cfgname2key()**: Converts configuration name to key.
- **dop2str()**: Converts DOP value to a string.
- **escapeall()**: Escapes all special characters.
- **get_bits()**: Retrieves specific bits from a byte.
- **getinputmode()**: Determines the input mode.
- **gnss2str()**: Converts GNSS ID to a string.
- **gpsfix2str()**: Converts GPS fix type to a string.
- **hextable()**: Generates a hexadecimal table.
- **isvalid_checksum()**: Checks if the checksum is valid.
- **itow2utc()**: Converts TOW to UTC time.
- **key_from_val()**: Generates a key from a value.
- **msgclass2bytes()**: Converts message class to bytes.
- **msgstr2bytes()**: Converts message string to bytes.
- **nomval()**: Returns the nominal value.
- **process_monver()**: Processes MONVER message.
- **protocol()**: Determines the protocol type.
- **sigid2str()**: Converts signal ID to a string.
- **utc2itow()**: Converts UTC time to TOW.
- **val2bytes()**: Converts a value to bytes.
- **val2signmag()**: Converts value to sign-magnitude format.
- **val2sphp()**: Converts value to sphp format.
- **val2twoscomp()**: Converts value to two's complement format.
```

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

### Get attribute size

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxhelpers.html

Returns the size of a UBX attribute in bytes based on its type string.

```python
def attsiz(att: str) -> int:
    """
    Helper function to return attribute size in bytes.

    :param str: attribute type e.g. 'U002'
    :return: size of attribute in bytes, or -1 if variable length
    :rtype: int

    """

    if att == "CH":  # variable length
        return -1
    return int(att[1:4])
```

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

### key_from_val - Get dictionary key from value

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

Retrieves the key from a dictionary corresponding to a given unique value.

```APIDOC
## key_from_val

### Description
Helper method - get dictionary key corresponding to (unique) value.

### Parameters
* **_dictionary** (_dict_) – dictionary
* **_value** (_object_) – unique dictionary value

### Returns
* **bytes** – dictionary key

### Raises
* **KeyError**: if no key found for value
```

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

### Initialize UBXReader

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxreader.html

Constructor for the UBXReader class, allowing configuration of the data stream, protocol filters, and error handling behavior.

```python
    def __init__(
        self,
        datastream,
        msgmode: Literal[0, 1, 2] = GET,
        validate: int = VALCKSUM,
        protfilter: int = NMEA_PROTOCOL | UBX_PROTOCOL | RTCM3_PROTOCOL,
        quitonerror: Literal[0, 1, 2] = ERR_LOG,
        parsebitfield: Literal[0, 1, 2] = 1,
        labelmsm: Literal[1, 2] = 1,
        bufsize: int = DEFAULT_BUFSIZE,
        parsing: bool = True,
        errorhandler: FunctionType | NoneType = None,
        encoding: int = ENCODE_NONE,
    ):
```

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

### UBXMessage Configuration Set

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxmessage.html

The `config_set` static method constructs a CFG-VALSET UBX message from a list of configuration key-value pairs, supporting both key IDs and key names.

```APIDOC
## UBXMessage.config_set

### Description
Construct CFG-VALSET message from an array of configuration database (key, value) tuples. Keys can be in int (keyID) or str (keyname) format.

### Method
```
config_set(layers: int, transaction: int, cfgData: list[tuple[int | str, object]]) -> bytes
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **layers** (int) - Required - memory layer(s) SET_LAYER_RAM (1) = RAM, SET_LAYER_BBR (2) = Battery Backed RAM, SETLAYER_FLASH (4) = Flash
- **transaction** (int) - Required - TXN_NONE (0) = no txn, TXN _START (1) = start txn, TXN_ONGOING (2) = continue txn, TXT_COMMIT (3) = apply txn
- **cfgData** (list[tuple[int | str, object]]) - Required - list of up to 64 tuples (key, value)

### Returns
- **bytes**: UBXMessage CFG-VALSET

### Raises
- **UBXMessageError**: If the number of configuration tuples exceeds 64.
```

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

### pyubx2.ubxvariants.get_alpsrv_dict

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

Selects the appropriate AID-ALPSRV GET payload definition by checking the value of the 'type' attribute (2nd byte of payload).

```APIDOC
## get_alpsrv_dict

### Description
Select appropriate AID-ALPSRV GET payload definition by checking value of ‘type’ attribute (2nd byte of payload).

### Method
GET

### Endpoint
/websites/semuconsulting_pyubx2/pyubx2/ubxvariants

### Parameters
#### Query Parameters
- **kwargs** (dict) - Optional - optional payload key/value pairs

### Response
#### Success Response (200)
- **dict** - dictionary representing payload definition

### Response Example
```json
{
  "example": "response body"
}
```
```

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

### nomval - Get nominal value for UBX attribute type

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

Retrieves the nominal (default) value for a given UBX attribute type.

```APIDOC
## nomval

### Description
Get nominal value for given UBX attribute type.

### Parameters
* **_att** (_str_) – attribute type e.g. ‘U004’

### Returns
* **object** – attribute value as int, float, str or bytes

### Raises
* **UBXTypeError**
```

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

### UBXMessage Constructor

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

Initializes a new UBXMessage instance for handling UBX protocol messages.

```APIDOC
## UBXMessage Constructor

### Description
Creates a new instance of the UBXMessage class. If no keyword parameters are provided, the payload is empty. If 'payload' is provided, it is used as the raw byte sequence.

### Parameters
- **msgClass** (str | int | bytes) - Required - Message class
- **msgID** (str | int | bytes) - Required - Message ID
- **msgmode** (Literal[0, 1, 2]) - Required - 0=GET, 1=SET, 2=POLL
- **parsebitfield** (Literal[0, 1, 2]) - Optional - 0=bytes, 1=bits, 2=both
- **kwargs** (dict) - Optional - Payload keyword arguments
```

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

### PyUBX2 Modules and Classes

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

Overview of the main modules and classes available in the PyUBX2 library.

```APIDOC
## PyUBX2 Library Structure

### Modules
- `pyubx2`
- `pyubx2.exceptions`
- `pyubx2.ubxhelpers`
- `pyubx2.ubxmessage`
- `pyubx2.ubxreader`
- `pyubx2.ubxtypes_configdb`
- `pyubx2.ubxtypes_core`
- `pyubx2.ubxtypes_decodes`
- `pyubx2.ubxtypes_get`
- `pyubx2.ubxtypes_poll`
- `pyubx2.ubxtypes_set`
- `pyubx2.ubxvariants

### Classes
- `UBXMessage` (in `pyubx2.ubxmessage`)
- `UBXReader` (in `pyubx2.ubxreader`)

### Exceptions
- `ParameterError`
- `UBXMessageError`
- `UBXParseError`
- `UBXReaderError`
- `UBXStreamError`
- `UBXTypeError
```

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

### Get Attribute Type as String - pyubx2.ubxhelpers.atttyp

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

Retrieves the attribute type as a string from a given attribute type identifier (e.g., 'U002' returns 'U').

```python
pyubx2.ubxhelpers.atttyp('U002')
```

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

### Get Attribute Size in Bytes - pyubx2.ubxhelpers.attsiz

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

Returns the size in bytes for a given UBX attribute type string (e.g., 'U002'). Returns -1 if the attribute has a variable length.

```python
pyubx2.ubxhelpers.attsiz('U002')
```

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

### Initialize UBXMessage with Class, ID, and Mode

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxmessage.html

Constructor for the UBXMessage class. Initializes a UBX message with its class, ID, and mode. Supports string, integer, or byte representations for class and ID. Raises UBXMessageError for invalid msgmode.

```python
def __init__(
        self,
        ubxClass: str | int | bytes,
        ubxID: str | int | bytes,
        msgmode: Literal[0, 1, 2],
        parsebitfield: Literal[0, 1, 2] = 1,
        **kwargs,
    ):
        """Constructor.

        If no keyword parms are passed, the payload is taken to be empty.

        If 'payload' is passed as a keyword parm, this is taken to contain the complete
        payload as a sequence of bytes; any other keyword parms are ignored.

        Otherwise, any named attributes will be assigned the value given, all others will
        be assigned a nominal value according to type.

        :param str | int | bytes msgClass: message class as str, int or byte
        :param str | int | bytes msgID: message ID as str, int or byte
        :param Literal[0,1,2] msgmode: message mode (0=GET, 1=SET, 2=POLL)
        :param Literal[0,1,2] parsebitfield: 0 = parse bitfield as bytes, 1 = parse as \
            individual bits, 2 = parse as bytes and bits (1)
        :param kwargs: optional payload keyword arguments
        :raises: UBXMessageError
        """

        # object is mutable during initialisation only
        super().__setattr__("_immutable", False)
        self._mode = msgmode
        self._payload = b""
        self._length = b""
        self._checksum = b""
        self._parsebf = parsebitfield

        if msgmode not in (GET, SET, POLL):
            raise UBXMessageError(f"Invalid msgmode {msgmode} - must be 0, 1 or 2")

        # accommodate different formats of msgClass and msgID
        if isinstance(ubxClass, str) and isinstance(
            ubxID, str
        ):  # string e.g. 'CFG', 'CFG-PRT'
            self._ubxClass, self._ubxID = msgstr2bytes(ubxClass, ubxID)
        elif isinstance(ubxClass, int) and isinstance(ubxID, int):  # int e.g. 6, 1
            self._ubxClass, self._ubxID = msgclass2bytes(ubxClass, ubxID)
        else:  # bytes e.g. b'\x06', b'\x01'
            self._ubxClass = ubxClass
            self._ubxID = ubxID

        self._do_attributes(**kwargs)

        self._immutable = True  # once initialised, object is immutable

```

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

### Construct CFG-VALSET Message

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxmessage.html

Use this function to construct a CFG-VALSET message to set configuration values. It supports setting multiple key-value pairs.

```python
keyb = val2bytes(kid, U4)
valb = val2bytes(val, att)
lis = lis + keyb + valb

return UBXMessage("CFG", "CFG-VALSET", SET, payload=payload + lis)
```

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

### Configuration Name to Key Conversion

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxhelpers.html

Converts a configuration database key name (e.g., 'CFG_NMEA_PROTVER') into its hexadecimal key and data type representation. It handles hyphens in names by replacing them with underscores.

```APIDOC
## cfgname2key(name: str) -> tuple

### Description
Return hexadecimal key and data type for given configuration database key name.

NB: UBX_CONFIG_DATABASE uses underscores in key names, whereas UBX documentation uses a mixture of hyphens and underscores.

### Parameters
#### Path Parameters
- **name** (str) - Required - config key as string e.g. "CFG_NMEA_PROTVER"

### Returns
- **tuple**: (key, type)
  - **key** (int): The hexadecimal key.
  - **type** (str): The data type string.

### Raises
- **UBXMessageError**: If the configuration database key is undefined.
```

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

### Convert Configuration Name to Key

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxhelpers.html

Converts a configuration database key name (e.g., 'CFG-NMEA_PROTVER') to its hexadecimal key and data type. It normalizes names by replacing hyphens with underscores.

```python
name = name.replace("-", "_")
    try:
        return ubcdb.UBX_CONFIG_DATABASE[name]
    except KeyError as err:
        raise ube.UBXMessageError(
            f"Undefined configuration database key {name}"
        ) from err
```

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

### Get Masked Bits from Bitfield

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxhelpers.html

Extracts the integer value of specified bits from a byte string representing a bitfield, using a provided bitmask. Assumes the bitfield is a byte and the bitmask is an integer.

```python
i = 0
    val = int(bitfield.hex(), 16)
    while bitmask & 1 == 0:
        bitmask = bitmask >> 1
        i += 1
    return val >> i & bitmask
```

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

### Convert Attribute Index to Name - pyubx2.ubxhelpers.att2name

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

Extracts the base name from a grouped attribute name by removing the index. For example, 'svid_06' becomes 'svid', and 'gnssId_103' becomes 'gnssId'. 'tow' remains 'tow'.

```python
pyubx2.ubxhelpers.att2name('svid_06')
```

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

### pyubx2.ubxhelpers Module

Source: https://www.semuconsulting.com/pyubx2/modules.html

Provides various utility functions for converting and manipulating data within UBX messages.

```APIDOC
## pyubx2.ubxhelpers

### Description
A collection of helper functions for data conversion, validation, and manipulation in UBX messages.

### Functions
- `att2idx(attribute)`: Converts an attribute name to its index.
- `att2name(index)`: Converts an attribute index to its name.
- `attsiz(attribute)`: Returns the size of an attribute.
- `atttyp(attribute)`: Returns the type of an attribute.
- `bytes2val(bytes, type)`: Converts bytes to a value of a specified type.
- `calc_checksum(data)`: Calculates the checksum for the given data.
- `cel2cart(celestial_coords)`: Converts celestial coordinates to Cartesian coordinates.
- `cfgkey2name(key)`: Converts a configuration key to its name.
- `cfgname2key(name)`: Converts a configuration name to its key.
- `dop2str(dop)`: Converts DOP value to a string representation.
- `escapeall(data)`: Escapes all special characters in the data.
- `get_bits(value, start_bit, num_bits)`: Extracts a specified number of bits from a value.
- `getinputmode(data)`: Determines the input mode from the data.
- `gnss2str(gnss_id)`: Converts a GNSS ID to its string representation.
- `gpsfix2str(fix_type)`: Converts a GPS fix type to its string representation.
- `hextable(data)`: Returns a hexadecimal representation of the data.
- `isvalid_checksum(data, checksum)`: Validates the checksum of the data.
- `itow2utc(itow, week)`: Converts iTOW to UTC time.
- `key_from_val(val)`: Generates a key from a value.
- `msgclass2bytes(msg_class)`: Converts a message class to bytes.
- `msgstr2bytes(msg_str)`: Converts a message string to bytes.
- `nomval(attribute)`: Returns the nominal value for an attribute.
- `process_monver(payload)`: Processes MONVER message payload.
- `protocol(data)`: Determines the protocol of the data.
- `sigid2str(sig_id)`: Converts a signal ID to its string representation.
- `utc2itow(year, month, day, hour, min, sec, ms)`: Converts UTC time to iTOW.
- `val2bytes(val, type)`: Converts a value to bytes of a specified type.
- `val2signmag(val, bits)`: Converts a value to sign-magnitude format.
- `val2sphp(val, bits)`: Converts a value to SPHP format.
- `val2twoscomp(val, bits)`: Converts a value to two's complement format.
```

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

### Get Nominal Value for UBX Attribute Type

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxhelpers.html

Retrieves the default or nominal value for a given UBX attribute type. Handles various types including strings, bytes, floats, integers, and arrays. Raises `UBXTypeError` for unknown types.

```python
def nomval(att: str) -> object:
    """
    Get nominal value for given UBX attribute type.

    :param str att: attribute type e.g. 'U004'
    :return: attribute value as int, float, str or bytes
    :rtype: object
    :raises: UBXTypeError

    """

    if att == "CH":
        val = ""
    elif atttyp(att) in ("X", "C"):
        val = b"\x00" * attsiz(att)
    elif atttyp(att) == "R":
        val = 0.0
    elif atttyp(att) in ("E", "I", "L", "U"):
        val = 0
    elif atttyp(att) == "A":  # array of unsigned integers
        val = [0] * attsiz(att)
    else:
        raise ube.UBXTypeError(f"Unknown attribute type {att}")
    return val
```

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

### pyubx2.ubxvariants Module Functions

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

Lists utility functions in the pyubx2.ubxvariants module for retrieving specific configuration data dictionaries.

```APIDOC
## pyubx2.ubxvariants Module Functions

### Description
Utility functions for retrieving configuration data dictionaries for various UBX message types.

### Functions

- **get_cfgtp5_dict()**: Retrieves the dictionary for CFG-TP5 messages.
- **get_mga_dict()**: Retrieves the dictionary for MGA messages.
- **get_rxmpmreq_dict()**: Retrieves the dictionary for RXM-PMREQ messages.
- **get_rxmpmp_dict()**: Retrieves the dictionary for RXM-PMP messages.
- **get_rxmrlm_dict()**: Retrieves the dictionary for RXM-RLM messages.
- **get_cfgnmea_dict()**: Retrieves the dictionary for CFG-NMEA messages.
- **get_aopstatus_dict()**: Retrieves the dictionary for AOPSTATUS messages.
- **get_relposned_dict()**: Retrieves the dictionary for RELPOSNED messages.
- **get_timvcocal_dict()**: Retrieves the dictionary for TIM-VCAL messages.
- **get_cfgdat_dict()**: Retrieves the dictionary for CFG-DAT messages.
- **get_secsig_dict()**: Retrieves the dictionary for SEC-SIG messages.
- **get_alpsrv_dict()**: Retrieves the dictionary for ALPSRV messages.
```

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

### Get UBX Payload Dictionary

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxmessage.html

Retrieves the payload dictionary for a given UBX message mode (GET/SET/POLL). Handles special variants for MGA messages and falls back to predefined dictionaries for other modes. Raises an error for unknown message types.

```python
try:
            msg = self._ubxClass + self._ubxID
            variant = VARIANTS[self._mode].get(msg, False)
            if variant and msg[0] == 0x13:  # MGA
                pdict = variant(msg, self._mode, **kwargs)
            elif variant:
                pdict = variant(**kwargs)
            elif self._mode == POLL:
                pdict = UBX_PAYLOADS_POLL[self.identity]
            elif self._mode == SET:
                pdict = UBX_PAYLOADS_SET[self.identity]
            else:
                # Unknown GET message, parsed to nominal definition
                if self.identity[-7:] == "NOMINAL":
                    pdict = {}
                else:
                    pdict = UBX_PAYLOADS_GET[self.identity]
            return pdict
        except KeyError as err:
            mode = ["GET", "SET", "POLL"][self._mode]
            raise UBXMessageError(
                f"Unknown message type {escapeall(self._ubxClass + self._ubxID)}, mode {mode}. "
                "Check 'msgmode' setting is appropriate for data stream"
            ) from err
```

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

### Type Definitions and Constants

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

Reference for type definitions and constants used across PyUBX2 modules.

```APIDOC
## Type Definitions and Constants

### `pyubx2.ubxtypes_decodes`
- `ParameterError`
- `PLPOSFRAME`
- `POL`
- `PROTIDS`
- `PROTOCOLID`
- `PSMSTATE`
- `PSMSTATUS`
- `QUALITYIND`
- `RESETMODE`
- `SBASINTEGRITYUSED`
- `SBASMODE`
- `SBASSYS`
- `SIGCFMASK`
- `SIGID`
- `SOURCEOFCURLS`
- `SPIMODE`
- `SPOOFDETSTATE`
- `SRCOFLSCHANGE`
- `STATE`
- `SVNUMBERING`
- `TIMEREF`
- `UTCSTANDARD`
- `VISIBILITY`

### `pyubx2.ubxtypes_core`
- `POLL`
- `RTCM3_PROTOCOL`
- `UBX_HDR`
- `UBX_PROTOCOL`
- `SET`
- `SETPOLL`
- `VALCKSUM`
- `VALNONE`

### `pyubx2.ubxtypes_configdb`
- `POLL_LAYER_BBR`
- `POLL_LAYER_DEFAULT`
- `POLL_LAYER_FLASH`
- `POLL_LAYER_RAM`
- `SET_LAYER_BBR`
- `SET_LAYER_FLASH`
- `SET_LAYER_RAM`
- `TXN_COMMIT`
- `TXN_NONE`
- `TXN_ONGOING`
- `TXN_START
```

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

### Configuration Set API

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxmessage.html

Constructs a CFG-VALSET message to set configuration values. It supports non-volatile memory layers and transaction management. Keys can be provided as integers (keyID) or strings (keyname).

```APIDOC
## POST /api/config/set

### Description
Constructs a CFG-VALSET message to set configuration values. It supports non-volatile memory layers and transaction management. Keys can be provided as integers (keyID) or strings (keyname).

### Method
POST

### Endpoint
/api/config/set

### Parameters
#### Request Body
- **layers** (int) - Required - Non-volatile memory layer(s) to set (e.g., SET_LAYER_BBR, SET_LAYER_FLASH).
- **transaction** (int) - Required - Transaction type (e.g., TXN_NONE, TXN_START, TXN_ONGOING, TXT_COMMIT).
- **keys** (list[int | str]) - Required - Array of configuration keys (keyID or keyname) to set. Maximum of 64 keys.

### Request Example
```json
{
  "layers": 4, 
  "transaction": 1, 
  "keys": [10, "some_key_name"]
}
```

### Response
#### Success Response (200)
- **message** (bytes) - The constructed UBXMessage for CFG-VALSET.
```

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

### pyubx2.ubxtypes_core Module

Source: https://www.semuconsulting.com/pyubx2/modules.html

Contains core type definitions and constants for the UBX protocol.

```APIDOC
## pyubx2.ubxtypes_core Constants

### Description
Core constants and type definitions for the Universal Binary (UBX) protocol.

### Constants
- `UBX_HDR`: The header bytes for a UBX message.
- `GET`: Operation code for GET.
- `SET`: Operation code for SET.
- `POLL`: Operation code for POLL.
- `SETPOLL`: Operation code for SET and POLL.
- `VALNONE`: Represents no value.
- `VALCKSUM`: Represents a checksum value.
- `NMEA_PROTOCOL`: Identifier for NMEA protocol.
- `UBX_PROTOCOL`: Identifier for UBX protocol.
- `RTCM3_PROTOCOL`: Identifier for RTCM3 protocol.
- `ERR_RAISE`: Error handling strategy: raise exception.
- `ERR_LOG`: Error handling strategy: log error.
- `ERR_IGNORE`: Error handling strategy: ignore error.
- `ATTTYPE`: Type identifier for attributes.
```

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

### UBXMessage Methods

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

Documentation for methods available in the UBXMessage class.

```APIDOC
## UBXMessage Methods

### `serialize()`

#### Description
Serializes the UBXMessage object into a byte string.

#### Method
`method`

#### Endpoint
N/A (Instance method)

### `payload` property

#### Description
Accesses the payload of the UBXMessage.

#### Method
`property`

#### Endpoint
N/A (Instance property)
```

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

### UBXReader Methods

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

Documentation for methods available in the UBXReader class.

```APIDOC
## UBXReader Methods

### `parse()`

#### Description
Parses a stream of bytes to extract UBX messages.

#### Method
`static method`

#### Endpoint
N/A (Class method)

### `read()`

#### Description
Reads a single UBX message from the reader.

#### Method
`method`

#### Endpoint
N/A (Instance method)
```

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

### Select NAV-RELPOSNED Payload by Version

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxvariants.html

Selects the NAV-RELPOSNED payload definition by checking the version attribute, which is the first byte of the payload. Requires 'version' or 'payload' keyword argument.

```python
def get_relposned_dict(**kwargs) -> dict:
    """
    Select appropriate NAV-RELPOSNED payload definition by checking
    value of 'version' attribute (1st byte of payload).

    :param kwargs: optional payload key/value pairs
    :return: dictionary representing payload definition
    :rtype: dict
    :raises: UBXMessageError

    """

    if "version" in kwargs:
        ver = val2bytes(kwargs["version"], U1)
    elif "payload" in kwargs:
        ver = kwargs["payload"][0:1]
    else:
        raise UBXMessageError(
            "NAV-RELPOSNED message definitions must include version or payload keyword"
        )
    if ver == b"\x00":
        return UBX_PAYLOADS_GET["NAV-RELPOSNED-V0"]
    return UBX_PAYLOADS_GET["NAV-RELPOSNED"]
```

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

### process_monver

Source: https://www.semuconsulting.com/pyubx2/_modules/pyubx2/ubxhelpers.html

Processes a parsed MON-VER UBX message into a dictionary containing hardware, firmware, software version, ROM version, model, and supported GNSS information.

```APIDOC
## process_monver

### Description
Process a parsed MON-VER sentence into a dictionary of hardware, firmware, and software version identifiers.

### Method
N/A (Python function)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **dict**: A dictionary containing version information with keys: `swversion`, `hwversion`, `fwversion`, `romversion`, `gnss`.

#### Response Example
N/A
```

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

### pyubx2.ubxtypes_core Module Constants

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

Details the core constants defined in the pyubx2.ubxtypes_core module, including message headers, protocol types, and error handling modes.

```APIDOC
## pyubx2.ubxtypes_core Module Constants

### Description
Core constants for UBX message structure, protocol identification, and error handling.

### Constants

- **UBX_HDR**: Represents the standard UBX message header.
- **GET**: Command type for retrieving data.
- **SET**: Command type for setting data.
- **POLL**: Command type for polling data.
- **SETPOLL**: Command type for setting and polling data.
- **VALNONE**: Represents an undefined or null value.
- **VALCKSUM**: Represents a checksum value.
- **NMEA_PROTOCOL**: Identifier for the NMEA protocol.
- **UBX_PROTOCOL**: Identifier for the UBX protocol.
- **RTCM3_PROTOCOL**: Identifier for the RTCM3 protocol.
- **ERR_RAISE**: Error handling mode: raise exceptions.
- **ERR_LOG**: Error handling mode: log errors.
- **ERR_IGNORE**: Error handling mode: ignore errors.
- **ATTTYPE**: Represents attribute type.
```