LogiBot PCB

LogiBot — Warehouse Autonomous Mobile Robot

An end-to-end warehouse AMR prototype that combines embedded motion control, fail-safe safety logic, real-time fleet monitoring, path planning, simulation, and production-oriented hardware design assets.

LogiBot is a multidisciplinary robotics project for moving between warehouse rack locations under operator supervision. The repository brings the complete engineering stack together: STM32 firmware for deterministic robot control, an ESP32-S3 communications bridge, a FastAPI control plane, a React dashboard, a four-robot simulator, and KiCad/FreeCAD design files.

Why this project matters

LogiBot demonstrates practical work across the boundary between software and physical systems:

• Embedded systems: motor PWM, software quadrature encoders, odometry, IMU/ToF/ultrasonic sensing, and a binary UART protocol.
• Safety-oriented design: latched E-stop, bumper, motor-fault, and communication-timeout states with a hardware safety output.
• Backend and web engineering: MQTT ingestion, REST APIs, WebSocket updates, SQLite telemetry history, and a responsive React dashboard.
• Robotics algorithms: occupancy-grid A* planning, waypoint following in simulation, and AprilTag-based pose-correction hooks.
• Hardware development: STM32G474 + ESP32-S3 PCB design, mechanical CAD, and manufacturable STEP/STL exports.

System architecture

flowchart TB
    subgraph Robot[LogiBot AMR]
        Sensors[Encoders • IMU • ToF • Ultrasonic • E-stop • Bumper]
        STM32[STM32G474RET6\nReal-time controller]
        Actuators[Motor drivers\nPWM + direction]
        ESP32[ESP32-S3\nWi-Fi / MQTT bridge]
        Sensors --> STM32
        STM32 --> Actuators
        STM32 <-->|Binary UART + heartbeat\n115200 baud| ESP32
    end

    Broker[(Mosquitto\nMQTT broker)]
    API[FastAPI backend\nREST + WebSocket + SQLite]
    UI[React / Vite\nFleet dashboard]
    Sim[Python fleet simulator\nUp to 4 robots]

    ESP32 <-->|Wi-Fi / MQTT| Broker
    Broker <-->|Telemetry, safety, commands| API
    API <-->|REST + WebSocket| UI
    Sim <-->|MQTT| Broker

Command and telemetry flow

sequenceDiagram
    participant Operator
    participant Dashboard as React Dashboard
    participant API as FastAPI
    participant MQTT as MQTT Broker
    participant ESP32 as ESP32-S3
    participant STM32 as STM32 Controller

    Operator->>Dashboard: Reserve robot and choose rack
    Dashboard->>API: POST /api/robots/{id}/goto/{rack}
    API->>API: Plan collision-free route with A*
    API->>MQTT: Publish navigation waypoints
    MQTT->>ESP32: Deliver command
    ESP32->>STM32: Relay framed UART command
    STM32-->>ESP32: Telemetry and safety events
    ESP32->>MQTT: Publish JSON telemetry
    MQTT->>API: Deliver telemetry
    API-->>Dashboard: Broadcast live update via WebSocket
    Dashboard-->>Operator: Show position, battery, and safety state

Safety model

stateDiagram-v2
    [*] --> Safe
    Safe: Motion enabled
    Safe --> EStopLatched: E-stop triggered
    Safe --> BumperLatched: Bumper triggered
    Safe --> CommTimeoutLatched: ESP32 heartbeat lost (> 1.5 s)
    Safe --> FaultLatched: Motor-driver fault
    EStopLatched --> Safe: Explicit reset + physical condition cleared
    BumperLatched --> Safe: Explicit reset + physical condition cleared
    CommTimeoutLatched --> Safe: Explicit reset after link recovery
    FaultLatched --> Safe: Explicit reset after fault recovery

All safety triggers are latched. Releasing an E-stop or bumper alone does not re-enable motion; an operator reset is required after the physical cause has cleared. SAFETY_OUT starts low and is intended to drive an external motor-power relay/contactor.

Key capabilities

Technology stack

Repository layout

LogiBot-master/
├── dashboard/
│   ├── stm32/                 # STM32 real-time control and safety firmware
│   ├── esp32/                 # ESP32-S3 Wi-Fi/MQTT bridge firmware
│   ├── backend/               # FastAPI, MQTT client, SQLite, A* planner
│   ├── frontend/              # React/Vite fleet-management dashboard
│   ├── simulator/             # Multi-robot warehouse simulation
│   └── docs/                  # ESP32 recovery/flashing notes
├── hardware/
│   ├── electronics/           # KiCad PCB project, PDF, and STEP assets
│   └── mechanical(demo)/      # FreeCAD assembly and exported STEP/STL files
├── firmware/                  # Reserved firmware workspace structure
├── simulation/                # Reserved Gazebo/world workspace structure
├── Software/                  # Reserved ROS 2/application workspace structure
└── docs/                      # Reserved project documentation structure

Quick start — run the digital twin

The fastest way to explore the project is to run the MQTT broker, backend, simulator, and dashboard locally. The simulator represents four robots in a 20 m × 12 m warehouse with racks A–D.

Prerequisites

1. Start the MQTT broker

Install Mosquitto, then open a terminal from dashboard/backend:

mosquitto -c mosquitto.conf

