Exercise 1 - Setup

Published: Monday Sep. 12.

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.

Software

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/daffy/.

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.

Dockerhub account. Needed for submitting exercises. Sign up here if you don’t have an account already.

Duckietown account. Needed to gain access to the autograder and many other features. Sign up here.

Stack Overflow account. Needed to gain access to our private Stack Overflow. You should have gotten an invite already. Ask the professor if not.

Laptop setup

Follow these instructions.

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

  • Docker

  • The Duckietown Shell

🤔 If you have problems with this step, please ask a question on our Stack Overflow with tag #laptop-setup.

NEW: Please set your version to daffy with the command:

> dts --set-version daffy

Make sure you finish the previous step before continuing!

Follow these instructions to set up your local environment with the Duckietown token.

Also make sure to tell the “challenges API” (this is what we will use to submit exercises) about your docker config:

> dts challenges config --docker-username yourusername --docker-password yourpassword

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 you correctly configured the token, then this command should work:

> dts challenges info
~        You are successfully authenticated:
~
~                     ID: YOUR ID
~                   name: YOUR NAME
~                  login: YOUR DUCKIETOWN ACCOUNT 
~
~         You can find the list of your submissions at the page:
~
~              https://challenges.duckietown.org/v4/humans/users/YOUR ID

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

Hardware

Duckiebot assembly and handling

Luckily the students from last year assembled the robots for you. You shouldn’t assume that they did everything correctly. We have tried to ensure that all the robots are in a fully correct state but it is up to you to verify.

Initialize your SD card (requires Linux)

The Duckiebot is a scaled differential drive vehicle powered by a small but powerful computer, the NVIDA Jetson Nano. Before assembling the robot, we can start setting up the hard drive memory disk of the Duckiebot’s onboard computer.

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 memory 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 the professor 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

⚠️ The Duckiebot is equipped with a lithium-ion battery, like a typical power bank for charging phones. These batteries can be dangerous if mishandled. Read Sec. 1.1 here to learn what to do and not do with a lithium-ion battery, and more about the Duckiebattery.

You can follow these instructions to see how the Duckiebot should be assembled and verify that everything was done correctly. Any mistakes should be corrected now. All the tools necessary for the job are included in the box.

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.

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.

IMPORTANT: Note that you should update the Duckiebattery as described in section 5.5.

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.

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

If you have problems with this step, please ask a question on our Stack Overflow with tag #DB21J.

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>

Report your MAC address

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.

Duckiebot user interface and operation

Now that we have a Duckiebot on the network it is time to learn how interact with it.

In addition to the Duckietown Shell, which is a terminal based interface, the Duckiebot is equipped with a browser based interface too: the “Dashboard”.

The Dashboard allows to interact with live camera stream, software running on the robot, real time diagnostics and more in an intuitive way.

Setup the dashboard

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, running containers, hardware diagnostics and camera data stream.

Take some time to explore your Duckiebot’s different functionalities. What are the containers running? What messages are being passed around?

🤔 If you have problems with these first two steps, please ask a question on our Stack Overflow with tag #dashboard.

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.

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.

🤔 If you have problems with making your Duckiebot move or see, please ask a question on our Stack Overflow with tag #DB21J-ops.

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.

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 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 (this will be useful so that you can reuse them if you need to reburn your SD card).

Getting Started with the Exercises API

Fork the mooc-exercices repo and clone it onto your computer. Set up an upstream remote. From inside the directory you just cloned:

$ git remote add upstream git@github.com:duckietown/mooc-exercises.git

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

$ git pull upstream <branch_name>

To enter the mooc-exercises folder that you just cloned do:

$ cd mooc-exercises

Now switch to the daffy branch.

$ git checkout daffy

For now we are going to be in the ros-template exercise

$ cd ros-template

The Anatomy of an Exercise

The things that are important for now:

  • Inside the solution folder is where your code is going to live. Specifically in the src subdirectory. This is where you can add things (it’s empty for now). In some of the other exercises there are also notebooks that can be useful.
  • In launchers you will see some bash scripts that launch your code. Specifically, the dts exercises test command is configured to run the one called run.sh and the dts challenges (more on this in a minute) is setup to run the one called submit.sh
  • In the assets folder are some other useful things. For example in the assets/setup folder are a bunch of .yaml files that contain environment variables that are loaded when you run with dts exercises test
  • There’s also a Dockerfile, this is only needed when you use dts challenges

Building your Code

You can start by building your code with:

$ dts exercises build

If you go inside the solution folder you will notice that there are more folders that weren’t there before. These are build artifacts that persist from the ROS building procedure because of mounting.

Note: every time you run a dts exercises command you have to be inside an exercise folder or you will see an error.

Running in Simulation

You can run your current solution in the gym simulator with:

 $ dts exercises test --sim

Then you can look at what’s happening by looking through the browser at http://localhost:8087 . Open 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 in the simulator.

You might want to launch a virtual joystick by opening a terminal and doing:

$ dt-launcher-joystick

or by clicking on the “Joystick” icon on the left hand side of the desktop.

By default the duckiebot is in joystick control mode, so you can freely drive it around. You can also set it to LANE FOLLOWING mode by pushing the a button when you have the virtual joystick active. If you do so you will see the robot move forward slowly try to follow the road.

You might also explore the other outputs that you can look at in rqt_image_view.

Also useful are some debugging outputs that are published and visualized in RViz. You can open RViz through the terminal in the novnc desktop by typing:

$ rviz

or clicking on the icon on the left hand side of the desktop.

In the window that opens click “Add” the switch to the topic tab, then find the segment_markers, and you should see the projected segments appear. Do the same for the pose_markers.

Another tool that may be useful is rqt_plot which also can be opened through the terminal in novnc. This opens a window where you can add “Topics” in the text box at the top left and then you will see the data get plotted live.

All of this data can be viewed as data through the command line also. Take a look at all of the rostopic command line utilities.

Testing Your Algorithm on the Robot

You have two options, local (i.e., the code runs on your laptop and communicates through wifi with your Duckiebot) and remote (i.e., everything runs on the Duckiebot). The local option can be a bit quicker because we don’t have to copy files to the Duckiebot, but it can be a bit more stochastic because latency can be introduced by the unpredictable wifi network.

To run locally:

 $ dts exercises test --duckiebot_name ![ROBOT_NAME] --local

To run on the Duckiebot:

$ dts exercises test --duckiebot_name ![ROBOT_NAME]

The first time you run on your Duckiebot it may take a bit of time to pull some images but this will only be the first time. You also will have to enter the password for your Duckiebot, which is by default quackquack.

In both cases you should still be able to look at things through novnc by pointing your browser to http://localhost:8087 . If you are running on Linux, you can load up the virtual joystick and start lane following as above.

Taking a log

You should see a directory call logs in the top level ros-template directory. This is where your logs will go. Also make sure that the images on your laptop are up to date with:

Now we will take a short log (rosbag) of your agent running in the simulator through the noVNC browser.

One you have everything running with dts exercises test --sim, open a terminal in noVNC and run:

$ dt-launcher-record_minimal_log

This will start logging. When you are ready to end your log, hit CTRL-C in the terminal. On your laptop you should see a log (a file with a .bag extension) in the logs directory.

Then take a short log (rosbag) of your agent running on the real robot.

Submitting your Agent

Now we will test submitting your agent for evaluation. If you want to see how you will do locally before sending it for cloud evaluation, you can do:

$ dts challenges evaluate --challenge mooc-ros-template

This will give you a link to follow the progress of the simulation in the browser. You can also look at the output files at the end to see your scores.

NB: This can take a long time to run, you really don’t have to wait for it to finish.

and then finally you can submit it with:

$ dts challenges submit

You can also test your submission on your duckiebot with:

$ dts duckiebot evaluate

NOTE: Our objective here is not performance. We are just trying to make sure that we have everything configured properly. The minimal requirement is that I can see that your submission was sent on the challenges server.

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

  • Fun picture of your robot posted to the Discord channel duckiebot-selfies
  • Collect into one zip file and submit here:
    • Your three calibration files
    • Log from agent running in simulator
    • Log from agent running on robot
  • Submitted challenge

Deadline Sept. 23, 2022