Set Up URSim Offline Simulator

Universal Robots provides a software emulator URSim, to test and validate motion planning and control algorithms using offline programming and simulation of robot programs. More information on the features and limitations of URSim can be found on this webpage.

The source files are different for CB series and e-series of robot manipulators. Execute the following steps sequentially to install the URSim simulator.

Metric Based on Host Operating System and Mode of Installation

Operating System Metric	Windows^® Host with MATLAB^® + Virtual Machine with ROS and URSim	Linux^® Host with MATLAB + Virtual Machine with ROS and URSim	Linux Host with MATLAB, ROS, and URSim
Ease of Installation	Medium	Medium	High
Reliability and Repeatability	Medium	Medium	High
Impact on Existing Installation	No impact	No impact	High (Negative)
Overall Performance	Medium	Medium	High

Extension to Hardware

Based on our analysis, we recommend that you use a Linux Host with MATLAB and ROS for connecting MATLAB with UR Series of cobots (even though we have not verified the functionalities of universalrobot object, available in the support package, with actual hardware). As mentioned in this page, the recommendation from Universal Robots is to use a Linux host with real-time kernel to get the best performance while controlling cobots using ROS.

When you use ROS installed on a virtual machine to establish a connection with cobot hardware, the additional interface between the physical host computer and virtual machine might increase the latency of the bi-directional communication. In some cases, ROS drivers may error out because of the unreliable communication between ROS and the hardware. Additionally, in this case, computational resources are shared between physical host computer and a virtual machine, which results in a poor performance while using a virtual machine.

Operating System Requirements

It is recommended that you build a new virtual machine with Ubuntu^® 18.04 or Ubuntu 20.04 and install URSim as well as ROS, because of these reasons:

For Windows Operating System
- The Non-Linux version of the URSim contains a virtual machine image with Ubuntu v14.04. However, the ROS driver packages are not compatible with Ubuntu v14.04. Hence, you need another virtual machine with Ubuntu 18.04 or Ubuntu 20.04 to install the ROS drivers.
- The ROS drivers are not able to maintain a constant communication with the URSim running in a virtual machine. Hence, Non-Linux version of the URSim is not recommended to use with ROS drivers.

For Linux Operating System
- The installation script of the Linux version of URSim is known to remove ROS packages during the installation process. Hence, it is recommended that you install and build the ROS and associated packages once the URSim installation is complete. For more details on this issue, refer to this discussion on Universal Robot forum.
- If you are fine with the removal of unspecified packages from your Linux host, you can follow the steps mentioned under the section Install URSim and Install ROS Packages and Dependencies for ROS directly on the Linux host with Ubuntu 18.04 or Ubuntu 20.04.

Follow the instructions mentioned below to build a new virtual machine, install URSim and ROS, and clone ROS drivers from Universal Robots. This support package also provides a shell script which automatically installs the required software packages. Refer Install Software Packages Automatically Using Shell Script for more details.

Required Software Packages

No.	Name	License Information
1	VMware Workstation Player	VMWARE END USER LICENSE AGREEMENT
2	URSim Offline Simulator	END USER SOFTWARE LICENSE AGREEMENT
3	OpenJDK 8	GNU General Public License
4	ROS Melodic or Noetic	The 3-Clause BSD License
5	Open SSH Server	BSD License

Set Up Virtual Machine

Download and install the VMware® Player software (license)
Download the Ubuntu 18.04 or 20.04 installation image.
Start the VMware® Player software and click on Create a New Virtual Machine.
Choose Installer disc image file and select the downloaded Ubuntu image file.
Click Next and fill the user credentials.
Edit the virtual machine name and select the location to store virtual machine files.
Select the maximum disk size and click Next.
Customize hardware options if required. Otherwise keep the default configuration and click Finish.
This launches the Ubuntu virtual machine. Complete the installation process based on the instructions.

Install URSim

URSim is available for CB series and E series. Select the desired version from the list and download the installation archive. This step will require you to create a user account and log in.
1. Available URSim versions for CB series
2. Available URSim versions for E series
Extract the downloaded archive.
Install JDK 8 by executing the following commands in a Linux terminal.
```
>> sudo apt-get update 
>> sudo apt-get install openjdk-8-jdk -y
```
Select the JDK 8 from the list of available versions by executing the following command in a Linux terminal.
```
>> sudo update-alternatives --config javac
>> sudo update-alternatives --config java 
```
Verify the Java^® version by executing the following command in Linux terminal.
```
>> java -version 
```
If you have configured version in step 4 correctly, the displayed version should be 1.8.*
Navigate to the extracted folder in step 2 and run the installation script install.sh by typing the following command in Linux terminal.
```
>>./install.sh
```
Note
If you are installing the URSim on Ubuntu 20, then replace libcurl3 with libcurl4 in install.sh because libcurl3 is obsolete for Ubuntu 20.
Install the libxmlrpc by executing the following command in a Linux terminal.
```
>> sudo apt install libxmlrpc-c++8v5:i386 -y
```

