CARLA Driving-Behavior Feedback System

A rule-based (no ML) system that compares the player's driving to nearby NPC traffic in CARLA and gives real-time popup + voice feedback, then a final driving report.

CARLA
  │
  ├── PLAYER CAR
  └── NPC CARS (driven by CARLA Traffic Manager — untouched)
        │
        ▼
  Read vehicle telemetry
        │
        ▼
  Compare player vs. nearby NPCs
        │
        ▼
  Rule engine (thresholds, no ML)
        │
        ▼
  Popup + voice feedback
        │
        ▼
  Log session data → Final driving report

Files

File	Responsibility
carla_connection.py	Connect to CARLA, find the player vehicle, attach sensors
telemetry.py	Read speed, steering, throttle, brake, position, lane offset
npc_comparison.py	Find nearby NPCs, compute their average speed/lane offset
event_detector.py	Threshold-based rules → list of event names
feedback.py	Popup text + offline text-to-speech (pyttsx3)
report.py	Builds the end-of-session score + report from the CSV log
main.py	Wires the whole pipeline together, runs the tick loop

Setup

1. Have a CARLA server running (CarlaUE4.exe / ./CarlaUE4.sh) with a player vehicle already spawned (ideally tagged role_name=hero) and some NPCs spawned via the Traffic Manager.
2. Install dependencies:

   pip install -r requirements.txt

   Note: the carla PyPI package version must match your CARLA server version — if pip install carla doesn't work for your version, use the .whl file shipped inside your CARLA installation's PythonAPI folder instead (pip install <path-to-carla-whl>).

Recommended build order

1. Milestone 1 — just prove telemetry + comparison works:

python main.py --print-only

This should print something like:

PLAYER SPEED: 62.0 km/h | NPC AVG SPEED: 49.2 km/h | LANE OFFSET: 0.62 m
   EVENT: OVERSPEEDING

2. Full run — popup + voice + logging + report:

python main.py --duration 300

This runs for 5 minutes, prints popups and speaks feedback (via pyttsx3) on rule violations, logs every tick to session_log.csv, and writes driving_report.txt with the final score at the end.

Useful flags:

• --no-voice — popups only, no speech
• --host / --port — if CARLA isn't on 127.0.0.1:2000
• --duration <seconds> — session length

Tuning the rules

Thresholds live in event_detector.py (DEFAULT_THRESHOLDS):

DEFAULT_THRESHOLDS = {
    "overspeed_margin_kmh": 10,
    "lane_departure_m": 0.5,
    "harsh_brake": 0.8,
    "aggressive_steer": 0.7,
}

Scoring penalties live in report.py (SCORE_PENALTIES).

Deliberately left out

No ML model, no training dataset, no computer vision, no custom NPC AI — CARLA's Traffic Manager already drives the NPCs, and all event detection is threshold-based. If a generative component is required later, the cleanest place to add one is inside feedback.py: keep event detection rule-based, and only use an LLM to turn an already-detected event + context into a more natural coaching sentence.