PyBullet Differential Drive Robot Simulation

A comprehensive PyBullet-based simulation environment for a differential drive robot with sensor streams, navigation capabilities, and RL training support.

Features

✅ 3D Physics Simulation: Full PyBullet physics with realistic robot dynamics
✅ Differential Drive Robot: Custom URDF model with wheels, base, and sensors
✅ Real-time Sensor Streams: Lidar, RGB camera, depth camera, IMU, and odometry
✅ Built-in Sensor Visualization: RGB, depth, and segmentation views in PyBullet GUI
✅ PID Navigation Controller: Simple, effective goal-based navigation with obstacle avoidance
✅ Multiple Environments: Warehouse, street, and maze environments for testing
✅ Sensor Data Logging: Record and analyze sensor data for training
✅ RL-Ready: Full Gymnasium environment wrapper for training
✅ Path Planning: A* and RRT path planning algorithms
✅ Advanced Navigation: Dynamic obstacle avoidance with replanning
✅ Performance Logging: Detailed timing and performance metrics
✅ Localization Tracking: Robot pose and velocity tracking

Quick Start

Prerequisites

Python 3.8-3.11 (Python 3.12+ may require conda)
Conda (recommended) or pip with virtual environment

Installation

Option 1: Using Conda (Recommended)

# Clone or navigate to the project
cd pybullet_sim

# Create conda environment
conda create -n pybullet_env python=3.11
conda activate pybullet_env

# Install PyBullet via conda
conda install -c conda-forge pybullet

# Install other dependencies
pip install -r requirements.txt

Option 2: Using pip (may have issues on macOS/Apple Silicon)

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

Note: If pip installation fails, see INSTALL.md for troubleshooting.

Verify Installation

python scripts/00_check_setup.py

Project Structure

pybullet_sim/
├── urdf/                          # Robot URDF files
│   └── diff_drive_robot.urdf     # Differential drive robot model
├── scripts/                       # Python scripts
│   ├── diff_drive_robot.py       # Robot controller class with sensors
│   ├── path_planner.py           # A* and RRT path planning
│   ├── localization_tracker.py   # Pose and velocity tracking
│   ├── pybullet_nav_env.py       # Gymnasium environment wrapper
│   ├── 00_check_setup.py         # Setup verification
│   ├── 01_test_pybullet.py       # Basic robot movement test
│   ├── 02_simple_navigation.py   # Simple goal navigation
│   ├── 03_sensor_streams.py       # Real-time sensor visualization
│   ├── 04_sensor_logger.py       # Sensor data recording
│   ├── 05_environment_builder.py # Environment creation
│   ├── 06_navigate_environment.py # PID navigation with obstacles
│   ├── 10_advanced_navigation.py # Path planning navigation
│   ├── 11_train_rl.py            # RL training script
│   ├── 12_evaluate_rl.py          # RL evaluation script
│   └── diagnose_pybullet.py      # Installation diagnostics
├── models/                        # Trained RL models (created during training)
├── logs/                          # Logs and sensor data
│   └── sensor_data/              # Recorded sensor data
├── configs/                       # Configuration files
├── assets/                        # Additional assets
├── requirements.txt               # Python dependencies
├── README.md                      # This file
├── SETUP.md                       # Detailed setup instructions
└── INSTALL.md                     # Installation troubleshooting

Usage

1. Basic Robot Movement Test

python scripts/01_test_pybullet.py

Tests basic robot movement: forward, backward, and turning motions.

2. Simple Navigation

python scripts/02_simple_navigation.py

Robot navigates to a goal position using a simple proportional controller.

3. Real-time Sensor Streams

python scripts/03_sensor_streams.py

Displays live sensor data in a matplotlib dashboard:

Lidar Scan: 2D top-down view with color-coded rays
RGB Camera: Live feed from robot's perspective
Depth Camera: Depth map visualization
IMU Data: Accelerometer and gyroscope readings
Odometry: Wheel velocities and robot velocity
Trajectory: Path visualization

Note: The matplotlib window may stay on top. You can minimize it or use Alt+Tab to switch windows.

4. Sensor Data Logging

python scripts/04_sensor_logger.py

Records all sensor data to JSON files and saves camera images in logs/sensor_data/.

5. Environment Builder

# Create warehouse environment
python scripts/05_environment_builder.py warehouse

# Create street environment
python scripts/05_environment_builder.py street

# Create maze environment
python scripts/05_environment_builder.py maze

Creates realistic environments with obstacles for testing navigation.

6. Navigation in Environments

# Navigate in warehouse
python scripts/06_navigate_environment.py warehouse

# Navigate in street
python scripts/06_navigate_environment.py street

# Navigate in maze
python scripts/06_navigate_environment.py maze

Tests robot navigation with PID-based obstacle avoidance in different environments. The robot uses a simple PID controller to navigate to the goal while avoiding obstacles.

