pyunigps package

Submodules

pyunigps.exceptions module

UNI Custom Exception Types.

Created on 6 Oct 2025

author:: semuadmin (Steve Smith)
copyright:: semuadmin © 2020
license:: BSD 3-Clause

exception pyunigps.exceptions.ParameterError[source]

Bases: Exception

Parameter Error Class.

exception pyunigps.exceptions.GNSSStreamError[source]

Bases: Exception

Generic Stream Error Class.

exception pyunigps.exceptions.UNIParseError[source]

Bases: Exception

UNI Parsing error.

exception pyunigps.exceptions.UNIStreamError[source]

Bases: Exception

UNI Streaming error.

exception pyunigps.exceptions.UNIMessageError[source]

Bases: Exception

UNI Undefined message class/id. Essentially a prompt to add missing payload types to UNI_PAYLOADS.

exception pyunigps.exceptions.UNITypeError[source]

Bases: Exception

UNI Undefined payload attribute type. Essentially a prompt to fix incorrect payload definitions to UNI_PAYLOADS.

pyunigps.unihelpers module

Collection of UNI helper methods which can be used outside the UNIMessage or UNIReader classes.

Created on 6 Oct 2025

author:: semuadmin (Steve Smith)
copyright:: semuadmin © 2020
license:: BSD 3-Clause

pyunigps.unihelpers.att2idx(att: str) → int | tuple[int][source]

Get integer indices corresponding to grouped attribute.

e.g. svid_06 -> 6; gnssId_103 -> 103, gsid_03_04 -> (3,4), tow -> 0

Parameters:: att (str) – grouped attribute name e.g. svid_01
Returns:: indices as integer(s), or 0 if not grouped
Return type:: int | tuple[int]

pyunigps.unihelpers.att2name(att: str) → str[source]

Get name of grouped attribute.

e.g. svid_06 -> svid; gnssId_103 -> gnssId, tow -> tow

Parameters:: att (str) – grouped attribute name e.g. svid_01
Returns:: name without index e.g. svid
Return type:: str

pyunigps.unihelpers.attsiz(att: str) → int[source]

Helper function to return attribute size in bytes.

Parameters:: str – attribute type e.g. ‘U002’
Returns:: size of attribute in bytes, or -1 if variable length
Return type:: int

pyunigps.unihelpers.atttyp(att: str) → str[source]

Helper function to return attribute type as string.

Parameters:: str – attribute type e.g. ‘U002’
Returns:: type of attribute as string e.g. ‘U’
Return type:: str

pyunigps.unihelpers.bytes2val(valb: bytes, att: str) → Any[source]

Convert bytes to value for given UNI attribute type.

Parameters:

valb (bytes) – attribute value in byte format e.g. b’\x19\x00\x00\x00’
att (str) – attribute type e.g. ‘U004’

Returns:

attribute value as int, float, str or bytes

Return type:

Any

Raises:

UNITypeError

pyunigps.unihelpers.calc_crc(message: bytes) → bytes[source]

Perform CRC32 cyclic redundancy check.

Parameters:: message (bytes) – message
Returns:: CRC as bytes
Return type:: bytes

pyunigps.unihelpers.escapeall(val: bytes) → str[source]

Escape all byte characters e.g. b’\x73’ rather than b`s`

Parameters:: val (bytes) – bytes
Returns:: string of escaped bytes
Return type:: str

pyunigps.unihelpers.get_bits(bitfield: bytes, bitmask: int) → int[source]

Get integer value of specified (masked) bit(s) in a UNI bitfield (attribute type ‘X’)

e.g. to get value of bits 6,7 in bitfield b’\x89’ (binary 0b10001001):

get_bits(b'\x89', 0b11000000) = get_bits(b'\x89', 192) = 2

Parameters:

bitfield (bytes) – bitfield byte(s)
bitmask (int) – bitmask as integer (= Σ(2**n), where n is the number of the bit)

