Telemetry Republisher Example

This example shows how to configure and run one instance of a Telemetry Republisher. As the Telemetry Republisher is a final component it works as provided, no compile time modification/customisation is needed.

In the provided example, one instance of the republisher with name: tel_repub_1 is instantiated.

Provided Example

Note

For simplicity reasons, the example uses the file-based implementation of OLDB, Persistent and Runtime Configuration Repositories, as well as file-based service discovery. This means that the underlying format of configuration and data points is different than the one used when the above mentioned services are used with the standard backends such as CII configuration service, CII OLDB, etc.

Example Location

The example code can be found in the following sub-directory of the rtctk project:

_examples/exampleTelRepub

Modules

The provided example is composed into the following directories:

  • config - Contains configuration of the telemetry republisher example system

  • scripts - Helper scripts for deployment and control

Dependencies

The provided example code depends on the following modules:

Dependency Name

Description

Component Framework

For RTC Component functionality and Services

Reusable Components

For usage of provided components like TelRepub and libraries.

Standalone Tools

Several supporting tools are used, e.g. data sources, etc.

The Example Components

The telemetry republisher example consists of the following components

Executable

Description

rtctkGenMudpiPub

A MUDPI data generator (standalone executable not based on Tk component infrastructure)

rtctkExampleTelRepub

Acquiring MUDPI frames and publishing Agnostic DDS Samples

rtctkGenDdsSub

A generic DDS Agnostic topic subscriber

Configuration

The configuration can be found in file:

config/resource/config/rtctk/exampleTelRepub/persistent_repo/depl1/defaults/tel_repub_1.yaml

It configures two MUDPI receivers:

  • rcv_00, which receives MUDPI topic traffic on multicast group: 225.3.3.3, port: 60000 using network adapter with IP: 127.0.0.1, with CPU affinity 1 for the receiving thread and two DDS topics - test_topic_00 and test_topic_01 - that map MUDPI topic 0 and 1 respectively.

  • second_mudpi_rcv, which receives MUDPI topic traffic on IP 127.0.0.1, port 60500 (unicast MUDPI is deprecated, its usage should be avoided) and the DDS topic topic_aaa that maps MUDPI topic 0.

It also configures a simulated DDS topic sim_topic_ex that generates data with a frequency of around 100Hz.

For configuration details please refer to Configuration section in Telemetry Republisher.

Running the Example

After installing the RTC Toolkit, the example can be quickly run using the following command:

$ rtctkExampleTelRepub.sh run

This will actually do the deployment and start the following two processes:

The component rtctkExampleTelRepub is brought to the running state, and MUDPI samples start to flow. This may take a few seconds or a minute to complete. You will see log messages from the component and various tools such as rtctkGenMudpiPub, used to generate sample MUDPI data, and rtctkClient, used to send commands to rtctkTelRepub.

Note

If you see error messages about “Synchronising: frame rejected” in the logs, it likely indicates that there are not enough resources on the machine where the example is being run. The example will need to be run on a machine with more RAM and/or CPU cores.

The current execution can be stopped and cleaned up by running the following commands:

$ rtctkExampleTelRepub.sh undeploy
$ rtctkExampleTelRepub.sh unprovision

We will now go through a step-by-step procedure for getting the example up and running in the following sections. This should give a better understanding of starting, commanding, checking and stopping the rtctkExampleTelRepub component.

Deployment

The rtctkExampleTelRepub is a SRTC component. It reads its configuration from the Runtime Configuration Repository. The Runtime Configuration Repository is populated from the Persistent Repository during the deployment phase.

These steps are encoded in the launch script and can be executed with the following command:

$ rtctkExampleTelRepub.sh provision
$ rtctkExampleTelRepub.sh deploy

Necessary configuration is prepared and deployed under the run/ directory. Specifically, into the $INTROOT/run/exampleTelRepub/ directory, if $INTROOT was used as the build prefix.

This will actually start the following process:

The rtctkExampleTelRepub component will however be left in the non-operational and not-ready state. Launching of the rtctkExampleTelRepub component’s process is effectively equivalent to executing the following command:

$ rtctkExampleTelRepub tel_repub_1 \
        --sde "file:$INTROOT/run/exampleTelRepub/service_disc.yaml" &