Features:

PID Controller: Proportional and derivative terms for smooth navigation
Obstacle Avoidance: Modifies heading when obstacles detected in front
Sensor Visualization: RGB, depth, and segmentation views in PyBullet GUI tabs
Lidar Visualization: Colored rays in 3D view (red=close, green=far)

7. Advanced Navigation with Path Planning

# Single goal with A* planner
python scripts/10_advanced_navigation.py astar

# Single goal with RRT planner
python scripts/10_advanced_navigation.py rrt

# Multi-goal navigation (visits multiple waypoints)
python scripts/10_advanced_navigation.py astar --multi
python scripts/10_advanced_navigation.py rrt --multi

Advanced navigation features with path planning algorithms:

Path Planning Algorithms:

A (A-Star)*: Grid-based optimal path planning
RRT (Rapidly-exploring Random Tree): Continuous space path planning

Features:

Dynamic Obstacle Avoidance: Replans path when obstacles detected
Path Visualization: Blue lines show planned path in 3D view
Multi-Goal Navigation: Visit multiple waypoints in sequence
Path Following: Smooth waypoint following with lookahead distance

Robot Specifications

Type: Differential drive robot
Wheel radius: 0.05 m
Wheel base: 0.22 m
Max linear velocity: 0.5 m/s
Max angular velocity: 2.0 rad/s

Sensors

Lidar: 36-ray 2D lidar, 5m range
RGB Camera: 320x240 resolution, 60° FOV
Depth Camera: Same resolution, 0.01-10m range
IMU: Simulated accelerometer and gyroscope (with noise)
Odometry: Wheel encoder simulation

Scripts Overview

Script	Description
`00_check_setup.py`	Verifies all dependencies are installed
`01_test_pybullet.py`	Basic robot movement demonstration
`02_simple_navigation.py`	Simple goal-based navigation
`03_sensor_streams.py`	Real-time sensor visualization dashboard
`04_sensor_logger.py`	Record sensor data for analysis
`05_environment_builder.py`	Build warehouse/street/maze environments
`06_navigate_environment.py`	Navigate with PID controller and obstacle avoidance
`10_advanced_navigation.py`	Advanced navigation with A*/RRT path planning
`11_train_rl.py`	Train RL agent (PPO, SAC, TD3)
`12_evaluate_rl.py`	Evaluate trained RL models

8. Reinforcement Learning Training

Train a reinforcement learning agent to navigate to goals:

# Train PPO agent (default)
python scripts/11_train_rl.py --algorithm ppo --timesteps 1000000 --num-envs 4

# Train with specific environment
python scripts/11_train_rl.py --algorithm ppo --env-type warehouse --timesteps 1000000

# Use Apple Silicon GPU (M1/M2/M3)
python scripts/11_train_rl.py --algorithm ppo --device mps --timesteps 1000000

# Train other algorithms
python scripts/11_train_rl.py --algorithm sac --timesteps 1000000
python scripts/11_train_rl.py --algorithm td3 --timesteps 1000000

Training Options:

--algorithm: PPO (default), SAC, or TD3
--env-type: warehouse (default), street, or maze
--timesteps: Total training timesteps (default: 1,000,000)
--num-envs: Number of parallel environments (default: 4)
--device: auto (default), mps, cuda, or cpu
--learning-rate: Learning rate (default: 3e-4)
--seed: Random seed for reproducibility

Training Output:

Models saved to models/ directory
Best model: models/best_model.zip
Final model: models/{algorithm}_{env_type}_final.zip
Checkpoints: models/checkpoints/
TensorBoard logs: logs/tensorboard/

9. Evaluate Trained RL Models

Evaluate trained models:

# Evaluate with default settings (auto-detects best model)
python scripts/12_evaluate_rl.py --algorithm ppo --env-type warehouse --num-episodes 5

# Evaluate with rendering
python scripts/12_evaluate_rl.py --algorithm ppo --env-type warehouse --num-episodes 5 --render

# Evaluate specific model
python scripts/12_evaluate_rl.py --algorithm ppo --model-path models/best_model --num-episodes 10

Evaluation Options:

--algorithm: PPO, SAC, or TD3
--env-type: warehouse (default), street, or maze
--model-path: Path to specific model (default: auto-detect)
--num-episodes: Number of evaluation episodes (default: 10)
--render: Enable PyBullet GUI visualization
--deterministic: Use deterministic policy (default: True)

Current Performance (Latest Training):

Success Rate: 5/5 (100.0%)
Average Reward: 57.43 ± 3.83
Average Episode Length: 164.0 ± 57.9 steps
Average Distance Traveled: 3.06m ± 1.09m
Algorithm: PPO (Proximal Policy Optimization)
Environment: Warehouse (31 obstacles)
Observation Space: 43 dimensions (dx, dy, dtheta, distance, v, w, lidar[36], min_lidar)
Action Space: [linear_velocity, angular_velocity] - forward-only (no backward driving)

