Skip to main content

RTCM3 protocol parser

Project description

pyrtcm

Current Status | Installation | Reading | Parsing | Generating | Serializing | Examples | Extensibility | Command Line Utility | Graphical Client | Author & License

pyrtcm is an original Python 3 parser for the RTCM3 © GPS/GNSS protocol. RTCM3 is a proprietary GPS/GNSS differential correction or DGPS protocol published by the Radio Technical Commission for Maritime Services.

RTCM STANDARD 10403.n DIFFERENTIAL GNSS (GLOBAL NAVIGATION SATELLITE SYSTEMS) SERVICES – VERSION 3.

The pyrtcm homepage is located at https://github.com/semuconsulting/pyrtcm.

This is an independent project and we have no affiliation whatsoever with the Radio Technical Commission for Maritime Services.

FYI There are companion libraries which handle standard NMEA 0183 © and UBX © (u-blox) GNSS/GPS messages:

Current Status

Status Release Build Codecov Release Date Last Commit Contributors Open Issues

Parses RTCM3 messages into their constituent data fields - DF002, DF003, etc. Refer to the RTCM_MSGIDS dictionary in rtcmtypes_core.py for a list of message types currently implemented. Additional message types can be readily added - see Extensibility.

Sphinx API Documentation in HTML format is available at https://www.semuconsulting.com/pyrtcm/

Contributions welcome - please refer to CONTRIBUTING.MD.

Bug reports and Feature requests - please use the templates provided. For general queries and advice, post a message to one of the pyrtcm Discussions channels.


Installation

Python version PyPI version PyPI downloads

pyrtcm is compatible with Python 3.9 - 3.13 and has no third-party library dependencies.

