Autonomous Guided Vehicle (AGV)

PMDS x DevNut Autonomous Guided Vehicle Project

Table of Contents

• Development Environment Setup
• Webots Configuration
• Project Rules
• Docker Database Setup
• Container Management

---

Development Environment Setup

Installing Dependencies

Option A: Automatic Setup (Recommended)
Run the provided setup script. It will automatically create a virtual environment and install all necessary dependencies. At the end of the script, it will print the absolute path to your Python interpreter, which you'll need for Webots.

./setup.sh

Option B: Manual Setup
If you prefer to set up the environment manually, follow these steps:

1. Create the virtual environment:

   python3.12 -m venv .venv

2. Activate the virtual environment (You must do this every time you open a new terminal):

   source .venv/bin/activate

3. Install the requirements: (Note: requirements.txt was last updated on 04/15/2026. If you experience dependency issues, ensure you pull the latest version).

   pip install -r requirements.txt

Installing React Dashboard Dependencies

The React dashboard dependencies are installed locally inside web-app/. This creates a node_modules/ folder, which is generated dependency code and should not be committed.

cd web-app
npm install react react-dom
npm install -D typescript vite @vitejs/plugin-react @types/react @types/react-dom

After the dependencies are installed, other contributors can restore the same local packages from package-lock.json with:

cd web-app
npm install

To open the web app, run:

cd web-app
npm run dev

---

Webots Configuration

To link your Python virtual environment with Webots:

1. Get the Python Path: Use the path printed by the setup.sh script. Alternatively, you can find the absolute path manually by navigating to .venv/bin/python3.12 and copying it.
2. Set the Path in Webots: Open Webots and navigate to Webots > Preferences > Python commands. Paste the copied absolute path into the dedicated input box.

Running the Webots Simulation

After Webots is configured with the project Python interpreter:

1. Make sure the Python environment has been created with ./setup.sh or the manual setup steps above.
2. Start the agv-logger MySQL container.
3. Start the standalone logging service in a separate terminal. Both robot controllers use this one service, and they refuse to move if it cannot create their simulation records after ten attempts:

   .venv/bin/python logging/logging_server.py

   The service listens on 127.0.0.1:8080 by default. Use --host and --port to override the listener, and set LOGGING_SERVER_URL to the matching URL for the robot controllers.
4. Open Webots.
5. From Webots, open the world file:

   AGV_Webots_World_and_Controllers/worlds/AGV_Warehouse_World.wbt
   

6. Confirm that each AGV robot is named PIONEER_3_<number> and uses the DefaultController controller. Routes are configured in AGV_Webots_World_and_Controllers/controllers/DefaultController/goals.config.json.

   controller "DefaultController"
   

7. Confirm the checked-in DYNAMIC_ENVIRONMENT_SUPERVISOR node uses the DynamicEnvironmentSupervisor controller so only that process moves humans and forklifts.
8. Press the Webots run/play control to start the simulation.
9. Keep Webots open while monitoring the AGVs. The logging service rebuilds the dashboard JSONL mirrors from committed MySQL rows after each successful transaction.
10. To monitor the React dashboard at the same time, start it separately from another terminal:

cd web-app
npm run dev

If Webots fails to start the controller, re-check Webots > Preferences > Python commands and confirm it points to the absolute Python path inside .venv.

---

Project Rules

Warning

Never save the world directly from Webots using Cmd + Shift + S or Ctrl + Shift + S. Doing so overwrites the .wbt file and strips all custom comments. If you accidentally save it, do not commit or push the resulting code to the repository!

---

Docker Database Setup

This section outlines how to install Docker, start a MySQL container, and set up the database structure required to store the robotic simulator logs.

Step 1: Install Docker Desktop

1. Download Docker Desktop for your operating system from the official site: docker.com.
2. Follow the standard installation process for your OS.
3. Open Docker Desktop and wait for the Docker Engine to fully start.

Step 2: Start the MySQL Container

Open your terminal and execute the following command to download and run the MySQL container in the background:

docker run --name agv-logger -e MYSQL_ROOT_PASSWORD=agv_pass -p 3306:3306 -d mysql:latest

• --name agv-logger: Assigns an easy-to-remember name to your container.
• -e MYSQL_ROOT_PASSWORD=agv_pass: Sets the MySQL root password to agv_pass (you can change this, but make sure to remember it!).
• -d: Runs the container in detached mode (background).
• -p 3306:3306: Maps the standard MySQL port to allow your Python script to communicate with the database.
• mysql:latest: Pulls the latest official MySQL image from Docker Hub.

Step 3: Access the MySQL Console

To create the database, access the container's interactive terminal:

docker exec -it agv-logger mysql -u root -p

When prompted for a password, type agv_pass and press Enter (the characters will be hidden as you type).

Step 4: Create the Database and Tables

Once inside the MySQL console (you will see the mysql> prompt), execute the following commands:

1. Create and select the database:

   CREATE DATABASE agv_data;
   USE agv_data;

2. Initialize the log tables: Open the Database_Structure.sql file in your editor and copy-paste the queries into the console. Ensure you execute each query separately rather than all at once.

If successful, you will see a Query OK message. You can exit the console by typing EXIT;.

Step 5: Verify the Database Setup

Before running a simulation that should save data to MySQL, verify that the database and tables exist.

If you are not already inside the MySQL console, open it again:

docker exec -it agv-logger mysql -u root -p

When prompted, enter agv_pass.

Inside the mysql> prompt, run:

SHOW DATABASES;
USE agv_data;
SHOW TABLES;

The table list should include:

Events
EventTelemetry
Simulations

To check that the table structures were created, run:

DESCRIBE Simulations;
DESCRIBE Events;
DESCRIBE EventTelemetry;

To check whether simulation data has been saved after running Webots, run:

SELECT COUNT(*) FROM Simulations;
SELECT COUNT(*) FROM Events;
SELECT COUNT(*) FROM EventTelemetry;

Counts of 0 are normal before the first saved run. After a run that saves successfully, at least Simulations should contain rows. If the database or tables are missing, re-run the creation commands and the queries from Database_Structure.sql.

Note

• Ensure the mysql-connector-python package is installed in your Python environment.
• Always check Database_Structure.sql when pulling new updates. If the database schema has changed, you must run the new queries to update your local database structure.

---

Container Management

1. Exiting the MySQL Console

If you are inside the MySQL command line (mysql>), you must exit to return to your normal system terminal. Type:

exit;

(You will see a "Bye" message).

2. Stopping the Container

Even after exiting the MySQL console, the database container remains running in the background. To stop it and free up system resources, run:

docker stop agv-logger

3. Restarting the Container

When you are ready to resume your Webots simulation, do not use docker run again (this will throw an error since the container name already exists). Instead, simply start the existing container:

docker start agv-logger

Once started, if you need to manage the database manually, you can re-enter the console using docker exec -it agv-logger mysql -u root -p, enter the password, and select the database (USE agv_data;) before executing any queries.

---

AGV Command Center Web App

The current monitoring interface is the React/Vite application in web-app/. It provides unit-specific realtime telemetry and images, a multi-robot fleet view, controller-owned goal management, an application-level global motion inhibit labelled Emergency Stop, and simulation/event analysis backed by MySQL through the standalone logging service.

The web app is a local operational prototype and must be started separately; it is not launched by DefaultController:

cd web-app
npm run dev

Open the URL printed by Vite, normally http://localhost:5173. The local API routes are implemented by Vite development-server middleware, so npm run preview does not provide the complete operational application. Start MySQL, the logging server, and Webots first when live and persistent data are required.

For the complete startup sequence and interface workflow, see docs/web-app-user-guide.md.