ANN-Guided Wall-Following Robot

End-to-end robotics AI system — from raw sensor data to a live ROS2 simulation, interactive ML dashboard, REST inference API, and MLflow experiment tracking, all containerised with Docker.

Course: AI 2002 – Artificial Intelligence · NUCES Islamabad
Author: Umer Iqbal (i242528)

---

Results at a Glance

Model	CV Acc	Test Acc	Macro F1	ROC-AUC	Infer (ms/sample)
Random Forest	99.95%	100.00%	1.0000	1.0000	0.060
Gradient Boosting	99.91%	100.00%	1.0000	1.0000	0.011
MLP (ANN)	98.37%	99.63%	0.9935	0.9999	0.004
SVM	98.19%	98.99%	0.9851	0.9998	0.054

---

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        DATA LAYER                               │
│   UCI Wall-Following Dataset · 2 ultrasonic sensors · 4 classes │
│   front_distance (m)  ·  left_distance (m)                      │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                   PHASE 1 — ML CORE                             │
│   EDA → Feature Engineering → 4-Model Benchmark → SHAP         │
│   MLP · Random Forest · SVM · Gradient Boosting                 │
│   GridSearchCV + Cross-Validation · sklearn pipelines (.pkl)    │
└───────────────────────────┬─────────────────────────────────────┘
                            │  .pkl files
               ┌────────────┼────────────┐
               ▼            ▼            ▼
┌──────────────────┐ ┌──────────────┐ ┌──────────────────────────┐
│  PHASE 2         │ │  PHASE 3     │ │  PHASE 4 — MLOps         │
│  Streamlit       │ │  ROS2 Humble │ │                          │
│  Dashboard       │ │  + Gazebo    │ │  ┌──────────────────┐    │
│                  │ │              │ │  │  MLflow Server   │    │
│  Live Inference  │ │  /scan       │ │  │  Experiment      │    │
│  Batch Predict   │ │  (LaserScan) │ │  │  Tracking        │    │
│  Model Compare   │ │      │       │ │  │  :5000           │    │
│  SHAP Explorer   │ │      ▼       │ │  └────────┬─────────┘    │
│                  │ │  ANN Node    │ │           │              │
│  :8501           │ │      │       │ │  ┌────────▼─────────┐    │
└──────────────────┘ │      ▼       │ │  │  FastAPI         │    │
                     │  /cmd_vel    │ │  │  Inference API   │    │
                     │  (Twist)     │ │  │  /predict        │    │
                     │              │ │  │  /metrics        │    │
                     │  TurtleBot3  │ │  │  :8000           │    │
                     │  Maze World  │ │  └──────────────────┘    │
                     └──────────────┘ └──────────────────────────┘

---

Project Structure

wall-following-robot/
├── data/
│   └── wall_following_2sensor.csv       # UCI dataset
├── models/                              # Phase 1 outputs
│   ├── mlp_pipeline.pkl
│   ├── random_forest_pipeline.pkl
│   ├── svm_pipeline.pkl
│   ├── gradient_boosting_pipeline.pkl
│   ├── label_encoder.pkl
│   └── benchmark_results.csv
├── notebooks/
│   └── phase1_ml_core.ipynb             # EDA, training, evaluation
├── dashboard/                           # Phase 2
│   ├── app.py                           # Home page
│   ├── utils.py
│   ├── requirements.txt
│   ├── Dockerfile
│   └── pages/
│       ├── 1_Live_Inference.py
│       ├── 2_Batch_Predict.py
│       ├── 3_Model_Comparison.py
│       └── 4_SHAP_Explorer.py
├── ros2_ws/                             # Phase 3
│   └── src/wall_follower_ros2/
│       ├── wall_follower_ros2/
│       │   ├── wall_follower_node.py    # LIDAR → ANN → /cmd_vel
│       │   └── sensor_bridge_node.py   # CSV replay / monitor
│       ├── launch/
│       │   ├── wall_follower.launch.py
│       │   └── simulation.launch.py
│       ├── worlds/maze_world.world
│       └── config/params.yaml
└── mlops/                               # Phase 4
    ├── docker-compose.yml
    ├── api/
    │   ├── main.py                      # FastAPI inference server
    │   ├── requirements.txt
    │   └── Dockerfile
    └── mlflow_tracking/
        ├── log_experiments.py
        └── Dockerfile

---

Quick Start — Full Stack (Docker)

Prerequisites: Docker Desktop installed and running.

# Clone the repo
git clone https://github.com/<your-username>/wall-following-robot.git
cd wall-following-robot/mlops

