Tutorials

Here we provide thorough, step-by-step, easy-to-follow tutorials to help make robotics easy!

1.Introduction

Welcome to our tutorials!

These tutorials are written to support users that run Ubuntu or Windows natively on their remote (aka “off-robot”) desktop PC or laptop. Meaning: if you currently run Windows as your operating system, you can continue to do so, whilst also running ROS on Ubuntu (on the same machine, in a window, as a virtual machine). We provide full details of how to work with our robots, regardless of how your PC is setup (Linux, or Windows). Enjoy!

Yes No

2.Robot Setup

All new robots require some minimal configuration to get them connected to the WiFi network. Here we provide instructions for doing that, and also detail logging into the robot over ssh. Finally, we tele-operate the robot using the PC keyboard.

Yes No

2.1.Pre-Requisites

To proceed, you will need the following items:

  • Your Rhoeby Dynamics robot!
  • An HDMI monitor and USB keyboard
  • Basic Linux skills for file editing, network configuration, etc

These instructions use the Mini-Turty robot as an example, but this process is essentially the same for all Rhoeby Dynamics robots.

Yes No

2.2.Setup the WiFi connection

1. Plug in the following items to the robot:

  • HDMI monitor (into the Raspberry Pi 3)
  • USB keyboard (into the Raspberry Pi 3)

2. Switch on the Mini-Turty, using the switch on the side of the robot

3. Wait for Linux to boot, and for the login prompt to appear on the HDMI monitor

4. Login with the following:

  • user name: ubuntu
  • password: (provided elsewhere)

5. Enable the robot to connect to your WiFi by adding your WiFi network credentials

$ sudo vi /etc/network/interfaces

Modify these lines to match your network:

iface wlan0 inet dhcp

wpa-ssid “Your Network SSID”

wpa-psk “Your Password”

Note: retain the quotes (“”), eg. if your WiFi network is called NETGEAR101, and your password is mypassword, the file entries would look like this:

iface wlan0 inet dhcp

wpa-ssid “NETGEAR101”

wpa-psk “mypassword”

The above are just examples, be sure to put the correct information for your network.

6. Reboot the robot

$ sudo reboot

Wait for the robot to reboot.

Yes No

2.3.Login to the robot over WiFi

1. On the PC, ‘ssh’ into the robot (default robot name is: ubuntu):

$ ssh -l ubuntu ubuntu

Alternatively, in Windows, you could use PuTTY*, as seen here:

* PuTTY is a simple terminal program you can run on any Windows PC, see Installing PuTTY for details.

Enter the robot host name where the red arrow is pointing. Then hit “Open”.

The first time you connect, you may see a dialog box similar to the above. Don’t worry, this is perfectly normal, just hit “Yes” to continue.

Login using the same credentials used earlier.

2. At the prompt, verify you can see the easy start scripts called: ‘mini_turty_init.sh’, ‘min_turty_mapping.sh’ and ‘mini_turty_nav.sh’

$ ls -ltr

You are now logged into your robot over SSH.

Yes No

2.4.Teleop your robot!

1. Unplug the HDMI cable, and the keyboard (if still plugged in).

2. At the ssh prompt, initialize the robot:

$./mini_turty_init

3. Wait for initialization to complete, then initiate mapping:

$./mini_turty_mapping

4. You should now be able to tele-operate (drive) the robot using the PC keyboard arrow keys.

Your robot setup is now complete.

Yes No

2.5.Shutting Down Your Robot

It’s important that you shutdown your robot in the proper manner. Before you can power off the robot, you need to shutdown Ubuntu and put the system into a state where it can be switched off. Failing to do this could corrupt your robot file system!

To power off, type the following command in the terminal session:

sudo halt

Observe the green flashing light on the Raspberry Pi. When it flashes with regular cadence ten times, with the last flash being longer, it is then safe to power off your robot.

Yes No

3.Remote PC Setup

