Tutorial: MBot System Setup

This guide will walk you through setting up all the code and automated services that allow the robot to run. This guide should be followed once before students begin their course projects. All project instructions assume that the robots have been setup following the steps outlined here.

The Robotics 102 philosophy is that students should be able to get up and running with the robots with as few obstacles as possible. At UM, instructional aides setup the robots for the students. Each offering of the course should choose which installation steps, if any, will be the responsibility of the students. It is beneficial to create an image with the desired setup to save time.

Contents

Prerequisites

For this setup, you will need:

  • A 16 or 32 GB SD card
  • A monitor and a mini-HDMI to HDMI cable
  • A keyboard and mouse
  • An assembled MBot
  • A fully charged robot battery
  • A laptop connected to the internet

Before you begin, install the following on your laptop:

The robot username and password are:

  Username: mbot
  Password: i<3robots!

Step 1: Flashing the Image

In this step, we will get a Raspberry Pi OS image on the robot.

  1. Download Balena Etcher to your laptop.
  2. Download the base Raspberry Pi OS image for the MBot to your computer. This is the standard 64-bit RPi OS image, but we have added a couple configurations (username, password, config changes, and a WiFi script).
  3. Flash the image to a blank SD card using Balena Etcher.

Step 2: Configuring the robot

At this stage, the Raspberry Pi is not connected to WiFi so we will need to configure it using a monitor, keyboard, and mouse.

  1. Prepare the MBot.
    1. Insert the SD card into the Raspberri Pi on your robot.
    2. Plug in a fully charged battery into the MBot. The barrel plug must be plugged into the Robotics Control Board (on the bottom plate), and the USB port must be plugged into the Raspberry Pi (on the middle plate).
    3. Connect the robot to a monitor using the mini-HDMI port located on the side of the Raspberry Pi. Connect your keyboard and mouse to the USB ports on the Raspberry Pi.
    4. Turn on the robot by toggling the battery switch.

  2. Connect to WiFi. At the University of Michigan, this can be accomplished running the setup script in the terminal: bash ./Desktop/SecureW2_JoinNow.run Enter your credentials when prompted. If on a personal network, connect using the network dropdown menu.

  3. Get the system utilities repo on the robot. We will clone a repo onto the robot which has a number of scripts to install necessary dependencies.
    1. Get the robot’s IP address. You will need to use the monitor and keyboard. Open a terminal then type ifconfig wlan0 to get the IP:
    2. Connect to the robot in a VSCode Remote session from your laptop. Instructions are here.
    3. Clone the repo mbot_sys_utils onto the robot. Open a terminal in the VSCode remote session, then do: 
       git clone https://github.com/MBot-Project-Development/mbot_sys_utils.git

      If this is the first time you have cloned a repo with HTTPS in VSCode on your laptop, it will prompt you to give VSCode permission to connect to GitHub and ask you to login on your browser. Follow the prompts to grant this permission. Your credentials will be stored in your laptop’s credential manager. You will not need to enter your GitHub credentials again.

      You must clone this repo in a VSCode terminal! The automated GitHub login will not work in a regular terminal (i.e. using the monitor and keyboard).

  4. Install dependencies and services.
    1. Install the dependencies, including LCM and NoMachine. 
       cd mbot_sys_utils/
 sudo ./install_scripts/install_mbot_dependencies.sh
 ./install_scripts/install_lcm.sh
 sudo ./install_scripts/install_nomachine.sh

      NoMachine is not needed for the MBot code to run, but it is very helpful for debugging later, and is required for these instructions.

    2. Setup the MBot configuration. First, copy the default config from mbot_sys_utils: 
       sudo cp mbot_config.txt /boot/

      Then, edit the config:

       sudo nano /boot/mbot_config.txt

      Give the robot a unique hostname under mbot_hostname. The hostname should match the hostname written on the MBot.

      You can also setup a home WiFi connection in this file, and update the IP registry repo. The defaults will work.

    3. Install the udev rules for the Lidar and Robotics Control Board: 
       cd ~/mbot_sys_utils/udev_rules
 ./install_rules.sh
    4. Install the services needed to start the networking and report the robot’s IP: 
       cd ~/mbot_sys_utils/services
 ./install_mbot_services.sh

    Now, test that everything worked. Restart the robot with sudo reboot. You will need to reload the VSCode remote window. The robot should now publish its IP address to the MBot IP registry (as configured in mbot_config.txt).

    The first time the robot is restarted, it might publish with the username raspberrypi. This should be resolved by rebooting the robot again.

At this point, the robot should publish its IP to the registry each time it turns on. The IP might change occasionally. You can now use VSCode, SSH, or NoMachine to interface with the MBot by using the IP it reports to the registry. You should not need the monitor or keyboard and mouse anymore.

Step 3: Calibrating and Flashing the MBot

Calibrate and then flash your robot following the instructions here.

Step 4: Install the MBot Code

This step will pull all the code utilities for the MBot Web App, SLAM, sensor drivers, and communication with the Robotics Control Board.

  1. Clone the necessary repos. You will need the following repos (you will need access to them):
  2. Install the base MBot code. This includes the message types and serial server which communicates between the Robotics Control Board and the RPi using LCM. The install script will compile the code and install it onto the robot. It will also install a service to automatically start the serial server on startup. 
     cd ~/mbot_ws/mbot_lcm_base/
 ./scripts/install.sh
  3. Install the MBot Web App. The web app is a useful tool for commanding the robot from your laptop’s browser.
    1. Download the latest web app release and unpack it: 
       wget https://github.com/MBot-Project-Development/mbot_web_app/releases/download/v1.1.0/mbot_web_app-v1.1.0.tar.gz
 tar -xvzf mbot_web_app-v1.1.0.tar.gz
    2. Install the web app dependencies: 
       cd mbot_web_app-v1.1.0/
 ./install_nginx.sh
 ./install_python_deps.sh
    3. Build and install the app: 
       ./deploy_app.sh --no-rebuild
    4. It’s now safe to delete the folder mbot_web_app-v1.1.0/ and the tar file mbot_web_app-v1.1.0.tar.gz.

The web app should now be available by going to your browser and typing in the robot’s IP address.

At this point, if the firmware is flashed and the serial server is running, you should be able to drive the robot through the webapp. Toggle drive mode on then use the keys AWSDQE to drive the robot.

  1. Install the RPLidar driver. To install the Lidar driver, do: 
     cd ~/mbot_ws/rplidar_lcm_driver/
 ./scripts/install.sh

    This will pull some code dependencies, compile and install the code, and install a service to start the driver on startup.

  2. Install the MBot Autonomy code. The autonomy code includes SLAM and a motion controller program. Install it with: 
     cd ~/mbot_ws/mbot_autonomy/
 ./scripts/install.sh

    Again, this installs the binaries and services needed to run SLAM and the motor controller.

  3. Install the MBot Bridge and API. The MBot Bridge includes a server that bridges student code with the MBot software, as well as APIs in C++ and Python. Install it with: 
     cd ~/mbot_ws/mbot_bridge/
 ./scripts/install.sh

    This installs the scripts and services needed to run the MBot Bridge Server and installs the MBot API and its dependencies.

Testing the Setup

We’re done! You should test your setup by making sure you can drive the robot around and create a map in the web app.

You should be able to remove all the setup code if desired (mbot_ws and mbot_sys_utils).