# Build and start all services
docker compose up --build

Service	URL	Description
Streamlit Dashboard	http://localhost:8501	Interactive ML dashboard
FastAPI + Swagger	http://localhost:8000/docs	REST inference API
MLflow UI	http://localhost:5000	Experiment tracking

To stop:

docker compose down

---

Phase 1 — ML Core

Run the notebook to train all models, generate benchmark results, and export .pkl files:

pip install -r dashboard/requirements.txt
jupyter notebook notebooks/phase1_ml_core.ipynb

What it produces:

• 4 trained sklearn pipelines (scaler + classifier)
• benchmark_results.csv with accuracy, F1, AUC, train time, inference latency
• SHAP feature importance plots
• Confusion matrices and ROC curves

---

Phase 2 — Streamlit Dashboard

cd dashboard
pip install -r requirements.txt
streamlit run app.py

Pages:

• Home — benchmark overview and quick stats
• Live Inference — drag sensor sliders, watch prediction update in real time
• Batch Predict — upload or paste CSV rows for bulk prediction
• Model Comparison — side-by-side confusion matrices and ROC curves
• SHAP Explorer — global feature importance and per-sample waterfall charts

---

Phase 3 — ROS2 Simulation

Requires WSL2 (Ubuntu 22.04) + ROS2 Humble + TurtleBot3.
Full setup instructions: ros2_ws/SETUP.md

# Launch Gazebo maze + ANN wall-follower node
ros2 launch wall_follower_ros2 simulation.launch.py \
    model_path:=/path/to/models/best_model_pipeline.pkl \
    label_encoder_path:=/path/to/models/label_encoder.pkl

# Monitor predictions in real time
ros2 topic echo /wall_follower/prediction
ros2 topic echo /wall_follower/confidence

ROS2 topic graph:

/scan (LaserScan) ──► wall_follower_node ──► /cmd_vel (Twist)
                             │
                             ├── /wall_follower/prediction (String)
                             └── /wall_follower/confidence (Float32)

Velocity map (ANN output → robot motion):

Action	Linear (m/s)	Angular (rad/s)
Move-Forward	0.30	0.00
Slight-Left-Turn	0.20	+0.30
Slight-Right-Turn	0.20	-0.30
Sharp-Right-Turn	0.05	-0.90

---

Phase 4 — MLOps: FastAPI + MLflow + Docker

API Endpoints

Method	Endpoint	Description
GET	/	Project info and loaded models
GET	/health	Health check
GET	/models	Model list with benchmark metadata
GET	/benchmark	Full benchmark table as JSON
GET	/metrics	Inference counts, avg latency, uptime
GET	/classes	Navigation class labels
POST	/predict	Single sample prediction
POST	/predict/batch	Batch prediction

Example: single prediction

curl -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{"front_distance": 1.5, "left_distance": 0.7, "model": "Random Forest"}'

{
  "model": "Random Forest",
  "action": "Move-Forward",
  "confidence": 0.9872,
  "probabilities": {
    "Move-Forward": 0.9872,
    "Sharp-Right-Turn": 0.0041,
    "Slight-Left-Turn": 0.0063,
    "Slight-Right-Turn": 0.0024
  },
  "inference_ms": 0.061,
  "front_distance": 1.5,
  "left_distance": 0.7
}

Example: metrics endpoint

curl http://localhost:8000/metrics

{
  "uptime_seconds": 142.3,
  "total_predictions": 47,
  "requests": { "predict_single": 12, "predict_batch": 3 },
  "per_model": {
    "Random Forest": { "inference_count": 22, "avg_latency_ms": 0.061 }
  }
}

---

Tech Stack

Layer	Technologies
ML / Training	Python · scikit-learn · NumPy · Pandas · SHAP
Visualisation	Plotly · Matplotlib · Streamlit
API	FastAPI · Uvicorn · Pydantic
Experiment Tracking	MLflow
Robotics	ROS2 Humble · Gazebo · TurtleBot3
Containerisation	Docker · Docker Compose

---

Dataset

UCI Wall-Following Robot Navigation
2 ultrasonic sensors (front distance, left distance) sampled while a robot navigated a maze.
The task is to classify the correct navigation action from 4 options.

Class	Description
Move-Forward	Clear path ahead, maintain course
Slight-Left-Turn	Drifting right, gentle correction
Slight-Right-Turn	Drifting left, gentle correction
Sharp-Right-Turn	Obstacle close ahead, hard turn

---

Screenshots

Add screenshots to a docs/screenshots/ folder and update paths below.

---

License

MIT