Set up MATLAB for UR Development

The purpose of this document is to demonstrate how to set up a connection between MATLAB and a physical UR robot or URSim. This guide solely focuses on establishing a connection of a UR arm through MATLAB. For documentation on programming, please see the Get Started UR Series from MathWorks.

Prerequisites / Software installation

Matlab 2023a (or superior) Setup:

  1. Install Matlab 2023a from the MathWorks site.

  2. Add the required addons:

    • Robotics System Toolbox Support Package for Universal Robots UR Series Manipulators.

    • ROS Toolbox.

    • Robotics System Toolbox.

Install Ubuntu 20.04 or 18.04

Setup a virtual machine

  1. Download and install VMware workstation player.

  2. Download Ubuntu 20.04.

  3. In the VMware workstation player, create a new virtual machine.

  4. Choose the Ubuntu 20.04 installation image in the wizard.

  5. Click next and follow the wizard’s installation instructions:

    1. Fill out user credentials.

    2. Select name for the virtual machine and where to store them.

    3. Select disk size. Minimum 30 GB is recommended.

  6. When finished, the Virtual Machine launches.

Install ROS, ROS driver and prerequisites for ROS driver host machine:

Option 1 - Automated script:

  • MATLAB provides an automatic installation script. This script can be located by executing the following command in the MATLAB command line:

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

  • Copy the script into the ROS host machine. Make the script executable and run it. This will automatically install ROS, the ROS driver and URSim:

chmod +x installation\_script.sh

./installation\_script.sh

Troubleshooting:

The automated script might fail to install the required prerequisites or its dependences properly:

  • If catking workspace hasn´t been created manually run its creation. Open a terminal on the ur_ws folder located at the home directory and execute:

rosdep update

rosdep install --from-paths src --ignore-src -y

catkin\_make

Option 2 - Manually install prerequisites:

Perform the installation of all prerequisites manually:

Install URsim

  • URSim is available for CB-Series and e-Series. Download the installation archive from UR download section. This step requires 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 commands in a Linux terminal.

sudo update-alternatives --config javac

sudo update-alternatives --config java

  • Verify the Java® version by executing the following command in a Linux terminal, the version should be 1.8.

java -version

  • 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

  • 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. Follow the instructions to clone and build ROS packages from Universal Robots:

    • Create a new workspace with src folder. This command will make a new catkin folder ur_ws inside the home directory.

mkdir -p ~/ur_ws/src

cd ~/ur_ws

    • Install git by executing the following command:

sudo apt install git -y

    • Download the ROS driver packages by executing the following command in the Linux terminal.

git clone https://github.com/UniversalRobots/Universal_Robots_ROS_Driver.git 
src/Universal_Robots_ROS_Driver

    • Download the Gazebo simulation related packages by executing the following command in the Linux terminal.

git clone -b calibration_devel https://github.com/fmauch/universal_robot.git src/fmauch_universal_robot

    • Install dependencies from the custom ROS packages by executing the following commands in the Linux terminal.

sudo apt update -qq

rosdep update

rosdep install --from-paths src --ignore-src -y

    • Build the workspace using catkin tool. This will take a few minutes to complete.

catkin_make

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 SSH start server.

sudo systemctl start ssh

Configurate the environment

  • Install MARLAB URCap for External Control

  • Set up the robot Network automatically using DHCP. Or manually configurate it as static IP if ethernet local network is configured, e.g:

  • Ip address: 197.168.1.10

  • Subnet mask: 255.255.255.0

  • Default Gateway: 192.168.1.100

  • Preferred DNS Server: 0.0.0.0

  • Alternative DNS Server: 0.0.0.0

  • If the Universal Robots hardware is connected to an external host running ROS, and the host running MATLAB® is separate, use the following environment variable to set the MATLAB global node’s advertised address. The IP must be the IP of the system running Matlab. (MATLAB command line)

setenv(‘ROS_IP’,’192.168.1.100’)

  • Configure the URCap addresses for the robot and the ROS device address.

  • Create a new program and add a node with the MARLAB URCap for External Control.

  • Set the robot in remote control mode.

Verify the environment

Make sure the commutation between the systems is successful. In MATLAB, navigate to the Manage Add-Ons section:

Then open the configuration option for the Robotics System Toolbox Support Package for Universal Robots UR Series Manipulators:

The Add-on wizard will then open:

Follow the steps, remembering the device machine IP is the IP of the machine where the ROS driver is installed and the robot IP must be either the UR robot IP or the IP of the machine where the simulator is running (Gazebo or URsim). You should be able to fetch the positions of the joints on the robot.

Controlling and connecting an UR5e

MATLAB provides an example on how to get started with controlling an UR5e. To open the example, execute the following command:

openExample('urseries/GettingStartedControllingSimulatedUR5eExample')

Otherwise, it is available here: Getting Started with Connecting and Controlling a UR5e Cobot from Universal Robots

Additionally, you can create your own live script and create your program manually:

  • Load rigid body tree model for Universal Robot UR5e robot manipulator.

clear;

ur5e = loadrobot('universalUR5e');

*   Set the interface variable and the addresses variable:

% Interface (‘Hardware’, ‘URSim’, ‘Gazebo’)

Interface = “Hardware”  
% IP of ROS enabled machine  
ROSDeviceAddress = '192.168.92.132';  
% IP of the robot (if using URSim, the IP address will be 127.0.0.1)  
robotAddress = '192.168.1.10';

  • Make sure the external control URCap is on the program as required, and that the robots or URSim are set on external control mode.

  • Provide parameters of the host machine with ROS.

username = 'user';

password = 'password';

ROSFolder = '/opt/ros/melodic';

WorkSpaceFolder = '~/ur_ws';

  • Connect the ROS driver.

device = rosdevice(ROSDeviceAddress,username,password);

device.ROSFolder = ROSFolder;

  • Generate launch script and transfer it to ROS host computer.

generateAndTransferLaunchScriptGettingStarted(device,WorkSpaceFolder,interface,robotAddress);

  • Launch the required nodes if the ROS core is not running.

if ~isCoreRunning(device)  
w = strsplit(system(device, 'who'));  
displayNum = cell2mat(w(2));  
system(device,\['export SVGA\_VGPU10=0;' 'export DISPLAY=' displayNum '.0; ' './launchUR.sh &'\]);  
pause(10);  
end

  • Initialize the ROS interface.

ur = urROSNode(ROSDeviceAddress,'RigidBodyTree',ur5e)

If everything is successful, the robot, either on the simulator or the real hardware, is ready to receive commands:

  • Read different values from the robot. Use the following command to read the current angles of the robots with a specific timeout and show the robot in its current joint configuration:

jointAngles = getJointConfiguration(ur,10)

show(ur.RigidBodyTree,jointAngles);

  • Command the robot. Create an array of the six joints position in a range from -pi to pi for all and use them as a parameter for the sendJointConfigurationAndWait function. Specify a timeout to perform the motion. The result output will indicate the success or failure of the command, and the state output will contain more information about the robot motion.

jointWaypoints = [0 -90 0 -90 0 0]*pi/180;

[result,state] = sendJointConfigurationAndWait(ur,jointWaypoints,'EndTime',5)

More functions for fetching data from the robot and commanding actions can be found at the MATLAB resources.