Class RTDEClient

Class Documentation

class RTDEClient

The RTDEClient class manages communication over the RTDE interface. It contains the RTDE handshake and read and write functionality to and from the robot.

Public Functions

RTDEClient() = delete
RTDEClient(std::string robot_ip, comm::INotifier &notifier, const std::string &output_recipe_file, const std::string &input_recipe_file, double target_frequency = 0.0, bool ignore_unavailable_outputs = false, const uint32_t port = UR_RTDE_PORT)

Creates a new RTDEClient object, including a used URStream and Producer to handle the communication with the robot.

Parameters:

  • robot_ip – The IP of the robot

  • notifier – The notifier to notify of start and stop events

  • output_recipe_file – Path to the file containing the output recipe

  • input_recipe_file – Path to the file containing the input recipe

  • target_frequency – Frequency to run at. Defaults to 0.0 which means maximum frequency.

  • ignore_unavailable_outputs – Configure the behaviour when a variable of the output recipe is not available

  • port – Optionally specify a different port from the robot: output is silently ignored if true, a UrException is raised otherwise.

RTDEClient(std::string robot_ip, comm::INotifier &notifier, const std::vector<std::string> &output_recipe, const std::vector<std::string> &input_recipe, double target_frequency = 0.0, bool ignore_unavailable_outputs = false, const uint32_t port = UR_RTDE_PORT)

Creates a new RTDEClient object, including a used URStream and Producer to handle the communication with the robot.

Parameters:

  • robot_ip – The IP of the robot

  • notifier – The notifier to notify of start and stop events

  • output_recipe – Vector containing the output recipe

  • input_recipe – Vector containing the input recipe

  • target_frequency – Frequency to run at. Defaults to 0.0 which means maximum frequency.

  • ignore_unavailable_outputs – Configure the behaviour when a variable of the output recipe is not available

  • port – Optionally specify a different port from the robot: output is silently ignored if true, a UrException is raised otherwise.

~RTDEClient()
bool init(const size_t max_connection_attempts = 0, const std::chrono::milliseconds reconnection_timeout = comm::TCPSocket::DEFAULT_RECONNECTION_TIME, const size_t max_initialization_attempts = 3, const std::chrono::milliseconds initialization_timeout = std::chrono::seconds(1))

Sets up RTDE communication with the robot. The handshake includes negotiation of the used protocol version and setting of input and output recipes.

Parameters:

  • max_connection_attempts – Maximum number of (socket) connection attempts before counting the connection as failed. Unlimited number of attempts when set to 0.

  • reconnection_timeout – Time in between connection attempts to the socket

  • max_initialization_attempts – Maximum number of initialization attempts before counting the initialization as failed. Initialization can fail given an established socket connection e.g. when the connected socket does not implement an RTDE interface.

  • initialization_timeout – Time in between initialization attempts of the RTDE interface

Returns:

Success of the handshake

bool start(const bool read_packages_in_background = true)

Triggers the robot to start sending RTDE data packages in the negotiated format.

Parameters:

read_packages_in_background – Whether to start a background thread to read packages from. If packages are read in the background, getDataPackage() will return the latest one received. If packages aren’t read in the background, the application is required to call getDataPackageBlocking() frequently.

Returns:

Success of the requested start

bool pause()

Pauses RTDE data package communication.

Returns:

Whether the RTDE data package communication was paused successfully

std::unique_ptr<rtde_interface::DataPackage> getDataPackage(std::chrono::milliseconds timeout)

Return the latest data package received.

Deprecated:

This method allocates memory on each call. Please use the overload which takes a reference to an existing DataPackage instead. This function will be removed in May 2027.

When packages are read from the background thread, this will return the latest data package received from the robot. When no new data has been received since the last call to this function, it will wait for the time specified in the timeout parameter.

When packages are not read from the background thread, this function will return nullptr and print an error message.

Parameters:

timeout – Time to wait if no data package is currently in the queue

Returns:

Unique ptr to the package, if a package was fetched successfully, nullptr otherwise

bool getDataPackage(DataPackage &data_package, std::chrono::milliseconds timeout)

Return the latest data package received.

When packages are read from the background thread, the latest data package received from the robot can be fetched with this. When no new data has been received since the last call to this function, it will wait for the time specified in the timeout parameter.

When packages are not read from the background thread, this function will return false and print an error message.

Parameters:

  • data_package – Reference to a DataPackage where the received data package will be stored if a package was fetched successfully.

  • timeout – Time to wait if no data package is currently in the queue

Returns:

Whether a data package was received successfully

bool getDataPackage(std::unique_ptr<DataPackage> &data_package, std::chrono::milliseconds timeout)
bool getDataPackageBlocking(std::unique_ptr<rtde_interface::DataPackage> &data_package)

