RTDE client Python module

The RTDE (Real-Time Data Exchange) is a communication interface for external applications to synchronize with the robot controller without breaking any real-time properties of the controller. External applications can configure packages of data fields to synchronize, and then start the actual synchronization involving both sending and receiving information to and from the robot controller.

RTDE clients can be developed in a large set of languages with socket communication support. The purpose of the RTDE client library written in Python is to provide an easy starting point and show some example applications. The functionality has been developed for Python 2.7.11.

For a more general introduction to the RTDE interface of the robot controller, please refer to the Real-Time Data Exchange-introduction document.

Examples

record.py

Use this script as an executable to record output data from the robot and save it to a csv file.

Optional arguments

  • --host: name of host or IP address to connect to (default: localhost)
  • --port: port number (default: 30004)
  • --samples: specific number of samples to record (otherwise the program will record data until receiving SIGINT/Ctrl+C)
  • --config: XML configuration file to use - it will use the recipe with key 'out' (default: record_configuration.xml)
  • --output: data output file to write to - an existing file will be overwritten (default: robot_data.csv)
  • --verbose: enable info logging output to console
  • -h: display help

example_plotting.py

This script is an example of a simple way to read and plot the data from a csv file generated using record.py.

example_control_loop.py

This script is an example of a simple control loop. A configuration with two input recipes and one output recipe is read from XML file and sent to the RTDE server. The control loop consist of a blocking read followed by some very simple data processing before sending new information to the robot.

rtde module

This section describes the different classes and their public interfaces of the rtde module for protocol version 2.

class csv_reader.CSVReader(csvfile, delimiter)

Reads the CSV file and maps each column into an entry in the namespace dictionary of the object. The column header are the dictionary key and the value is an array of data points in the column.

Input parameters

  • csvfile (file): Any file-like object that has a read() method.
  • delimiter (string): A one-character string used to separate fields. It defaults to ' '.

class csv_writer.CSVWriter(csvfile, names, types, delimiter)

Returns a writer object that can take RTDE DataObjects and convert them into delimited string and write them to a file like object.

Input parameters

  • csvfile (file): Any file-like object that has a write() method.
  • names (array<string>): list of variable names
  • types (array<string>): list of variable types
  • delimiter (string): A one-character string used to separate fields. It defaults to ' '.

writeheader()

Write column headers to current line in file based on variable names. Multidimensional variables will get an index appended to the name in each column.

writerow(data_object)

Write a new row to the file based on the provided DataObject.

Input parameters

  • data_object (DataObject): Data object with member variables matching the names of the configured RTDE variables

class rtde_config.ConfigFile(filename)

An RTDE configuration can be loaded from an XML file containing a list of recipes. Each recipe should have a key and a list of field with a variable name and type. An example is shown below.

get_recipe(key)

Gets the recipe associated to the specified key given as a list of names and a list of types.

Input parameters

  • key (string): The key associated to the recipe

Return values

  • variables (array<string>): list of variable names
  • types (array<string>): list of variable types
<?xml version="1.0"?>
<rtde_config>
    <recipe key="out">
        <field name="timestamp" type="DOUBLE"/>
        <field name="target_q" type="VECTOR6D"/>
        <field name="target_qd" type="VECTOR6D"/>
        <field name="speed_scaling" type="DOUBLE"/>
        <field name="output_int_register_0" type="INT32"/>
    </recipe>
    <recipe key="in1">
        <field name="input_int_register_0" type="INT32"/>
        <field name="input_int_register_1" type="INT32"/>
    </recipe>
    <recipe key="in2">
        <field name="input_double_register_0" type="DOUBLE"/>
    </recipe>
</rtde_config>

class serialize.DataObject():

A data transfer object where the RTDE variable names configured for synchronization has been added to the namespace dictionary of the class for convenient accessing. This means that for example the timestamp can be accessed on an output DataObject like this: objName.timestamp. The DataObject is used for both input and output.

recipe_id

The recipe_id is an integer member variable on the DataObject instance used to identify input packages configured in the RTDE server. It is not used for output packages.

class Rtde.RTDE(hostname, port)

The constructor takes a hostname and port number as arguments.

Input parameters

  • hostname (string):  hostname or IP of RTDE server
  • port (int): [Optional] port number (default value: 30004)

connect()

Initialize RTDE connection to host.

Return value

  • success (boolean)

disconnect()

Close the RTDE connection.

is_connected()

Returns True if the connection is open.

Return value

  • open (boolean)

get_controller_version()

Returns the software version of the robot controller running the RTDE server.

Return values

  • major (int)
  • minor (int)
  • bugfix (int)
  • build (int)

negotiate_protocol_version(protocol)

Negotiate the protocol version with the server. Returns True if the controller supports the specified protocol version. We recommend that you use this to ensure full compatibility between your application and future versions of the robot controller.

Input parameters

  • protocol (int): protocol version number

Return value

  • success (boolean)

send_input_setup(variables, types)

Configure an input package that the external application will send to the robot controller. An input package is a collection of input variables that the external application will provide to the robot controller in a single update. Variables is a list of variable names and should be a subset of the names supported as input by the RTDE interface.The list of types is optional, but if any types are provided it should have the same length as the variables list. The provided types will be matched with the types that the RTDE interface expects and the function returns None if they are not equal. Multiple input packages can be configured. The returned InputObject has a reference to the recipe id which is used to identify the specific input format when sending an update.

Input parameters

  • variables (array<string>): Variable names from the list of possible RTDE inputs
  • types (array<string>): [Optional] Types matching the variables

Return value

  • input_data (DataObject): Empty object with member variables matching the names of the configured RTDE variables

send_output_setup(variables, types, frequency)

Configure an output package that the robot controller will send to the external application at the control frequency. Variables is a list of variable names and should be a subset of the names supported as output by the RTDE interface. The list of types is optional, but if any types are provided it should have the same length as the variables list. The provided types will be matched with the types that the RTDE interface expects and the function returns False if they are not equal. Only one output package format can be specified and hence no recipe id is used for output.

Input parameters

  • variables (array<string>): Variable names from the list of possible RTDE outputs
  • types (array<string>): [Optional] Types matching the variables
  • frequency (double): [Optional] The update frequency for the output packages. The frequency must be between 1 and 125 Hz. The output rate will be according to floor(125 / frequency). Default value is 125.

Return value

  • success (boolean)

send_start()

Sends a start command to the RTDE server to initiate the actual synchronization. Setup of all inputs and outputs should be done before starting the synchronization.

Return value

  • success (boolean)

send_pause()

Sends a pause command to the RTDE server to pause the synchronization. When paused it is possible to change the input and output configurations and start the synchronization again.

Return value

  • success (boolean)

send(input_data)

Send the contents of a DataObject as input to the RTDE server. Returns True if successful.

Input parameters

  • input_data (DataObject): object with member variables matching the names of the configured RTDE variables

Return value

  • success (boolean)

send_message(message, source, type)

Send a message to the log in PolyScope.

Input parameters

  • message (string): Message to send to the log.
  • source (string): [Optional] Message source identification (sender id) that will be attached to the log message. Default value is "Python Client".
  • type (MessageType): [Optional] Log warning level. Default value is "INFO_MESSAGE".

Return value

  • success (boolean)

has_data()

Non-blocking check if any data has been received.

Return value

  • data_available (boolean)

receive()

Blocking call to receive next output DataObject from RTDE server.

Return value

  • output_data (DataObject): object with member variables matching the names of the configured RTDE variables