ntripstreams

ntripstreams: NTRIP communication and RTCM 3 handling.

Re-exports the main public API: the NtripStream client/server class, the Rtcm3 message encoder/decoder, and the crc24q() and crcNmea() checksum helpers.

class ntripstreams.NtripStream[source]

Bases: object

An asyncio NTRIP client and server connection.

A single instance holds the connection to one caster and the state used while framing RTCM 3 messages. Typical client use is to call requestSourcetable() to list mountpoints, or requestNtripStream() followed by repeated getRtcmFrame() calls to read the stream. Server use publishes with requestNtripServer() and sendRtcmFrame().

getHeaderStrings(rawHeader: bytes | list) → list[source]

Decode a raw header into a list of stripped ISO-8859-1 lines.

Parameters:

rawHeader (bytes or list of bytes) – Either a single bytes blob (split on CRLF) or a list of raw header line bytes.

Returns:

The decoded header lines with trailing whitespace removed.

Return type:

list of str

async getNtripResponseHeader() → None[source]

Read and parse the caster’s HTTP response header.

Populates self.ntripResponseHeader, self.ntripStreamChunked and self.ntripResponseStatusCode.

Raises:

ConnectionError – If the connection fails while reading the response header.

async getRtcmFrame()[source]

Read the next complete, CRC-validated RTCM 3 frame from the stream.

Data is buffered until a frame preamble is found and the frame is CRC-24Q verified; on a CRC mismatch the buffer is realigned and the search continues.

Raises:

  • ConnectionError – If the connection fails while receiving data.

  • IOError – If a chunk is malformed or incomplete.

Returns:

The validated RTCM 3 frame and the Unix timestamp at which it was received.

Return type:

tuple of (bitstring.BitStream, float)

ntripResponseStatusOk() → bool[source]

Check whether the caster returned HTTP status 200.

Raises:

ConnectionError – If the status code is not 200; the writer is closed first and the response header lines are logged.

Returns:

True when the caster responded with status 200.

Return type:

bool

async openNtripConnection(casterUrl: str) → bool[source]

Open a TCP (or TLS) connection to an NTRIP caster.

Parameters:

casterUrl (str) – Caster URL and port, e.g. http[s]://caster.hostname.net:port. The https scheme opens a TLS connection.

Raises:

  • TimeoutError – If the connection attempt times out.

  • OSError – If the connection cannot be established.

Returns:

True once the connection is open and ready to write.

Return type:

bool

async requestNtripServer(casterUrl: str, mountPoint: str, user: str = None, passwd: str = None, ntripVersion: int = 2) → None[source]

Connect to a caster and send a server (upload) request header.

Parameters:

  • casterUrl (str) – Caster URL and port, e.g. http[s]://caster.hostname.net:port.

  • mountPoint (str) – Mountpoint name to publish to, without the leading /.

  • user (str, optional) – Username for basic authentication (NTRIP 2 only). The default is None.

  • passwd (str, optional) – Password / upload token. The default is None.

  • ntripVersion (int, optional) – NTRIP protocol version, 1 or 2. The default is 2.

async requestNtripStream(casterUrl: str, mountPoint: str, user: str = None, passwd: str = None) → None[source]

Connect to a caster and send a client (stream) request header.

Parameters:

  • casterUrl (str) – Caster URL and port, e.g. http[s]://caster.hostname.net:port.

  • mountPoint (str) – Mountpoint name to consume, without the leading /.

  • user (str, optional) – Username for basic authentication. The default is None.

  • passwd (str, optional) – Password for basic authentication. The default is None.

async requestSourcetable(casterUrl: str) → list[source]

Connect to a caster and return its full source table.

Parameters:

casterUrl (str) – Caster URL and port, e.g. http[s]://caster.hostname.net:port.

Raises:

ConnectionError – If the connection fails while receiving the source table.

Returns:

The source table lines, ending with ENDSOURCETABLE.

Return type:

list of str

async sendRequestHeader() → None[source]

Send the prepared request header and read the caster’s response.

Writes self.ntripRequestHeader to the caster, then reads the response header and validates the status code.

async sendRtcmFrame(rtcmFrame: BitStream) → None[source]

Send a single RTCM 3 frame to the caster.

Parameters:

rtcmFrame (bitstring.BitStream) – A complete RTCM 3 frame (preamble, payload and CRC). It is converted to bytes before being written.