API Usage

Using the Robot Class

from scripts.diff_drive_robot import DiffDriveRobot
import pybullet as p

# Initialize PyBullet
p.connect(p.GUI)
p.setGravity(0, 0, -9.81)

# Create robot
robot = DiffDriveRobot("urdf/diff_drive_robot.urdf", start_pos=[0, 0, 0.1])

# Control robot
robot.set_velocity(v=0.3, w=0.0)  # Move forward

# Get sensor data
pose = robot.get_pose()                    # [x, y, theta]
lidar = robot.get_lidar_scan()             # Array of distances
rgb, depth = robot.get_camera_image()      # Camera images
imu = robot.get_imu_data()                 # IMU readings
odom = robot.get_odometry()                # Odometry data

Troubleshooting

Installation Issues

See INSTALL.md for detailed troubleshooting:

PyBullet build failures
"No matching distribution" errors
Apple Silicon (M1/M2/M3) issues
Python version compatibility

Common Issues

Matplotlib window stays on top (sensor streams script):

This is a known matplotlib behavior
Use Alt+Tab (Cmd+Tab on Mac) to switch windows
Or minimize the matplotlib window
Note: 06_navigate_environment.py uses built-in PyBullet GUI sensor panels instead

PyBullet GUI doesn't open:

Ensure you're using p.GUI mode (not p.DIRECT)
On macOS, may need XQuartz for older systems
Try: pip install --upgrade pybullet

Import errors:

Ensure conda/virtual environment is activated
Verify installation: python scripts/00_check_setup.py

Apple Silicon GPU (M1/M2/M3) for RL Training:

The training script automatically detects and uses MPS (Metal Performance Shaders) if available
Use --device auto (default) to auto-detect the best device
Or explicitly use --device mps to use Apple Silicon GPU
Ensure PyTorch is installed: pip install torch (should include MPS support by default)
GPU acceleration can significantly speed up training compared to CPU

RL Training Results

Current Performance

Latest Training Run (PPO, Warehouse Environment):

✅ Success Rate: 5/5 (100.0%)
✅ Average Reward: 57.43 ± 3.83
✅ Average Episode Length: 164.0 ± 57.9 steps
✅ Average Distance Traveled: 3.06m ± 1.09m

Reward Function:

Progress-based: Primary reward for distance reduction
Heading alignment: Small reward for facing goal when far
Goal bonus: +50.0 when reached
Collision penalty: -10.0
Time penalty: -0.01 (encourages efficiency)

Observation Space: 43 dimensions

Relative goal position (dx, dy, dtheta)
Distance to goal
Current velocities (v, w)
Lidar scan (36 rays)
Minimum lidar distance

Action Space: [linear_velocity, angular_velocity]

Forward-only movement (no backward driving)
Linear: 0.0 to 0.7 m/s
Angular: -2.0 to 2.0 rad/s

Next Steps

Environment Setup: Create warehouse/street environments with obstacles
Advanced Navigation: Implement path planning and obstacle avoidance
RL Training: Set up Gymnasium environment for reinforcement learning
Reward Function Optimization: Achieved 100% success rate with simplified reward
Hyperparameter tuning for RL algorithms
Curriculum learning for harder environments
Multi-environment training (warehouse + street + maze)
Sim-to-Real: Prepare for real robot deployment

Contributing

Feel free to submit issues, fork the repository, and create pull requests.

License

See LICENSE file for details.

Acknowledgments

PyBullet physics engine
Stable-Baselines3 for RL algorithms
Gymnasium for RL environment interface

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
scripts		scripts
urdf		urdf
.gitignore		.gitignore
INSTALL.md		INSTALL.md
LICENSE		LICENSE
README.md		README.md
SETUP.md		SETUP.md
requirements.txt		requirements.txt

License

padawanabhi/pybullet_sim

Folders and files

Latest commit

History

Repository files navigation

PyBullet Differential Drive Robot Simulation

Features

Quick Start

Prerequisites

Installation

Option 1: Using Conda (Recommended)

Option 2: Using pip (may have issues on macOS/Apple Silicon)

Verify Installation

Project Structure

Usage

1. Basic Robot Movement Test

2. Simple Navigation

3. Real-time Sensor Streams

4. Sensor Data Logging

5. Environment Builder

6. Navigation in Environments

7. Advanced Navigation with Path Planning

Robot Specifications

Sensors

Scripts Overview

8. Reinforcement Learning Training

9. Evaluate Trained RL Models

API Usage

Using the Robot Class

Troubleshooting

Installation Issues

Common Issues

RL Training Results

Current Performance

Next Steps

Contributing

License

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages