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 29 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";

Internally, the RTDE client uses the same producer / consumer architecture as show in the Primary Pipeline example example. However, it doesn’t have a consumer thread, so data has to be read by the user to avoid the pipeline’s queue from overflowing.

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 30 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();

An RTDE data package containing every key-value pair from the output recipe can be fetched using the getDataPackage() method. This method will block until a new package is available.

Reading data from the RTDE client

Once the RTDE client is initialized, we’ll have to start communication separately. As mentioned above, we’ll have to read data from the client once communication is started, hence we start communication right before a loop reading data.

Listing 31 examples/rtde_client.cpp

  // 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();

  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)
  {
    // Read latest RTDE package. This will block for READ_TIMEOUT, so the
    // robot will effectively be in charge of setting the frequency of this loop unless RTDE
    // communication doesn't work in which case the user will be notified.
    // In a real-world application this thread should be scheduled with real-time priority in order
    // to ensure that this is called in time.
    std::unique_ptr<rtde_interface::DataPackage> data_pkg = my_client.getDataPackage(READ_TIMEOUT);
    if (data_pkg)
    {
      // 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.
      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;
    }

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 32 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. See the RTDE guide for more information.