Driving Your Donkeycar

​

Overview

​

Starting Your Car

​

Basic Drive Command

cd ~/mycar
python manage.py drive

PID: 12345
You can now go to <your-hostname>.local:8887 to drive your car.

​

With a Trained Model

# Drive with autopilot available
python manage.py drive --model models/mypilot.h5

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

​

With Joystick

# Use physical joystick controller
python manage.py drive --js

USE_JOYSTICK_AS_DEFAULT = True

​

Web Interface

​

Accessing the Interface

http://<your-pi-hostname>.local:8887

• http://donkeypi.local:8887
• http://raspberrypi.local:8887
• Or use IP address: http://192.168.1.100:8887

​

Web Interface Features

• Shows real-time view from your car’s camera
• Updates as you drive

• Steering: Left/right control (-1.0 to 1.0)
• Throttle: Forward/reverse control (-1.0 to 1.0)

• Switch between User, Local Angle, and Local (autopilot) modes

• Shows when data is being saved
• Displays number of recorded frames

• Current steering/throttle values
• FPS (frames per second)
• Model information (when using autopilot)

​

Driving with Web Interface

​

Keyboard Controls

• A / Left Arrow: Steer left
• D / Right Arrow: Steer right

• W / Up Arrow: Forward
• S / Down Arrow: Reverse/Brake
• Space: Quick stop

• R: Toggle recording

• 1: User mode
• 2: Local Angle mode
• 3: Local mode (full autopilot)

​

Driving Modes

​

User Mode

• Steering: Human
• Throttle: Human

• Collecting training data
• Testing car setup
• Learning the track

WEB_INIT_MODE = "user"  # Default on startup

​

Local Angle Mode

• Steering: AI/Autopilot
• Throttle: Human

• Testing steering model safely
• Learning how the AI steers
• Maintaining speed control during testing

• You control the speed
• Easier to stop if AI makes mistakes
• Good for initial autopilot testing

​

Local Mode (Full Autopilot)

• Steering: AI/Autopilot
• Throttle: AI/Autopilot

• After successful Local Angle testing
• Racing
• Demonstrating autonomous driving

​

Mode Comparison

​

Recording Training Data

​

Auto-Record on Throttle

AUTO_RECORD_ON_THROTTLE = True

• Recording starts automatically when throttle > 0
• Recording stops when throttle returns to 0
• Prevents recording while stationary

​

Manual Recording

AUTO_RECORD_ON_THROTTLE = False

• Web interface: Recording switch
• Keyboard: R key
• Joystick: Assigned button

​

Recording During AI

RECORD_DURING_AI = True

​

Tub Management

AUTO_CREATE_NEW_TUB = True  # New directory for each session

AUTO_CREATE_NEW_TUB = False  # Add to existing data/

data/
├── tub_1_21-03-15/  # First session
├── tub_2_21-03-15/  # Second session (if AUTO_CREATE_NEW_TUB=True)
└── tub_3_21-03-16/  # Next day's session

​

What Gets Recorded

• Camera image (cam/image_array)
• Steering angle (user/angle) - range: -1.0 to 1.0
• Throttle value (user/throttle) - range: -1.0 to 1.0
• Drive mode (user/mode) - “user”, “local_angle”, “local”
• Timestamp
• Optional: IMU data, LIDAR data, speed, behaviors

​

Joystick Control

​

Supported Controllers

• PlayStation 3 (PS3)
• PlayStation 4 (PS4)
• Xbox One/360
• Nintendo Switch Pro
• Logitech F710
• Custom controllers (via donkey createjs)

​

Enabling Joystick

USE_JOYSTICK_AS_DEFAULT = True
CONTROLLER_TYPE = 'xbox'  # or 'ps4', 'ps3', etc.
JOYSTICK_DEVICE_FILE = "/dev/input/js0"

​

Xbox Controller Mapping

• Left Stick: Steering
• Right Trigger: Forward throttle
• Left Trigger: Reverse throttle

• A button: User mode
• B button: Local Angle mode
• X button: Local (autopilot) mode

• Y button: Toggle recording
• RB (Right Bumper): Increase max throttle
• LB (Left Bumper): Decrease max throttle

​

PS4 Controller Mapping

• Left Stick: Steering
• R2: Forward throttle
• L2: Reverse throttle

• Cross (X): User mode
• Circle: Local Angle mode
• Square: Local mode

• Triangle: Toggle recording
• R1: Increase max throttle
• L1: Decrease max throttle

​

Joystick Configuration

# Throttle settings
JOYSTICK_MAX_THROTTLE = 0.5  # Limit to 50% for safety
JOYSTICK_THROTTLE_DIR = -1.0  # Flip direction if needed

