Autonomous robot that navigates obstacles, executes missions, and delivers real-time insights through a web dashboard.
Full ROS2 AMR dashboard showing real-time robot status, mission control, map view, and performance metrics
Intuitive mission management with demo navigation, custom goal creation, and real-time execution controls
Live map visualization with robot position, navigation trail, obstacles, and goal markers
A comprehensive, demo-ready ROS2 Autonomous Mobile Robot (AMR) system featuring Nav2 navigation, real-time web dashboard, mission management, and automated data logging. Built for M3 Mac compatibility with Webots simulation and Docker-based ROS2 Humble deployment.
- 🤖 Autonomous Navigation: Nav2 stack with SLAM, path planning, and obstacle avoidance
- 🎯 Mission Management: Queue-based goal execution with real-time status tracking
- 📊 Live Dashboard: Next.js web interface with real-time telemetry and control
- 📈 Performance Metrics: Prometheus-compatible metrics collection and visualization
- 📹 Automatic Recording: Rosbag2 integration with mission-based start/stop
- 🔍 Fiducial Detection: OpenCV-based ArUco marker recognition
- 🌐 WebSocket Bridge: Real-time communication between ROS2 and dashboard
- 📱 Responsive UI: Modern, mobile-friendly dashboard design
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Webots Sim │ │ ROS2 Stack │ │ Dashboard │
│ │ │ │ │ │
│ • Diffbot Robot │◄──►│ • Nav2Navigation│◄──►│ • Next.js UI │
│ • Showfloor Map │ │ • Mission Mgmt │ │ • Real-time │
│ • Sensors │ │ • Perception │ │ • Control Panel │
│ • Physics │ │ • Metrics │ │ • Map View │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ FastAPI Server │
│ │
│ • REST API │
│ • WebSocket │
│ • Mission CRUD │
└─────────────────┘
ros2-amr/
├─ sim/ # Webots simulation assets
│ ├─ worlds/showfloor.wbt # Showroom environment
│ └─ robots/diffbot.wbo # Differential drive robot
│
├─ ros2/ # ROS2 packages (Docker)
│ ├─ packages/ # ROS2 workspace packages
│ │ ├─ amr_bringup/ # System launch & configuration
│ │ ├─ amr_nav/ # Nav2 configuration
│ │ ├─ amr_perception/ # Fiducial detection
│ │ ├─ amr_mission/ # Mission queue management
│ │ ├─ amr_bridge/ # WebSocket/REST bridge
│ │ ├─ amr_metrics/ # Prometheus metrics
│ │ └─ amr_logger/ # Rosbag2 recorder
│ ├─ overlays/ # Maps and parameters
│ └─ docker/ # Container configuration
│
├─ server/ # FastAPI backend
│ ├─ app.py # Main API server
│ └─ requirements.txt # Python dependencies
│
├─ dashboard/ # Next.js frontend
│ ├─ components/ # React components
│ ├─ pages/ # Next.js pages
│ └─ styles/ # Tailwind CSS
│
├─ ops/ # Orchestration
│ ├─ compose.yml # Docker Compose
│ ├─ net.env # Network configuration
│ └─ Makefile # Operation commands
│
├─ scripts/ # Utility scripts
│ ├─ record_demo.sh # Demo recording
│ └─ verify_topics.sh # System verification
│
└─ media/ # Documentation assets
├─ screenshots/ # UI screenshots
└─ README.md # Media documentation
- macOS (tested on M3 Mac)
- Docker Desktop with 8GB+ RAM allocation
- Node.js 20+ (for local dashboard development)
- Webots 2023b (optional, for simulation)
-
Clone and setup:
git clone <repository-url> cd ros2-amr
-
Install dependencies:
# Install system requirements brew install docker docker-compose node # Install Webots (optional) brew install --cask webots
-
Start the system:
cd ops make up -
Access the dashboard:
- Dashboard: http://localhost:3002
- API Server: http://localhost:8002
- Metrics: http://localhost:8080/metrics
- Open http://localhost:3002 in your browser
- Click "Start Demo Mission" in the Mission Panel
- Watch the robot navigate in the Map View
- Monitor real-time metrics in the Performance Panel
- Create Missions: Add custom goal points by clicking on the map
- Start/Stop: Control mission execution
- Queue Management: View and manage mission queue
- Real-time Tracking: See robot position and trail
- Goal Setting: Click anywhere to add navigation goals
- Obstacle Visualization: View detected obstacles and landmarks
- Live Telemetry: Position, velocity, battery level
- Mission State: Current status and progress
- Connection Status: WebSocket connectivity indicator
- Performance Data: Goals completed, success rate, distance traveled
- System Health: Uptime, replan count, navigation stability
- Visual Indicators: Status badges and trend analysis
# System management
make up # Start all services
make down # Stop all services
make logs # View all logs
make status # Check service status
# ROS2 operations
make ros2-topics # List ROS2 topics
make ros2-nodes # List active nodes
make ros2-info # System information
# Data management
make bag # Start rosbag recording
make bag-list # List available bags
make clean-bags # Clean up recordings
# Development
make dev # Start development environment
make test # Run system tests
make shell # Open ROS2 shell# Get system status
curl http://localhost:8002/api/status
# Create a mission
curl -X POST http://localhost:8002/api/mission \
-H "Content-Type: application/json" \
-d '{
"name": "Custom Mission",
"goals": [
{"x": 2.0, "y": 2.0, "theta": 0.0},
{"x": -1.0, "y": 1.0, "theta": 1.57}
]
}'
# Start mission
curl -X POST http://localhost:8002/api/mission/{mission_id}/start
# Stop mission
curl -X POST http://localhost:8002/api/mission/stopconst ws = new WebSocket('ws://localhost:8002/ws');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
switch(data.type) {
case 'status_update':
// Robot status update
break;
case 'mission_started':
// Mission started
break;
case 'mission_stopped':
// Mission stopped
break;
}
};The system tracks comprehensive metrics:
| Metric | Description | Type |
|---|---|---|
robot_pose_x/y/theta |
Current robot position | Gauge |
robot_velocity_linear/angular |
Current velocities | Gauge |
mission_goals_completed |
Total completed goals | Counter |
mission_total_replans |
Path replanning events | Counter |
mission_distance_traveled |
Total distance | Counter |
mission_success_rate |
Completion rate | Gauge |
battery_level |
Robot battery percentage | Gauge |
system_uptime |
System runtime | Counter |
Access metrics at http://localhost:8080/metrics for Prometheus scraping.
Key configuration files:
ros2/packages/amr_bringup/params/nav2_params.yaml- Navigation parametersros2/packages/amr_bringup/params/robot_params.yaml- Robot configurationros2/overlays/maps/showfloor.yaml- Map configuration
# Network configuration
API_URL=http://localhost:8002
WS_URL=ws://localhost:8002/ws
PORT_DASHBOARD=3002
PORT_SERVER=8002
# ROS2 configuration
RMW_IMPLEMENTATION=rmw_fastrtps_cpp
ROS_DOMAIN_ID=0
# Development settings
DEBUG=false
NODE_ENV=development# Check Docker resources
docker system df
docker system prune -f
# Restart Docker Desktop
# Increase memory allocation to 8GB+# Check if API server is running
curl http://localhost:8002/health
# Check logs
make logs-server# Verify system health
./scripts/verify_topics.sh
# Check ROS2 logs
make logs-ros2
# Restart system
make down && make up# Check Webots logs
make logs-webots
# Restart Webots container
make webots-restart
# Verify display settings
echo $DISPLAY- CPU: 4+ cores recommended
- RAM: 8GB minimum, 16GB recommended
- Storage: 10GB free space
- Network: Local network access for WebSocket
# Docker Desktop settings
CPU: 4+ cores
Memory: 8GB+
Swap: 2GB+- Adjust
controller_frequencyin nav2_params.yaml - Optimize costmap resolution and update rates
- Tune DWB controller parameters for your robot
- Enable browser hardware acceleration
- Use Chrome/Edge for best WebSocket performance
- Monitor memory usage in browser dev tools
- Fork the repository
- Create a feature branch:
git checkout -b feature-name - Make changes and test thoroughly
- Submit a pull request with detailed description
# Development environment
make dev
# Run tests
make test
# Code formatting
npm run lintThis project is licensed under the Apache-2.0 License - see the LICENSE file for details.
- ROS2 Community for the excellent navigation stack
- Webots for the realistic simulation environment
- Nav2 Team for the comprehensive navigation framework
- OpenCV for computer vision capabilities
- Next.js and Tailwind CSS for the modern dashboard
- Issues: GitHub Issues for bug reports
- Discussions: GitHub Discussions for questions
- Documentation: This README and inline code comments
Built with ❤️ for the ROS2 community
Perfect for demonstrations, educational purposes, and as a foundation for real-world AMR applications.