The Meinberg Binary Protocol

External Meinberg devices usually send an ASCII time string in periodic intervals via a serial port.

However, configuration and extended status information is exchanged using a binary protocol, which is very flexible but also quite complex. Usually, the binary protocol is only supported via the first serial port of a Meinberg device, e.g. COM0.

Though the protocol was originally designed to work via a serial connection, it was extended to also support connection via a proprietary network port, or via USB, with devices that support this.

The protocol is also used by configuration software like the Meinberg Device Manager or the older gpsmon32 software.

Please note that the Meinberg API for bus-level devices (i.e. PCI cards and USB devices requiring a Meinberg driver package) can not be used with these external devices.

However, even though the binary protocol is neither required nor supported when accessing Meinberg bus level devices directly via the internal data bus, many PCI cards support this protocol via their serial port COM0 that is accessible via the 9 pin connector in the slot cover.

There is a git repo available that provides example programs for the binary protocol as C source code:

• https://git.meinbergglobal.com/example-code/gpsxmple.git/

The repo can be cloned and afterwards updated using the git version control system, or specific versions can be downloaded from the web page as .zip or .tar.gz archive, where HEAD marks the latest version.

The example programs expect a command line parameter indicating the name of the serial port of the computer to which the device is connected. If no parameter is given, the first serial port of the computer is assumed.

The format of the port name depends on the target operating system. For example, the name of the first serial port of the computer is /dev/ttyS0 on Linux, or COM1 on Windows.

The file gpsxmple.c in the base directory is the original example program that demonstrates how to use some of the API functions. Over the years, the program has been more and more extended, so it became pretty complex.

If you run the compiled binary, the program reads and displays some general information on the device that is connected to the specified serial port. Running the program with parameter -? prints some more usage information.

The file set-serial-port.c in the base directory shows how to set the serial port parameters of the connected device.

Care must be taken that the settings of the port which is actually used for binary communication is not changed. Otherwise it can become tricky to keep or establish the connection to the device.

Other example programs may be added occasionally, should the need arise.

The example programs can be built and used at least on Linux and Windows, and maybe some other operating systems. There are different subdirectories for specific build environments.

For Linux and other Unix-like systems, you can (re-)build the example program using these commands:

<codedoc code> cd unix make clean; make </code>

For Windows, there are some Visual Studio project files in different directories below the windows subdirectory, so you can open the appropriate project file in Visual Studio and build the solution.

Depending on the target operating system, the API and the example programs can be used either via the serial interface (the default) or via a network socket connection, provided that the connected target device supports this.

The mbglib directory contains the C source code of the API functions, including the header files with the function prototypes and the definitions of the associated data structures.

The data structures used with the binary protocol are mostly the same ones that are described here for the bus level API:

• https://kb.meinbergglobal.com/mbglib-api/classes.html

The protocol has originally been used with Meinberg GPS receivers only, so large parts of the code or comments refer to “GPS”. However, this protocol is currently supported by most external devices.

The files in this directory should be left untouched to facilitate future maintenance of applications by simply updating these files.

If you think there are changes required in those files, or if there are any questions or suggestions, please don't hesitate to contact techsupport@meinberg.de, or martin.burnicki@meinberg.de directly.

Basically, an application has to call one of the mbgextio_open_…() functions, e.g. mbgextio_open_serial() to open the serial port of the computer to which the device is connected.

On success, a pointer to an allocated MBG_MSG_CTL structure is returned, which can be considered similar to a FILE handle, and has to be passed to subsequent API calls.

Prototypes of the public API functions can be found in files mbgextio.h and extiohlp.h in subdirectory mbglib/common. These files also include more header files, so mbglib/common should be added to the include search path of the project.

C source modules have to be linked to a project as required.

— Martin Burnicki martin.burnicki@meinberg.de, last updated 2022-07-19