As well as running ROS on the robot itself, users will also want to run another installation of ROS “Off-robot” on a remote PC. This is the best way to visualize many aspects of your robot using a program like RViz. It’s also a great way to gain insight into the operational status of your robot, using tools like rqt_console, ROS topics, and much more.

Yes No

3.1.Standard Setup

The canonical reference for setting up ROS is (of course) to be found at: 

http://wiki.ros.org/ROS/Installation

That webpage provides clear instructions on how to install ROS on an Ubuntu system, and is essential reading.

Yes No

3.2.Why You Might Prefer to Run ROS in a Virtual Machine

If you are new to the world of ROS robotics, and especially if you’re relatively new to Linux, then you may face multiple steep learning curves trying to get started. Perhaps you typically run Windows as your operating system, and the prospect of “going-native” with Linux seems rather onerous, to say the least. Well the good news is, you don’t have to go that route. You can dip your toes in the waters of both Linux and ROS (or even dive right in!) by running a “virtual machine”. Whilst this requires a little effort to get up and running, it will be worth it and you can continue to use your PC much as you previously did: running Windows as your primary OS.

Of course the alternative is to switch out your OS and run Linux natively (ie. booting straight into Linux directly from power on). But that may require a substantial change in the way you work with your PC, and many of the apps you are used to working with will either have to be replaced by the Linux equivalent (and all your files somehow copied over), or you may not have access to them at all. That’s a big price to pay, and one that’s just not necessary.

Pros:
  • Keep your existing Windows-based system
  • Use your favorite Windows-based tools (eg. IDE/editor, PuTTY, CAD program)
  • Linux runs in a window on your desktop
  • If your Linux system has a problem, it does not affect your entire PC
  • Can run multiple versions of Linux and ROS
Cons:
  • Heavy use of complex environments in RViz or Gazebo may function slower

If you know you are going to be doing a lot of complex work in simulation, then a virtual machine may not be for you. However, a great deal of work can be done without that, and you can access many of the functions like mapping, navigation, computer vision and much more using a virtual machine. Besides, if you do find yourself wanting to make heavy use of simulation, well you can always switch over later.

Note: All our robots work with any PC (as well as a phone, tablet or joystick), regardless of whether it runs a virtual machine, or not.

Yes No

3.3.Installing VMware Player on a Windows PC (optional)

Many budding roboticists want to work with ROS running on Ubuntu Linux, but would prefer to use Windows as their primary operating system.

Well, this configuration is certainly possible, and some would consider even preferable, as doing so may get you the best of all worlds! The answer to how to go about that, is to employ a virtual machine. Don’t worry, this may sound complicated, but it’s really quite easy. In this tutorial, we’re going to dive right in and show you how to get setup with ROS, running under Ubuntu in a VMware Workstation Player virtual machine. We’ll start from scratch and provide step-by-step information to guide you through the process.

Install VMware Workstation Player

VMware is an application that users can install on a Windows machine which acts as a kind of wrapper around Ubuntu, allowing it to run like a regular application on the Windows desktop. The free version is available for non-commercial, personal and home use. A google search of “vmware free player” will get you to the site where you can download and install it. I found this page:

VMware Workstation Player 15.0

Select the “Download” button. When you begin the download process (for Player 15.0.2), it will present a dialog box similar to:

Hit “Save File” in the usual manner and save the file to your computer, and then run it. Follow the instructions to install the Player.

Hit “Next”.

Accept the terms and hit “Next”. 

Hit “Next”. 

Hit “Next”. 

Hit “Next”.

Hit “Install”. The setup wizard will run, after which it should report completion.

Assuming you got through that successfully, you can hit “Finish” and you are done with the install of VMware Player!

Running VMware Workstation Player

Check your Windows start menu for the player and start it (or start it from your desktop).

Select “Continue”.

Hit “Finish”.

You are now running VMware Player! Next we’ll tackle creating and running a new virtual machine…

Yes No

3.4.Creating and Running a New Virtual Machine

Having installed VMware Workstation Player, we can proceed to create a new virtual machine.

