> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/autorope/donkeycar/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
donkey createcar --path ~/mycar
```

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

### Command Options

```bash theme={null}
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

```bash theme={null}
# 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:**

```bash theme={null}
# 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:**

```python theme={null}
# 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
```

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

### calibrate.py

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

```bash theme={null}
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.

```bash theme={null}
# 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:**

```python theme={null}
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:**

```python theme={null}
DRIVE_TRAIN_TYPE = "PWM_STEERING_THROTTLE"
# See hardware setup guide for full configuration
```

**Controller:**

```python theme={null}
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:**

```python theme={null}
WEB_CONTROL_PORT = 8887
WEB_INIT_MODE = "user"  # user, local_angle, local
```

**Recording:**

```python theme={null}
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:**

```python theme={null}
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:**

```python theme={null}
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](/parts/custom-parts) for details.

## Updating Your Car

### Update manage.py and Scripts

When you update Donkeycar library, update your car application:

```bash theme={null}
cd ~/mycar
donkey update --template complete
```

This updates:

* `manage.py`
* `calibrate.py`
* `train.py`
* `config.py`

<Warning>
  `myconfig.py` is never overwritten by the update command. Your custom settings are safe.
</Warning>

## Common Configuration Patterns

### Beginner Setup

```python theme={null}
# 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

```python theme={null}
# 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

```python theme={null}
# 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**

```bash theme={null}
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

<Steps>
  ### Calibrate your car

  Now that you have a car application, [calibrate your steering and throttle](/guides/calibration).

  ### Start driving

  Once calibrated, [learn to drive and collect training data](/guides/driving).

  ### Train a model

  After collecting data, [train your first autopilot model](/training/deep-learning).
</Steps>