Skip to main content

Porting GBX to other Applications

Phase 4 of 6Advanced tutorials

Learn the basics of parsing GBX output streams for use in other applications.

Overview​

A common use case of PpRx output is to provide GNSS measurements and full PNT solutions to external applications. This is typically accomplished by streaming the GBX output to a parsing application through a POSIX pipe.

This tutorial provides a guide for running the example gbx_parser.py on a GBX stream produced by PpRx in either the GUI or CLI. The gbx_parser.py example comes pre-packaged within the locus-lock folder.

GUI Instructions​

Set up PpRx to output a GBX stream to a named pipe:

  1. Configure PpRx .opt and .config files within the GUI.
  2. Configure PpRx for Post-Processing mode and enable Simulate Realtime.
  3. Select a pre-recorded .bin file as the data input.
  4. Configure PpRx to output to a Named Pipe (for example gbx_pipe) in the configured output folder.
  5. In a terminal window, navigate to the output folder and create the named pipe with mkfifo gbx_pipe.

Set up gbx_parser.py in a terminal window:

  1. cd <locus-lock directory>/utilities/gbx-toolbox
  2. Build the python virtual environment with setup_venv.sh
  3. Source the virtual environment with source venv/bin/activate
  4. Run the parser with python3 gbx_parser.py --verbose --pipe_path '<output-folder-path>/gbx_pipe' --output_path '<output-folder-path>/parser_output.gbx'
note

The --output_path argument sets the file path to which parsed data is logged.

note

The parser will wait until data is published to the pipe.

To run PpRx and verify outputs:

  1. In the GUI, press the Run PpRx button.
  2. In the terminal window running gbx_parser.py, observe the parsed message contents printed to the terminal.

CLI Instructions​

Set up PpRx for CLI use:

  1. Create PpRx .opt and .config files (for example example.opt and example.config) for post-processing a pre-recorded .bin dataset.
  2. Create a POSIX pipe with mkfifo gbx_pipe.
  3. Ensure PpRx is configured to write GBX data to the POSIX pipe with the .opt file argument -o gbx_pipe.

Set up gbx_parser.py in a terminal window:

  1. cd <locus-lock directory>/utilities/gbx-toolbox
  2. Build the python virtual environment with setup_venv.sh
  3. Source the virtual environment with source venv/bin/activate
  4. Run the parser with python3 gbx_parser.py --verbose --pipe_path '<path-to-gbx_pipe>' --output_path '<output-path-to-parser_output.gbx>'

To run PpRx from the CLI and verify outputs:

  1. In a terminal window, run PpRx with pprx -f example.opt
  2. In the terminal window running gbx_parser.py, observe the parsed message contents printed to the terminal.

Streaming Over UDP​

PpRx does not have a native UDP output option. To reach a parsing application over the network, keep PpRx writing to a local named pipe as above, then use netcat to forward that pipe's contents to a UDP port.

Create the named pipe and point PpRx at it as described in the CLI or GUI instructions above (for example -o gbx_pipe), then in a separate terminal window, forward the pipe to the destination host and port:

nc -u <hostname-or-ip> <port> < gbx_pipe

This works for keeping PpRx and the parsing application on the same host too: point netcat at 127.0.0.1 and a listening application bound to the same port.

On the receiving end, any application that can bind a UDP listener on the configured port can consume the stream. This includes gbx_parser.py, though it expects a file or named pipe path by default. Using gbx_parser.py with a UDP source as-is requires a small wrapper that binds a UDP socket and writes received data to a named pipe, or feeds it directly into a parser.

Expected Result​

If run with gbx_parser.py --verbose, the parser will print parsed GBX message data while PpRx is running.

Additional Reading​

gbx_parser.py is an example. For reduced overhead in high-performance applications, optimized parsing applications are recommended. See GBX Protocol Description for useful information when creating a GBX parsing application.