pyqgc package

Submodules

pyqgc.exceptions module

QGC Custom Exception Types.

Created on 6 Oct 2025

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

exception pyqgc.exceptions.ParameterError[source]

Bases: Exception

Parameter Error Class.

exception pyqgc.exceptions.GNSSStreamError[source]

Bases: Exception

Generic Stream Error Class.

exception pyqgc.exceptions.QGCParseError[source]

Bases: Exception

QGC Parsing error.

exception pyqgc.exceptions.QGCStreamError[source]

Bases: Exception

QGC Streaming error.

exception pyqgc.exceptions.QGCMessageError[source]

Bases: Exception

QGC Undefined message class/id. Essentially a prompt to add missing payload types to QGC_PAYLOADS.

exception pyqgc.exceptions.QGCTypeError[source]

Bases: Exception

QGC Undefined payload attribute type. Essentially a prompt to fix incorrect payload definitions to QGC_PAYLOADS.

pyqgc.qgchelpers module

Collection of QGC helper methods which can be used outside the QGCMessage or QGCReader classes.

Created on 6 Oct 2025

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

pyqgc.qgchelpers.att2idx(att: str) → object[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 or tuple for nested group

pyqgc.qgchelpers.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

pyqgc.qgchelpers.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

pyqgc.qgchelpers.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

pyqgc.qgchelpers.bytes2val(valb: bytes, att: str) → object[source]

Convert bytes to value for given QGC 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:

object

Raises:

QGCTypeError

pyqgc.qgchelpers.calc_checksum(content: bytes) → int[source]

Calculate checksum.

Parameters:: content (bytes) – message content, excluding header and checksum bytes
Returns:: return code
Return type:: int

pyqgc.qgchelpers.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

pyqgc.qgchelpers.get_bits(bitfield: bytes, bitmask: int) → int[source]

Get integer value of specified (masked) bit(s) in a QGC 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

pyqgc.qgchelpers.getinputmode(data: bytes) → int[source]

Return input message mode (SET or POLL).

Parameters:: data (bytes) – raw QGC input message
Returns:: message mode (1 = SET, 2 = POLL)
Return type:: int

pyqgc.qgchelpers.hextable(raw: bytes, cols: int = 8) → str[source]

Formats raw (binary) message in tabular hexadecimal format e.g.

000: 2447 4e47 5341 2c41 2c33 2c33 342c 3233 | b’$GNGSA,A,3,34,23’ |

Parameters:

raw (bytes) – raw (binary) data
cols (int) – number of columns in hex table (8)

Returns:

table of hex data

Return type:

str

pyqgc.qgchelpers.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

pyqgc.qgchelpers.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

pyqgc.qgchelpers.nomval(att: str) → object[source]

Get nominal value for given QGC attribute type.

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

pyqgc.qgchelpers.val2bytes(val, att: str) → bytes[source]

Convert value to bytes for given QGC attribute type.

Parameters:

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

Returns:

attribute value as bytes

Return type:

bytes

Raises:

QGCTypeError

pyqgc.qgchelpers.val2signmag(val: int, att: str) → int[source]

Convert signed integer to sign magnitude binary representation.

High-order bit represents sign (0 +ve, 1 -ve).

Parameters:

val (int) – value
att (str) – attribute type e.g. “U024”

Returns:

sign magnitude representation of value

Return type:

int

pyqgc.qgchelpers.val2twoscomp(val: int, att: str) → int[source]

Convert signed integer to two’s complement binary representation.

Parameters:

val (int) – value
att (str) – attribute type e.g. “U024”

Returns:

two’s complement representation of value

Return type:

int

pyqgc.qgcmessage module

QGCmessage.py

Main QGC Message Protocol Class.

Created on 26 Sep 2020

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

class pyqgc.qgcmessage.QGCMessage(msggrp: bytes, msgid: bytes, msgmode: int = 0, parsebitfield: bool = True, **kwargs)[source]

Bases: object

QGC Message Class.

__init__(msggrp: bytes, msgid: bytes, msgmode: int = 0, parsebitfield: bool = True, **kwargs)[source]

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.

Parameters:

msggrp (object) – message group
msgID (object) – message ID
msgmode (int) – message mode (0=GET, 1=SET, 2=POLL)
parsebitfield (bool) – parse bitfields (‘X’ type attributes) Y/N
kwargs – optional payload keyword arguments

Raises:

QGCMessageError

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 QGC-NOMINAL and the term ‘NOMINAL’ is appended to the identity.

Returns:: message identity e.g. ‘RAW-HASE6’
Return type:: str

property msg_grp: bytes

Message group getter.

Returns:: message class as bytes
Return type:: bytes

property msg_id: bytes

Message id getter.

Returns:: message id as bytes
Return type:: bytes

property length: int

Payload length getter.

Returns:: payload length as integer
Return type:: int

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

pyqgc.qgcreader module

QGCReader class.

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

QGC message bit format (little-endian):

sync	msggrp	msgnum	length	payload	cksum
0x5147	8 bits	8 bits	16 bits	variable	16 bits
6 bytes

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

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

Created on 6 Oct 2025

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

class pyqgc.qgcreader.QGCReader(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

QGCReader 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), QGC_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:

QGCStreamError (if mode is invalid)

read() → tuple[source]

Read a single QGC 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 QGCMessage)
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) → object[source]

Parse QGC byte stream to QGCMessage 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:

QGCMessage object

Return type:

QGCMessage

Raises:

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

pyqgc.qgctypes_core module

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

Created on 6 Oct 2025

author:: semuadmin (Steve Smith)

pyqgc.qgctypes_core.QGC_HDR = b'QG': QGC message header

pyqgc.qgctypes_core.GET = 0: GET (receive, response) message types

pyqgc.qgctypes_core.SET = 1: SET (command) message types

pyqgc.qgctypes_core.POLL = 2: POLL (query) message types

pyqgc.qgctypes_core.SETPOLL = 3: SETPOLL (SET or POLL) message types

pyqgc.qgctypes_core.VALNONE = 0: Do not validate checksum

pyqgc.qgctypes_core.VALCKSUM = 1: Validate checksum

pyqgc.qgctypes_core.NMEA_PROTOCOL = 1: NMEA Protocol

pyqgc.qgctypes_core.QGC_PROTOCOL = 2: QGC Protocol

pyqgc.qgctypes_core.RTCM3_PROTOCOL = 4: RTCM3 Protocol

pyqgc.qgctypes_core.ERR_RAISE = 2: Raise error and quit

pyqgc.qgctypes_core.ERR_LOG = 1: Log errors

pyqgc.qgctypes_core.ERR_IGNORE = 0: Ignore errors

pyqgc.qgctypes_core.ATTTYPE = {'R': <class 'float'>, 'S': <class 'int'>, 'U': <class 'int'>, 'X': <class 'bytes'>}: Permissible attribute types

pyqgc.qgctypes_get module

QGC Protocol output payload definitions.

Created on 6 Oct 2025

author:: semuadmin (Steve Smith)

pyqgc.qgctypes_poll module

QGC Protocol poll payload definitions.

Created on 6 Oct 2025

author:: semuadmin (Steve Smith)

pyqgc.qgctypes_set module

QGC Protocol command payload definitions.

Created on 6 Oct 2025

author:: semuadmin (Steve Smith)

Module contents

Created on 6 Oct 2025

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