Creating a Car Application

Overview

The donkey createcar command creates a new Donkeycar application with all the necessary files, configuration, and directory structure for your autonomous vehicle.

Creating Your Car

Basic Command

donkey createcar --path ~/mycar

This creates a new car application in the ~/mycar directory.

Command Options

donkey createcar [options]

Options:

--path: Directory path where car folder will be created (default: ~/mycar)
--template: Car template to use (default: complete)
--overwrite: Replace existing files if they exist

Available Templates

Donkeycar provides several templates for different use cases: complete (Default)

Full-featured template with all capabilities
Web controller + joystick support
Image transformations and augmentations
Telemetry and logging
Recommended for most users

basic

Minimal setup for simple driving
Good for learning the basics
Less configuration overhead

path_follow

GPS or odometry-based path following
For outdoor navigation

cv_control

Computer vision-based control
Uses OpenCV for line detection
No neural network training required

simulator

Configured for Donkey Gym simulator
Test without physical hardware

Template Examples

# Create with specific template
donkey createcar --path ~/mycar --template complete

# Create basic car for learning
donkey createcar --path ~/testcar --template basic

# Create simulator car
donkey createcar --path ~/simcar --template simulator

# Overwrite existing car
donkey createcar --path ~/mycar --overwrite

Directory Structure

After running createcar, you’ll have this structure:

mycar/
├── config.py          # Default configuration
├── myconfig.py        # Your configuration overrides
├── manage.py          # Main application (drive, train)
├── calibrate.py       # Calibration script
├── train.py           # Training script
├── data/              # Recorded training data (tubs)
├── models/            # Trained AI models
└── logs/              # Application logs

Key Files Explained

manage.py

The main application script that runs your car. Usage:

# Drive in manual mode
python manage.py drive

# Drive with a trained model
python manage.py drive --model models/mypilot.h5

# Specify model type
python manage.py drive --model models/mypilot.h5 --type linear

Command Line Options:

--model=<model>: Path to trained model file
--type=<type>: Model architecture (linear, categorical, resnet18)
--js: Use physical joystick controller
--myconfig=<filename>: Specify custom config file (default: myconfig.py)

config.py

Default configuration file with all available settings. Do not edit this file directly - it will be overwritten when you update Donkeycar. Key sections:

Hardware setup (camera, drive train, sensors)
AI and training parameters
Driving modes and behaviors
Web controller settings

myconfig.py

Your personal configuration overrides. Edit this file to customize your car. How it works:

config.py is loaded first with defaults
myconfig.py overrides any settings you specify
Only uncomment and set the values you want to change

Example myconfig.py:

# My car configuration

# Camera settings
CAMERA_TYPE = "PICAM"
IMAGE_W = 160
IMAGE_H = 120
CAMERA_FRAMERATE = 20

# Drive train (after calibration)
DRIVE_TRAIN_TYPE = "PWM_STEERING_THROTTLE"
PWM_STEERING_THROTTLE = {
    "PWM_STEERING_PIN": "PCA9685.1:40.1",
    "PWM_STEERING_SCALE": 1.0,
    "PWM_STEERING_INVERTED": False,
    "PWM_THROTTLE_PIN": "PCA9685.1:40.0",
    "PWM_THROTTLE_SCALE": 1.0,
    "PWM_THROTTLE_INVERTED": False,
    "STEERING_LEFT_PWM": 460,
    "STEERING_RIGHT_PWM": 290,
    "THROTTLE_FORWARD_PWM": 500,
    "THROTTLE_STOPPED_PWM": 370,
    "THROTTLE_REVERSE_PWM": 220,
}

# Joystick
USE_JOYSTICK_AS_DEFAULT = True
JOYSTICK_MAX_THROTTLE = 0.5
CONTROLLER_TYPE = 'xbox'

# AI throttle multiplier (reduce for safety)
AI_THROTTLE_MULT = 0.8

# Recording
AUTO_RECORD_ON_THROTTLE = True
AUTO_CREATE_NEW_TUB = False