# Steering settings  
JOYSTICK_STEERING_SCALE = 1.0  # Adjust sensitivity
JOYSTICK_DEADZONE = 0.01  # Ignore small movements

​

Driving Tips for Good Training Data

​

Track/Environment

• Consistent lighting: Avoid shadows and changing light
• Clear boundaries: Well-defined edges (tape, walls, etc.)
• Simple at first: Start with straight paths, add complexity later
• Repeatable: Same track for all training laps

​

Driving Technique

• Avoid jerky steering corrections
• Gradual throttle changes
• Consistent speed throughout track

• Stay in middle of track/path
• Consistent positioning
• Recovery when needed

• 5-10 laps minimum
• Both directions if possible
• Variety of speeds (if training for different speeds)

​

Data Quality

• Smooth, centered driving
• Consistent speed
• Clear, well-lit images
• 1000-3000 frames minimum

• Erratic steering
• Off-track excursions
• Stopped/stationary frames
• Blurry or dark images

​

Checking Your Data

​

View Recorded Images

# Install donkeycar utilities
cd ~/mycar
ls data/tub_1_21-03-15/images/

​

Tub Statistics

donkey tubhist --tub data/tub_1_21-03-15

​

Make a Movie

donkey makemovie --tub data/tub_1_21-03-15 --out myvideo.mp4

​

Safety Guidelines

​

Before Driving

• Car is properly calibrated
• Emergency stop is accessible (switch to User mode)
• Clear area with no obstacles
• Battery charged
• Camera view is clear

​

During Driving

• Start at low throttle (30-50%)
• Keep hand near controller for quick stop
• Watch for unexpected behavior
• Stop if car acts erratically
• Avoid driving near people or pets

​

Autopilot Testing

• Test in large, clear area first
• Start with Local Angle mode
• Be ready to take over instantly
• Gradually increase trust in AI
• Never use untested models in competitions

​

Throttle Control

​

Limiting Speed

JOYSTICK_MAX_THROTTLE = 0.5  # 50% max speed

AI_THROTTLE_MULT = 0.8  # 80% of learned throttle

​

Launch Control

AI_LAUNCH_DURATION = 1.0  # Boost for 1 second
AI_LAUNCH_THROTTLE = 1.0  # Full throttle during boost  
AI_LAUNCH_ENABLE_BUTTON = 'R2'  # Button to activate

​

Troubleshooting

​

Web interface won’t load

• Pi is powered on and booted
• Connected to same network as Pi
• Correct hostname or IP address
• Port 8887 is not blocked by firewall

# Find your Pi's IP
hostname -I

# Use IP instead of hostname
http://192.168.1.100:8887

​

Camera feed not showing

• Camera is connected properly (CSI or USB)
• Camera is enabled: sudo raspi-config → Interface Options → Camera
• Correct CAMERA_TYPE in myconfig.py

# For Pi Camera
raspistill -o test.jpg

# Check camera permissions
ls -l /dev/video*

​

Car doesn’t respond to controls

• Motors/servos are powered (check battery)
• Calibration values are set in myconfig.py
• Correct DRIVE_TRAIN_TYPE
• PCA9685 is connected (if using)

# Check I2C connection
sudo i2cdetect -y 1

# Should show device at 0x40

​

Recording not working

• Recording toggle is enabled in web UI
• Throttle > 0 (if AUTO_RECORD_ON_THROTTLE=True)
• Sufficient disk space: df -h
• Write permissions in data/ directory

# Check data directory
ls -la ~/mycar/data/

# Manually enable recording in config
AUTO_RECORD_ON_THROTTLE = False

​

Steering/throttle reversed

# Reverse steering
"PWM_STEERING_INVERTED": True,

# Reverse throttle  
"PWM_THROTTLE_INVERTED": True,

​

Joystick not detected

# List input devices
ls /dev/input/

# Should see js0 or js1

# Test joystick
jstest /dev/input/js0

sudo chmod a+rw /dev/input/js0

​

Performance Tuning

​

Increase Frame Rate

DRIVE_LOOP_HZ = 30  # Up from default 20
CAMERA_FRAMERATE = 30  # Match camera to loop rate

• Higher CPU usage
• More frames for AI to process
• Better for fast-moving cars

​

Reduce Latency

IMAGE_W = 120  # Smaller images process faster
IMAGE_H = 90

​

Show Performance Info

SHOW_FPS = True
FPS_DEBUG_INTERVAL = 10  # Print FPS every 10 seconds

​

Next Steps

​

Additional Resources

• Training your autopilot
• Advanced driving techniques
• Creating custom parts
• Donkeycar Community Discord