In the following, python3 & pip refer to the Python 3 executables. You may need to substitute python for python3, depending on your particular environment (on Windows it's generally python).

The recommended way to install the latest version of pyrtcm is with pip:

python3 -m pip install --upgrade pyrtcm

If required, pyrtcm can also be installed into a virtual environment, e.g.:

python3 -m pip install --user --upgrade virtualenv
python3 -m virtualenv env
source env/bin/activate (or env\Scripts\activate on Windows)
python3 -m pip install --upgrade pyrtcm
...
deactivate

For Conda users, pyrtcm is also available from conda-forge:

Anaconda-Server Badge Anaconda-Server Badge

conda install -c conda-forge pyrtcm

Reading (Streaming)

class pyrtcm.rtcmreader.RTCMReader(stream, **kwargs)

You can create a RTCMReader object by calling the constructor with an active stream object. The stream object can be any data stream which supports a read(n) -> bytes method (e.g. File or Serial, with or without a buffer wrapper). pyrtcm implements an internal SocketStream class to allow sockets to be read in the same way as other streams (see example below).

Individual RTCM messages can then be read using the RTCMReader.read() function, which returns both the raw binary data (as bytes) and the parsed data (as a RTCMMessage, via the parse() method). The function is thread-safe in so far as the incoming data stream object is thread-safe. RTCMReader also implements an iterator.

Example - Serial input:

from serial import Serial
from pyrtcm import RTCMReader
with Serial('/dev/tty.usbmodem14101', 9600, timeout=3) as stream:
  rtr = RTCMReader(stream)
  raw_data, parsed_data = rtr.read()
  if parsed_data is not None:
    print(parsed_data)
"<RTCM(1077, DF002=1077, DF003=0, DF004=204137001, DF393=1, DF409=0, DF001_7=0, ..., DF404_15=-9556, DF404_16=-2148, DF404_17=-2174)>",     

Example - File input (using iterator).

from pyrtcm import RTCMReader
with open('rtcmdata.log', 'rb') as stream:
  rtr = RTCMReader(stream)
  for raw_data, parsed_data in rtr:
    print(parsed_data)

Example - Socket input (using iterator):

import socket
from pyrtcm import RTCMReader
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as stream:
  stream.connect(("localhost", 50007))
  rtr = RTCMReader(stream)
  for raw_data, parsed_data in rtr:
    print(parsed_data)

Parsing

You can parse individual RTCM messages using the static RTCMReader.parse(data) function, which takes a bytes array containing a binary RTCM message and returns a RTCMMessage object.

NB: Once instantiated, an RTCMMessage object is immutable.

Example:

from pyrtcm import RTCMReader
msg = RTCMReader.parse(b"\xd3\x00\x13>\xd0\x00\x03\x8aX\xd9I<\x87/4\x10\x9d\x07\xd6\xafH Z\xd7\xf7")
print(msg)
<RTCM(1005, DF002=1005, DF003=0, DF021=0, DF022=1, DF023=1, DF024=1, DF141=0, DF025=4444030.8028, DF142=1, DF001_1=0, DF026=3085671.2349, DF364=0, DF027=3366658.256)>

The RTCMMessage object exposes different public attributes depending on its message type or 'identity'. Attributes are defined as data fields (DF002, DF003, etc.) e.g. the 1097 multiple signal message (MSM) contains the following data fields:

print(msg)
print(msg.identity)
print(msg.DF248)
print(msg.DF404_07)
"<RTCM(1097, DF002=1097, DF003=0, DF248=204137001, DF393=1, DF409=0, DF001_7=0, DF411=0, DF412=0, DF417=0, DF418=0, DF394=216181732825628672, NSat=5, DF395=1073872896, NSig=2, DF396=1023, NCell=10, PRN_01=007, PRN_02=008, PRN_03=021, PRN_04=027, ..., DF404_07=5534, DF404_08=5545, DF404_09=-7726, DF404_10=-7733)>",             
'1097'
204137001
5534

Attributes within repeating groups are parsed with a two-digit suffix (DF419_01, DF419_02, etc. See example below for an illustration of how to iterate through grouped attributes).

Helper methods are available to interpret the individual datafields:

from pyrtcm import RTCM_DATA_FIELDS, datadesc
dfname = "DF012"
print(RTCM_DATA_FIELDS[dfname])
print(datadesc(dfname))
(INT20, 0.0001, "GPS L1 PhaseRange - L1 Pseudorange")
'GPS L1 PhaseRange - L1 Pseudorange'

The payload attribute always contains the raw payload as bytes.

Iterating Through Group Attributes

To iterate through a group of one or more repeating attributes in a given RTCMMessage object, the following construct can be used (in this illustration, repeating attributes CELLPRN, CELLSIG, DF405, DF406, DF407, DF408, DF420 and DF404 are extracted from an MSM 1077 message msg and collated in the array msmarray):

msmarray = []
for i in range(msg.NCell): # msg = MSM 1077, number of cells = NCell
  vals = []
  for attr in ("CELLPRN", "CELLSIG", "DF405", "DF406", "DF407", "DF408", "DF420", "DF404"):
    val = getattr(msg, f"{attr}_{i+1:02d}")
    vals.append(val)
  msmarray.append(vals)
print(msmarray)
[['005', '1C', 0.00014309026300907135, 0.00014193402603268623, 341, 45.0, 0, -0.9231], ..., ['030', '2L', -0.00030865520238876343, -0.00030898721888661385, 341, 41.0, 0, -0.2174]]

The following dedicated helper methods are available to parse selected RTCM3 message types into a series of iterable data arrays:

  • parse_msm - for MSM message types (e.g. 1077, 1125, etc.).
  • parse_4076_201 - for 4076_201 SSR (harmonic coefficients) message types.

Generating

class pyrtcm.rtcmmessage.RTCMMessage(**kwargs)

You can create an RTCMMessage object by calling the constructor with the following keyword arguments:

  1. payload as bytes

Example:

from pyrtcm import RTCMMessage
msg = RTCMMessage(payload=b">\xd0\x00\x03\x8aX\xd9I<\x87/4\x10\x9d\x07\xd6\xafH ")
print(msg)
<RTCM(1005, DF002=1005, DF003=0, DF021=0, DF022=1, DF023=1, DF024=1, DF141=0, DF025=4444030.8028, DF142=1, DF001_1=0, DF026=3085671.2349, DF364=0, DF027=3366658.256)>

Serializing

The RTCMMessage class implements a serialize() method to convert a RTCMMessage object to a bytes array suitable for writing to an output stream.

e.g. to create and send a 1005 message type:

from serial import Serial
from pyrtcm import RTCMMessage
serialOut = Serial('COM7', 38400, timeout=5)
msg = RTCMMessage(payload=b">\xd0\x00\x03\x8aX\xd9I<\x87/4\x10\x9d\x07\xd6\xafH ")
print(msg)
output = msg.serialize()
print(output)
serialOut.write(output)
<RTCM(1005, DF002=1005, DF003=0, DF021=0, DF022=1, DF023=1, DF024=1, DF141=0, DF025=4444030.8028, DF142=1, DF001_1=0, DF026=3085671.2349, DF364=0, DF027=3366658.256)>
b'\xd3\x00\x13>\xd0\x00\x03\x8aX\xd9I<\x87/4\x10\x9d\x07\xd6\xafH Z\xd7\xf7'

Examples

The following examples are available in the /examples folder:

  1. rtcmpoller.py - illustrates how to read and display RTCM messages 'concurrently' with other tasks using threads and queues. This represents a useful generic pattern for many end user applications.
  2. rtcmfile.py - illustrates how to stream RTCM data from binary log file.
  3. rtcmsocket.py - illustrates how to implement a TCP Socket reader for RTCM messages using RTCMReader iterator functionality.
  4. msmparser.py - illustrates how to parse RTCM3 MSM (multiple signal messages) into a series of iterable data arrays keyed on satellite PRN and signal ID.
  5. rtcm_ntrip_client.py - illustrates a simple NTRIP client using pyrtcm to parse the RTCM3 output.

Extensibility

The RTCM protocol is principally defined in the modules rtcmtypes_core.py and rtcmtypes_get.py as a series of dictionaries. RTCM uses a series of pre-defined data fields ("DF002", DF003" etc.), each of which has a designated data type (UINT32, etc.). Message payload definitions must conform to the following rules:

1. datafield names must be unique within each message class
2. datafield types must be one of the valid data fields ("DF026", "DF059", etc.)
3. repeating or bitfield groups must be defined as a tuple ('numr', {dict}), where:
   'numr' is either:
     a. an integer representing a fixed number of repeats e.g. 32
     b. a string representing the name of a preceding attribute containing the number of repeats e.g. 'DF029'
   {dict} is the nested dictionary of repeating items or bitfield group

Repeating attribute names are parsed with a two-digit suffix ("DF030_01", "DF030_02", etc.). Nested repeating groups are supported.


Command Line Utility

A command line utility gnssdump is available via the pygnssutils package. This is capable of reading and parsing NMEA, UBX and RTCM3 data from a variety of input sources (e.g. serial, socket and file) and outputting to a variety of media in a variety of formats. See https://github.com/semuconsulting/pygnssutils for further details.

To install pygnssutils:

python3 -m pip install --upgrade pygnssutils

For help with the gnssdump utility, type:

gnssdump -h

Graphical Client

A python/tkinter graphical GPS client which supports NMEA, UBX, RTCM3, NTRIP and SPARTN protocols is available at:

https://github.com/semuconsulting/PyGPSClient


Author & License Information

semuadmin@semuconsulting.com

License

pyrtcm is maintained entirely by unpaid volunteers. It receives no funding from advertising or corporate sponsorship. If you find the utility useful, please consider sponsoring the project with the price of a coffee...

Sponsor

Project details


Release history Release notifications | RSS feed

This version

1.1.4

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyrtcm-1.1.4.tar.gz (86.4 kB view details)

Uploaded Source

Built Distribution

pyrtcm-1.1.4-py3-none-any.whl (43.6 kB view details)

Uploaded Python 3

File details

Details for the file pyrtcm-1.1.4.tar.gz.

File metadata

  • Download URL: pyrtcm-1.1.4.tar.gz
  • Upload date:
  • Size: 86.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.13.1

File hashes

Hashes for pyrtcm-1.1.4.tar.gz
Algorithm Hash digest
SHA256 a1932edf36f6f57edaef96b4022d957b251334252c0576caa01a1370ffeaa32c
MD5 21b904e7d5c0b0ea3c40fc1635525926
BLAKE2b-256 c2324c3d59df5d3ef30ef76713dcc47a23ac7c0124b287888b08f15ac078e509

See more details on using hashes here.

File details

Details for the file pyrtcm-1.1.4-py3-none-any.whl.

File metadata

  • Download URL: pyrtcm-1.1.4-py3-none-any.whl
  • Upload date:
  • Size: 43.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.13.1

File hashes

Hashes for pyrtcm-1.1.4-py3-none-any.whl
Algorithm Hash digest
SHA256 37a36a500c5f8902b976d04c73756de35f578aceb2aa079d9bfeb418422ca4b7
MD5 d4a4060bbb4e2595863cfe0e2e33dc33
BLAKE2b-256 424091208da01162c7ce4cf2307156f887466924992248d484e2109c9547244c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page