Skip to content

Getting Started

Please read this page in full before you do anything else!

Introduction

MiRo Developer Kit (MDK) is a ROS-based software package that includes everything required for working with a MiRo robot, either simulated or physical. MDK requires a specific version of the Robot Operating System (ROS) — the middleware layer that powers the robot. Throughout this course you will be working with the most up-to-date version of ROS1: ROS Noetic Ninjemys (or "ROS Noetic" for short). Every version of ROS is tied to a particular version of the Ubuntu Operating System. While it's possible to run ROS on other operating systems (including Windows), we have opted for Ubuntu for stability, reliability and ease! ROS Noetic runs on Ubuntu 20.04 (Focal Fossa).

The three MDK profiles

When working with MiRo and MDK it is useful to define three 'profiles', which describe different ecosystems. These three profiles are 'on-board', 'off-board', and 'simulator'. The 'simulator' profile refers to working in simulation without the use of a physical robot; while 'on-board' and 'off-board' refer to the way the software is used to control the robot, which can either run 'on-board' the robot, or run 'off-board' on your workstation, communicating with the robot over Wi-Fi. Software written for one profile is suitable for use with the others, and what you learn working in one profile will be applicable to the others. A small number of caveats regarding compatibility and profile limitations are described below, along with the pluses and minuses of each approach.

Simulator

The 'simulator' profile is the simplest to start since it doesn't require a physical robot, and this is what you will use in the first lab session. For this course we have created a custom ROS and Ubuntu 20.04 environment which runs as a virtual machine on Windows, using the Windows Subsystem for Linux (WSL). Throughout this Wiki we refer to this as the "WSL-ROS Environment" or "WSL-ROS".

Important

Please browse through the dedicated WSL-ROS section of this website to learn more.

The WSL-ROS comes with the MDK package and all the dependencies pre-installed, thus requiring no additional setup procedures. However, with all the perks there is a downside — a lack of graphical accelerator available to the virtual machine. This means that Gazebo graphical simulator is forced to run on the CPU, which might result in a suboptimal performance and relatively low FPS. For those of you who prefer to have more control and flexibility, we have provided instructions on how to set up an equivalent environment on your machines. More details about specific WSL-ROS setup for COM3528 are given below.

Info

It is also possible to work in simulation on the Diamond laptops, which natively run Ubuntu.

Warning

The simulated robot lacks some of the functionality present of the physical robot: touch and audio sensors, audio output, and illumination output are not implemented.

Off-board

Off-board profile is when you develop the code on a laptop or a workstation and then use a remote connection to control the robot from that device. Unfortunately, due to University network settings at the moment it is not possible to control the robots via the CR3 workstations running WSL-ROS. To overcome this, for the off-board profile we have prepared exactly the same OS/Software as the WSL-ROS environment, i.e. Ubuntu 20.04 and ROS Noetic on the dedicated Diamond laptops that we have in the robotics lab.

On the laptops there is a 'student' user account that you should use when working in the lab. The laptop should log you into this user account automatically on startup, but we will provide you with the account password as well, during the lab sessions, should you need it. The laptops, along with more detailed instructions will be given out in the second lab session.

On-board

On-board profile refers to the way of controlling the robot when a user establishes a remote connection with the robot (e.g. via SSH) and all the ROS nodes and the rest of ROS infrastructure are run on the robot.

Info

MiRo's 'brain' (Raspberry Pi 3B+) still runs on an older Raspbian version (akin to Ubuntu 16.04) and has and older ROS version — Kinetic Kame. This version of ROS has limited support for Python 3, which is important to remember when running the code 'on-board'.

Profiles comparison

Profile Characteristics
On-board No reliance on the network once controller is running, can be useful for multiple robots or field robotics. Control is at low latency and with no bandwidth concerns. Development cycle is slower and compile-times, if using, are long. Overall compute power is limited.
Off-board Requires network at run-time, which can introduce variable latency and limited bandwidth. Development is convenient and rapid and compiling is fast. Compute power can be scaled.
Simulator No requirement for physical robot, so no effort on maintenance and repair. Imperfect match with the real world, some faculties missing. Compute power can be scaled, sub-real-time can be used to scale also.

The Simulation Environment (WSL-ROS) for COM3528

You will start your work in simulation (i.e. simulator profile) using the WSL-ROS environment.

Abstract

Please make sure to read carefully the whole section on WSL-ROS (even if you have done COM2009 the year before!)

Before proceeding further, check that you know/remember how to:

  1. Find and launch the WSL-ROS environment on selected machines
  2. Configure the IDE of our choice (VS Code) to work with WSL-ROS
  3. Use the WSL-ROS version of the Windows Terminal
  4. Back up and restore your data
  5. Access WSL-ROS remotely

WSL-ROS settings for MDK

Switching between MiRo and TB3 robots

Note

The default ROS settings in the WSL-ROS settings environment are those used for COM2009 labs, and are tailored for the Turtlebot3 robot.

We have prepared a few helpers scripts that would automatically change the settings between TB3s and MiRos, without the need for a user to manually change anything in the ~/.bashrc. To switch to the MiRo profile, simply type in the terminal:

  robot_switch miro

It is very easy to distinguish which profile is being used at the moment by opening a new terminal window: the TB3 profile will simply show a prompt, while the MiRo profile will show an info screen with all the current MDK settings.

WSL robot switch

If you have any other terminal windows open make sure to either restart them or re-source the profile by using an alias $ src, which is shorthand for $ source ~/.bashrc to apply the latest settings.

Tip

I always restart all the terminal instances after switching the settings in this manner — better safe than sorry!

Switching between physical and simulated robot

The robot_switch script has a counterpart, called robot_mode. This second script allows you to easily switch your ROS network settings between working with a physical robot and a simulated one.

Note

This script is usually not available on the WSL-ROS machines, but is present on the Diamond laptops. It can also be optionally installed on your own machine, as part of the MDK installation kit.

It's very simple to use, you just pass onto it one of the two accepted options: robot or sim; we'll cover the robot option later. For now, if you do have this script installed, make sure to switch to working in the simulator:

robot_mode sim

WSL robot mode

Summary

On this page, we have looked at the three ways how one can develop programs with the MiRo Developer Kit. The "simulation" profile was chosen as the one to start with, since it's the easiest to learn and doesn't require a physical MiRo. We have also looked at the specialist WSL-ROS environment, which was prepared to make sure that the required software is easily accessible to you, both on and off campus.

Success

You are all set up and ready to go!

Now head on over to MDK Overview to get started on this lab course!