RTDE Client example

This example shows how to use the RTDEClient class for the robot’s Real-Time Data Exchange (RTDE) interface.

The RTDE client has to be initialized with a list of keys that should be streamed from the robot and a list of keys that should be sent to the robot. The client will then start a background thread establishing communication.

In this example, those keys are stored in two text files relative to this repository’s root: rtde_input_keys.txt and rtde_output_keys.txt. The example will read those files and use them to initialize the RTDE client.

Listing 30 examples/rtde_client.cpp

const std::string OUTPUT_RECIPE = "examples/resources/rtde_output_recipe.txt";
const std::string INPUT_RECIPE = "examples/resources/rtde_input_recipe.txt";

Creating an RTDE Client

An RTDE client can be directly created passing the robot’s IP address, a INotifier object, an output and an input recipe. Optionally, a communication frequency can be passed as well. If that is omitted, RTDE communication will be established at the robot’s control frequency.

Listing 31 examples/rtde_client.cpp

  comm::INotifier notifier;
  const double rtde_frequency = 50;  // Hz
  rtde_interface::RTDEClient my_client(robot_ip, notifier, OUTPUT_RECIPE, INPUT_RECIPE, rtde_frequency);
  my_client.init();

Reading data from the RTDE client

To read data received by the RTDE client, it has to be polled. See the RTDEClient section for details on two possible strategies. In this example, we do not use background read and instead fetch data synchronously. Hence, we pass false to the start() method.

Listing 32 examples/rtde_client.cpp

  auto data_pkg = std::make_unique<rtde_interface::DataPackage>(my_client.getOutputRecipe());
  // Once RTDE communication is started, we have to make sure to read from the interface buffer, as
  // otherwise we will get pipeline overflows. Therefor, do this directly before starting your main
  // loop.
  my_client.start(false);  // false -> do not start background read thread.

  auto start_time = std::chrono::steady_clock::now();
  while (second_to_run <= 0 ||
         std::chrono::duration_cast<std::chrono::seconds>(std::chrono::steady_clock::now() - start_time).count() <
             second_to_run)
  {
    // Wait for a DataPackage. In a real-world application this thread should be scheduled with real-time priority in
    // order to ensure that this is called in time.
    bool success = my_client.getDataPackageBlocking(data_pkg);
    if (success)
    {
      // Data fields in the data package are accessed by their name. Only names present in the
      // output recipe can be accessed. Otherwise this function will return false.
      // We preallocated the string TARGET_SPEED_FRACTION to avoid allocations in the main loop.
      data_pkg->getData(TARGET_SPEED_FRACTION, target_speed_fraction);
      printFraction(target_speed_fraction, TARGET_SPEED_FRACTION);
    }
    else
    {
      // The client isn't connected properly anymore / doesn't receive any data anymore. Stop the
      // program.
      std::cout << "Could not get fresh data package from robot" << std::endl;
      return 1;
    }

In our main loop, we wait for a new data package to arrive using the blocking read method. Once received, data from the received package can be accessed using the getData() method of the DataPackage object. This method takes the key of the data to be accessed as a parameter and returns the corresponding value.

Note

The key used to access data has to be part of the output recipe used to initialize the RTDE client. Passing a string literal, e.g. "actual_q", is possible but not recommended as it is converted to an std::string automatically, causing heap allocations which should be avoided in Real-Time contexts.

Writing Data to the RTDE client

In this example, we use the RTDE client to oscillate the speed slider on the teach pendant between 0 and 1. While this doesn’t bear any practical use it shows how sending data to the RTDE interface works.

To send data to the RTDE client, we can use RTDEWriter object stored in the RTDE client. This has methods implemented for each data type that can be sent to the robot. The input recipe used to initialize the RTDE client has to contain the keys necessary to send that specific data.

Listing 33 examples/rtde_client.cpp

    if (!my_client.getWriter().sendSpeedSlider(speed_slider_fraction))
    {
      // This will happen for example, when the required keys are not configured inside the input
      // recipe.
      std::cout << "\033[1;31mSending RTDE data failed." << "\033[0m\n" << std::endl;
      return 1;
    }

Note

Many RTDE inputs require setting up the data key and a mask key. That is done internally, but the mask keys have to be part of the input recipe, as well. See the RTDE guide for more information.

Note

Every send... call to the RTDEWriter triggers a package sent to the robot. If you want to modify more than one input at a time, it is recommended to use the sendPackage() method. That allows setting up the complete data package with its input recipe and sending that to the robot at once.