The Complete Way#

What you will need

  • Functional DTS installation

  • An SD card with at least 64 GB of space

  • An SD card adapter appropriate for the computer you are using to flash the SD card

  • A broadband internet connection

  • 20 - 40 mins, depending on internet connection speed

  • At least 40 GB of free space on your hard drive before starting

What you will get

An initialized SD card for your Duckietown robot.

Use this procedure if you want full control over the configuration settings of your robot.

Burning the SD card with dts sd_card init#

Note

The default username (not to be confused with the hostname/robot name) is duckie. During initialization, DTS prompts you to enter and confirm the password for this account; there is no default account password.

Start by plugging the SD card into your computer using a SD card reader or the USB to microSD card adapter provided in your Duckiebot kit. Make sure the SD card is detected before proceeding.

Then, open a terminal and use the command:

dts sd_card init --hostname HOSTNAME --type TYPE --configuration CONFIGURATION --wifi WIFI[,WIFI2,...,WIFIN] [--country COUNTRY] [--version VERSION]

Note

If you are using a Duckietown Workspace and dts is installed on the host machine, you can run this command inside or outside the Duckietown Workspace. When the command is run inside the Duckietown Workspace, it is automatically delegated to the host machine so that it can access the SD card.

Where:

  • --hostname is the name of the robot you are flashing the SD card for.

  • When the setup step runs, DTS securely prompts you to enter and confirm the password for the duckie account. It must contain at least eight characters and cannot contain colons or line breaks. The characters you enter are not displayed. If DTS reports that the selected disk image does not support setting a password, use a current supported image version.

Duckiebot naming constraints#

Attention

The HOSTNAME, or robot name, is going to be used extensively in future interactions with the robot, and can only be changed by reflashing your SD card.

Choose a hostname for your robot that meets all of the following requirements:

  • It is unique within a fleet of Duckiebots connected to the same network.

  • It is entirely lowercase.

  • It starts with a letter.

  • It contains only letters, numbers, or underscores.

For example:

  • ✅ myduckiebot

  • ✅ myduckiebot01

  • ❌ 123bot

  • ❌ MyDuckiebot

  • ❌ Whatabot!

  • --type is what kind of robot you are flashing. Types are duckiebot (default), duckiedrone, watchtower, and traffic_light.

  • --configuration is the model of your robot. This is associated with --type option. Supported options for duckiebot in ente is DB21J, for duckiedrone is DD24. Other legacy and experimental images exist, such as DB26 (for Jetson Orin Nano Super), DBR4 (Raspberry Pi 4), DB21M (Jetson Nano 2GB developer Kit), DB19 (Raspberry Pi 3B+), or DB18 (Raspberry Pi 3B).

Attention

  • If you have a Duckiebot with a 4GB Jetson Nano - the model is DB21J.

  • If you have a Duckiebot with a 2GB Jetson Nano (you should not) - the model is DB21M. Note that DB21M are not supported in ente. Switch back to daffy if you have a DB21M or upgrade by obtaining a Jetson Nano 4GB developer kit.

  • If you are not using a Jetson Nano, the model is the model of your Duckiebot (e.g., DB19 or DBR4).

  • If you are not sure what Duckiebot you have, refer to Duckiebot Models or reach out to support.

  • --wifi is a comma-separated list of Wi-Fi networks, each passed in the format wifiname:wifipassword. For example, the default is duckietown:quackquack; this is a Wi-Fi credential, not the password for the duckie account. Networks can be edited after the robot is initialized too, without needing to reflash the SD card. Nonetheless, making sure your initial credentials are correct simplifies next steps.

Attention

  • If you plan on the robot connecting over different networks (e.g., at home and in class), list all your networks without spaces after the commas:

dts sd_card init ... --wifi duckietown:quackquack,myhomenetwork:myhomepassword,myuninetwork:myunipassword

dts sd_card init ... --wifi "my fancy network name:quackquack"

  • Networks in the list can support additional arguments:

    - Open networks (no password): "ssid".

- PSK (Pre-shared key) protected networks: "ssid:psk"

- EAP (Extensible Authentication Protocol) protected networks: "ssid:username:password"

  • --country is an optional argument but highly recommended. Neglecting this sometimes will result in specific Wi-Fi hotspots not being seen by the Duckiebot. COUNTRY arguments could be, e.g., CA for Canada, CH for Switzerland, or US for the United States of America. A full list of codes can be found, e.g., on Wikipedia: ISO 3166-1 alpha-2 codes.

  • --version is an optional numeric argument to download a specific version of the Duckietown image for the specific CONFIGURATION and TYPE. In default (recommended), it will download the latest available. Example VERSION parameters could be 2.0.1 or 1.4.2.

Additional options for sd_card init exist. For a full list of the options, run:

dts sd_card init --help

The flashing procedure#

After you run the dts sd_card init command, follow the instructions that appear on screen.

Downloading the compressed image#

The process will start by downloading the image to your /tmp/duckietown/ folder. Note that if a compliant image is detected in that path, this step will be skipped. It is not necessary to re-download the image repeatedly if flashing multiple SD cards in the same session.

Extracting the archive#

The process will continue with extracting the .img image from the downloaded file.

Warning

You might feel tempted to abort the procedure at this stage and flash this .img file to an SD card using a third-party tool, e.g., Balena Etcher. Resist this temptation, it will not work (yet). Carry on reading.

Writing the image#

At this stage you will be prompted to choose the device where to flash the image file to. All storage devices connected to your computer are candidates.

Given the danger (from data loss to OS files corruption) of choosing a wrong device, the procedure will prompt you for the nominal size of the SD card you want to flash the image to. Devices that do not match the given size will not be shown. A standard Duckietown SD is nominally 64 GB.

A list of devices with capacity close to the number provided will be shown. Type in or copy-paste the device name from the list and press Enter.

Attention

You can choose to write the image to a file instead of a device, e.g., by typing in /my/nonprotected/path/duckietown_image_9.9.9.img. Once this file is created, it can be successfully flashed to a device using any third-party tool.

Finalizing the sd_card init process#

On successful end of the procedure, the drive will be automatically ejected, and you will be instructed to remove the SD card from the SD card reader and insert it, e.g., into the Duckiebot’s SD card slot.

If you experience any issues while flashing the SD card, make sure you check the Troubleshooting section before asking for help on Stack Overflow.

Troubleshooting#

Troubleshooting

SYMPTOM

  • The SD card does not appear to have been written.

  • The flashing process seemed too fast, and there is no data on my SD card.

RESOLUTION

  • Check if your SD card adapter has a write protection switch.

  • Make sure you selected the correct drive name during the flashing procedure.

Troubleshooting

SYMPTOM

I am using a microSD-to-SD card adapter with write protection disabled, but the SD card does not appear to have been initialized after the procedure.

RESOLUTION

Try again, making sure that you enter the correct drive name during the procedure.

Troubleshooting

SYMPTOM

The procedure fails due to a “Bad archive” error.

RESOLUTION

Try again using the --no-cache option.

Troubleshooting

SYMPTOM

The verification process fails with the error Please set up a token using "dts tok set".

RESOLUTION

Make sure that you have completed the Duckietown token setup procedure Accounts.

Additional information is available at Network troubleshooting.