UR Primary Client Python Library

Overview

This client is designed to connect to a Universal Robots' e-series cobot via the primary client interface. It receives messages, deserializes them into a human readable format, and writes the content to files.

Demo

Program demonstrates client curating robot state messages.

Essential Technical Details

Universal Robots' provides a primary client interface within their robots, allowing external devices to connect with the robot's software and facilitate the exchange of communication messages. The robot's software periodically sends out serialized messages containing robot state information as outlined in their primary / secondary specification. In short, a sent message consists of a hexadecimal string representing binary data, with robot parameters encoded within it. These strings are divided into sections, with the first section called the "package," starting at byte 0 and all subsequent sections being "subpackages." This client is designed to parse these messages, extract the packages and make them human readable.

Usage

Requirements

• Python
• Git
• UR e-series model, simulated or physical, running PolyScope version 5.9 or newer.

Simulator Options

• VirtualBox simulator
• Docker simulator setup

  • With docker installed run the following command then navigate to http://localhost:6080/ using Google Chrome.

    docker run -it -e ROBOT_MODEL=UR3e -p 30001:30001 -p 30002:30002 -p 30004:30004 -p 6080:6080 --name ur3e_container universalrobots/ursim_e-series

Setup

1. Identify your cobot's IP address in the Hamburger menu within PolyScope.

   • If using docker, then you'll use your host machine's IPv4

   

2. Clone this repository into a directory of your choice with the following command:

   git clone https://github.com/Shawn-Armstrong/UR_Primary_Client_Python_Library.git

3. Curate packages by navigating inside the cloned directory /client from a console and running the following command:

   python client.py ip_address=YOUR_IP_ADDRESS max_reports=NUMBER_YOU_WANT_TO_CAPTURE_PER_PACKAGE

Output & Behavior

The client captures a specified number of packages, max_reports, for each package type and writes them to the end of their corresponding text files within the output directory. When the max_reports limit for a specific package type has been reached, the client will remove the oldest entry and add the newest incoming entry, maintaining a rolling buffer of the most recent packages. At the beginning of each execution, the text files are cleared to ensure a fresh start. The program can be terminated with a keyboard interrupt: ctrl + c .

Default program arguments are as follows:

• --max_reports=10
• --ip_address=<local ip address>

Custom Reports

To enable custom reports, run python client.py --custom_report. When enabled, the client will track every variable listed in ../client/watch_list.txt and report it in the ../output/custom_report.txt file. Custom reports consist of a table that captures a specified number of entries, max_reports. When a new entry is added, the oldest entry will be discarded if the table has reached its maximum capacity. Every new entry contains the last observed value; if a value has not been received yet, its corresponding field in the table will remain empty. At the beginning of each execution, custom_report.txt is cleared to ensure a fresh start.

Each variable in watch_list.txt should be on a separate line within the file, prepended by their owning subpackage name and separated by a comma. The variable and subpackage name should be spelled exactly as they appear in their related package output file.

# watch_list.txt example
Robot Mode Data,timestamp
Cartesian Info,X
Master Board Data,robotVoltage48V

# custom_report.txt output example
+------------------------+-----------------------------+--------------------+-------------------------------------+
| Timestamp              |   Robot_Mode_Data_timestamp |   Cartesian_Info_X |   Master_Board_Data_robotVoltage48V |
+========================+=============================+====================+=====================================+
| 2023-04-02 17:52:55.21 |                  3711040000 |          -0.143969 |                                  48 |
+------------------------+-----------------------------+--------------------+-------------------------------------+
| 2023-04-02 17:52:55.31 |                  3711136000 |          -0.143969 |                                  48 |
+------------------------+-----------------------------+--------------------+-------------------------------------+
| 2023-04-02 17:52:55.41 |                  3711230000 |          -0.143969 |                                  48 |
+------------------------+-----------------------------+--------------------+-------------------------------------+
| 2023-04-02 17:52:55.51 |                  3711326000 |          -0.143969 |                                  48 |
+------------------------+-----------------------------+--------------------+-------------------------------------+

Implementation Details

Technical Overview

As described in the Essential Technical Details, this client is specifically designed to receive these messages, deserialize them, and write the content to files. The client's implementation consists of four main components: client.py, package.py, subpackage.py, and packagewriter.py.

client.py

This is the entry point of the program. It connects with the cobot, receives messages and uses them to instantiate a Package object. Afterwards, a PackageWriter object writes the Package to a file.

package.py

This file defines the Package class. In principle, this is a container class designed to create, store and manage SubPackages also leveraging the relationship between them. Package employs a class factory pattern defined in SubPackage to instantiate SubPackage objects..

subpackage.py

This file defines the SubPackage class and its subclasses. SubPackage implements an inheritance hierarchy where every subclass is a subpackage defined in the primary / secondary specification. The hierarchy is designed around named tuples to facilitate table construction while taking advantage of polymorphism.

packagewriter.py

This file defines the PackageWriter class, which is essentially a utility class that utilizes data from Package objects to write to files. The class streamlines file handling by maintaining a separate text file for each package type defined in the specification and writing corresponding Package objects to the appropriate file.

Development

Notices

• This client was developed using a simulated e-series UR3e running PolyScope 5.13. As it is in the early stages of development, its results should be treated with caution and skepticism.
• Currently, only robot state messages are supported.

Unit Tests

• Directory test contains unit tests used to support test driven development.

Future Features

• Implement package type 20.
• Implement a method of filtering variables.
• Implement unit tests.

Bugs

• While deserializing a Robot State Message, package type 16, an unknown subpackage type 14 was observed.
  • There may be a potential logic error in class Package function read_subpackages().
  • There may be an undocumented subpackage.
• Custom reports cannot differentiate between subpackages that share variables names.
  • Potentially resolved, pending more tests.