Install ROS

Install ROS melodic (Ubuntu 18.04), or ROS noetic (Ubuntu 20.04) according to the OS version selected in step 2 of Set Up Virtual Machine.
Refer Install ROS Packages and Dependencies for ROS to clone and build ROS packages from Universal Robots.

Install SSH Server

Execute the following command in Linux terminal to install SSH server.
```
>> sudo apt-get install openssh-server 
```
Execute the following command in Linux terminal to enable SSH server.
```
>> sudo systemctl enable ssh
```
Execute the following command in Linux terminal to enable start server.
```
>> sudo systemctl start ssh
```

Install Software Packages Automatically Using Shell Script

The support package provides a shell script to automatically install required software packages mentioned in above sections.

Copy the install script from the support package folder location to the Ubuntu virtual machine. The install script install_URSim.sh can be located by navigating to the location returned by execution of the following command in MATLAB.
```
fullfile(codertarget.robotmanipulator.internal.getSpPkgRootDir,'resources')
```
Execute the setup script from the Ubuntu host machine by launching terminal from the location of the install script and then running the ./install_URSim.sh command. If the script is not executable, make it executable (Right click, select Properties > Permissions > Allow executing file as program).
Provide the user input as and when required during the installation process.
The installation script will install URSim, ROS and clone ROS packages from the Universal Robots.

Configure URSim for ROS drivers

You need to follow some additional steps to configure URSim to communicate with the ROS driver. First, you need to complete the steps for CB3 series or the steps for E series to configure the URSim simulator. After completing that initial setup, follow this procedure:

Copy the externalcontrol-1.0.5.urcap UR cap program from resources folder of the UR ROS drivers to program folder of a particular URSim simulator.
Note
- The URCap program is located at ~/ur_ws/src/ Universal_Robots_ROS_Driver/ur_robot_driver/resources
- The programs folder for URSim can be found inside the installation folder for the URSim.
- For each model of Universal Robots cobot, you have a different URCap program folder.
Launch the URSim by running the start-ursim.sh shell script. You can ignore the popup messages at the start of the URSim. The shell script is located inside the extracted archive of the URSim.
Note
The start script accepts an optional argument for the robot model. By default, the simulation is launched for UR5 but can also be launched for UR3, UR10 or UR16 (only for e series).
Install the externalcontrol URCap using the settings menu. For more details, refer the steps for CB3 series or the steps for E series.
Restart the URSim simulator.
Configure External Control URCap to connect with the ROS master located at IP Address ‘127.0.0.1’. Because both the ROS drivers and URSim are running on a same virtual machine (as per the setup instructions provided in this section), the IP address of the localhost is used for the communication.
Save this installation by overwriting to the default installation configuration.
Create a new program and insert the external control URCap node. Save this program for the future use.

Verify communication between URSim and UR ROS drivers

Launch the URSim using start-ursim.sh shell script with preferred robot model.
Note
For each model of Universal Robots, you have a different programs folder. Hence ensure that you launch the URSim with the cobot model for which you have configured the URCap as mentioned in the previous section.
Turn on the cobot by pressing the led at the bottom left corner of the window (for E series) or at the top left corner of the window (for CB3 series).
Note
If you are using URSim for CB3 series and facing a 'No Controller’ error, open a separate terminal at the URSim installation directory and launch the starturcontrol.sh script with sudo permission.
Open the terminal from the catkin workspace where you have cloned ROS driver packages from UR, and execute the following two commands:
- ```
>> source devel/setup.bash
```
- ```
>> roslaunch ur_robot_driver ur<ur model>_bringup.launch robot_ip:=127.0.0.1
```
  Here, ur model is 3,5,10,3e,5e,10e, or 16e.
- Go to the URSim and load the program you created in step 8 of Configure URSim for ROS drivers.
- Start the program by clicking Play at the bottom of the simulator window.
  Once the program is running, the ROS terminal displays a message that cobot is ready to receive control commands.
Stop the program from URSim and also kill the ROS master by pressing Ctrl+c from the terminal where ROS was launched.

Note
If you are using URSim for CB3 series, execute the stopurcontrol.sh shell script with sudo permission.

Troubleshooting URSim Offline Simulator

Data is not received from the cobot and error occurred in the connection to reserve interface

Sometimes, the TCP communication between the ROS drivers and URSim becomes unstable in the presence of heavy network traffic. In particular, if the host, in which virtual machine is configured, is being accessed via remote desktop client, the errors appear frequently, and the simulated robot is no longer controllable from MATLAB.

To solve the issue, it is recommended that you use minimal network traffic while running the simulation and avoid using the remote desktop client.

'No Controller' error with URSim CB3 series

If you are using URSIm for CB3 series and facing ‘No Controller’ error, perform one of the following:

Ensure that the libxmlrpc package is installed.
Open a separate terminal at the URSim installation directory and launch the starturcontrol.sh script with sudo permission.