AGV_simulator / README.md
Ducdata1808's picture
ci: add HuggingFace Space configuration to README metadata
998d713
|
Raw History Blame Contribute Delete
4.66 kB
metadata
title: AGV Simulator
emoji: πŸ€–
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false

VDA 5050 Robot Simulator

Python-based simulation environment for robots with VDA 5050 protocol (specifically targeting version 2.0.0). It allows simulating multiple AGVs (Automated Guided Vehicles), sending them orders, and visualizing their movement and status.

Demo Video

IMAGE

Features

  • VDA 5050 v2.0.0 Compliance: Simulates key aspects of the VDA 5050 protocol including:
    • Connection states (ONLINE, OFFLINE, CONNECTION_BROKEN)
    • Vehicle State (State, AgvPosition, ActionState, etc.)
    • Order processing (Order, Node, Edge)
    • Instant Actions (InstantActions, Action)
    • Visualization messages (Visualization)
  • Multi-Robot Simulation: Can simulate multiple AGVs concurrently, configured via kα»‹ch bαΊ£n JSON.
  • AI Fleet Coordination Benchmarking: Evaluates LLMs (Gemini, Llama, Qwen) in generating optimal conflict-free routes and actions under VDA 5050 constraints.
  • Web UI Dashboard: Interactive frontend displaying real-time simulation runs, layout configurations, obstacle avoidance, and remaining battery levels.
  • CI/CD Integration: Automated unit tests and Docker image build verification via GitHub Actions.

Directory Structure

vda5050-robot-simulator/
β”œβ”€β”€ .github/workflows/      # CI configuration (automated test & docker build)
β”œβ”€β”€ benchmark/              # Core evaluation engine (runner, metrics logger)
β”œβ”€β”€ factory_layouts/        # Warehouse maps (nodes, edges, walls, charging zones)
β”œβ”€β”€ frontend/               # Web UI visualizer dashboard (index.html)
β”œβ”€β”€ legacy_mqtt/            # Legacy visualizer and MQTT runner scripts
β”œβ”€β”€ models/                 # API adapters (Gemini, Qwen Cloud, Groq, HF, OpenRouter)
β”œβ”€β”€ protocol/               # VDA 5050 protocol data structures (Python dataclasses)
β”œβ”€β”€ scenarios/              # JSON scenarios (Level 1 Basic -> Level 4 Expert)
β”œβ”€β”€ scripts/                # API connection tests and helper utilities
β”œβ”€β”€ tests/                  # Automated unit test suite
β”œβ”€β”€ app.py                  # FastAPI backend server
β”œβ”€β”€ config.py / config.toml # Base simulator configuration files
β”œβ”€β”€ main.py                 # Core AGV state machine and simulator logic
β”œβ”€β”€ run_benchmark.py        # CLI benchmark execution tool
└── requirements.txt        # Python dependency list

Setup

  1. Clone & Virtual Environment:

    git clone git@github.com:datascience180806/AGV_research.git
    cd vda5050-robot-simulator
    python -m venv venv
    source venv/bin/activate  # On Windows: .\venv\Scripts\activate
    pip install -r requirements.txt
    
  2. API Credentials: Create a .env file in the root directory:

    # API Keys for Model Adapters (Fill in what you use)
    GEMINI_API_KEY=your_gemini_api_key
    GROQ_API_KEY=your_groq_api_key
    QWEN_API_KEY=your_alibaba_qwen_api_key
    OPENROUTER_API_KEY=your_openrouter_api_key
    HF_TOKEN=your_huggingface_token
    

Web Visualizer & Benchmark Tool

This project features a Web-based interactive visualizer dashboard and benchmark suite that runs without needing a local MQTT broker.

  1. Start the Backend API Server:

    python -m uvicorn app:app --host 127.0.0.1 --port 8000
    

    This runs the FastAPI server at http://127.0.0.1:8000. You can access the API documentation at http://127.0.0.1:8000/docs.

  2. Start the Frontend Client: Run a local static web server in the root directory:

    python -m http.server 3000
    

    Then, open your browser and navigate to http://localhost:3000/frontend/.

  3. Run Benchmarks via CLI: You can also run scenarios via command line:

    # Run a single scenario with Gemini 2.5 Flash
    python run_benchmark.py --scenario scenarios/level_1_basic/scenario_001.json --model gemini-2.5-flash
    
    # Run a scenario using Qwen Max Cloud
    python run_benchmark.py --scenario scenarios/level_1_basic/scenario_001.json --model qwen-max
    

Running Tests

To run the unit tests locally:

python -m unittest discover -s tests -p "test_*.py"

Docker Deployment

To build and run the backend using Docker:

# Build the Docker image
docker build -t vda5050-robot-simulator .

# Run the container
docker run -p 7860:7860 vda5050-robot-simulator

The FastAPI backend will then be exposed at http://localhost:7860.