RTDE Client Python Module
RTDE clients can be implemented in different languages that support socket communication. The purpose of this 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.
Download the example from our Github repository.
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)--frequency: the sampling frequency in Hertz--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
Provides a simple way to read and plot the data from a CSV file recorded with the record.py.
example_control_loop.py
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 consists 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.
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 headers 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 aread()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 strings and write them to a file-like object.
Input parameters:
csvfile (file): Any file-like object that has awrite()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 ‘ ‘.
Methods:
writeheader(): Write column headers to the current line in the 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 fields with a variable name and type. An example XML recipe:
<?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>
Methods:
get_recipe(key): Gets the recipe associated with the specified key given as a list of names and a list of types.Input parameters:
key (string): The key associated with the recipe.
Return values:
variables (array<string>): List of variable names.types (array<string>): List of variable types.
class serialize.DataObject()
A data transfer object where the RTDE variable names configured for synchronization have 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: Therecipe_idis 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).
Methods:
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. It is recommended to 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): 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.
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)
receive(): Blocking call to receive the next output DataObject from the RTDE server.Return value:
output_data (DataObject): Object with member variables matching the names of the configured RTDE variables.