Creating a Car Application

Initialize your Donkeycar application using donkey createcar and understand the project structure

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:

1. config.py is loaded first with defaults
2. myconfig.py overrides any settings you specify
3. 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:

1. Loads configuration from config.py and myconfig.py
2. Creates a Vehicle object
3. Adds parts (camera, controller, motors, etc.) to the vehicle
4. 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