Installing and Running the Duckiematrix#

What you will need

What you will get

  • A successful Duckiematrix installation

  • Knowledge on how to start the Duckiematrix

How to install the Duckiematrix#

The Duckiematrix is installed with the Duckietown Shell with the command:

dts matrix install

How to Run the Duckiematrix#

The basic command to run the Duckiematrix is dts matrix run. However, in order to run the Duckiematrix you need to provide two pieces of information:

  1. Where the engine is running

  2. What map to load

In most cases, you will probably want to run the engine locally. You can do so by adding the --standalone flag. 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

  • demo

  • empty

  • intersections

  • loop

In summary, the following command

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

would start the Duckiematrix on your local machine and load the sandbox map that is predefined. By default, the Duckiematrix runs in tutorial mode, where the key bindings are introduced. If you want to disable this behavior your can add the --no-tutorial flag. If something is going wrong and you don’t see the renderer intializing, you can see what’s going wrong by adding the --verbose flag.

Using a Remote Engine#

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

dts matrix run --engine ENGINE_HOSTNAME

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 you have a Duckiematrix Engine up and running, you connect a Duckiebot (physical or virtual) to an entity in the Duckiematrix. You can do this with the command:

dts matrix attach [--engine ENGINE_HOSTNAME] DUCKIEBOT_NAME ENTITY_NAME

where you can omit ENGINE_HOSTNAME if the engine is running locally. You can find the name of the matrix entity by looking through 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. The default for a Duckiebot is map_0/vehicle_0 so that’s usually a good guess.

Using a Custom Map#

The map can be defined on the local file system and loaded by the engine. To learn how to define a local map see the page on creating maps. This map can then be loaded by omitting the --embedded flag and specifying the path:

dts matrix run --standalone --map PATH_TO_MAP