Donkey Gym Simulator

Train and race in virtual environments using the Donkey Gym simulator

The Donkey Gym simulator allows you to train and test your autonomous models in virtual environments without risking your physical car. Built on Unity and OpenAI Gym, it provides realistic physics and multiple track environments.

Overview

Donkey Gym enables:

• Virtual racing on generated tracks and real-world courses
• Safe training without hardware wear
• Rapid iteration with instant resets
• Latency simulation to test real-world conditions
• Multi-environment support including warehouse and AVC tracks

Installation

Download the simulator binary for your platform:

# Linux
wget https://github.com/tawnkramer/donkey_gym/releases/download/v18.9/DonkeySimLinux.zip
unzip DonkeySimLinux.zip

Install the Python gym environment:

pip install gym-donkeycar

Configuration

Edit your myconfig.py to enable the simulator:

# Enable Donkey Gym
DONKEY_GYM = True

# Path to simulator executable
DONKEY_SIM_PATH = "/path/to/donkey_sim.x86_64"
# Use "remote" to connect to running sim
# Use "remote" when racing on virtual-race-league

# Choose environment
DONKEY_GYM_ENV_NAME = "donkey-generated-track-v0"
# Options:
# - donkey-generated-track-v0 (procedural tracks)
# - donkey-generated-roads-v0 (road networks)
# - donkey-warehouse-v0 (indoor warehouse)
# - donkey-avc-sparkfun-v0 (AVC course)

# Gym configuration
GYM_CONF = {
    "img_h": 120,
    "img_w": 160,
    "body_style": "donkey",  # donkey|bare|car01
    "body_rgb": (128, 128, 128),
    "car_name": "car",
    "font_size": 100,
    "racer_name": "Your Name",
    "country": "Place",
    "bio": "I race robots."
}

# Network settings
SIM_HOST = "127.0.0.1"
# Use "trainmydonkey.com" for virtual-race-league

# Artificial latency (milliseconds)
SIM_ARTIFICIAL_LATENCY = 0
# Try 100-400ms to simulate network delay

DonkeyGymEnv Part

The DonkeyGymEnv part connects your vehicle to the simulator:

from donkeycar.parts.dgym import DonkeyGymEnv

# Create gym environment
cam = DonkeyGymEnv(
    cfg.DONKEY_SIM_PATH,
    host=cfg.SIM_HOST,
    env_name=cfg.DONKEY_GYM_ENV_NAME,
    conf=cfg.GYM_CONF,
    delay=cfg.SIM_ARTIFICIAL_LATENCY
)

# Add to vehicle
V.add(cam, 
      inputs=['angle', 'throttle', 'brake'],
      outputs=['cam/image_array'],
      threaded=True)

From donkeycar/parts/dgym.py:67-71:

cam = DonkeyGymEnv(cfg.DONKEY_SIM_PATH, 
                   host=cfg.SIM_HOST, 
                   env_name=cfg.DONKEY_GYM_ENV_NAME, 
                   conf=cfg.GYM_CONF, 
                   delay=cfg.SIM_ARTIFICIAL_LATENCY)

Recording Telemetry

Capture additional telemetry from the simulator:

# Enable telemetry recording
SIM_RECORD_LOCATION = True    # x, y, z position and speed
SIM_RECORD_GYROACCEL = True   # gyroscope and accelerometer
SIM_RECORD_VELOCITY = True    # velocity vector
SIM_RECORD_LIDAR = False      # lidar data (if enabled)

When enabled, the simulator outputs include:

cam = DonkeyGymEnv(
    cfg.DONKEY_SIM_PATH,
    host=cfg.SIM_HOST,
    env_name=cfg.DONKEY_GYM_ENV_NAME,
    conf=cfg.GYM_CONF,
    record_location=cfg.SIM_RECORD_LOCATION,
    record_gyroaccel=cfg.SIM_RECORD_GYROACCEL,
    record_velocity=cfg.SIM_RECORD_VELOCITY,
    record_lidar=cfg.SIM_RECORD_LIDAR
)

# Outputs: image, pos_x, pos_y, pos_z, speed, cte, 
#          gyro_x, gyro_y, gyro_z, accel_x, accel_y, accel_z

Latency Simulation

The simulator supports artificial latency to test control algorithms under realistic network conditions:

# Add 150ms delay (typical network latency)
SIM_ARTIFICIAL_LATENCY = 150

The delay buffer implementation from donkeycar/parts/dgym.py:47-62:

def delay_buffer(self, frame, info):
    now = time.time()
    buffer_tuple = (now, frame, info)
    self.buffer.append(buffer_tuple)

    # go through the buffer
    num_to_remove = 0
    for buf in self.buffer:
        if now - buf[0] >= self.delay:
            num_to_remove += 1
            self.frame = buf[1]
        else:
            break

    # clear the buffer
    del self.buffer[:num_to_remove]

Running the Simulator

Local Mode

Start your car in simulator mode:

python manage.py drive --js

The simulator will launch automatically and connect.

Remote Mode

Start the simulator manually, then connect:

DONKEY_SIM_PATH = "remote"

python manage.py drive --js

Training

Train models using simulator data:

# Record training data in simulator
python manage.py drive

# Train model
python train.py --tub data/ --model models/sim_pilot.h5

# Test in autopilot mode
python manage.py drive --model models/sim_pilot.h5

Virtual Race League

Race against others online:

SIM_HOST = "trainmydonkey.com"
DONKEY_SIM_PATH = "remote"

Configure your racer profile:

GYM_CONF["racer_name"] = "SpeedDemon"
GYM_CONF["country"] = "USA"
GYM_CONF["bio"] = "Testing autonomous racing algorithms"

Resource Management

The simulator uses GPU resources. To avoid conflicts:

import os
if cfg.DONKEY_GYM:
    # Disable CUDA for model to free GPU for simulator
    os.environ["CUDA_VISIBLE_DEVICES"] = "-1"

From donkeycar/templates/simulator.py:47-50.

Troubleshooting

Connection Issues

# Check simulator is running
# Verify SIM_HOST and port (default 9091)
SIM_HOST = "127.0.0.1"

Performance

• Lower image resolution in GYM_CONF
• Disable unnecessary telemetry recording
• Close other GPU-intensive applications

Path Not Found

# Verify simulator path
ls -l /path/to/donkey_sim.x86_64

# Make executable
chmod +x /path/to/donkey_sim.x86_64

Best Practices

1. Start with generated tracks - Test algorithms on varied terrain
2. Use artificial latency - Prepare for real-world network delays
3. Record telemetry - Analyze car behavior and track position
4. Transfer learning - Fine-tune simulator models with real-world data
5. Test edge cases - Use simulator to safely test failure scenarios

Next Steps

• Configure telemetry to monitor performance
• Add path following for waypoint navigation
• Explore kinematics models for physics simulation