Exercise 1 - Setup

Published: Monday Sep. 23, 2024.

Due: Friday Oct. 3, 2024

In this exercise you will set up and calibrate your robot and laptop so that you can successfully complete the later exercises. There is a lot to read in this exercise (reading is probably the majority of the job), but it is important that you do it diligently or you will very likely run into problems later that may be hard to diagnose.

Part 1: Software Setup

Ready to get started? Your first task is to set up your development environment.

This document summarizes the steps that you need to do. Usually the details are in one of our Duckiebooks at the site docs.duckietown.org/ente/.

Make all the accounts

At some point, in the next steps, you will need the following accounts:

Github account. Needed for checking out the code. Sign up here if you don’t have an account already. It is also strongly suggested that you set up a ssh key.

Dockerhub account. Sign up here if you don’t have an account already.

Duckietown account. Sign up here.

Laptop setup

Follow these instructions including Steps 1-3 in the left hand sub-menu.

At the end of the instructions, you will have installed some essential software, such as

  • Docker

  • The Duckietown Shell

Make sure you finish the previous step before continuing!

Follow these instructions to set up your local environment with the Duckietown token. Follow Step 0 on that page and Steps 1 and 2 on the left hand sub-menu.

Note: Make sure to generate a DT1 token.

Checkpoint!

Before we go on, this is a checkpoint to make sure you have installed everything.

If some of these commands don’t work, please go back and fix it before continuing.

If the Docker installation went well, then you can run the following command:

> docker run hello-world
Hello from Docker!
This message shows that your installation appears to be working correctly.

If you set up a Github account and private key, you should be able to run this command successfully:

> ssh -T git@github.com
Hi GITHUB_USERNAME! You've successfully authenticated, but GitHub does not provide shell access.

If you have a valid DockerHub account then you can login as follows.

> docker login -u DOCKER_USERNAME
Password:

If the Duckietown Shell was installed, then you can run a command like this:

> dts version

If there is something not working, please stop here. Ask for help on Discord.

Part 2: Robot Setup

Duckiebot assembly and handling

For most of you, the students from a previous year assembled the robots for most of you. You shouldn’t assume that they did everything correctly.

Initialize your SD card (requires Linux)

As you lay the Duckiebox components on your working surface, take the micro sd card from the Duckiebox (along with the SD card adapter if needed) and follow these instructions to initialize the Duckiebot’s operating system from the computer you have previously set up.

IMPORTANT For the --configuration put DB21J. You may list several WiFi networks but you will want to include DaffyTown:iuu4EyjwRArSBYgQeGHw5AwihJis2T2Nv5sURFW which is the SSID and password of the network in the lab (you could also include your lab’s or your home network credentials if you plan to work in those places). The hostname should be the name that you told Liam when you received your Duckiebot and should match the label on the side of your box.

At the end of this step you will have an initialized and verified SD card. This does take some time.

Verify the Assembly of your Duckiebot

If your robot did not come assembled, you should follow these instructions to assemble it. If your robot came assembled, you should go through those instructions anyway to make sure your robot was assembled correctly.

At then end of this step you should have a correctly initialized, fully charged, ready to go Duckiebot. Don’t forget to put the second label that we gave you onto your duckiebot somewhere. Feel to customize your robot if you like.

Take a picture of your Duckiebot and post it in the Discord channel duckiebot-selfies.

Duckiebot handling

Before delving in the middle of things, let’s learn how to perform fundamental operations for Duckiebot handling, such as powering it on and off, recharging it, and keeping the hardware up to date.

Follow these instructions to learn about Duckiebot handling.

Checkpoint

At this point you should be able to:

  • turn your Duckiebot on for the first time and see the screen on the top turn on showing basic diagnostics, and the LEDs turn white. This can take a little bit of time especially the first time. The button to turn the robot ON is the black one on the side.

  • find your Duckiebot on the network by typing:

     > dts fleet discover
        |   Type    | Model |  Status  |  Internet  |  Dashboard  |  Hostname
   ---- | --------- | ----- | -------- | ---------- | ----------- | ----------
   ![YOUR_ROBOT_NAME] | duckiebot | DB21J |  Ready   |    Yes     |     Up      | ![YOUR_ROBOT_NAME].local

it might take a few seconds for the discovery to happen.

You should moreover be able to turn off your Duckiebot by pressing the button on the top plate (and holding for about 4 seconds).

If you have problems with this step, please ask a question on Discord.

IMPORTANT: To make sure you get the latest images that might have changed since we pushed the last official image release, on your laptop do:

> dts duckiebot update <robot_name>

This may also take some time.

Report your MAC address (only necessary if you built your robot from scratch)

In order for your robot to be able to connect to the network in the lab, we need to know its MAC address. To obtain it, ssh into your robot:

> ssh duckie@<your_hostname>.local

if you are asked for a password it is quackquack.

From there you can run the command

> ifconfig

to find the MAC address. Once you have found it please post a message with in the Discord channel duckiebot-mac-addresses.

