Quick Start Guide

This guide will help you get started with Donkeycar quickly. You’ll create a car application, configure it, and be ready for your first drive.

This quick start assumes you have already built your Donkeycar hardware. If not, refer to the hardware build guide.

Prerequisites

Before starting, ensure you have:

A Raspberry Pi, Jetson Nano, or PC/Mac with Donkeycar installed
Basic familiarity with the command line terminal
Your hardware assembled (for physical car)

Installation

Install Donkeycar

Choose the appropriate installation for your platform:

Raspberry Pi

pip install donkeycar[pi]

Jetson Nano

pip install donkeycar[nano]

PC/Mac

pip install donkeycar[pc]

macOS with GPU

pip install donkeycar[macos]

For PyTorch support, add the torch extra: pip install donkeycar[pc,torch]

Verify Installation

Verify that Donkeycar is installed correctly:

donkey --help

You should see the Donkey Car ASCII art and a list of available commands:

 ____   ___  _   _ _  _________   __  ____     _    ____
|  _ \ / _ \| \ | | |/ / ____\ \ / / / ___|   / \  |  _ \
| | | | | | |  \| | ' /|  _|  \ V / | |      / _ \ | |_) |
| |_| | |_| | |\  | . \| |___  | |  | |___  / ___ \|  _ <
|____/ \___/|_| \_|_|\_\_____| |_|   \____|/_/   \_\_| \_\

using donkey v5.2.dev6 ...

Create Your Car Application

Generate Car Folder

Use the donkey createcar command to create a new car application:

donkey createcar --path ~/mycar

This creates a new directory with the following structure:

~/mycar/
├── config.py          # Default configuration
├── myconfig.py        # Your custom configuration
├── manage.py          # Main car application
├── train.py           # Training script
├── calibrate.py       # Calibration script
├── data/              # Recorded driving data
├── models/            # Trained models
└── logs/              # Log files

The config.py file contains all default settings. The myconfig.py file is where you override settings for your specific car.

Choose a Template

Donkeycar provides several templates for different use cases. The default template is complete, which includes all features.

To create a car with a specific template:

donkey createcar --path ~/mycar --template <template_name>

Available templates:

complete - Full-featured car with deep learning autopilot (default)

basic - Minimal configuration for simple cars

path_follow - GPS-based path following

cv_control - Computer vision control

simulator - For use with the Donkey Simulator

Navigate to Car Directory

cd ~/mycar

Basic Configuration

Edit Your Configuration

Open myconfig.py in a text editor:

nano myconfig.py

Uncomment and modify the settings you want to change. Here are the most common settings:

# Camera Configuration
CAMERA_TYPE = "PICAM"  # Options: PICAM, WEBCAM, CVCAM, MOCK
IMAGE_W = 160
IMAGE_H = 120
IMAGE_DEPTH = 3
CAMERA_FRAMERATE = 20

# Drive Train Type
DRIVE_TRAIN_TYPE = "PWM_STEERING_THROTTLE"  # Standard RC car

# Controller Type
CONTROLLER_TYPE = 'xbox'  # Options: ps3, ps4, xbox, nimbus, wiiu
USE_JOYSTICK_AS_DEFAULT = True
JOYSTICK_MAX_THROTTLE = 0.5  # Limit speed for beginners

# Drive Loop
DRIVE_LOOP_HZ = 20  # How fast the main loop runs

# Web Control
WEB_CONTROL_PORT = 8887  # Port for web interface

Start with JOYSTICK_MAX_THROTTLE = 0.5 if you’re a beginner. You can increase it as you get comfortable.

Camera Selection

Raspberry Pi Camera

CAMERA_TYPE = "PICAM"

USB Webcam

CAMERA_TYPE = "WEBCAM"
CAMERA_INDEX = 0  # If you have multiple cameras

Testing without Camera

CAMERA_TYPE = "MOCK"

Drive Train Configuration

For a standard RC car with servo and ESC:

DRIVE_TRAIN_TYPE = "PWM_STEERING_THROTTLE"

# Configure your pins (Raspberry Pi GPIO)
PWM_STEERING_THROTTLE = {
    "PWM_STEERING_PIN": "RPI_GPIO.BOARD.33",
    "PWM_STEERING_SCALE": 1.0,
    "PWM_STEERING_INVERTED": False,
    "STEERING_LEFT_PWM": 460,
    "STEERING_RIGHT_PWM": 290,
    "PWM_THROTTLE_PIN": "RPI_GPIO.BOARD.32",
    "PWM_THROTTLE_SCALE": 1.0,
    "PWM_THROTTLE_INVERTED": False,
    "THROTTLE_FORWARD_PWM": 500,
    "THROTTLE_STOPPED_PWM": 370,
    "THROTTLE_REVERSE_PWM": 220,
}

You’ll need to calibrate these PWM values for your specific hardware. See the calibration section below.

Calibrate Your Car

Before your first drive, you need to calibrate the steering and throttle.

Run Calibration Script

python calibrate.py

