Exercise 1 - Setup and ROS

Published: Wednesday Sep. 17, 2025.

Due: Wednesday Oct. 1, 2025

In this exercise you will set up your laptop and Duckiebot, and calibrate your Duckiebot 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 Setup and Preliminaries

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

Make some Accounts (if necessary)

Ref: Accounts

Follow the above instructions to setup accounts for Github, Docker, and Duckietown.

Laptop setup

Ref: Your Computer Setup

Ref: Software Dependencies

Follow the above instructions to install necessary software and dependencies related to Docker and the Duckietown Shell.

Note: Make sure to generate a DT2 token (the default).

(Optional) Devcontainer Setup

COMING VERY SOON

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

and see the version of your shell.

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

Duckiebot Setup

Duckiebot assembly

Ref: Assembly instructions

The students from a previous year assembled the robots for mostly for you. You shouldn’t assume that they did everything correctly. Use the above instructions to make sure things were done 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.

Initialize your SD card (requires Linux)

Ref: Initilizing the SD Card

IMPORTANT For the --configuration put DB21J. You may list several WiFi networks but you will want to include duckietown:quackquack 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.

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 see a status of Booting on first boot for some time.

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.

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

Note: You can also do this with your virtual Duckiebot so that it syncs code without a password.

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

Ref: Dashboard Setup

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. Follow the above instructions. 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).

Get Familiar with the Dashboard

Ref: Using the Duckietown Dashboard

After successfully logging in, you can follow the above references which provides 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

Ref: Make it Move!

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

See what the Duckiebot sees

Ref: Make it See!

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

Make it Shine

Ref: Make it Shine!

The robot is also equipped with 4 LEDs that we can control. Follow the above 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.

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

Calibrate the Wheels

Ref: Wheel Calibration

When you command your robot to go straight you might notice that it doesn’t really go straight. Follow the above instructions to calibrate the wheels.

Note: You really don’t need to be obsessive about this - the robot won’t always drive straight. Just make it drive ``reasonably’’ straight (this is why we will need feedback control later).

Calibrate the Camera

Ref: Camera Calibration

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. Click on FILE MANAGER on the left hand menu. Then navigate to config/calibrations. You should see three folders: camera_extrinsic, camera_intrinsic, and kinematics. Inside each one you should see a file ![ROBOT_NAME].yaml. If you don’t, and you only see default.yaml stop - something went wrong in the calibration procedure.

Tip: Download the robot specific calibration files to your local computer and store them somewhere safe. This could save you time if you reburn your SD card your SD card for some reason since you won’t have to redo all of the calibraiton procedures. .

Virtual Robots and the DuckieMatrix

Virtual Robots

Ref: Virtual Duckiebots

“Virtual robots” are just like real robots but they have no physical body.

Start by creating your virtual robot with:

> dts duckiebot virtual create <VIRTUAL_ROBOT_NAME> -t duckiebot -c DB21J

to create a virtual Duckiebot with the DB21J configuration (same as our real Duckiebots). This takes a few minutes to download some Docker images. Just like your real robot, the virtual robot name will be the hostname that you can connect to so pick something that you can remember.

Next you can start your virtual Duckiebot with

> dts duckiebot virtual start <VIRTUAL_ROBOT_NAME>

After a few seconds it should show up if you run dts fleet discover (if you also have your real robot running you should see them both).

Now just to be safe let’s update it:

> dts duckiebot update <VIRTUAL_ROBOT_NAME>

The Duckiematrix

Ref: Getting Started with the Duckiematrix

The Duckiematrix is a simulation environment written in the Unity game engine.

If you run:

> dts matrix run --standalone --sandbox

To get some info about the robot you can click on where is says “1 robots”. We can see that the name of this robot is map_0/vehicle_0 and it has 4 sensors. (It is not important that this robot is actually configuration DB21M for now).

Attaching your Virtual Robot to the Duckiematrix

Your virtual robot is created but it doesn’t really exist anywhere. So what we want to do is take the virtual robot that we made and associate it with this robot that is in the Duckiematrix. To do that run the command (you will need a new terminal for this):

> dts matrix attach <VIRTUAL_ROBOT_NAME> map_0/vehicle_0

Once that is done - we can treat the virtual robot just like it was a real robot above. For example you can check out the dashboard, see the camera feed, or make it move with the joystick. Verify that this is the case by following the same instructions above except replacing your real robot name with your virtual robot name. (You don’t need to worry about the NTP thing on your virtual robot).

Writing a ROS Node to Drive your Robot

Ref: General Procedure for Running Learning Experiences

Follow the procedure above to complete the lx-ros-basics learning experience.

This will include:

  • Forking the repo and setting up an upstream remote
  • Getting familiar with the dts code API (editor, build, start_matrix, workbench, vnc)
  • Walking through the notebook activities
  • Creating a ROS Node to Drive your Duckiebot as described in the final notebook

Getting Help!

Please report problems quickly on discord or in class. If you are not sure if something is working properly ask. Don’t spend hours trying to fix it first.

Final Deliverables

  • Your laptop is correctly configured (Duckiematrix, Dashboard, etc) (1pt)
  • You can make your robot move, see, and shine (1 pt)
  • Your robot is calibrated (camera and wheels) (1 pt)
  • Your ROS node moves your real robot (2pt)