setRequestServerHeader(casterUrl: str, ntripMountPoint: str, ntripUser: str = None, ntripPassword: str = None, ntripVersion: int = 2) → None[source]

Build the request header used to publish a stream (server).

The result is stored on self.ntripRequestHeader. NTRIP version 2 uses an HTTP POST with basic authentication; version 1 uses the legacy SOURCE request with the password only.

Parameters:

  • casterUrl (str) – Caster URL and port, e.g. http[s]://caster.hostname.net:port.

  • ntripMountPoint (str) – Mountpoint name, without the leading /.

  • ntripUser (str, optional) – Username for basic authentication (NTRIP 2 only). The default is None.

  • ntripPassword (str, optional) – Password / upload token. The default is None.

  • ntripVersion (int, optional) – NTRIP protocol version, 1 or 2. The default is 2.

setRequestSourceTableHeader(casterUrl: str) → None[source]

Build the request header used to fetch a caster’s source table.

The result is stored on self.ntripRequestHeader.

Parameters:

casterUrl (str) – Caster URL and port, e.g. http[s]://caster.hostname.net:port.

setRequestStreamHeader(casterUrl: str, ntripMountPoint: str, ntripUser: str = None, ntripPassword: str = None, nmeaString: str = None) → None[source]

Build the request header used to consume an NTRIP stream (client).

The result is stored on self.ntripRequestHeader.

Parameters:

  • casterUrl (str) – Caster URL and port, e.g. http[s]://caster.hostname.net:port.

  • ntripMountPoint (str) – Mountpoint name, without the leading /.

  • ntripUser (str, optional) – Username for basic authentication. The default is None.

  • ntripPassword (str, optional) – Password for basic authentication. The default is None.

  • nmeaString (str, optional) – NMEA GGA sentence sent to request a virtual reference station. The default is None.

class ntripstreams.Rtcm3[source]

Bases: object

Encode and decode RTCM 3 messages.

Provides frame-level helpers (decodeRtcmFrame(), encodeRtcmFrame()) that handle the preamble and CRC, message-level decoding of the legacy GPS/GLONASS observables (1001-1004, 1009-1012) and the Multiple Signal Messages (MSM, 1071-1127), and lookups for message descriptions, GNSS constellations and MSM signal types.

constellation(messageType: int)[source]

Return the GNSS constellation for any supported message type.

Parameters:

messageType (int) – An RTCM 3 message number.

Returns:

Constellation name for legacy GPS (1001-1004), GLONASS (1009-1012) and MSM (1071-1127) messages; "GNSS" for any other message type.

Return type:

str

decodeRtcmFrame(rtcmFrame)[source]

Decode a complete RTCM 3 frame.

Strips the 24-bit header/preamble and the trailing 24-bit CRC, then decodes the payload with decodeRtcmMessage().

Parameters:

rtcmFrame (bitstring.BitStream) – A complete, CRC-validated RTCM 3 frame.

Returns:

The message type and its decoded data; see decodeRtcmMessage() for the data layout.

Return type:

tuple of (int, list)

decodeRtcmMessage(message)[source]

Decode an RTCM 3 message payload (without preamble or CRC).

Fully decodes the legacy GPS/GLONASS observables (1001-1004, 1009-1012) and the Multiple Signal Messages (1071-1127). Other message types are recognised but not field-decoded.

Parameters:

message (bitstring.BitStream) – The message payload (frame with the 24-bit header and 24-bit CRC removed).

Returns:

(messageType, [head, satData, signalData]) where head is the list of decoded header fields (or the string "Message type not implemented"), and satData / signalData are column-wise lists of the per-satellite and per-signal fields (empty for non-observable messages).

Return type:

tuple of (int, list)

encodeRtcmFrame(messageType: int, dataDict)[source]

Encode an RTCM 3 message into a frame.

Note

Currently only message type 1029 is implemented, and the returned frame does not yet include the preamble, length and CRC wrapper.

Parameters:

  • messageType (int) – RTCM 3 message number to encode.

  • dataDict (dict) – Field values for the message; missing fields fall back to defaults.

Returns:

The encoded message.

Return type:

bitstring.BitStream

encodeRtcmMessage(messageType: int, dataDict)[source]