Returns:

value of masked bit(s)

Return type:

int

pyunigps.unihelpers.get_parts(message: bytes | str) → tuple[list, list, bytes][source]

Get header, payload and CRC of ASCII UNI message.

Parameters:: message (bytes | str) – entire message as bytes or string
Returns:: tuple of (hdr, payload, crc)
Return type:: tuple[list, list, bytes]
Raises:: UNIMessageError (if message is badly formed)

pyunigps.unihelpers.msgname2id(msgname: str) → int | None[source]

Get numeric message id for given message name

Parameters:: msgname (str) – message name
Returns:: corresponding message ide
Return type:: int | NoneType

pyunigps.unihelpers.header2bytes(msgid: int, length: int, cpuidle: int = 0, timeref: int = 1, timestatus: int = 0, wno: int | None = None, tow: int | None = None, version: int = 0, leapsecond: int = 0, delay: int = 0) → bytes[source]

Convert individual values to header structure (excluding 3 fixed sync bytes).

Parameters:

msgid (int) – msgid
length (int) – payload length
cpuidle (int) – cpuidle
timeref (int) – time reference (GPS/BDS)
timestatus (int) – timestatus
wno (int | NoneType) – week no (defaults to now if None)
tow (int | NoneType) – time of week (defaults to now if None)
version (int) – message version
leapsecond (int) – leap second
delay (int) – delay in ms

Returns:

header as bytes

Return type:

bytes

pyunigps.unihelpers.header2vals(header: bytes) → tuple[source]

Convert header bytes (excluding 3 fixed sync bytes) into individual values.

Parameters:: header (bytes) – header bytes
Returns:: tuple of (cpuidle, msgid, length, timeref, timestatus, wno, tow, version, reserved, leapsecond, delay)

pyunigps.unihelpers.isvalid_checksum(message: bytes) → bool[source]

Validate message checksum.

Parameters:: message (bytes) – message including header and checksum bytes
Returns:: checksum valid flag
Return type:: bool

pyunigps.unihelpers.key_from_val(dictionary: dict, value) → str[source]

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

Parameters:

dictionary (dict) – dictionary
value (object) – unique dictionary value

Returns:

dictionary key

Return type:

str

Raises:

KeyError: if no key found for value

pyunigps.unihelpers.nomval(att: str) → Any[source]

Get nominal value for given UNI attribute type.

Parameters:: att (str) – attribute type e.g. ‘U004’
Returns:: attribute value as int, float, str or bytes
Return type:: Any
Raises:: UNITypeError

pyunigps.unihelpers.str2val(valstr: str, adef: str) → object[source]

Convert ASCII string to typed value

Parameters:

valstr (str) – attribute value as string
adef (str) – attribute type e.g. ‘R001’

Returns:

attribute value

Return type:

object

Raises:

UNITypeError

pyunigps.unihelpers.utc2wnotow(utc: datetime | None = None) → tuple[int, int][source]

Get GPS Week number (wno) and Time of Week (tow) in milliseconds for given utc datetime.

GPS Epoch 0 = 6th Jan 1980

Parameters:: utc (datetime | NoneType) – utc datetime (defaults to now if None)
Returns:: wno, tow
Return type:: tuple[int,int]

pyunigps.unihelpers.val2bytes(val: Any, att: str) → bytes[source]

Convert value to bytes for given UNI attribute type.

Parameters:

val (Any) – attribute value e.g. 25
att (str) – attribute type e.g. ‘U004’

Returns:

attribute value as bytes

Return type:

bytes

Raises:

UNITypeError

pyunigps.unimessage module

UNImessage.py

Main UNI Message Protocol Class.

Created on 26 Sep 2020

author:: semuadmin (Steve Smith)
copyright:: semuadmin © 2020
license:: BSD 3-Clause