The included configuration is intentionally for trusted local development. It accepts anonymous connections on port 1883; do not deploy it unchanged to a production network.

2. Start the API

Open another terminal:

cd dashboard/backend
python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS/Linux
# source .venv/bin/activate

pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

The API starts at http://localhost:8000, and interactive API documentation is available at http://localhost:8000/docs.

3. Start the fleet simulator

Open a third terminal:

cd dashboard/simulator
python -m venv .venv

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS/Linux
# source .venv/bin/activate

pip install -r requirements.txt
python fleet_simulator.py --broker localhost

The simulator publishes telemetry for logibot-01 through logibot-04 and follows navigation waypoints sent by the backend.

4. Start the dashboard

Open a fourth terminal:

cd dashboard/frontend
copy .env.example .env     # Windows Command Prompt
# Copy-Item .env.example .env  # Windows PowerShell
# cp .env.example .env         # macOS/Linux

npm install
npm run dev

Open http://localhost:5173. Reserve a robot, select it, then send it to racks A–D. The dashboard shows the warehouse map, live telemetry, connection status, reservation state, and safety events.

Build the dashboard for deployment

cd dashboard/frontend
npm run build

The frontend, backend, and simulator each include a Dockerfile. Their runtime configuration is deliberately kept explicit; a production deployment should supply a hardened MQTT configuration, persistent database storage, environment-specific origins, and an orchestration configuration.

Hardware and firmware

STM32G474 real-time controller

The STM32 owns time-sensitive functions:

• Left/right motor PWM and direction control
• Software quadrature encoder decoding and odometry
• I²C IMU and VL53L0X ToF integration
• Ultrasonic sensing
• E-stop, bumper, motor-fault, and communication-timeout safety logic
• Framed UART communication with the ESP32
• ESP32 reset and boot-mode supervision

To prepare an STM32 project, create an STM32G474RET6 project in STM32CubeMX/CubeIDE, configure the peripherals and pins specified in dashboard/stm32/Core/Inc/pinout.h, then integrate the supplied Core/Inc and Core/Src sources. The system clock target is 170 MHz, and SWD is wired to PA13/PA14.

Before operating a physical robot, calibrate the wheel radius, wheel base, encoder ticks per revolution, and PID gains in dashboard/stm32/Core/Src/main.c. The current odometry values are documented as placeholders and must not be treated as final mechanical constants.

ESP32-S3 communications bridge

The ESP32 receives binary telemetry frames from the STM32, converts them to JSON, publishes to MQTT, relays dashboard commands back over UART, emits a heartbeat, and supports OTA updates through ArduinoOTA.

Configure the following values before flashing:

• ROBOT_ID
• WIFI_SSID and WIFI_PASSWORD
• MQTT_BROKER_HOST
• UART GPIO mapping for the installed ESP32-S3 module

They are located in dashboard/esp32/include/config.h. Build and upload with PlatformIO:

cd dashboard/esp32
pio run -t upload
pio device monitor

For recovery-flashing details, see dashboard/docs/flashing.md.

MQTT contract

Topics are scoped by robot ID, allowing the backend and simulator to handle a fleet consistently.

API overview

FastAPI automatically exposes the complete OpenAPI specification at /docs. Core endpoints include:

Command and reservation endpoints require X-Operator-Id and X-Operator-Name headers. In the current prototype, those identities are browser-generated operational identifiers, not production authentication.

Navigation and localization approach

flowchart LR
    Start[Current robot pose] --> Grid[0.5 m occupancy grid]
    Racks[Static rack bounds\n+with 0.35 m margin] --> Grid
    Grid --> AStar[A* route search\n8-connected neighbors]
    AStar --> Simplify[Remove collinear waypoints]
    Simplify --> MQTT[Publish navigation goal]
    MQTT --> Follow[Robot/simulator\nlocal waypoint follower]
    Tags[AprilTags at aisles\nand rack approaches] --> Correct[Pose correction event]
    Correct --> Live[Live dashboard update]

The warehouse layout is defined once in dashboard/backend/app/warehouse.py and is shared by the API, planner, and simulator. This helps keep the dashboard view, planned route, and digital twin aligned.

Hardware design assets

• PCB project: hardware/electronics/LogiBot PCB
• PCB PDF: LogiBot PCB.pdf
• Mechanical CAD: hardware/mechanical(demo)/cad
• STEP/STL exports: hardware/mechanical(demo)/cad/export
• Mechanical handoff notes: PROJECT_HANDOFF.md

The handoff notes should be reviewed before manufacturing: the mechanical design is actively evolving and some exports are identified there as needing refresh after final geometry validation.

Engineering limitations and next steps

This is a functional engineering prototype, not a certified commercial AMR. The most valuable next steps are:

• Replace browser-stored operator identities with authenticated, role-based access control.
• Require MQTT credentials and TLS; restrict CORS origins for deployment.
• Add automated unit, integration, hardware-in-the-loop, and safety validation tests.
• Add dynamic-obstacle perception and multi-robot conflict resolution beyond static-map planning.
• Validate and tune odometry/PID values on the assembled robot.
• Complete a manufacturing readiness review for mechanical exports and the PCB revision.
• Perform a formal safety assessment before use around people, forklifts, or production operations.

License

No license has been assigned yet. Contact the project owner before reusing, distributing, or deploying this work.