However, before we create the virtual machine, we will need to have our Ubuntu operating system image stored somewhere on the computer. This tutorial targets ROS Kinetic which is well-tested on Ubuntu 16.04, so we’re going to install Ubuntu 16.04 into the virtual machine. To do this, download the image (.iso file) from:

http://releases.ubuntu.com/16.04/

Here’s a screenshot of that page:

[Hint: A google search of “ubuntu iso 16.04” can get you there.]

You will need to select the appropriate image for your computer. If you have a 64-bit machine, be sure to select the “64-bit PC (AMD64) desktop image”. If you’re not sure whether your machine is 32-bit or 64-bit, hit the right mouse button on the Windows “Start” button, select “System” and scroll down to the “System type” (example for Windows 10).

We’re going to select the 64-bit image.

Select “Save File” and hit “OK”. It will take a little while to download, as it is quite a large file. It has the whole Ubuntu Linux operating system in it!

When it’s done downloading, just make sure you know where the image is being stored on your computer. For example, in the Firefox browser you can select the download arrow (top right corner), hover over the .iso file, then hit the right mouse button and select “Open Containing Folder”.

Starting in the VMware Workstation Player app:

In the VMware Workstation Player app, hit the “Create a New Virtual Machine” selection. Then select the radio button “Installer disk image file (iso)”. Browse to the location where you downloaded the Ubuntu image (.iso file).

Hit “Next”.

Fill in your details for your Linux operating system. Provide your Full name, a new User name and a password (just choose these, according to what you want). Then hit “Next”.

Name your virtual machine (or accept the one offered), and hit “Next”.

As it says in the dialog box, the virtual machine’s hard disk is stored as one or more files on the host computer’s physical disk. ROS along with other items can end up needing quite a lot of space, so I prefer to specify a disk capacity of at least 30 GB. So change the “Maximum disk size (GB)” to 30 and hit “Next”.

We’re going to be using a fair amount of the computer’s resources running ROS in Ubuntu, so we want to customize our use of the hardware resources. So hit the “Customize Hardware…” button.

Here we are going to grab more resources for Ubuntu. They will be “borrowed” whilst the virtual machine is running, and returned back when it is stopped (or paused). Giving more resources is good, but you may want to hold some back so that other Windows apps don’t suffer when the virtual machine is running. For example, you could set:

  • Memory: 4GB
  • Processors: 3
  • Network Adapter: Bridged

The above would represent a good choice for a system with at least 8GB installed and 4 processors. Don’t worry too much about these settings, as they can be changed later. If in doubt, you could safely accept the defaults and review the settings later.

[Hint: you could find out about your computer by hitting the right mouse button on the Windows “Start”, and then selecting “System”. The number of available processors can be found in Windows “Device Manager”]

For the “Network” part, we want Ubuntu to be able to interact with the desktop and the wider network, including the internet. I like to run with a “Bridged” network connection as it allows me to assign a static IP to the Ubuntu virtual machine and have it be visible as a separate device on the network. Again, don’t worry if all this seems tricky. Worst-case, just accept the default (NAT), and come back to it later. For the example, we’re going with “Bridged”. So select “Network Adapter”, then hit the “Bridged” radio button.

Hit the “Configure Adapters” button.


We’re only going to bridge the WiFi adapter, so deselect every other adapter by unchecking the boxes, and hit “OK”, then hit “Close”.

Hit “Finish”. You’re done setting up Ubuntu under VMware!

If you see the following on your screen, do not worry. There is nothing wrong, we just need to do a bit of extra configuration…

Just follow the steps outlined here:

https://www.howtogeek.com/213795/how-to-enable-intel-vt-x-in-your-computers-bios-or-uefi-firmware/

Or do a google search for “intel vt-x is disabled” and find some instructions. Modifying the BIOS is easier than it sounds!

Running your Virtual Machine

The first time you start your virtual machine, you will be presented with a dialog box:

