API Reference

adafruit_ublox

CircuitPython Library for interfacing with u-blox GPS Modules

  • Author(s): Limor Fried/Ladyada

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_ublox.GPS_UBloxI2C(ddc: UBloxDDC, *, debug: bool = False)

GPS NMEA parsing for u-blox modules over I2C (DDC).

Subclasses adafruit_gps.GPS to provide NMEA parsing, using a UBloxDDC instance for I2C transport.

Parameters:

  • ddc (UBloxDDC) – DDC transport instance

  • debug (bool) – Enable GPS debug output, default False

class adafruit_ublox.UBloxDDC(i2c_bus: I2C, *, address: int = 0x42, timeout: float = 5.0)

I2C (DDC) transport for u-blox GPS modules.

Parameters:

  • i2c_bus (I2C) – The I2C bus connected to the module

  • address (int) – I2C address, default 0x42

  • timeout (float) – Timeout in seconds for readline, default 5.0

property in_waiting: int

Number of bytes available to read from the module.

read(num_bytes: int = 1) → bytearray | None

Read up to num_bytes from the DDC data stream.

Parameters:

num_bytes (int) – Maximum number of bytes to read

Returns:

Data read, or None if no data available

Return type:

bytearray or None

readline() → bytearray | None

Read a newline-terminated line from the DDC data stream.

Buffers bytes internally until a newline (0x0A) is found or timeout.

Returns:

Newline-terminated bytearray, or None if timeout

Return type:

bytearray or None

write(buffer: bytes) → None

Write raw bytes to the module over I2C.

Parameters:

buffer (bytes) – Data to write

class adafruit_ublox.UBloxUBX(stream, *, debug: bool = False)

UBX binary protocol engine for u-blox GPS modules.

Parameters:

  • stream – Stream-like transport (UBloxDDC, busio.UART, or any object with read(), write(), and in_waiting)

  • debug (bool) – Enable debug output, default False

property callback: Callable | None

Get/set callback for received UBX messages.

Callback signature: callback(msg_class, msg_id, payload) where payload is a bytearray.

check_messages() → bool

Process available bytes through the UBX parser.

Reads bytes from the stream and feeds them through the state machine. Triggers the callback when a complete valid message is received.

Returns:

True if a complete message was received

Return type:

bool

send(msg_class: int, msg_id: int, payload: bytes = b'') → bool

Send a UBX message.

Builds the complete frame with sync chars, header, payload, and checksum.

Parameters:

  • msg_class (int) – UBX message class

  • msg_id (int) – UBX message ID

  • payload (bytes) – Message payload, default empty

Returns:

True if message was sent

Return type:

bool

send_with_ack(msg_class: int, msg_id: int, payload: bytes = b'', timeout: float = 0.5)

Send a UBX message and wait for ACK/NAK.

Parameters:

  • msg_class (int) – UBX message class

  • msg_id (int) – UBX message ID

  • payload (bytes) – Message payload

  • timeout (float) – Timeout in seconds, default 0.5

set_nmea_output(enabled: set | None = None, *, timeout: float = 0.5)

Enable/disable individual NMEA sentences on the current port.

Parameters:

  • enabled (set) – Set of NMEA message IDs to enable (e.g. {NMEA_GGA, NMEA_RMC}). All others are disabled. Defaults to {NMEA_GGA, NMEA_RMC} if None.

  • timeout (float) – ACK timeout in seconds per message

set_ubx_only(port_id: int = UBX_PORT_DDC, timeout: float = 0.5)

Configure a port to use UBX protocol only (disable NMEA).

Parameters:

  • port_id (int) – Port to configure, default UBX_PORT_DDC

  • timeout (float) – ACK timeout in seconds

set_update_rate(rate_hz: int = 1, timeout: float = 0.5)

Set navigation measurement/update rate.

Parameters:

  • rate_hz (int) – Update rate in Hz (1, 2, 5, or 10)

  • timeout (float) – ACK timeout in seconds