class pyunigps.unimessage.UNIMessage(msgid: int | str, length: int | None = None, cpuidle: int = 0, timeref: int = 0, timestatus: int = 0, wno: int | None = None, tow: int | None = None, version: int = 0, leapsecond: int = 0, delay: int = 0, checksum: bytes | None = None, msgmode: int = 0, parsebitfield: bool = True, **kwargs)[source]

Bases: object

UNI Message Class.

__init__(msgid: int | str, length: int | None = None, cpuidle: int = 0, timeref: int = 0, timestatus: int = 0, wno: int | None = None, tow: int | None = None, version: int = 0, leapsecond: int = 0, delay: int = 0, checksum: bytes | None = None, msgmode: int = 0, parsebitfield: bool = True, **kwargs)[source]

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.

Parameters:

msgid (int | str) – message id or message name
length (int | NoneType) – length (will be derived if None)
cpuidle (int) – header cpuidle
timeref (int) – header timeref
timestatus (int) – header timestatus
wno (int | NoneType) – header week number (defaults to now if None)
tow (int | NoneType) – header time of week (defaults to now if None)
version (int) – header version
leapsecond (int) – header leapsecond
delay (int) – header delay
checksum (bytes | NoneType) – CRC (will be derived if None)
msgmode (int) – message mode (0 = GET, 1 = SET, 2 = POLL)
parsebitfield (bool) – 0 = parse as bytes, 1 = parse as individual bits
kwargs – optional keywords representing payload attributes

Raises:

UNITypeError, UNIMessageError

serialize() → bytes[source]

Serialize message.

Returns:: serialized output
Return type:: bytes

property identity: str

Returns message identity in plain text form.

If the message is unrecognised, the message is parsed to a nominal payload definition UNI-NOMINAL and the term ‘NOMINAL’ is appended to the identity.

Returns:: message identity e.g. ‘OBSVMCMP’
Return type:: str

property checksum: bytes

CRC checksum getter.

Returns:: CRC as bytes
Return type:: bytes

property payload: bytes

Payload getter - returns the raw payload bytes.

Returns:: raw payload as bytes
Return type:: bytes

property msgmode: int

Message mode getter.

Returns:: msgmode as integer
Return type:: int

property unimode: str

UNI mode getter (B = Binary, A = ASCII).

Returns:: unimode
Return type:: str

pyunigps.unireader module

UNIReader class.

Reads and parses individual UNI messages from any viable data stream which supports a read(n) -> bytes method.

UNI binary message format (little-endian):

sync	cpuidle	msgid	length	timeinfo	payload	crc
0xaa44b5	1 byte	2 bytes	2 bytes	16 bytes	variable	4 bytes
header = 24 bytes

UNI ascii message format (comma-delimited, with header and payload separated by “;” and payload and checksum separated by “*”):

sync	msgname	cpuidle	timeinfo	payload	crc
#	header = “MSGNAME,,,,,,,,,;”				*nnnnnnnn

timeinfo:

timeref	timestat	wno	tow	version	reserved	leapsec	delay
1 byte	1 byte	2 bytes	4 bytes	4 bytes	1 byte	1 byte	2 bytes

Command response format (comma-delimited):

sync	command	response	response code	crc
“$command”	text	“response: “	“OK” or error message	2 bytes

e.g. $command,STATSINFO COM1 1,response: OK*46 $command,SATSXXXX COM1 1,response: PARSING FAILD NO MATCHING FUNC SATSXXXX*01

Returns both the raw binary data (as bytes) and the parsed data (as an UNIMessage object).

‘protfilter’ governs which protocols (NMEA, UNI or RTCM3) are processed
‘quitonerror’ governs how errors are handled
‘parsing’ governs whether messages are fully parsed

Created on 26 Jan 2026

author:: semuadmin (Steve Smith)
copyright:: semuadmin © 2020
license:: BSD 3-Clause

