What you will need

• A working Duckietown Shell installation: Duckietown Shell (dts)

What you will get

• A successful Duckiematrix installation

• Knowledge on how to start the Duckiematrix

• Knowledge of Duckiematrix optional features

Duckiematrix installation

The Duckiematrix automatically installs the first time it is run, so no explicit installation action is required.

Ubuntu

To get started immediately, open a terminal, and run:

dts matrix run --standalone --embedded --map sandbox

Duckietown Workspace

There are two ways to use the Duckiematrix from Workspaces:

1. (better performance) If dts is installed on the host machine:

   Inside the Workspace, start the engine with:

   dts matrix engine run --sandbox --verbose
   

   On the host machine instead, start the renderer with:

   dts matrix run
   

   and it will automatically connect to the engine running inside the workspace.

   Note

   To run the Linux version of the Duckiematrix on Windows, add --os-family linux to the above command.

2. (broader compatibility) If dts is not installed on the host machine, inside the Workspace, run:

   dts matrix run --standalone --sandbox --verbose --browser
   

   the renderer will be run through the browser (WebGL).

   Note

   For the WebGL version of the Duckiematrix, if the colors look desaturated, try a different browser.

Note

After the Duckiematrix renderer window opens, click on it and press Enter to enable keyboard interaction. Press Esc to release the mouse to desktop again.

How to run the Duckiematrix

As seen above, the command to (install and) run the Duckiematrix is dts matrix run.

However, two additional pieces of information are required:

1. Where is the engine running. Options are:

   • locally (choice for most use cases): add the --standalone flag to the matrix run command;

   • remotely: read Using a remote engine.

2. Which map to load. Options are:

   • use a default map: Duckiematrix maps

   • create your own map: Using a Custom Map

Common optional run flags

• --help: get a comprehensive list of optional flags with explanations of use.

• --map: followed by the path of a customized map.

• --embedded: in conjuntion with --map when using one of the default maps. For example, you can run the demo map in an engine with:

  dts matrix engine run –embdedded –map demo

• --no-tutorial: by default, the Duckiematrix runs in tutorial mode, where the key bindings are introduced at startup. Use this flag to disable this introduction. Note that relevant keyboard bindings can always be found though the “Settings” tab in the renderer (bottom left of the screen).

• --verbose: provide a more detailed terminal output, useful for debugging in case of need.

• --browser: to run the browser (WebGL) version of the Duckiematrix, especially useful when using Duckietown Workspaces on macOS or Windows OSs.

Note

For the WebGL (browser) version of the Duckiematrix, if the colors look desaturated, try a different browser.

Using a remote engine

To run a local renderer and connect it to a remote engine, specify the location of the engine (as a hostname or IP address) using the --engine flag:

dts matrix run --engine ENGINE_HOSTNAME

Note

If you are using a Duckietown Workspace and the engine is running inside the dev container, run this renderer command from a terminal on your host machine.

In this case you do not need to specify a map since that was already specified when the Duckiematrix engine was initially run.

Connecting a Duckiebot to a remote engine

Once a Duckiematrix engine is running, you can “attach” a Duckietown robot, physical or virtual, to an entity in the simulated world:

dts matrix attach [--engine ENGINE_HOSTNAME] DUCKIEBOT_NAME ENTITY_NAME [--dreamwalk]

where:

• ENGINE_HOSTNAME is not necessary if the engine is running locally.

• DUCKIEBOT_NAME is the hostname of your virtual or physical robot

• ENTITY_NAME is the name of the entity in the Duckiematrix world you are attaching DUCKIEBOT_NAME to. A list of available entities for the engine running can be found in the map configurations or more simply by clicking on the Robots tab at the bottom of a Duckiematrix rendering window, and then looking at the Name.

Fig. 3 Find the available entity names by clicking on the “Robots” section

Fig. 4 The default entity name for a Duckiebot is map_0/vehicle_0.

Duckiematrix maps

With respect to the map, you can choose to either define your own map and tell the Duckiematrix where to find it on the file system, or you can choose to use one of the default maps that are provided by including the --embedded flag.

The default maps are named:

• sandbox : 5x5 tiles map with 4x 3-way intersections, traffic lights, demo traffic signs, watchtowers, one DB21 Duckiebot and garage for calibrations.

Fig. 5 The default sandbox map.

• demo: same map layout and content as sandbox map, but including multiple Duckiebots (DB21, DB19), night-day cycle, and ornamental moving duckies.

Fig. 6 The default demo map includes multiple Duckiebots and night-day cycle.

• empty: empty map (only grass)

Fig. 7 The default empty map.

• intersections: same map layout as sandbox, but with one intersection having traffic signs arranged according to the appearance specifications. Good map for testing intersection navigation agents.

Fig. 8 The default intersections map.

Fig. 9 The default intersections map from a Duckiebot’s point of view.

• loop: 3x3 tiles minimal road loop; the smallest legal Duckietown. One DB21 Duckiebot on the track.

Fig. 10 The default loop map: the minimal Duckietown.

In summary, the following command:

dts matrix run --standalone --embedded --map sandbox

will:

1. download and install the latest version of the Duckiematrix if it has not already been installed,

2. start it on your local machine and load the sandbox map.

Note

If you are using a Duckietown Workspace, the --standalone flag starts both the Duckiematrix Engine and Renderer in the same environment. For the split workspace workflow, start the Engine separately and connect to it with dts matrix run from a local terminal outside the dev container.

Using a Custom Map

The Duckiematrix map loaded in the engine can be locally defined. To learn how to create a compliant map read: creating Duckiematrix compliant maps. This map can then be loaded by omitting the --embedded flag and specifying the path, i.e.:

dts matrix run --standalone --map PATH_TO_MAP

Note

If you are using a Duckietown Workspace, the --standalone flag starts both the Duckiematrix Engine and Renderer in the same environment. For the split workspace workflow, start the Engine separately and connect to it with dts matrix run from a local terminal outside the dev container.