Encode an RTCM 3 message payload.

Note

Only message type 1029 (Unicode Text String) is implemented; other message types return None.

Parameters:

  • messageType (int) – RTCM 3 message number to encode.

  • dataDict (dict) – Field values for the message; missing fields fall back to defaults.

Returns:

The packed message payload, or None for unimplemented types.

Return type:

bitstring.BitStream or None

messageDescription(messageType: int)[source]

Return a human-readable description for an RTCM 3 message type.

Parameters:

messageType (int) – RTCM 3 message number.

Returns:

The message description, or a “currently not implemented” note for unknown message types.

Return type:

str

messageDescriptionText = {1001: 'L1-Only GPS RTK Observables', 1002: 'Extended L1-Only GPS RTK Observables', 1003: 'L1 & L2 GPS RTK Observables', 1004: 'Extended L1 & L2 GPS RTK Observables', 1005: 'Stationary RTK Reference Station ARP', 1006: 'Stationary RTK Reference Station ARP with Antenna Height', 1007: 'Antenna Descriptor', 1008: 'Antenna Descriptor & Serial Number', 1009: 'L1-Only GLONASS RTK Observables', 1010: 'Extended L1-Only GLONASS RTK Observables', 1011: 'L1 & L2 GLONASS RTK Observables', 1012: 'Extended L1 & L2 GLONASS RTK Observables', 1013: 'System Parameters', 1014: 'Network Auxiliary Station Data', 1015: 'GPS Ionospheric Correction Differences', 1016: 'GPS Geometric Correction Differences', 1017: 'GPS Combined Geometric and Ionospheric Correction Differences', 1018: 'RESERVED for Alternative Ionospheric Correction Difference Message', 1019: 'GPS Ephemerides', 1020: 'GLONASS Ephemerides', 1021: 'Helmert / Abridged Molodenski Transformation Parameters', 1022: 'Molodenski-Badekas Transformation Parameters', 1023: 'Residuals, Ellipsoidal Grid Representation', 1024: 'Residuals, Plane Grid Representation', 1025: 'Projection Parameters, Projection Types other than Lambert Conic Conformal (2 SP) and Oblique Mercator', 1026: 'Projection Parameters, Projection Type LCC2SP (Lambert Conic Conformal (2 SP))', 1027: 'Projection Parameters, Projection Type OM (Oblique Mercator)', 1028: '(Reserved for Global to Plate-Fixed Transformation)', 1029: 'Unicode Text String', 1030: 'GPS Network RTK Residual Message', 1031: 'GLONASS Network RTK Residual Message', 1032: 'Physical Reference Station Position Message', 1033: 'Receiver and Antenna Descriptors', 1034: 'GPS Network FKP Gradient', 1035: 'GLONASS Network FKP Gradient', 1037: 'GLONASS Ionospheric Correction Differences', 1038: 'GLONASS Geometric Correction Differences', 1039: 'GLONASS Combined Geometric and Ionospheric Correction Differences', 1042: 'BDS Satellite Ephemeris Data', 1044: 'QZSS Ephemerides', 1045: 'Galileo F/NAV Satellite Ephemeris Data', 1046: 'Galileo I/NAV Satellite Ephemeris Data', 1057: 'SSR GPS Orbit Correction', 1058: 'SSR GPS Clock Correction', 1059: 'SSR GPS Code Bias', 1060: 'SSR GPS Combined Orbit and Clock Corrections', 1061: 'SSR GPS URA', 1062: 'SSR GPS High Rate Clock Correction', 1063: 'SSR GLONASS Orbit Correction', 1064: 'SSR GLONASS Clock Correction', 1065: 'SSR GLONASS Code Bias', 1066: 'SSR GLONASS Combined Orbit and Clock Corrections', 1067: 'SSR GLONASS URA', 1068: 'SSR GLONASS High Rate Clock Correction', 1070: 'Reserved MSM', 1071: 'GPS MSM1', 1072: 'GPS MSM2', 1073: 'GPS MSM3', 1074: 'GPS MSM4', 1075: 'GPS MSM5', 1076: 'GPS MSM6', 1077: 'GPS MSM7', 1078: 'Reserved MSM', 1079: 'Reserved MSM', 1080: 'Reserved MSM', 1081: 'GLONASS MSM1', 1082: 'GLONASS MSM2', 1083: 'GLONASS MSM3', 1084: 'GLONASS MSM4', 1085: 'GLONASS MSM5', 1086: 'GLONASS MSM6', 1087: 'GLONASS MSM7', 1088: 'Reserved MSM', 1089: 'Reserved MSM', 1090: 'Reserved MSM', 1091: 'Galileo MSM1', 1092: 'Galileo MSM2', 1093: 'Galileo MSM3', 1094: 'Galileo MSM4', 1095: 'Galileo MSM5', 1096: 'Galileo MSM6', 1097: 'Galileo MSM7', 1098: 'Reserved MSM', 1099: 'Reserved MSM', 1100: 'Reserved MSM', 1101: 'SBAS MSM1', 1102: 'SBAS MSM2', 1103: 'SBAS MSM3', 1104: 'SBAS MSM4', 1105: 'SBAS MSM5', 1106: 'SBAS MSM6', 1107: 'SBAS MSM7', 1108: 'Reserved MSM', 1109: 'Reserved MSM', 1110: 'Reserved MSM', 1111: 'QZSS MSM1', 1112: 'QZSS MSM2', 1113: 'QZSS MSM3', 1114: 'QZSS MSM4', 1115: 'QZSS MSM5', 1116: 'QZSS MSM6', 1117: 'QZSS MSM7', 1118: 'Reserved MSM', 1119: 'Reserved MSM', 1120: 'Reserved MSM', 1121: 'BeiDou MSM1', 1122: 'BeiDou MSM2', 1123: 'BeiDou MSM3', 1124: 'BeiDou MSM4', 1125: 'BeiDou MSM5', 1126: 'BeiDou MSM6', 1127: 'BeiDou MSM7', 1128: 'Reserved MSM', 1129: 'Reserved MSM', 1130: 'Reserved MSM', 1131: 'IRNSS MSM1 (Experimental, not implemented)', 1132: 'IRNSS MSM2 (Experimental, not implemented)', 1133: 'IRNSS MSM3 (Experimental, not implemented)', 1134: 'IRNSS MSM4 (Experimental, not implemented)', 1135: 'IRNSS MSM5 (Experimental, not implemented)', 1136: 'IRNSS MSM6 (Experimental, not implemented)', 1137: 'IRNSS MSM7 (Experimental, not implemented)', 1138: 'Reserved MSM (Experimental)', 1139: 'Reserved MSM (Experimental)', 1140: 'Reserved MSM (Experimental)', 1230: 'GLONASS L1 and L2 Code-Phase Biases'}
mjd(unixTimestamp)[source]