Hit “Download and Install”. Software updates will be installed and then your virtual machine will be running!

[Hint: Let Ubuntu run it’s updates, and be aware this may take some time]

When you see the login prompt, your Ubuntu install is running. Congratulations!

Now go ahead and login using the credentials you specified during the installation.

The first time you login, Ubuntu will likely present you with a dialog box asking you if you want to upgrade. Which is nice, but we don’t want this.

Hit “Don’t Upgrade”. Then hit “OK”. You should now see your Ubuntu desktop running in the VMware virtual machine. The reason we don’t want to upgrade is because our ROS version (Kinetic) demands that we use 16.04.

Next we’ll tackle installing ROS into the virtual machine…

Yes No

3.5.Installing ROS into the Virtual Machine

The ROS install is really quite well documented on the official ROS webpage http://wiki.ros.org/ROS/Installation, so do make that your primary reference! There are some additional pointers that can help guide new users, so here we go.

Begin by logging in to your new Ubuntu Linux system:

Start the Firefox browser and head on over to the ROS Install page (again,
http://wiki.ros.org/ROS/Installation).

Select “ROS Kinetic Kame”.

Select “Ubuntu”.

Follow the steps detailed in the above page carefully.

Begin by opening up a “Terminal” session. You can do this by clicking the top-left icon in your Ubuntu virtual machine, to “Search your computer”. Enter “terminal” as the search term and then click on the terminal icon that appears below the search bar.

At the command prompt, begin entering the commands provided on the ROS Installation page. One can often skip over step 1.1 and go straight to ‘1.2 Setup your sources.list’. Just begin copying and pasting the commands from the gray boxes on the page into the terminal window.

[Hint: you can copy the command with Ctrl-C, and paste it into the terminal with Shift-Ctrl-V]

Keep copying and pasting commands and work you way through the installation.

In step 1.3, I had to substitute the keyserver (the default did not work), so my command looked like:

sudo apt-key adv –keyserver hkp://keyserver.ubuntu.com:80 –recv-key 421C365BD9FF1F717815A3895523BAEEB01FA116

In step 1.4, be very patient! It can look like nothing is happening at times. Also, be sure and select the full desktop install:

sudo apt-get install ros-kinetic-desktop-full

Again, be patient grasshopper.

When the installation finishes, you should see an output similar to the above. You can do a quick sanity check by starting that most elemental of programs:

roscore

Enter the above command in the terminal.

If you see output similar to the above, congratulations! You have started a ROS master (roscore). Terminate this ROS master (Ctrl-C), as we’ll be running the master on the robot going forward.

Yes No

4.Connecting a ROS robot to a remote PC

So you’ve got your ROS robot and setup your remote PC (also running ROS) . You’re getting closer to the fun stuff! Now it’s time to establish a connection between the two, so that you can start using all the cool stuff like mapping, navigation, image recognition and more.

In order to get your PC to inter-operate with your robot, you need to setup the networking between the two machines. This topic is covered quite well here:

http://wiki.ros.org/ROS/NetworkSetup

And, as is typically the case, the ROS wiki should be your primary reference whenever a subject is covered there. Right now, we’re going to go through the network setup process, one step at a time. It would be a good idea to have that page open in another tab and work through it together with the information presented on this page.

As mentioned on the ROS wiki page, there must be complete, bi-directional connectivity between both machines (robot and PC), and this connectivity must be available on all network ports (meaning none are blocked by other devices in the network, such as a router). Furthermore, each machine should advertise itself by a name that the other can resolve. It’s worth re-iterating that although both the robot and the remote PC will be using ROS, there will be only one ROS “master” (more about this later). In this example, we will be using the Mini-Turty Robot and we’ll make the robot the ROS master.

Yes No

4.1.Change Ubuntu Hostname

If you’re running a brand new install of Ubuntu, one of the first things you will want to do is change the system hostname. This is the name the OS uses to identify itself by name on the network. By default it’s set to ‘ubuntu’. That could get to be a common name. So let’s set it to something more descriptive. In our example, we’re going to be running with our Ubuntu virtual machine, so our descriptive hostname could be set to (for example):

vm-ubuntu-01

Starting in a terminal window in Ubuntu:

1. Set the new hostname in the ‘/etc/hostname’ file:

sudo vi /etc/hostname

Edit the file with the new hostname (vm-ubuntu-01 is just an example, you may choose a different name), save and exit.

2. Set the new hostname in the ‘/etc/hosts’ file:

sudo vi /etc/hosts

Change the hostname to vm-ubuntu-01:

Save and exit.

3. Reboot Ubuntu

sudo reboot

4. After the OS restarts, you can verify the new hostname was set by running:

hostname

Your new hostname is now set.

Yes No

4.2.Establishing Basic ROS to ROS Connectivity

Here we establish basic ROS connectivity between our robot and our remote PC.

1. From the remote PC, open a terminal window and ping the robot by hostname:

Above you can see the screenshot of our ‘vm-ubuntu-01’ remote PC pinging our robot named ‘ubuntu’.

[Hint: If you are having trouble getting ping to work with the robot, see the Troubleshooting section Activating Avahi]

2. SSH into the robot (in our example, we’ll do this using PuTTY and the robot hostname ‘ubuntu’):

and type:

roscore

3. With roscore running on the robot (robot is now acting as the ROS master), go to your remote PC terminal session running on Ubuntu, and set the ROS_MASTER environment variable to point to the robot, by typing:

export ROS_MASTER_URI=http://ubuntu:11311

4. List the ROS topics, by running:

rostopic list

5. Check that you can see the topics ‘/rosout’ and ‘/rosout_agg’:

If you see the above topics, then you have basic ROS to ROS (robot to remote PC) connectivity.

6. Determine the IP address of the robot.

To make sure that all nodes in the system can communicate, we need to specify the IP address of the robot. This needs to be done on the remote PC, but first we need to find out what IP address the robot is using (this is set automatically by DHCP, when the robot boots up). So let’s go back to our SSH session on the robot, and type:

ifconfig

In the above example, our robot has an IP address of 192.168.0.33.

7. Set the ‘/etc/hosts’ IP address of the robot on the remote PC, by typing:

sudo vi /etc/hosts

Add the following line to that file:

192.168.0.33 ubuntu

This IP address is just an example. Your robot will likely have a different address.

The above tells Ubuntu (on our remote PC) that the hostname ‘ubuntu’ (our robot name) has the IP address 192.168.0.33.

[Hint: if you shutdown or reboot your robot, you may find when it starts up again that it has been given a different IP address. If this happens you will need to update the /etc/hosts file to reflect the new IP address]

Your robot and remote PC now have full connectivity, and all standard ROS functions should be available to both machines.

Yes No

5.Miscellaneous

5.1.Installing PuTTY

PuTTY is a simple terminal program you can run on any Windows PC, see:

https://putty.org

It does a great job at providing a client for SSH, telnet and serial port console. On visiting the above URL, you’ll be presented with a screen similar to:

Select “here” (see red arrow).

Select one of the MSI (“Windows Installer”) links (see red arrow), according to if your system is 32-bit or 64-bit. If you’re not sure, the 32-bit version is generally the safe option.

Hit “Save File”. Then open the file.

Hit “OK”.

PuTTY is a well-respected application that is generally safe to install. As long as you downloaded this file from putty.org, it should be fine.

Hit “Run”.

Hit “Next”.

Hit “Next”

Hit “Install”.

Hit “Finish”. Then find PuTTY on your Windows start menu and run it.

PuTTY is now running.

Yes No

6.Troubleshooting

6.1.Activating Avahi

Sometimes local hostnames fail to resolve on the local network. If you are having trouble pinging your robot, this might be the cause. Try the following commands to get things working:

systemctl is-active avahi-daemon.service

Then restart the Avahi service:

systemctl restart avahi-daemon.service

Yes No