Passwordless SSH

If you created SSH keys for Github (you should have), then you can copy those ssh-keys onto your robot so that you don’t need to enter a password everytime you do ssh or rsync:

> ssh-copy-id duckie@ROBOT_NAME.local

and then put in the password of quackquack once prompted (unless you changed it).

Change the NTP server on your robot (specific for working the UdeM lab)

For some inexplicable reason, the university has blocked access to NTP servers, which are used to keep the time on your computer up to date. They do however provide their own NTP server that we can use.

Do the following on your Duckiebot (through SSH):

> sudo timedatectl set-ntp no
> echo "NTP=tic.iro.umontreal.ca" | sudo tee -a /etc/systemd/timesyncd.conf
> sudo timedatectl set-timezone America/Montreal
> sudo systemctl restart --now systemd-timesyncd.service
> sudo systemctl enable --now systemd-timesyncd.service

Test that everything has worked by typing the command:

> date

And verify that the result is accurate.

Setup the dashboard

In addition to the Duckietown Shell, which is a terminal based interface, the Duckiebot is equipped with a browser based interface too: the “Dashboard”, which is at the URL `http://ROBOT_NAME.local. Once you finish the setup and login you should see several things on the list on the left. The most useful are “File Manager” where you can see files that are stored on your robot, Portainer, which is a visual Docker interface and shows you information about things like which containers are running, and “Robot” which shows you diagnostics about your resource usage as well as other things (for example under the “Mission Control” tab you should see a stream from your robots camera).

You can follow these instructions to set up the Dashboard.

Get familiar with the dashboard

After successfully logging in, you can follow this tutorial providing an overview of the functionalities included in the Dashboard.

After this step you should be able to orient yourself through the Duckiebot graphical user interface and access stored files, view running containers, see hardware diagnostics and the camera data stream.

Make the Duckiebot move

We are ready to have the Duckiebot move! Remotely control your Duckiebot by following these instructions.

See what the Duckiebot sees

We used Dashboard to view the camera image stream, but to see what the Duckiebot sees, we need a different approach. Follow these instructions to view the camera data from terminal.

Make it Shine

The robot is also equipped with 4 LEDs that we can control. Follow these instructions to make sure that you can control the LEDs.

Checkpoint

At this point you are able to drive your Duckiebot around while comfortably sitting at your computer. You are able to see what the robot sees through browser or terminal. You might also be interested to check out some of the software tools which we will be using.

🤔 If you have problems with making your Duckiebot move or see, please ask on Discord.

Calibrate the Wheels

When you command your robot to go straight you might notice that it doesn’t really go straight. Follow these instructions to calibrate the wheels. You really don’t need to be obsessive about this - the robot won’t always drive straight. Just make it drive reasonably straight.

Calibrate the Camera

Every camera is different and you might have installed it a lit bit differently. Follow these instructions using the calibraiton pattern that came in your box or is in the lab to calibrate your camera.

Checkpoint

You should be able to see your calibration files in the file manager in the dashboard. Download them to your local computer and store them somewhere safe (this will be useful so that you can reuse them if you need to reburn your SD card).

Part 3: Writing a ROS Node to Drive your Robot

Getting Started with the dts code API

Fork the lx-ros-basics repo and clone it onto your computer:

> git clone git@github.com:![YOUR_GIT_USERNAME]/lx-ros-basics.git

Set up an upstream remote. From inside the directory you just cloned:

> git remote add upstream git@github.com:duckietown/lx-ros-basics.git

Now to pull anything new from the original repo you can do:

> git pull upstream main

To enter the lx-ros-basics folder that you just cloned do:

> cd lx-ros-basics

Notebooks Walkthrough in VSCode

To start going through the Jupyter notebooks inside the VSCode environment type:

> dts code editor

This should open the browser. You can follow the intsructions in the README and go through the notebooks. The final notebook will ask you to build a ROS node for controlling your robot. To test it you will need to go back to your laptop and execute:

> dts code workbench --duckiebot DUCKIEBOT_NAME

where DUCKIEBOT_NAME should be the name of your Duckiebot.

This should also give you a link to a novnc server that you can also open in the browser. From here you can monitor and interact with your environment using ROS tools. For example, ppen up the rqt_image_view, resize it, and choose /agent/camera_node/image/compressed in the dropdown. You should see the image from the robot.

You can also open up a “Joystick” using the icon on the left hand side of the desktop, and, if you did I good job creating your node, you should be able to use it to make your robot move.

Getting Help!

Please report problems quickly on discord, in class, on Stack Overflow, as github issues, etc. If you are not sure if something is working properly ask. Don’t spend hours trying to fix it first.

Final Deliverables

  • A properly assembled robot (1pt)
  • Your laptop is correctly configured (1pt)
  • Your robot drives relatively straight (1 pt)
  • Your camera is calibrated (1 pt)
  • Your ROS node moves your real robot (2pt)