Main Content

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.

Note

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.

Note

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 InstallationMediumMediumHigh
Reliability and RepeatabilityMediumMediumHigh
Impact on Existing InstallationNo impactNo impact

High (Negative)

Overall PerformanceMediumMediumHigh

Simulation - Connection Options Between URSim, MATLAB, and ROS Master PC

The simulation workflow for bin picking example can be achieved in the following ways,

WorkflowROS MasterURSimMATLABSchematic
1

VM (Ubuntu® - Linux)

(ROSDeviceAddress)

Windows

2

Ubuntu – Linux

(ROSDeviceAddress) 

Key takeaways relating to robotAddress and ROSDeviceAddress,

  • 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 (127.0.0.1).

    • Therefore, the robotAddress for URSim will be 127.0.0.1

      Example: roslaunch ur_robot_driver ur5e_bringup.launch robot_ip:= <robotAddress>

  • The rosdevice API uses the ROSDeviceAddress where the IP address is from ROS Master.

    Example: rosdevice(ROSDeviceAddress,username,password)

Note

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 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. NameLicense Information
1 VMware Workstation Player -NA-
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

To install virtual machine:

  1. Navigate to broadcom.com.

  2. In the upper right corner, click 'Support Portal'.

  3. Either log in by clicking 'Go To Portal' or 'Register' for a basic Broadcom account.

  4. Once logged in, look for the ‘Software’ dropdown menu. From there, select the VMware Cloud Foundation division and click on 'My Downloads'.

  5. Select VMware Workstation and choose the required version.

  6. Download and install the VMware Player.

After installing VMWare Player, follow these steps to set up the VM:

  1. Download the Ubuntu 18.04 or 20.04 installation image.

  2. Start the VMware® Player software and click Create a New Virtual Machine.

  3. Choose Installer disc image file and select the downloaded Ubuntu image file.

  4. Click Next and fill the user credentials.

  5. Edit the virtual machine name and select the location to store virtual machine files.

  6. Select the maximum disk size and click Next. It is recommended to select at least 30 GB.

  7. 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.

Setup Options

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.

Automated Method

Install Software Packages Automatically Using Shell Script.  The support package provides a shell script to automatically install required software packages mentioned in above sections.

  1. Copy the install script from the support package folder location to the Ubuntu virtual machine. The install script installation_script.sh can be located by navigating to the location returned by execution of the following command in MATLAB. 

    fullfile(codertarget.urseries.internal.getSpPkgRootDir,'resources')

  2. 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.sh command. If the script is not executable, make it executable (Right click, select Properties > Permissions > Allow executing file as program).

  3. 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.

Manual Method

Install URSim

  1. 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

  2. Extract the downloaded archive.

  3. Install JDK 8 by executing the following commands in a Linux terminal.

    >> sudo apt-get update 
>> sudo apt-get install openjdk-8-jdk -y

  4. 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

  5. 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.*

  6. 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.

  7. Install the libxmlrpc by executing the following command in a Linux terminal.

    >> sudo apt install libxmlrpc-c++8v5:i386 -y

Install ROS

  1. 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.

  2. Refer Install ROS Packages and Dependencies for ROS to clone and build ROS packages from Universal Robots.

Install SSH Server

  1. Execute the following command in Linux terminal to install SSH server.

    >> sudo apt-get install openssh-server

  2. Execute the following command in Linux terminal to enable SSH server.

    >> sudo systemctl enable ssh

  3. 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.

  1. Download matlab_externalcontrol-1.0.0.urcap from here for R2022b to your local computer. After downloading, copy the file to the programs folder of your URSim.

    Note

    • 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.

  2. 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).

  3. 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.

  4. In the file selector, select the matlab_externalcontrol-1.0.0.urcap file 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.

  5. Restart the URSim simulator.

  6. 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.

  7. Save this installation by overwriting to the default installation configuration. To do so, navigate to Panel > Save > Save Installation.

  8. 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

  1. 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.

  2. 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.

  3. 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.

  4. 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.