MxMessageSystem SDK v1.1

To show the use of the MxMessageSystem SDK, a small sample program was developed, which is contained as source code. The sample program can send and receive MxMessages. This README file serves as an guide for compiling and using the sample program.

Compiling the Sample Program

The MxMessageSystem SDK can be compiled and used on Windows, Linux and OS X computers.

Compiling on Ubuntu 16.4 Linux x86_64

Make sure that the following programs have been installed on Ubuntu 16.4 Linux x86_64:

sudo apt-get install build-essential openssl libssl-dev cmake

Make sure that the program versions are current:

To compile the sdk-demo program, execute:

cmake .
make

Compiling on OS X

OS X 10.9 or higher must be used.

To compile the sdk-demo program, execute:

cmake .
make

It is also possible to generate an Xcode project:

cmake -G Xcode .

Compiling on Windows

Make sure that the program versions are current:

To compile the sdk-demo program, execute:

cmake -G "Visual Studio 14 2015"
cmake --build . --target ALL_BUILD --config Release

Configuration

The MxMessageSystem SDK has two configurations that are controlled by one JSON file each in our sample program:

  1. system_config.json
  2. user_config.json

Important Prerequisites

  1. The systems must be on the same subnet. For debugging purposes, you need to configure the camera on a static IP address.
  2. The port and passphrase need to match the values in the user configuration (see also broadcast.port and broadcast.passphrase below under "User Configuration").
  3. The time of the camera and the computer must be in sync. You should use the same NTP server for both systems (see also broadcast.max_time_offset below under "User Configuration").

1. System Configuration

This configuration does not change while the process is running. It is used for static adaptation to different platforms. The system configuration of the sample program can be found in the system_config.json file.

Options

  1. log_list_max (integer, optional) Max. number of entries in the status output ("Publication") of the distributor.

  2. broadcast.interfaces (array of strings, mandatory) Lists the Ethernet interfaces on which usable broadcast addresses will be searched. The interfaces are searched in the given order. The first found IPv4 broadcast address will be used. This list basically sets the default values for the user configuration.

Example

{
    "broadcast" : {
        "interfaces" : [
            "eth1:0",
            "eth1",
            "eth0",
            "en0"
        ]
    }
}

2. User Configuration

This configuration can be changed by the user while the process is running. In this case, you need to call the DistributorBroadcastCore::init() function with the new configuration. If something goes wrong with the (re-) initialization (e.g., no IPv4 broadcast address can be found) the function will return the boolean false value. The distributor is then inactive. The user configuration of the sample program is stored in the user_config.json file.

Options

  1. broadcast.iface (string, optional) Name of the interface whose IPv4 broadcast address should be used.
  2. broadcast.max_time_offset (integer, optional) Max. difference between package timestamps. If the difference between the timestamps and the local system time is too large, the packages are discarded.
  3. broadcast.passphrase (string, optional) The AES key is generated from this phrase. If the option is not available or is an empty string, encryption will be turned off! You should only work without encryption for debugging purposes!
  4. broadcast.poll_freq (integer, optional) Number of sent/received packages per second. The value 0 sets the polling frequency to 0.1 Hz. This value is only to be used for debugging purposes!
  5. broadcast.port (integer, optional) UDP port to be used.
  6. broadcast.resend (integer, optional) Number of sending attempts of an MxMessage.

Example

{
    "broadcast" : {
        "max_time_offset" : 666,
        "passphrase" : "ThisIsMySpecialPassPhrase",
        "poll_freq" : 6,
        "port" : 33566,
        "resend" : 6
    }
}

Using the Sample Program

Usually, the program will be started as follows:

./sdk-demo -s system_config.json -u user_config.json

Parameters

  1. -d 1: Sets the debug level between 0..3.
  2. -s system_config.json: Specifies the system configuration JSON file.
  3. -u user_config.json: Specifies the user configuration JSON file.
  4. -v: Verbose mode; the sample program writes status information to the console.

Sending and Receiving MxMessages

Once the program is running, the received MxMessages are displayed in the following form:

messages.global.Input1=true

Messages can be sent from the program by first specifying the path of the message and then its value, for example.

Example:

Enter path or '!' to exit or '?' to get statistics: messages.global.Input1
Enter value or '!' to exit or '?' to get statistics: true

The output shows the following:

path=messages.global.Input1
value=true

Entering a question mark returns statistical information as follows:

put_publication = {
    "peers" :
    [
        {
            "IP" : "10.12.226.182",
            "PID" : 768,
            "msg_rx" : 2,
            "msg_rx_dup" : 4,
            "msg_rx_err" : 0,
            "msg_rx_resend" : 0,
            "pkt_rx" : 4,
            "pkt_rx_err" : 0
        }
    ],
    "self" :
    {
        "IP" : "10.3.0.1",
        "PID" : 9710
    },
    "summary" :
    {
        "msg_rx" : 2,
        "msg_rx_dup" : 4,
        "msg_rx_err" : 0,
        "msg_rx_resend" : 0,
        "msg_tx" : 0,
        "pkt_rx" : 4,
        "pkt_rx_err" : 0,
        "pkt_tx" : 0,
        "pkt_tx_err" : 0
    }
}

Entering an exclamation mark terminates the program.

Test System

In the beginning, it is recommended to build a local test system. If this works without errors, a camera can be added. Next, MxBus modules can be connected.

Setting Up a Local Test System

You can simply run the sample program twice to test the MxMessageSystem on one computer.

./sdk-demo -s system_config.json -u user_config.json

Then simply send an MxMessage:

Enter path or '!' to exit or '?' to get statistics: messages.global.Input1
Enter value or '!' to exit or '?' to get statistics: true

... and watch the output of the other program.

messages.global.Input1=true

Setting Up a Test System With a Camera

To build a test system with a MOBOTIX camera, you should read the "Technical Note: MxMessageSystem" under "https://www.mobotix.com/other/Support/MX-Media-Library/Compact-Guides". It describes how to configure the camera so it can receive and transmit MxMessages. The document also contains an introduction to the MxBus modules.