Only include the settings you want to change in myconfig.py. This keeps your configuration clean and makes it easier to upgrade Donkeycar later.

calibrate.py

A dedicated calibration script for fine-tuning your steering and throttle.

python calibrate.py drive

This starts a web server where you can adjust PWM values in real-time at:

http://<your-car>.local:8887/calibrate

train.py

Script for training AI models on your collected data.

# Train on collected data
python train.py --tubs data/ --model models/mypilot.h5

# Train with specific model type
python train.py --tubs data/ --model models/mypilot.h5 --type linear

Data and Models Directories

data/

Stores recorded driving sessions (called “tubs”). Structure:

data/
├── tub_1_21-03-15/     # Session from March 15
│   ├── manifest.json
│   ├── catalog_manifest.json
│   └── images/
├── tub_2_21-03-15/     # Second session
└── tub_3_21-03-16/

Each tub contains:

Camera images
Steering/throttle values
Timestamps
Metadata

models/

Stores trained AI models. Common formats:

.h5: Keras model (TensorFlow)
.tflite: TensorFlow Lite (optimized for Pi)
.pth: PyTorch model
.savedmodel: TensorFlow SavedModel format

Configuration Overview

Essential Settings

Camera:

CAMERA_TYPE = "PICAM"  # PICAM, WEBCAM, CVCAM, etc.
IMAGE_W = 160
IMAGE_H = 120
IMAGE_DEPTH = 3  # 3=RGB, 1=Grayscale
CAMERA_FRAMERATE = 20

Drive Train:

DRIVE_TRAIN_TYPE = "PWM_STEERING_THROTTLE"
# See hardware setup guide for full configuration

Controller:

USE_JOYSTICK_AS_DEFAULT = True  # or False for web only
CONTROLLER_TYPE = 'xbox'  # ps3, ps4, xbox, etc.
JOYSTICK_MAX_THROTTLE = 0.5  # Limit max speed

Web Interface:

WEB_CONTROL_PORT = 8887
WEB_INIT_MODE = "user"  # user, local_angle, local

Recording:

AUTO_RECORD_ON_THROTTLE = True  # Auto-record when moving
RECORD_DURING_AI = False  # Don't record AI driving
AUTO_CREATE_NEW_TUB = False  # Append to existing tub

AI/Training:

DEFAULT_AI_FRAMEWORK = 'tensorflow'  # or 'pytorch'
DEFAULT_MODEL_TYPE = 'linear'  # or 'categorical'
BATCH_SIZE = 128
MAX_EPOCHS = 100
AI_THROTTLE_MULT = 1.0  # Scale AI throttle output

Template Customization

How manage.py Works

The manage.py file is a Python script that:

Loads configuration from config.py and myconfig.py
Creates a Vehicle object
Adds parts (camera, controller, motors, etc.) to the vehicle
Runs the vehicle loop at specified frequency

Key components:

import donkeycar as dk
from donkeycar.parts.camera import PiCamera
from donkeycar.parts.controller import LocalWebController
from donkeycar.parts.actuator import PWMSteering, PWMThrottle

# Initialize vehicle
V = dk.vehicle.Vehicle()

# Add camera
cam = PiCamera(image_w=cfg.IMAGE_W, image_h=cfg.IMAGE_H)
V.add(cam, outputs=['cam/image_array'], threaded=True)

# Add web controller
ctr = LocalWebController(port=cfg.WEB_CONTROL_PORT)
V.add(ctr, inputs=['cam/image_array'],
      outputs=['user/angle', 'user/throttle', 'user/mode', 'recording'],
      threaded=True)

# Add steering and throttle
# ... (actuator setup)

# Start the vehicle loop
V.start(rate_hz=cfg.DRIVE_LOOP_HZ)

Adding Custom Parts

You can modify manage.py to add custom functionality. See the Parts documentation for details.

Updating Your Car

Update manage.py and Scripts

