Donkey Command-line Utilities

The donkey command is created when you install the donkeycar Python package. This is a Python script that adds some important functionality. The operations here are vehicle independent, and should work on any hardware configuration.

Create Car

This command creates a new dir which will contain the files needed to run and train your robot.

Usage:

donkey createcar --path <dir> [--overwrite] [--template <donkey2>]

• This command may be run from any dir
• Run on the host computer or the robot
• It uses the --path as the destination dir to create. If .py files exist there, it will not overwrite them, unless the optional --overwrite is used.
• --overwrite will update the files in the destination directory except the myconfig.py. This is useful if you have update donkeycar and you want those changes reflected in you mycar folder but you don't want to have to recreate your myconfig.py.
• The optional --template will specify the template file to start from. For a list of templates, see the donkeycar/templates dir. This source template will be copied over the manage.py for the user. Common templates are:
  • --template=complete: the Deep Learning Autopilot
  • --template=path_follow: the Path Follow Autopilot
  • --template=cv_control: the Computer Vision Autopilot

Find Car

This command attempts to locate your car on the local network using nmap.

Usage:

donkey findcar

• Run on the host computer
• Prints the host computer IP address and the car IP address if found
• Requires the nmap utility:

sudo apt install nmap

Calibrate Car

This command allows you to manually enter values to interactively set the PWM values and experiment with how your robot responds. See also more information.

Usage:

donkey calibrate --channel <0-15 channel id>

• Run on the host computer
• Opens the PWM channel specified by --channel
• Type integer values to specify PWM values and hit enter
• Hit Ctrl + C to exit

Clean data in Tub

Opens a web server to delete bad data from a tub.

Usage:

donkey tubclean <folder containing tubs>

• Run on pi or host computer.
• Opens the web server to delete bad data.
• Hit Ctrl + C to exit

Train the model

Note: This section only applies to version >= 4.1 This command trains the model. There is more detail in Deep Learning Autopilot.

donkey train --tub=<tub_path> [--config=<config.py>] [--model=<model path>] [--type=(linear|categorical|inferred)] [--transfer=<transfer model path>]

• Uses the data from the --tub datastore. You may specify more than one tub using a comma separated list --tub=foo/data,bar/data or just leaving spaces like --tub foo/data bar/data.
• Uses the config file from the --config path (optionally)
• Saves the model into path provided by --model. Auto-generates a model name if omitted. Note: There was a regression in version 4.2 where you only had to provide the model name in the model argument, like --model mypilot.h5. This got resolved in version 4.2.1. Please update to that version.
• Uses the model type --type
• Allows to continue training a model given by --transfer
• Supports filtering of records using a function defined in the variable TRAIN_FILTER in the myconfig.py file. For example:

def filter_record(record):
    return record.underlying['user/throttle'] > 0

TRAIN_FILTER = filter_record

only uses records with positive throttle in training.

• In version 4.3.0 and later all 3.x models are supported again:

donkey train --tub=<tub_path> [--config=<config.py>] [--model=<model path>] [--type=(linear|categorical|inferred|rnn|imu|behavior|localizer|3d)] [--transfer=<transfer model path>]

In addition, a Tflite model is automatically generated in training. This can be suppressed by setting CREATE_TF_LITE = False in your config. Also Tensorrt models can now be generated. To do so, you set CREATE_TENSOR_RT = True.

• Note: The createcar command still creates a train.py file for backward compatibility, but it's not required for training.

Make Movie from Tub

This command allows you to create a movie file from the images in a Tub.

Usage:

donkey makemovie --tub=<tub_path> [--out=<tub_movie.mp4>] [--config=<config.py>] [--model=<model path>] [--model_type=(linear|categorical|inferred|rnn|imu|behavior|localizer|3d)] [--start=0] [--end=-1] [--scale=2] [--salient]

• Run on the host computer or the robot
• Uses the image records from --tub dir path given
• Creates a movie given by --out. Codec is inferred from file extension. Default: tub_movie.mp4
• Optional argument to specify a different config.py other than default: config.py
• Optional model argument will load the keras model and display prediction as lines on the movie
• model_type may optionally give a hint about what model type we are loading. Categorical is default.
• optional --salient will overlay a visualization of which pixels excited the NN the most
• optional --start and/or --end can specify a range of frame numbers to use.
• scale will cause ouput image to be scaled by this amount

Plot Predictions

This command allows you to plot steering and throttle against predictions coming from a trained model.

Usage:

donkey tubplot --tub=<tub_path> --model=<model_path> [--limit=<end_index>] [--type=<model_type>] 

• This command may be run from ~/mycar dir
• Run on the host computer
• Will show a pop-up window showing the plot of steering values in a given tub compared to NN predictions from the trained model
• Optional --limit=<end_index> will use all records up to that index, defaults to 1000.
• Optional --type=<model_type> will use a different model type than the DEFAULT_MODEL_TYPE

Tub Histogram

Note: Requires version >= 4.3

This command allows you to plot tub data (usually steering and throttle) as a histogram.

Usage:

donkey tubhist --tub=<tub_path> --record=<record_name> --out=<output_filename>

• This command may be run from ~/mycar dir
• Run on the host computer
• Will show a pop-up window showing the histogram plot of tub values in a given tub
• Optional --record=<record_name> will only show the histogram of a certain data series, for example "user/throttle"
• Optional --out=<output_filename> saves histogram under that name, otherwise the name is auto-generated from the tub path

Joystick Wizard

This command line wizard will walk you through the steps to create a custom/customized controller.

Usage:

donkey createjs

• Run the command from your ~/mycar dir
• First make sure the OS can access your device. The utility jstest can be useful here. Installed via: sudo apt install joystick You must pass this utility the path to your controller's device. Typically this is /dev/input/js0 However, it if is not, you must find the correct device path and provide it to the utility. You will need this for the createjs command as well.
• Run the command donkey createjs and it will create a file named my_joystick.py in your ~/mycar folder, next to your manage.py
• Modify myconfig.py to set CONTROLLER_TYPE="custom" to use your my_joystick.py controller

Visualize CNN filter activations

Shows feature maps of the provided image for each filter in each of the convolutional layers in the model provided. Debugging tool to visualize how well feature extraction is performing.

Usage:

donkey cnnactivations [--tub=<data_path>] [--model=<path to model>]

This will open a figure for each Conv2d layer in the model.

Example:

donkey cnnactivations --model models/model.h5 --image data/tub/1_cam-image_array_.jpg

Show Models database

Note: This is only available in donkeycar >= 4.3.1.

This lists the models that are stored in models/database.json. Displays information like model type, model name, tubs used in training, transfer model and a comment if --comment was used in training or the model was trained in the UI.

Usage:

donkey models [--group] 

• Run from your ~/mycar directory
• If the optional --group flag is given, then the tub path info is combined into groups, if different models used different tubs. Useful, if you use multiple tubs, and the models have used different tub combinations because it compresses the output information.
• You need to install pandas first if you want to run it on the car

Donkey UI

Note: This section only applies to version >= 4.2.0

Usage:

donkey ui

This opens a UI to analyse tub data supporting following features:

• show selected data fields live as values and graphical bars
• delete or un-delete records
• try filters for data selection
• plot data of selected data fields

The UI is an alternative to the web based donkey tubclean.

A full documentation of the UI is here.