For Contributors Simulator QuickStart

🏠 Simulator

Quick Start Guide

1. How to run the simulator?

Prerequisites

• Python: Version 3.11 (as specified in Pipfile).
• A terminal or command-line interface.
• Pipenv: For dependency management (installed below).
• Assumes the repository (CS3300-Project) is already cloned.

Initial Setup

1. Install Pipenv

   pip install --user pipenv

   Note: Ensure ~/.local/bin (or equivalent) is in your PATH. On Windows, use py -m pip install pipenv.

2. Verify Python 3.11

   python3 --version

   If Python 3.11 is not installed, download it from python.org or use pyenv.

Method 1: Run Entire Project (Simulator + Extractor)

This method starts both the simulator and the extractor from the root directory.

1. Navigate to Root Directory

   cd /path/to/CS3300-Project

2. Install Dependencies with Pipenv

   pipenv install

   This installs dependencies from Pipfile (e.g., fastapi, flask, h5py, pytest).

3. Activate Virtual Environment

   pipenv shell

4. Run the Project Assuming main.py in the root directory launches both components:

   python main.py

   Note: The root main.py likely runs the extractor (possibly Flask on port 5000) and may launch the simulator separately. If it’s Flask-based (due to flask-socketio in Pipfile), try:

   flask run --host=0.0.0.0 --port=5000

   The simulator may need to be started separately (see Method 2). Check main.py or project documentation for exact commands.

5. Access the Simulator API

   • If the simulator runs on port 8000, open http://localhost:8000/docs/api for Swagger UI or http://localhost:8000/docs/printer for the welcome page.
   • Test endpoints:

     curl http://localhost:8000/api/v1/printer

   • If the extractor runs on port 5000, check http://localhost:5000 for its interface.

Method 2: Run Simulator Only

This method starts only the simulator from the backend directory.

1. Navigate to Simulator Backend

   cd /path/to/CS3300-Project

2. Install Dependencies with Pipenv Use the root Pipfile (copy it to simulator/v2/backend if needed):

   pipenv install

   Note: If a separate Pipfile exists in simulator/v2/backend, use that instead.

3. Activate Virtual Environment

   pipenv shell

4. Run the Simulator

   uvicorn simulator.v2.backend.main:app --host 127.0.0.1 --port 8000 --reload

   • --reload: Enables auto-reload for development.
   • The simulator runs on http://127.0.0.1:8000.

5. Access the API

   • Visit http://127.0.0.1:8000/docs/api for Swagger UI.
   • Go to http://127.0.0.1:8000/docs/printer for the welcome page.
   • Test endpoints:

     curl http://127.0.0.1:8000/api/v1/printer

Running Tests

To verify the simulator:

cd /path/to/CS3300-Project/simulator/v2/backend
pipenv run pytest tests/

👈 Last section: Introduction

👉 Next section: Architecture