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

Bases: Exception

Parameter Error Class.

exception pyunigps.exceptions.GNSSStreamError

Bases: Exception

Generic Stream Error Class.

exception pyunigps.exceptions.UNIParseError

Bases: Exception

UNI Parsing error.

exception pyunigps.exceptions.UNIStreamError

Bases: Exception

UNI Streaming error.

exception pyunigps.exceptions.UNIMessageError

Bases: Exception

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

exception pyunigps.exceptions.UNITypeError

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.

pyunigps also inherits pynmeagps helper methods.

Created on 6 Oct 2025

author:

semuadmin (Steve Smith)

copyright:

semuadmin © 2020

license:

BSD 3-Clause

pyunigps.unihelpers.attsiz(att: str) → int

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

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, adef: str) → Any

Convert bytes to value for given UNI attribute type.

Parameters:

• valb (bytes) – attribute value in byte format e.g. b’\x19\x00\x00\x00’

• adef (str) – attribute definition e.g. ‘U004’

Returns:

attribute value as int, float, str or bytes

Return type:

Any

Raises:

UNITypeError

pyunigps.unihelpers.calc_crc(message: bytes) → bytes

Perform CRC32 cyclic redundancy check.

Parameters:

message (bytes) – message

Returns:

CRC as bytes

Return type:

bytes

pyunigps.unihelpers.escapeall(val: bytes) → str

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.msgname2id(msgname: str) → int | None

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, leapsec: int = 0, delay: int = 0) → bytes

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

• leapsec (int) – leap second

• delay (int) – delay in ms

Returns:

header as bytes

Return type:

bytes

pyunigps.unihelpers.header2vals(header: bytes) → tuple

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

Validate message checksum.

Parameters:

message (bytes) – message including header and checksum bytes

Returns:

checksum valid flag

Return type:

bool

pyunigps.unihelpers.nomval(adef: str) → Any

Get nominal value for given UNI attribute type.

Parameters:

adef (str) – attribute definition e.g. ‘U004’

Returns:

attribute value as int, float, str or bytes

Return type:

Any

Raises:

UNITypeError

pyunigps.unihelpers.val2bytes(val: Any, adef: str) → bytes

Convert value to bytes for given UNI attribute type.

Parameters:

• val (Any) – attribute value e.g. 25

• adef (str) – attribute definition 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)

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)

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.

If the wno or tow arguments are None, wno, tow and leapsecond will default to the current datetime and leapsecond offset.

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

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

pyunigps.unireader module

UNIReader class.

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

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

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

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 ASCII text:

$command,SATSINFOB COM1 1,response: OK*46

$command,SATSXXXXB COM1 1,response: PARSING FAILD NO MATCHING FUNC SATSXXXXB*01

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: LambdaType | None = None)

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: LambdaType | None = None)

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 (FunctionType | NoneType) – error handling object or function (None)

Raises:

UNIStreamError (if mode is invalid)

read() → tuple[bytes | None, UNIMessage | NMEAMessage | RTCMMessage | None]

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[bytes | NoneType, UNIMessage | NMEAMessage | RTCMMessage | NoneType]

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

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 Reference Commands R1.13 © Dec 2025 Unicore https://en.unicore.com/uploads/file/Unicore%20Reference%20Commands%20Manual%20For%20N4%20High%20Precision%20Products_V2_EN_R1.13.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.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 Reference Commands R1.13 © Dec 2025 Unicore https://en.unicore.com/uploads/file/Unicore%20Reference%20Commands%20Manual%20For%20N4%20High%20Precision%20Products_V2_EN_R1.13.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', 31: 'UM981S', 40: 'UMD982', 41: 'UMD981', 42: 'UMD981S', 43: 'UM981C', 52: 'UB9A0', 53: 'UBD9A0', 62: 'UMD960', 63: 'UMD980', 64: 'UM980C', 65: 'UM982C'}

Hardware Device Code

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

SATSINFO GNSS Satellite System Code

pyunigps.unitypes_decodes.GNSSSAT = {0: 'GPS', 1: 'GLONASS', 2: 'SBAS', 5: 'GAL', 6: 'BDS', 7: 'QZSS', 9: 'IRNSS'}

SATELLITE GNSS Satellite System Code

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_decodes.POSTYPE = {0: 'NONE', 1: 'FIXEDPOS', 2: 'FIXEDHEIGHT', 8: 'DOPPLER_VELOCITY', 16: 'SINGLE', 17: 'PSRDIFF', 18: 'SBAS', 32: 'L1_FLOAT L1', 33: 'IONOFREE_FLOAT', 34: 'NARROW_FLOAT', 48: 'L1_INT', 49: 'WIDE_INT', 50: 'NARROW_INT', 52: 'INS', 53: 'INS_PSRSP', 54: 'INS_PSRDIFF', 55: 'INS_RTKFLOAT', 56: 'INS_RTKFIXED', 68: 'PPP_CONVERGING', 69: 'PPP'}

Position/Velocity Type

pyunigps.unitypes_decodes.SOLSTATUS = {0: 'SOL_COMPUTED', 1: 'INSUFFICIENT_OBS', 2: 'NO_CONVERGENCE', 4: 'COV_TRACE'}

Solution Status

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

Rover Position Status

pyunigps.unitypes_decodes.PSRSTD = {0: 0.05, 1: 0.075, 2: 0.113, 3: 0.169, 4: 0.253, 5: 0.38, 6: 0.57, 7: 0.854, 8: 1.281, 9: 2.375, 10: 4.75, 11: 9.5, 12: 19.0, 13: 38.0, 14: 76.0, 15: 152.0}

OBSVMCMP Pseudorange Standard Deviation Lookup

pyunigps.unitypes_decodes.PSRIONOCORR = {0: 'Unknown', 1: 'Klobuchareph', 2: 'SBASionogrid', 3: 'Multifreq', 4: 'Psrdiff'}

EXTSOLSTAT Pseudorange Ionospheric Correction

pyunigps.unitypes_decodes.BD3EPH_FREQTYPE = {0: 'B1C', 1: 'B2a', 2: 'B2b'}

BD3EPH Frequency Type

pyunigps.unitypes_decodes.GLOEPH_SATTYPE = {0: 'GLO_SAT', 1: 'GLO_SAT_M', 2: 'GLO_SAT_K'}

GLOEPH Satellite Type

pyunigps.unitypes_get module

UNI Protocol output definitions.

Created on 26 Jan 2026

Information sourced from public domain Unicore Reference Commands R1.13 © Dec 2025 Unicore https://en.unicore.com/uploads/file/Unicore%20Reference%20Commands%20Manual%20For%20N4%20High%20Precision%20Products_V2_EN_R1.13.pdf

author:

semuadmin (Steve Smith)

pyunigps.unitypes_poll module

UNI Protocol query definitions.

Created on 26 Jan 2026

author:

semuadmin (Steve Smith)

pyunigps.unitypes_set module

UNI Protocol command payload definitions.

Created on 26 Jan 2026

author:

semuadmin (Steve Smith)

Module contents

Created on 6 Oct 2025

author:

semuadmin (Steve Smith)

copyright:

semuadmin © 2020

license:

BSD 3-Clause