This starts a web server. Open your browser and navigate to:

http://raspberrypi.local:8887/calibrate

Replace raspberrypi.local with your car’s hostname or IP address.

Find Your IP Address

If you don’t know your car’s IP address:

donkey findcar

Or check directly:

hostname -I

Calibrate Steering

Use the web interface to adjust steering values

Find the PWM value for full left turn

Find the PWM value for full right turn

Update these values in myconfig.py:

STEERING_LEFT_PWM = 460   # Your calibrated left value
STEERING_RIGHT_PWM = 290  # Your calibrated right value

Calibrate Throttle

Find the PWM value for stopped (usually around 370)

Find the PWM value for maximum forward speed

Find the PWM value for maximum reverse (if applicable)

Update in myconfig.py:

THROTTLE_FORWARD_PWM = 500
THROTTLE_STOPPED_PWM = 370
THROTTLE_REVERSE_PWM = 220

Be careful when calibrating throttle! Your car may move suddenly. Have someone ready to catch it or prop up the wheels.

Your First Drive

Start the Car

Run the main application:

python manage.py drive

You should see output indicating the car is starting:

PID: 1234
Starting vehicle at 20 Hz

Connect to Web Interface

Open your browser to:

http://raspberrypi.local:8887

You should see:

Live camera feed

Steering and throttle controls

Recording controls

Mode indicators

Drive Manually

Connect your game controller or use the web interface to drive:

Game Controller

If you configured a joystick (Xbox, PS4, etc.):

Left stick: Steering
Right trigger: Forward throttle
Left trigger: Reverse throttle
Button mapping varies by controller type

Web Interface

Click and drag on the web UI or use keyboard:

Arrow keys: Steering and throttle
Space: Stop
R: Toggle recording

Start Recording Data

To train an autopilot later, you need to record driving data:

Press the Record button in the web interface

Drive the car around your track 10-20 laps

Try to drive smoothly and consistently

Press Record again to stop

Your data is saved in ~/mycar/data/ as a “tub”.

Record at least 10,000 frames (about 8-10 minutes at 20 Hz) for good autopilot performance.

Stop the Car

Press Ctrl+C in the terminal to stop the car application gracefully.

Train Your First Model

Once you have recorded driving data, you can train an autopilot model:

python train.py --tubs data/ --model models/mypilot.h5

Training can take 5-30 minutes depending on your hardware and dataset size. For Raspberry Pi, it’s recommended to train on a more powerful PC and transfer the model.

Drive on Autopilot

Test your trained model:

python manage.py drive --model models/mypilot.h5

In the web interface:

Switch mode to Autopilot or Local Pilot
The car will now drive itself using the trained model
You can take over control at any time

Always be ready to take manual control! Start with low throttle limits until you trust your model.

Next Steps

Installation Details

Detailed installation for your specific platform

Configuration Guide

Deep dive into all configuration options

Training Guide

Advanced training techniques and model tuning

Hardware Build

Build your own Donkeycar from scratch

Troubleshooting

Camera not working

Check that the camera is properly connected
For Raspberry Pi Camera: Ensure it’s enabled in raspi-config
For USB camera: Try CAMERA_INDEX = 0 or CAMERA_INDEX = 1
Test camera: raspistill -o test.jpg (Pi Camera) or v4l2-ctl --list-devices (USB)

Car not responding to controls

Verify your DRIVE_TRAIN_TYPE is correct
Check pin connections match your configuration
Run calibration script to verify PWM output
Check that motors are receiving power

Can't connect to web interface

Verify car’s IP address: hostname -I
Check firewall settings
Try connecting from the same WiFi network
Ensure WEB_CONTROL_PORT is not blocked

Import errors when starting

Verify Donkeycar is installed: pip list | grep donkey
Ensure you’re using Python 3.11: python --version
Reinstall with correct extras: pip install donkeycar[pi]

Getting Help

If you run into issues:

Check the official documentation
Join the Discord community
Search GitHub issues
Ask questions in the #help channel on Discord

Getting Started

Core Concepts

Building Your Car

Training & Autopilots

Parts Reference

Advanced Topics

Prerequisites

Installation

Create Your Car Application

Basic Configuration

Calibrate Your Car

Your First Drive

Train Your First Model

Drive on Autopilot

Next Steps

Installation Details

Configuration Guide

Training Guide

Hardware Build

Troubleshooting

Getting Help

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Building Your Car

Training & Autopilots

Parts Reference

Advanced Topics

​Prerequisites

​Installation

​Create Your Car Application

​Basic Configuration

​Calibrate Your Car

​Your First Drive

​Train Your First Model

​Drive on Autopilot

​Next Steps

Installation Details

Configuration Guide

Training Guide

Hardware Build

​Troubleshooting

​Getting Help

Build docs developers (and LLMs) love

Prerequisites

Installation

Create Your Car Application

Basic Configuration

Calibrate Your Car

Your First Drive

Train Your First Model

Drive on Autopilot

Next Steps

Troubleshooting

Getting Help