Students: You should not need to set up an image from scratch! Check with your instructor for the link to the OS image for your class. Then, start the setup process by installing the image.

This guide is intended to help you set up a new Raspberry Pi image from the base MBot image.

Note: The base image has the following login credentials:

  • Username: mbot
  • Password: i<3robots!

Starting from a base Raspberry Pi OS image? The MBot Base Raspberry Pi image is a Raspberry Pi OS 12 (Bookworm) image with the MBot standard system utilities set up. See the instructions for this setup on GitHub.

1. Flash the image

  1. Download the base MBot Raspberry Pi image from this link. We use a custom image with RPiOS based on Debian 12 Bookworm. It has been configured with the MBot System Utilities instructions.
  2. Download Balena Etcher then flash the OS image to your SD card. Plug in the SD card to your laptop using SD card reader then following the steps in Balena Etcher.

You now have an SD card with the OS image flashed on it for the Raspberry Pi. Keep the card in your laptop for now and proceed to the next step.

Warning: If you use a Windows computer, you may see many file explorer windows and error messages pop up when you insert the SD card and when you finish flashing. Those are expected, and you can safely close the file explorer windows and dismiss the error messages. However, if Windows asks you to format the SD card through a popup dialog box, close the message through the “Cancel” button and do not click the “Format Disk” button.

2. Configure the image

If the flash succeeded, the SD card will have two partitions: a 134MB Volume formatted as fat32 and a 16GB Volume formated as ext4. When you insert the SD card in your laptop, it should mount the smaller fat32 partition. Find the file mbot_config.txt on this volume and modify it as follows:

  • Set mbot_hostname to a unique hostname for your robot. Tip: If you are setting up an MBot fleet (e.g. for a course) you may want to set a naming convention for the robots to keep track of them more easily, like mbot-fleetname-XX. You can then fill in XX for each robot later from your image.

Set up WiFi

For the following steps, you will need to connect to your robot remotely. To do that, your laptop and the robot must be on the same WiFi network.

See the Networking Guide to choose how your robot will connect to the network.

If you are using a standard password-protected network: Enter your WiFi details in mbot_config.txt.

  • new_wifi_ssid is the name of the WiFi network.
  • new_wifi_password is the password for the WiFi network.

If you are using an institutional or enterprise network: If your WiFi connection requires you to log on (e.g. a university WiFi network), you will need a monitor on first boot to log in to the WiFi. Proceed to Step 3.

Determine how to get your IP address

In order to connect to the MBot in the next steps, you will need a way of knowing the robot’s IP address. See the Networking Guide for details on how to make this choice.

If you are using the MBot’s display or getting the IP from the SD Card: This is set up by default on the MBot base image. No further action is needed. Go to Step 3.

If you are using an IP registry: Enter the details of your IP registry in mbot_config.txt:

  • mbot_ip_list_url is the URL to the IP registry on GitHub for your fleet of robots. It should be in the form https://github.com/<my-org>/mbot_ip_registry.git.
  • mbot_ip_list_user is the username for the account that will manage publishing the data to the registry for your fleet.

  • mbot_ip_list_token is a token for the GitHub account.

    See the Networking Guide for details on setting up an IP registry if you have not already done so.

3. Boot the robot

  1. Insert the SD card into your Raspberry Pi. The SD card slot is located on the bottom on the side opposite the USB ports.

    Image from RPi Foundation

  2. Turn on the power bank and ensure that the power cables are connected as per the assembly guide.

  3. If you need to manually log in to WiFi: Connect your robot to a monitor, keyboard and mouse. Log in to WiFi manually. Restart the robot.

    If you set up a WiFi connection in Step 2: Skip to #4.

  4. Allow a few minutes for the robot to initialize (this is slow on first boot). Once the initialization is complete, get the MBot’s IP address from the MBot display or from the IP registry.

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 MBot Control Board. For this part, you should first connect to your robot using VSCode and open a VSCode terminal.

  1. Clone the necessary repos. You will need the following repos:

    In a terminal on the MBot (using a VSCode Remote session), do:

     mkdir ~/mbot_ws
 cd ~/mbot_ws
 git clone https://github.com/mbot-project/mbot_lcm_base.git
 git clone https://github.com/mbot-project/rplidar_lcm_driver.git
 git clone https://github.com/mbot-project/mbot_bridge.git
  2. Install the base MBot code. This includes the message types and serial server which communicates between the MBot 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/
 git checkout v1.0.0
 ./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: 
       cd ~/mbot_ws/
 wget https://github.com/mbot-project/mbot_web_app/releases/download/v1.3.0/mbot_web_app-v1.3.0.tar.gz
 tar -xvzf mbot_web_app-v1.3.0.tar.gz
    2. Install the web app dependencies: 
       cd mbot_web_app-v1.3.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.3.0/ and the tar file mbot_web_app-v1.3.0.tar.gz.

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

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

  5. 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/
 git checkout v1.0.0
 ./scripts/install.sh

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

  6. Optional: Install the LCM Monitor: The web-based LCM monitor is a useful tool for viewing all the published LCM channels and their data in the browser. To install it:
    1. Download the latest release and unpack it: 
       cd ~/mbot_ws/
 wget https://github.com/mbot-project/mbot_lcm_monitor/releases/download/v1.0.0/mbot_lcm_monitor-v1.0.0.tar.gz
 tar -xvzf mbot_lcm_monitor-v1.0.0.tar.gz
    2. Install the app: 
       cd mbot_lcm_monitor-v1.0.0/
 ./deploy_app.sh --no-rebuild
    3. Follow the printed instructions (which you can also find in mbot_lcm_monitor-v1.0.0/README.txt) to configure NGINX.
    4. It’s now safe to delete the folder mbot_lcm_monitor-v1.0.0/ and the tar file mbot_lcm_monitor-v1.0.0.tar.gz.
  7. Optional: Install the MBot Autonomy code. The autonomy code includes SLAM and a motion controller program. You need access to this repository to download it. Install it with: 
     cd ~/mbot_ws/mbot_autonomy/
 git checkout v1.0.0
 ./scripts/install.sh -t <TYPE>

    Replace <TYPE> with DIFF for the classic, or OMNI for the Omni. Again, this installs the binaries and services needed to run SLAM and the motor controller.

    Warning: If you are using the classic, there is a known issue where motion_controller interfers with other scripts. You may want to disable mbot-motion-controller.service.

5. Change the password

For network security, we encourage you to change your password once you have set up your MBot. The default password is i<3robots!, which everyone uses. You should pick a unique password for your fleet. Here’s how to change your MBot’s password:

  1. Open a VSCode terminal in the VSCode Remote session to the robot on your laptop.
  2. Enter this command: passwd. You will be prompted to enter your current password.
  3. Next, you will be asked to enter your new password and retype it to confirm.
  4. If the passwords match, you will see a message indicating that your password has been updated successfully.

The output will look like this:

$  passwd
Changing password for mbot.
Current password:
New password:
Retype new password:
passwd: password updated successfully

Testing your setup

You test your setup by calibrating the robot and flashing the firmware onto the MBot Control Board. Then you should be able to drive your robot.