class pyunigps.unireader.UNIReader(datastream, msgmode: int = 0, validate: int = 1, protfilter: int = 7, quitonerror: int = 1, parsebitfield: bool = True, bufsize: int = 4096, parsing: bool = True, errorhandler: object = None)[source]

Bases: object

UNIReader class.

__init__(datastream, msgmode: int = 0, validate: int = 1, protfilter: int = 7, quitonerror: int = 1, parsebitfield: bool = True, bufsize: int = 4096, parsing: bool = True, errorhandler: object = None)[source]

Constructor.

Parameters:

stream (datastream) – input data stream
msgmode (int) – 0=GET, 1=SET, 2=POLL, 3=SETPOLL (0)
validate (int) – VALCKSUM (1) = Validate checksum, VALNONE (0) = ignore invalid checksum (1)
protfilter (int) – NMEA_PROTOCOL (1), UNI_PROTOCOL (2), RTCM3_PROTOCOL (4). Can be OR’d (7)
quitonerror (int) – ERR_IGNORE (0) = ignore errors, ERR_LOG (1) = log continue, ERR_RAISE (2) = (re)raise (1)
parsebitfield (bool) – 1 = parse bitfields, 0 = leave as bytes (1)
bufsize (int) – socket recv buffer size (4096)
parsing (bool) – True = parse data, False = don’t parse data (output raw only) (True)
errorhandler (object) – error handling object or function (None)

Raises:

UNIStreamError (if mode is invalid)

read() → tuple[source]

Read a single UNI message from the stream buffer and return both raw and parsed data.

‘quitonerror’ determines whether to raise, log or ignore parsing errors.

Returns:: tuple of (raw_data as bytes, parsed_data as UNIMessage)
Return type:: tuple
Raises:: Exception (if invalid or unrecognised protocol in data stream)

property datastream: object

Getter for stream.

Returns:: data stream
Return type:: object

static parse(message: bytes, msgmode: int = 0, validate: int = 1, parsebitfield: bool = True) → UNIMessage[source]

Parse binary UNI byte stream to UNIMessage object.

Parameters:

message (bytes) – binary message to parse
msgmode (int) – GET (0), SET (1), POLL (2) (0)
validate (int) – VALCKSUM (1) = Validate checksum, VALNONE (0) = ignore invalid checksum (1)
parsebitfield (bool) – 1 = parse bitfields, 0 = leave as bytes (1)

Returns:

UNIMessage object

Return type:

UNIMessage

Raises:

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

pyunigps.unitypes_core module

UNI Protocol core globals, constants, datatypes and message identifiers.

Created on 26 Jan 2026

Information sourced from public domain Unicore UM980 Interface Specifications © 2023, Unicore https://www.ardusimple.com/wp-content/uploads/2023/04/Unicore-Reference-Commands-Manual-For-N4-High-Precision-Products_V2_EN_R1.4-1.pdf

author:: semuadmin (Steve Smith)

pyunigps.unitypes_core.UNI_HDR = b'\xaaD\xb5': UNI message header

pyunigps.unitypes_core.GET = 0: GET (receive, response) message types

pyunigps.unitypes_core.SET = 1: SET (command) message types

pyunigps.unitypes_core.POLL = 2: POLL (query) message types

pyunigps.unitypes_core.SETPOLL = 3: SETPOLL (SET or POLL) message types

pyunigps.unitypes_core.VALNONE = 0: Do not validate checksum

pyunigps.unitypes_core.VALCKSUM = 1: Validate checksum

pyunigps.unitypes_core.NMEA_PROTOCOL = 1: NMEA Protocol

pyunigps.unitypes_core.UNI_PROTOCOL = 2: UNI Binary Protocol

pyunigps.unitypes_core.RTCM3_PROTOCOL = 4: RTCM3 Protocol

pyunigps.unitypes_core.UNI_ASCII_PROTOCOL = 8: UNI ASCII Protocol

pyunigps.unitypes_core.ERR_RAISE = 2: Raise error and quit