Blocking call to get the next data package received from the robot.

This function will block until a new data package is received from the robot and return it.

Parameters:

data_package – Reference to a unique ptr where the received data package will be stored. For optimal performance, the data package pointer should contain a pre-allocated data package that was initialized with the same output recipe as used in this RTDEClient. If it is not an initialized data package, a new one will be allocated internally which will have a negative performance impact and print a warning.

Returns:

Whether a data package was received successfully

inline double getMaxFrequency() const

Getter for the maximum frequency the robot can publish RTDE data packages with.

Returns:

The maximum frequency

inline double getTargetFrequency() const

Getter for the target frequency that the robot will publish RTDE data packages with.

Returns:

The target frequency

inline VersionInformation getVersion()

Getter for the UR control version received from the robot.

Returns:

The VersionInformation received from the robot

std::string getIP() const

Returns the IP address (of the machine running this driver) used for the socket connection.

Returns:

The IP address as a string (e.g. “192.168.0.1”)

RTDEWriter &getWriter()

Getter for the RTDE writer, which is used to send data via the RTDE interface to the robot.

Returns:

A reference to the used RTDEWriter

inline std::vector<std::string> getOutputRecipe()

Getter for the RTDE output recipe.

Returns:

The output recipe

inline std::vector<std::string> getInputRecipe()

Getter for the RTDE input recipe.

Returns:

The input recipe

inline ClientState getClientState() const
void startBackgroundRead()

Starts a background thread to read data packages from the robot.

After calling this function, getDataPackage() can be used to get the latest data package received from the robot.

void stopBackgroundRead()

Stops the background thread reading data packages from the robot.

After calling this function, getDataPackageBlocking() must be used to get data packages from the robot.

Note

When getDataPackageBlocking() is not called frequently enough, the internal buffer of received data packages might fill up, causing the robot to shutdown the RTDE connection.

Public Static Functions

static std::vector<std::string> readRecipe(const std::string &recipe_file)

Reads output or input recipe from a file and parses it into a vector of strings where each string is a line from the file.

Protected Functions

std::vector<std::string> ensureTimestampIsPresent(const std::vector<std::string> &output_recipe) const
bool setupCommunication(const size_t max_num_tries = 0, const std::chrono::milliseconds reconnection_time = std::chrono::seconds(10))
uint16_t negotiateProtocolVersion()
bool queryURControlVersion()
void setTargetFrequency()
bool setupOutputs()
bool setupInputs()
void disconnect()
void resetOutputRecipe(const std::vector<std::string> new_recipe)

Updates the output recipe to the given one and recreates all the objects which depend on it. It should only be called while setting up the communication.

Parameters:

new_recipe – the new output recipe to use

bool isRobotBooted()

Checks whether the robot is booted, this is done by looking at the timestamp from the robot controller, this will show the time in seconds since the controller was started. If the timestamp is below 40, we will read from the stream for approximately 1 second to ensure that the RTDE interface is up and running. This will ensure that we don’t finalize setting up communication, before the controller is up and running. Else we could end up connecting to the RTDE interface, before a restart occurs during robot boot which would then destroy the connection established.

Returns:

true if the robot is booted, false otherwise which will essentially trigger a reconnection.

bool sendStart()
bool sendPause()
void reconnect()

Reconnects to the RTDE interface and set the input and output recipes again.

void reconnectCallback()
void backgroundReadThreadFunc()

Protected Attributes

comm::URStream<RTDEPackage> stream_
std::vector<std::string> output_recipe_
bool ignore_unavailable_outputs_
std::vector<std::string> input_recipe_
RTDEParser parser_
std::unique_ptr<comm::URProducer<RTDEPackage>> prod_
comm::INotifier notifier_
RTDEWriter writer_
std::atomic<bool> reconnecting_
std::atomic<bool> stop_reconnection_
std::mutex reconnect_mutex_
std::thread reconnecting_thread_
VersionInformation urcontrol_version_
double max_frequency_
double target_frequency_
std::unique_ptr<RTDEPackage> data_buffer0_
std::unique_ptr<RTDEPackage> data_buffer1_
std::mutex read_mutex_
std::mutex write_mutex_
std::atomic<bool> new_data_ = false
std::atomic<bool> background_read_running_ = false
std::thread background_read_thread_
std::condition_variable background_read_cv_
DataPackage preallocated_data_pkg_
ClientState client_state_
uint16_t protocol_version_
size_t max_connection_attempts_
std::chrono::milliseconds reconnection_timeout_
size_t max_initialization_attempts_
std::chrono::milliseconds initialization_timeout_

Protected Static Attributes

static constexpr const double CB3_MAX_FREQUENCY = 125.0
static constexpr const double URE_MAX_FREQUENCY = 500.0