When you update Donkeycar library, update your car application:

cd ~/mycar
donkey update --template complete

This updates:

manage.py
calibrate.py
train.py
config.py

myconfig.py is never overwritten by the update command. Your custom settings are safe.

Common Configuration Patterns

Beginner Setup

# myconfig.py - Safe settings for beginners
CAMERA_TYPE = "PICAM"
USE_JOYSTICK_AS_DEFAULT = True
JOYSTICK_MAX_THROTTLE = 0.3  # Slow speed
AUTO_RECORD_ON_THROTTLE = True
AI_THROTTLE_MULT = 0.5  # Very cautious AI

Racing Setup

# myconfig.py - Performance settings
CAMERA_FRAMERATE = 30  # Higher frame rate
DRIVE_LOOP_HZ = 30
JOYSTICK_MAX_THROTTLE = 1.0  # Full speed
AI_THROTTLE_MULT = 1.0
AI_LAUNCH_DURATION = 1.0  # Boost at start
AI_LAUNCH_THROTTLE = 1.0

Development/Testing

# myconfig.py - Development settings
DRIVE_TRAIN_TYPE = "MOCK"  # No motors
CAMERA_TYPE = "MOCK"  # Simulated camera
DONKEY_GYM = True  # Use simulator
SHOW_FPS = True  # Display performance
HAVE_CONSOLE_LOGGING = True
LOGGING_LEVEL = 'DEBUG'

Troubleshooting

“No module named ‘donkeycar’”

Activate your Python virtual environment
Verify Donkeycar is installed: pip list | grep donkey

“Permission denied” when running manage.py

chmod +x manage.py

Config changes not taking effect

Ensure changes are in myconfig.py, not config.py
Check for Python syntax errors
Verify indentation (Python is whitespace-sensitive)

Car runs but doesn’t match config

Specify myconfig explicitly: python manage.py drive --myconfig=myconfig.py
Check that myconfig.py is in the same directory as manage.py

Next Steps

Calibrate your car

Now that you have a car application, calibrate your steering and throttle.

Start driving

Once calibrated, learn to drive and collect training data.

Train a model

After collecting data, train your first autopilot model.

Getting Started

Core Concepts

Building Your Car

Training & Autopilots

Parts Reference

Advanced Topics

Creating a Car Application

Overview

Creating Your Car

Basic Command

Command Options

Available Templates

Template Examples

Directory Structure

Key Files Explained

manage.py

config.py

myconfig.py

calibrate.py

train.py

Data and Models Directories

data/

models/

Configuration Overview

Essential Settings

Template Customization

How manage.py Works

Adding Custom Parts

Updating Your Car

Update manage.py and Scripts

Common Configuration Patterns

Beginner Setup

Racing Setup

Development/Testing

Troubleshooting

Next Steps

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Building Your Car

Training & Autopilots

Parts Reference

Advanced Topics

​Overview

​Creating Your Car

​Basic Command

​Command Options

​Available Templates

​Template Examples

​Directory Structure

​Key Files Explained

​manage.py

​config.py

​myconfig.py

​calibrate.py

​train.py

​Data and Models Directories

​data/

​models/

​Configuration Overview

​Essential Settings

​Template Customization

​How manage.py Works

​Adding Custom Parts

​Updating Your Car

​Update manage.py and Scripts

​Common Configuration Patterns

​Beginner Setup

​Racing Setup

​Development/Testing

​Troubleshooting

​Next Steps

Build docs developers (and LLMs) love

Overview

Creating Your Car

Basic Command

Command Options

Available Templates

Template Examples

Directory Structure

Key Files Explained

manage.py

config.py

myconfig.py

calibrate.py

train.py

Data and Models Directories

data/

models/

Configuration Overview

Essential Settings

Template Customization

How manage.py Works

Adding Custom Parts

Updating Your Car

Update manage.py and Scripts

Common Configuration Patterns

Beginner Setup

Racing Setup

Development/Testing

Troubleshooting

Next Steps