pyunigps.unitypes_core.ERR_LOG = 1: Log errors

pyunigps.unitypes_core.ERR_IGNORE = 0: Ignore errors

pyunigps.unitypes_core.BINARY = 'B': UNI binary protocol

pyunigps.unitypes_core.ASCII = 'A': UNI ASCII protocol

pyunigps.unitypes_core.ATTTYPE = {'C': <class 'str'>, 'R': <class 'float'>, 'S': <class 'int'>, 'U': <class 'int'>, 'X': <class 'bytes'>}: Permissible attribute types

pyunigps.unitypes_decodes module

unitypes_decodes.py

UNI Protocol decodes and enumerations.

Created on 26 Jan 2026

Information sourced from public domain Unicore UM980 Interface Specifications © 2023, Unicore https://www.ardusimple.com/wp-content/uploads/2023/04/Unicore-Reference-Commands-Manual-For-N4-High-Precision-Products_V2_EN_R1.4-1.pdf

author:: semuadmin (Steve Smith)

pyunigps.unitypes_decodes.DEVICE = {0: 'UNKNOWN', 1: 'UB4B0', 2: 'UM4B0', 3: 'UM480', 4: 'UM440', 5: 'UM482', 6: 'UM442', 7: 'UB482', 8: 'UT4B0', 10: 'UB362L', 11: 'UB4B0M', 12: 'UB4B0J', 13: 'UM482L', 14: 'UM4B0L', 16: 'CLAP-B', 17: 'UM982', 18: 'UM980', 19: 'UM960', 21: 'UM980A', 23: 'CLAP-C', 24: 'UM960L', 26: 'UM981', 52: 'UB9A0'}: Hardware Device Code

pyunigps.unitypes_decodes.GNSS = {0: 'GPS', 1: 'GLONASS', 2: 'SBAS', 3: 'GAL', 4: 'BDS', 5: 'QZSS', 6: 'IRNSS', 7: 'Reserved'}: GNSS Satellite System Code

pyunigps.unitypes_decodes.POSTYPE = {0: 'Invalid', 1: 'Single point', 2: 'Pseudorange differential', 4: 'Fixed', 5: 'Float', 7: 'Input a fixed position'}: Rover Position Status

pyunigps.unitypes_decodes.CALCSTATUS = {0: 'No differential data input', 1: 'Insufficient observation at the differential source', 2: 'High latency of differential data', 3: 'Active ionosphere (valid for base station mode)', 4: 'Insufficient observation at the ROVER', 5: 'RTK solution available'}: RTK Calculate Status

pyunigps.unitypes_get module

UNI Protocol output definitions.

Created on 26 Jan 2026

Information sourced from public domain Unicore UM980 Interface Specifications © 2023, Unicore https://www.ardusimple.com/wp-content/uploads/2023/04/Unicore-Reference-Commands-Manual-For-N4-High-Precision-Products_V2_EN_R1.4-1.pdf

author:: semuadmin (Steve Smith)

pyunigps.unitypes_poll module

UNI Protocol query definitions.

Created on 26 Jan 2026

Information sourced from public domain Unicore UM980 Interface Specifications © 2023, Unicore https://www.ardusimple.com/wp-content/uploads/2023/04/Unicore-Reference-Commands-Manual-For-N4-High-Precision-Products_V2_EN_R1.4-1.pdf

author:: semuadmin (Steve Smith)

pyunigps.unitypes_set module

UNI Protocol command payload definitions.

Created on 26 Jan 2026

Information sourced from public domain Unicore UM980 Interface Specifications © 2023, Unicore https://www.ardusimple.com/wp-content/uploads/2023/04/Unicore-Reference-Commands-Manual-For-N4-High-Precision-Products_V2_EN_R1.4-1.pdf

author:: semuadmin (Steve Smith)

Module contents

Created on 6 Oct 2025

author:: semuadmin (Steve Smith)
license:: BSD 3-Clause