Simulator/intel/dashboard.md

BATL CARLA Dashboard Architecture

This document outlines the architecture, data flow, and inner workings of the BATL CARLA Dashboard (GUI Orchestrator). It is designed to be easily digestible for both human maintainers and AI assistants iterating on the codebase.

1. High-Level Overview

The BATL CARLA Dashboard is a web-based GUI that replaces manual CLI interactions. It allows users to:

1. Select scenarios intuitively.
2. Override configuration parameters (frames, weather, etc.).
3. Spawn the simulation as a background process.
4. Stream real-time standard output (stdout) directly from the simulation to the browser.

The system is split into three main layers:

• Frontend (Browser): HTML/CSS/JavaScript located in dashboard/templates and dashboard/static.
• Backend (Web Server): A Flask application defined in dashboard/app.py.
• Execution Engine (CLI Pipeline): The pre-existing run.bat wrapper and src/main.py Python script.

---

2. Component Breakdown

A. The Launcher (dashboard.bat)

This simple batch script is the entry point for the user. It activates the appropriate Python environment and executes dashboard/app.py, launching the Flask development server on port 5000.

B. The Web Server (dashboard/app.py)

Flask acts as the bridge between the user's browser HTTP requests and the host operating system's command line.

• API Endpoints: It serves /api/config and /api/scenario_params/<name> to dynamically inform the UI about available scenarios, config limits, and tunable parameters.
• Process Orchestration: When a user clicks "Run" on the UI, the frontend sends a POST request to /api/run containing the selected options. Flask parses this JSON payload and heavily formats a CLI command array.

C. The Frontend (dashboard/static/app.js)

The JavaScript logic handles state management. It:

1. Fetches scenarios on load and populates dropdowns.
2. Intercepts the "Run" form submission to prevent page reloads.
3. Opens a standard Server-Sent Events (SSE) connection via the built-in EventSource API to receive real-time text streams from Flask.

---

3. How the Dashboard Interacts with run.bat

The most critical interface in this architecture is how Flask triggers and monitors the underlying CARLA simulation.

When the /api/run endpoint is hit:

1. Command Construction: Flask builds the command array. A payload of {"scenario": "showcase", "frames": 50} translates to the equivalent of typing: cmd.exe /c run.bat showcase --frames 50

2. Subprocess Spawning: Flask leverages Python's subprocess.Popen to spawn a detached child process running the constructed command.

   • cwd=PROJECT_ROOT: Ensures run.bat is executed contextually from the root workspace so relative imports inside src/main.py do not break.
   • stdout=subprocess.PIPE / stderr=subprocess.STDOUT: Captures both standard and error console outputs, merging them into a single pipe that Flask can read dynamically.

3. Stream Unbuffering (Crucial Step): By default, Python buffers stdout when piping it to another program, causing massive delays (the GUI appears to "freeze"). To fix this, Flask injects env["PYTHONUNBUFFERED"] = "1" into the sub-environment, and run.bat also calls set PYTHONUNBUFFERED=1. This forces the downstream Python simulation (src/main.py and its dependencies) to emit logs instantly, allowing real-time progress bar renders in the GUI console.

4. Event Streaming (Yield): Instead of waiting for the process to return an exit code, Flask uses a specific Python generator (def generate():) paired with a standard Response(mimetype="text/event-stream"). As process.stdout.readline() pulls new text from the unbuffered stream, Flask yields it to the browser wrapped in data: ... \n\n syntax. The JS EventSource catches these fragments and appends them to the <div id="console"> log box.

---

4. Extension Guidelines for AI

When asked to extend the Dashboard, observe the following patterns:

• Adding new CLI flags: Update the POST /api/run payload parser in app.py, extend the cmd.extend() builder, and add the corresponding HTML <input> in index.html.
• Adding new data streams: The SSE generator currently pipes raw text. To parse structured data (like active ego speed) for live graphs, consider formatting the intermediate Python prints as JSON and having app.js parse the event.data payload conditionally.
• Pathing: Remember that app.py lives in a sub-folder. Operations manipulating the CARLA simulation must be rooted up two levels using the PROJECT_ROOT pointer established in the file.