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 steps mentioned in this topic sequentially to install the URSim simulator.
For the complete model based design workflow involving MATLAB® simulation, verification with URSim, and connectivity with UR series hardware, we recommend Linux® host with MATLAB and ROS. The URSim can be installed in the virtual machine running on Linux host to avoid any unintentional changes to the Linux host.
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
|Reliability and Repeatability
|Impact on Existing Installation
Simulation - Connection Options Between URSim, MATLAB, and ROS Master PC
The simulation workflow for bin picking example can be achieved in the following ways,
VM (Ubuntu® - Linux)
Ubuntu – Linux
Key takeaways relating to
In above Workflow(s), URSim is installed in the same device as ROS device,
Hence the robot IP will be the same as the local host IP (
robotAddressfor URSim will be
roslaunch ur_robot_driver ur5e_bringup.launch robot_ip:= <robotAddress>
rosdeviceAPI uses the
ROSDeviceAddresswhere the IP address is from ROS Master.
In the above-mentioned workflows for simulation and cobot, workflow-2 using Linux PC is recommended.
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 and 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 for more details.
Required Software Packages
|VMware Workstation Player
|VMWARE END USER LICENSE AGREEMENT
|URSim Offline Simulator
|END USER SOFTWARE LICENSE AGREEMENT
|GNU General Public License
|ROS Melodic or Noetic
|The 3-Clause BSD License
|Open SSH Server
Set Up Virtual Machine
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. It is recommended to select at least 30 GB.
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.
This section helps you with the available setup options. You can either use the automated method to automatically install the required software packages using shell script or manually install the required software.
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
installation_script.shcan be located by navigating to the location returned by execution of the following command in MATLAB.
Execute the setup script from the Ubuntu host machine by launching terminal from the location of the install script and then running the
./installation_script.shcommand. 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.
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.
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.
If you are installing the URSim on Ubuntu 20, then replace
libcurl4in install.sh because
libcurl3is 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 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
Configure URSim for ROS drivers
You need to follow some additional steps to configure URSim to communicate with the ROS driver.
MathWorks® provides a URCap file named
matlab_externalcontrol-1.0.0.urcap, which allows external
control for the Universal Robots UR Series cobots. The source files are located at
the GitHub® location MATLAB-URCap-for-External-Control.
matlab_externalcontrol-1.0.0.urcapfrom here for R2022b to your local computer. After downloading, copy the file to the programs folder of your URSim.
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.shshell 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.
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 MATLAB URCap for External Control using the settings menu.
Select Settings, and then select System > URCaps.
Click the plus sign at the bottom of the interface to open the file selector.
In the file selector, select the
matlab_externalcontrol-1.0.0.urcapfile from the available URCaps from the program folder, and click Open. The URCaps view is updated to display MATLAB URCap for External Control in the list of Active URCaps.
Restart the URSim simulator.
Configure External Control URCap to connect with the ROS master located at IP Address ‘127.0.0.1’. To set the ROS master address, navigate to the MATLAB URCap for External Control section in Installation panel and enter the Host IP Address. Since, both the ROS drivers and URSim are running on a same virtual machine (as per the setup instructions provided in this section above), the IP address of the localhost (127.0.0.1) is used for the communication.
Save this installation by overwriting to the default installation configuration. To do so, navigate to Panel > Save > Save Installation.
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.shshell script with preferred robot model.
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).
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
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
ur modelis 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.
If you are using URSim for CB3 series, execute the
stopurcontrol.shshell script with
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
libxmlrpcpackage is installed.
Open a separate terminal at the URSim installation directory and launch the