Convert a Unix timestamp to a Modified Julian Date (integer day).

Parameters:

unixTimestamp (float) – Seconds since the Unix epoch.

Returns:

The Modified Julian Date (whole days).

Return type:

int

msmConstellation(messageType: int)[source]

Return the GNSS constellation for an MSM message type.

Parameters:

messageType (int) – An MSM message number in the range 1071-1127.

Returns:

Constellation name, e.g. "GPS", "GLONASS", "GALILEO", "SBAS", "QZSS" or "BEIDOU".

Return type:

str

msmSignalTypes(messageType: int, msmSignals)[source]

Resolve the signal-type codes selected by an MSM signal mask.

Parameters:

  • messageType (int) – An MSM message number in the range 1071-1127.

  • msmSignals (str) – The 32-bit GNSS signal mask as a string of "0"/"1" characters (the gnssSignalMask header field).

Returns:

RINEX-style signal codes (e.g. "L1C", "L2W") for each bit set in the mask, in mask order.

Return type:

list of str

ntripstreams.crc24q(data)[source]

Calculate the Qualcomm 24-bit CRC (CRC-24Q) used by RTCM 3.

Parameters:

data (bitstring.BitStream) – The data to check-sum (an RTCM 3 frame excluding its 24-bit CRC). Must be a whole number of bytes.

Returns:

The 24-bit CRC remainder (checksum).

Return type:

int

ntripstreams.crcNmea(data)[source]

Calculate the NMEA 0183 checksum (XOR of all data bytes).

Parameters:

data (bitstring.BitStream) – The bytes between $ and * of an NMEA sentence. Must be a whole number of bytes.

Returns:

The 8-bit checksum, matching the two hex digits after *.

Return type:

bitstring.BitStream