Duckietown Shell

Duckietown Shell is a pure Python, easily distributable (few dependencies) utility for Duckietown.

The idea is that most of the functionality is implemented as Docker containers, and dt-shell provides a nice interface for that, so that user should not type a very long docker run command line.

Note: Duckietown Shell requires Python 3.6 or higher.

Prerequisites

The duckietown shell has very minimal requirements. Please use the links provided and follow the instructions for your OS

1. Git
2. Git LFS (for building and working with the docs only)
3. Docker

Docker Prerequisites

Note: You need to add yourself to the docker group:

$ sudo adduser `whoami` docker

Important: after you do that, you must log out and in to have the group change take effect.

Docker on MacOS

By default, Docker uses the OS X keychain to store credentials, but this is not good.

Edit ~/.docker/config.json and remove all references to an "osxkeychain".

Then run docker login again.

Then you should see an auth entry of the type:

{
    "auths": {
        "https://index.docker.io/v1/": {
            "auth": "mXXXXXXXXXXXXXXXXXXXXXXXXXX"
        }
    },
}

Installing the Duckietown Shell

Installation on Ubuntu 18.xx or higher

Note: 22.xx and above are officially supported

Install using pipx

Install pipx:

$ sudo apt install -y pipx

Install the duckietown-shell:

$ pipx install duckietown-shell

To upgrade to the latest version of duckietown-shell:

$ pipx upgrade duckietown-shell

Install using pip

Install pip3

$ sudo apt install -y python3-pip

Install the duckietown-shell Python package:

$ pip3 install --no-cache-dir --user -U duckietown-shell

Testing the Installation on Ubuntu

Typing

$ which dts

should output something like: /home/![user]/.local/bin/dts

If nothing is output, you may need to add /home/![user]/.local/bin to your shell path. You can do so by adding the line:

`export PATH=$PATH:/root/.local/bin`

into your ~/.bashrc file (if you use bash, otherwise the corresponding shell initialization file).

Installation on Ubuntu 16.xx

The Duckietown shell requires Python 3.6 or higher, which is not standard on Ubuntu 16. A workaround is to install Homebrew by following the instructions here. Then, run :

$ brew install python3
$ python3.7 -m pip install --no-cache-dir --user -U duckietown-shell

Then, typing

$ which dts

should output: /home/linuxbrew/.linuxbrew/bin/dts

Duckietown Shell on MacOS X

Using pipx to install

Install pipx:

(see https://pipx.pypa.io/stable/installation/ for more details)

$ brew install pipx
$ pipx ensurepath
$ sudo pipx ensurepath --global # optional to allow pipx actions in global scope. See "Global installation" section below.

Install the duckietown-shell:

$ pipx install duckietown-shell

To upgrade to the latest version of duckietown-sheel:

$ pipx upgrade duckietown-shell

Using pip to install

Install pip3.

Install the duckietown-shell:

Note: Never use sudo pip install to install duckietown-shell.

$ pip3 install --no-cache-dir --user -U duckietown-shell

Testing the Installation

Typing

$ which dts

should output the path to the dts executable. This path can vary based on your Python setup. If it is not found, you may need to add something to your shell path.

Installation in other operating systems

To install the shell, use:

$ pip3 install --no-cache-dir --user -U duckietown-shell

The shell itself does not require any other dependencies besides standard cross-platform Python libraries.

Note: Never use sudo pip3 install to install duckietown-shell.

Installation on Docker (experimental)

Assuming that Docker is already installed, place the following in your ~/.bashrc or other initialization file for a shell:

alias dts='docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock  -w $PWD -v $PWD:$PWD -v ~/.dt-shell:/root/.dt-shell -v ~/.docker:/root/.docker duckietown/duckietown-shell:v3 dts'

Some functionality might not be available.

Testing Duckietown shell

At this point, try to enter the Duckietown shell by typing the command

$ dts

If you get an error, delete the subfolder commands in the folder ~/.dt-shell

~/.dt-shell$ rm -rf commands/

Then, try again

$ dts

---

You have successfully installed the Duckietown Shell. If you know what you want to do with it, go ahead. Below are some examples of things you can do with the Duckietown Shell

Non-interactive setup

The Duckietown Shell can be preconfigured without interactive prompts by setting a few environment variables before the first run:

• DTSHELL_PROFILE – name of the profile to use or create.
• DTSHELL_COMMANDS – path to the command set repository.
• DTSHELL_DISTRO – distribution to associate with the profile.
• DTSHELL_TOKEN or DUCKIETOWN_TOKEN – a Duckietown authentication token.

With these variables exported, running dts will not ask for input during the initial configuration, which is useful for scripted or containerized setups.

Compile one of the (legacy) "Duckumentation" (books)

To compile one of the books (e.g., docs-duckumentation, but there are many others):

$ git clone https://github.com/duckietown/docs-duckumentation.git
$ cd docs-duckumentation
$ git submodule init
$ git submodule update
$ dts docs build

There is an incremental build system. To clean and run from scratch:

$ dts docs clean
$ dts docs build

The new Duckietown documentation infrastructure requires only the command

$ dts docs build

to compile a book locally.

Authenticate a Duckietown Token

Run the command dts tok set to set the Duckietown authentication token:

$ dts tok set

Instructions will guide you, and you will be prompted for the token.

If you already know the token, then you can use:

$ dts tok set dt2-YOUR-TOKEN

Verifying that a token is valid

To verify that a token is valid, you can use:

$ dts tok verify dt2-TOKEN-TO-VERIFY

This exits with 0 if the token is valid, and writes on standard output the following json:

{"uid": 3, "expiration": "2018-09-23"}

which means that the user is identified as uid 3 until the given expiration date.

---

Duckiebot setup

Command for flashing SD card

This command will install DuckieOS on the SD-card:

$ dts init_sd_card

---

Command for starting ROS GUIs

This command will start the ROS GUI container:

$ dts start_gui_tools <DUCKIEBOT_NAME_GOES_HERE>

---

Command for calibrating the Duckiebot

This command will run the Duckiebot calibration procedure:

$ dts calibrate_duckiebot <DUCKIEBOT_NAME_GOES_HERE>

Uninstalling or resetting

In some cases, you might want to uninstall the duckietown-shell, or reset the configurations.

If you want to just uninstall the duckietown-shell Python module, you could do:

$ python3 -m pip uninstall duckietown-shell

If you also want to reset the settings, e.g., your Duckietown token, Docker logins, version of the shell, etc, you would Also, want to remove the .duckietown/shell folder in your home folder.

On Ubuntu/Mac, for example, this could be done with:

$ rm -rf ~/.duckietown/shell

---

Developing Duckietown Shell

Clone the Duckietown Shell repository

$ git clone git@github.com:duckietown/duckietown-shell.git

Install from Local Source

You can install Duckietown Shell from your local source

$ cd duckietown-shell
$ pipx install -e .

Note: using the -e option would install dts and link it directly to your source code. This means that any changes to the source code would reflect directly in the environment.

You can also use pip to install

$ pip install -e .

Running & Debugging from Visual Studio Code

To run the app in debug mode using Visual Studio Code, follow these steps:

1. Open the Debug view by clicking on the Debug icon in the Activity Bar on the side of the window.
2. Select the dts Launch configuration from the dropdown menu.
3. Click the green play button to start debugging.
4. Enter the arguments that you want to pass to the dts command, for example profile list -- this is the same as executing dts profile list.

This will launch the application in debug mode, allowing you to set breakpoints and step through the code.

Developing Duckietown Shell Commands

Note: Duckietown Shell comes with a core set of commands used to manage the Duckietown Shell environment. All Duckietown-specific commands come from the Duckietown Shell Commands repository - https://github.com/duckietown/duckietown-shell-commands

For Duckietown Shell Commands development, you need to tell dts where to find the command set.

Use the env variable to work on your local copy of the commands:

export DTSHELL_COMMANDS=/path/to/my/duckietown-shell-commands

For additional information, see devel.

Debugging with Visual Studio Code

You can set the DTSHELL_COMMANDS variable via the python.env file located under .vscode directory.

To simplify development, you can symlink the duckietown-shell-commands directory/repository to be inside the duckietown-shell project:

# assuming that the duckietown-shell-commands repository has been cloned
# at the same level as the duckietown-shell repo
cd ~/duckietown-shell
ln -s $(realpath ../duckietown-shell-commands) ./

Note: don't forget to set your DTSHELL_COMMANDS environment variable by editing the python.env file.

This allows you to easily add breakpoints in the duckietown-shell-commands Python files and run dts in debug mode.

Development Environment

DevContainer Setup

This repository includes a pre-configured development container for VS Code that provides a consistent development environment with all necessary tools pre-installed.

Quick Start with DevContainer

1. Prerequisites:

   • VS Code
   • Dev Containers extension
   • Docker

2. Open in DevContainer:

   # Clone the repository
   git clone https://github.com/duckietown/duckietown-shell.git
   cd duckietown-shell
   
   # Open in VS Code
   code .
   
   # When prompted, click "Reopen in Container"
   # Or use Command Palette: "Dev Containers: Reopen in Container"

3. Environment Configuration (Optional):

   # Create .env.local for secure token storage (gitignored)
   echo "DTSHELL_TOKEN=your-secret-token-here" > .env.local
   
   # The devcontainer will automatically:
   # - Set DTSHELL_PROFILE=ente
   # - Set DTSHELL_DISTRO=ente
   # - Load DTSHELL_TOKEN from host environment
   # - Auto-create the profile on first shell run

DevContainer Features

The development container includes:

• OS: Ubuntu 24.04.2 LTS
• Python: python3 and pip3 pre-installed and available on PATH
• Git: Up-to-date version built from source, pre-installed and available on PATH
• Docker: Docker CLI (docker) with dedicated daemon running inside the container
• Tools: apt, dpkg, curl, wget, ssh, scp, rsync, gpg, ps, lsof, netstat, top, tree, find, grep, zip, unzip, tar, gzip, bzip2, xz

Auto-Profile Creation

The devcontainer is pre-configured to automatically create a shell profile on first run:

# Test the shell - should auto-create 'ente' profile with warning
dts --help

# Verify profile creation
ls -la ~/.duckietown/shell/profiles/ente/

Environment Variables

The shell supports automatic configuration via environment variables:

Variable	Description	Example
DTSHELL_PROFILE	Profile name to use or create	ente
DTSHELL_DISTRO	Distribution for new profiles	ente, daffy
DTSHELL_TOKEN	Duckietown authentication token	dt2-xxx...

Secure Token Management

# Method 1: Environment file (recommended)
echo "DTSHELL_TOKEN=your-token-here" > .env.local
# .env.local is gitignored for security

# Method 2: Host environment
export DTSHELL_TOKEN="your-token-here"

# Method 3: Shell configuration
dts tok set your-token-here

Debugging

Use the provided VS Code launch configurations for debugging:

1. F5 or Run & Debug view
2. Select configuration:
   • "Debug DTS Shell" - Basic shell debugging
   • "Debug DTS Command" - Debug specific commands
   • "Debug DTS Profile Creation" - Test auto-profile creation
3. Set breakpoints and start debugging

# Manual debugging with verbose output
dts --debug -vv version

Browser Integration

Open webpages in the host's default browser from the container:

"$BROWSER" https://www.duckietown.org

Development & Releases

Automated Releases

This repository uses automated semantic versioning for releases. Instead of manually creating tags like v0.2.8, you can now specify the type of release:

• Go to Actions → Automated Release → Run workflow
• Choose version bump type:
  • patch - Bug fixes (6.2.12 → 6.2.13)
  • minor - New features (6.2.12 → 6.3.0)
  • major - Breaking changes (6.2.12 → 7.0.0)

The workflow automatically:

• Updates version numbers
• Creates git tags
• Generates changelogs
• Creates GitHub releases

For detailed instructions, see docs/RELEASE_PROCESS.md.