The first mandatory positional argument is the name of the component instance, which must be unique in the system. It is used to identify the configuration parameters to use for the component within the Runtime Configuration Repository. The optional –sde` argument is the URI to the service discovery, which the component communicates with to identify where the Runtime Configuration Repository actually is. One can think of this as a boot strapping mechanism to identify and setup connections to the needed services, such as the Runtime Configuration Repository and OLDB. In the example the service discovery is being simulated by a YAML file on disk.

Send State Steering Commands

Once the component process is running, we need to steer it to the running state for it to actually republish samples to the DDS. Normally, this is done by the RTC Supervisor. But, in this example, we are running rtctkExampleTelRepub standalone. Therefore, we need to send the appropriate steering commands manually.

The following commands need to be sent to rtctkExampleTelRepub in the given order:

  1. Init - This triggers the loading of the configuration from the Runtime Configuration Repository and construction of the various internal objects, such as the MUDPI receivers and processors, DDS publisher, and dedicated processing and monitoring threads.

  2. Enable - It does not do anything in particular.

  3. Run - Sets the Telemetry Republisher to start reading MUDPI samples for topic 0 from UDP socket, process them, and publish them to DDS. Besides that, it starts sending simulated DDS topic sample data with a frequency of around 100Hz.

The steering commands can be sent to the component as follows:

$ rtctkExampleTelRepub.sh send Init
$ rtctkExampleTelRepub.sh send Enable
$ rtctkExampleTelRepub.sh send Run

Sending sample data

Now we should have the republisher in On::Operational::Running state, which means that it is ready to republish topic sample data i.e. receives MUDPI topic data, and publishes it via DDS topics.

MUDPI traffic can be generated (and sent to the Telemetry Republisher) by invoking:

$ rtctkExampleTelRepub.sh start_data

It sends MUDPI topic 0 samples with a frequency of approximately 10Hz with 6 frames per topic sample.

Note

The same can be achieved manually by using the Generic MUDPI publisher standalone tool application. E.g. to send data to MULTICAST GROUP 225.3.3.3 using NIC with IP 127.0.0.1 PORT 60000 with TOPIC_ID 0 and FREQUENCY ~100Hz use:

$ rtctkGenMudpiPub --mpc 127.0.0.1, 60000, 225.3.3.3, 0, 47808

After executing the command you should get an output similar to:

Start sending the MUDPI samples ....
# of MUDPI publishers = 1
==> Ctrl-C to exit <=.
[11:54:30:741][INFO ][rtctk] DDS Topic: "test_topic" MUDPI Topic [0] SampleId: 0 FrameId:  1. Synchronised again

Checking the data flow

If the data flows through, i.e. MUDPI samples are published by: Generic MUDPI publisher standalone tool, received and processed by Telemetry Republisher component and re-published as DDS samples, they can be checked using the Generic DDS subscriber application. E.g. to listen to DDS topic with name test_topic_00 that maps in the example to MUDPI topic with Id 0, use:

$ rtctkGenDdsSub -d -a 127.0.0.1 -t test_topic_00

The example is configured for more topics, i.e. there are other defined DDS topics with mapping to a MUDPI topic. So we can start manually another source of MUDPI topic data running in parallel (e.g. for topic with id 1) as follows:

$ rtctkGenMudpiPub -d --mpc 127.0.0.1, 60000, 225.3.3.3, 1, 47808

As was the case for the topic with id 0 and with frequency around 100Hz, we are sending data to multicast to group 225.3.3.3 via NIC with ip 127.0.0.1 on port 60000.

As this topic is mapped to a DDS topic named test_topic_01, we can monitor both of them executing Generic DDS subscriber in the following way:

$ rtctkGenDdsSub -d -a 127.0.0.1 -t test_topic_00 test_topic_01

Checking the State

It is useful to check the current state of the component. This can be done by executing the command as follows to query the state of the tel_sub_1 Telemetry Subscriber component:

$ rtctkExampleTelRepub.sh send GetState

This will print one of the following strings, depending on the current state the component is in:

  • Off - Indicates that the rtctkExampleTelRepub process is not running.

  • On::NotOperational::NotReady - The component is running but not yet initialised.

  • On::NotOperational::Ready - The component is initialised but not enabled.

  • On::Operational::Idle - The component is enabled but not running.

  • On::Operational::Running - The component is running and receiving and processing MUDPI samples, and publishing them as DDS samples.

Stopping and Clean up

First we need to stop sending the MUDPI traffic (started via the script) by executing:

$ rtctkExampleTelRepub.sh stop_data

To stop the rtctkExampleTelRepub component cleanly, one should first steer it to the not-ready state. Assuming we already brought the component to the running state, we need to first take it from running to idle, then down to not-ready. This is done by executing the following commands in the indicated order:

$ rtctkExampleTelRepub.sh send Idle
$ rtctkExampleTelRepub.sh send Disable
$ rtctkExampleTelRepub.sh send Reset

The rtctkExampleTelRepub process will still be running however. To terminate the process, one needs to send it the SIGTERM signal. This is all done conveniently in the rtctkExampleTelRepub.sh script by running the following command:

$ rtctkExampleTelRepub.sh undeploy

At this stage, none of the example components or related utilities for this tutorial should be running. However, some configuration files still remain in the $INTROOT/run/exampleTelRepub/ directory. To clean that up also, the following command should be executed to delete the directory:

$ rtctkExampleTelRepub.sh unprovision