🤖 MazeQuest: Intelligent Maze Navigation and Real-Time Mapping Robot

Project Overview

MazeQuest targets structured maze environments and focuses on the complete loop of Autonomous Exploration → Exit Localization → Auto Return. The system consists of a Robot (STM32) and a Host PC (Python):

• The robot performs sensor acquisition, low-level motion control, and odometry;
• The host handles visualization, map construction (BreezySLAM pre-integrated), and mid/high-level trajectory/waypoint management (supports piecewise straight-line stitching).

👥 Team

Hardware Team

Responsible for hardware selection, integration, and firmware development (STM32).

• Lead: FangTaoxiang
  Overall coordination and management, ensuring on-schedule delivery.

• Member: WangBangzhen
  Technical core and main firmware developer. Led complex HW/SW data communication, Lidar-based autonomous mapping (SLAM), and parts of navigation algorithms, providing key technical support for the robot.

• Member: ZhangZhen
  Owner of report materials; led the final defense PPT design and edited the demo video.

• Member: CaoYifan
  Implemented specific firmware modules, contributing to the stability and functionality of the embedded system.

• Member: MeiHongxi
  Contributed to firmware development and unit testing, ensuring reliability and compatibility of related code modules.

• Member: GuanZirui
  Actively contributed to firmware features and undertook module implementation tasks, supporting project completeness and standardization.

Software Team

Responsible for advanced software development (Python), including SLAM, path planning, and the user interface.

• Lead: WangYibo
  Coordinated and managed the software team and interfaced with the hardware team. Supervised task allocation and progress tracking, contributed to overall system architecture and technical roadmap, and played a key role in building the core framework for software simulation experiments.

• Member: SongZijun
  Led software architecture design, including module partitioning and overall framework planning. Ensured adaptability and compatibility to the robot platform while maintaining scalability and maintainability; provided technical support for key challenges.

• Member: WanYunyun
  Developed and debugged core modules, including data processing logic, autonomous navigation algorithms, and performance optimization. Contributed substantial coding and made notable improvements to key algorithms.

• Member: LiuYifan
  Owned software testing and feedback analysis. Identified and tracked issues via systematic tests, helping locate defects and ensuring stability and validity of results.

• Member: ChenSihan
  Ensured reliable communication between software and hardware, including lidar data transfer and protocol implementation. Developed and maintained data interfaces and resolved communication errors.

🔧 System & Directory Layout

• Hardware: Hardware/ (STM32F446; lidar, IMU, motors/encoders, Bluetooth, etc.)

  • Core: Hardware/Core/ — STM32 core configs and drivers
  • Car modules: Hardware/Car/ — function-oriented hardware modules
    • Communication/ — Bluetooth communication
    • IMU/ — inertial measurement unit
    • Lidar/ — lidar driver
    • Motion/ — motion control and odometry
    • Motor/ — motors and encoders
  • STM32 project: Hardware/MDK-ARM/ — Keil MDK project files
  • Notes: Hardware/ProjectNote/ — hardware interface/config docs

• Software: Software/

  • Entry point: Software/main.py
  • Communication: Software/Comunnication/ — serial transport and protocol
  • Exploration & Visualization: Software/Exploration/Visulization/ — lidar processing and visualization
  • Packages: Software/Package/ — third-party integrations
    • BreezySLAM/ — SLAM library
    • PyRoboViz/ — robotics visualization toolkit
  • Configuration: Software/TheConfig/
  • Logs: Software/logs/

Coordinate System & Maze Dimensions

• Maze size: 280 cm × 280 cm; cell size: 70 cm × 70 cm (4×4).
• Default entry at bottom-left (1,1). Initial pose x=0.35, y=0.35 (m) is the center of the bottom-left cell.
• Heading: 0° along +x, 90° along +y (configurable in Visualization.yaml).
• Lidar mount: centered at the rear, offset backward by 0.0515 m (angle/range calibration supported in config).

---

📡 Communication Protocol (PC ↔ Robot)

• Frame: {type}|{seq}|{payload}|{crc32} (CRC32 over type|seq|payload).
• Downlink (PC → Robot): SETPOSE, WAYPOINT, CONTROL, STOP
• Uplink (Robot → PC): ACK, NACK, ARRIVAL, POSE, IMU, ENCODER, LIDAR, LIDAR_RAW
• Reliability & arrival logic:
  • Wait for ACK/NACK; on timeout/rejection, resend (configurable retries/intervals).
  • Robot reports ARRIVAL upon completion with result details.
  • To avoid “first packet lost before robot ready”, the PC probes readiness and prioritizes sending the entry pose at startup.

---

Software Environment & Dependencies

Windows 10/11 + Python 3.10–3.12 recommended. See Software/requirements.txt:

• pyserial, PyYAML, numpy, matplotlib, pyroboviz, pytest (tests)

Setup (virtual env recommended):

python -m venv .venv
./.venv/Scripts/activate
pip install -r Software/requirements.txt

Tip: Check the serial COM port in Device Manager and update the config.

---

⚙️ Configuration (Software/TheConfig)

Serial communication Comunnication.yaml

• port: serial port (e.g., COM4)
• baudrate: default 921600
• resend_limit/resend_interval: ACK retry strategy
• ack_timeout_s/arrival_timeout_s: timeouts for ACK and arrival

Visualization & SLAM Visualization.yaml

• grid: maze size, ticks, and figure style
• robot: geometry, entry pose, lidar mount, colors
• lidar: range/filtering/near-field projection; BreezySLAM sampling/FOV/rate
• slam: map size/quality (aligned with BreezySLAM presets)
• viz: refresh rate and layer alpha

---

🚀 Quick Start & Demos

Run from the project root.

1) Grid only (no hardware)

python -m Software.main --viz-grid --viz-config Software/TheConfig/Visualization.yaml

2) Robot overlay (static)

python -m Software.main --viz --viz-config Software/TheConfig/Visualization.yaml

3) Connect to the real robot: visualization + control

python -m Software.main \
  --config Software/TheConfig/Comunnication.yaml \
  --viz-config Software/TheConfig/Visualization.yaml

Then:

• Console commands: wp x y [heading_deg], stop, q
• Example: wp 0.7 0.0 → go forward 0.7 m; wp 0.7 -0.7 -90 → turn right then forward
• Logs at Software/logs/control-*.log

4) Automated demo sequence (no interaction)

python -m Software.main --test-loop

Visualization is refreshed on the main thread via Matplotlib to ensure real-time updates; near-field point cloud and robot heading update with incoming data.

---

💡 FAQ

• Serial port not opening/in use: verify COM port in Device Manager; close conflicting apps.
• pyserial missing: install dependencies per section above.
• Plot not refreshing: do not move visualization to a worker thread; current implementation uses main-thread plt.pause().
• Empty lidar data: check LIDAR/LIDAR_RAW frame formats; or disable use_raw_passthru in Visualization.yaml and use compatibility mode.

🫂 Navigation Algorithms

MazeQuest implements multiple exploration and navigation strategies:

Right-hand rule exploration (rhandSeek.py)

• Autonomous exploration controller based on 2D lidar scans
• Plans right-wall-following trajectories by estimating right-wall distance and angle
• Smooth right-wall following via a PD controller
• Flexible parameters to tune safety distance and turning strategy

Mapping and localization during exploration

• Real-time mapping and localization with BreezySLAM
• Combine simple behavior strategies with SLAM data to improve exploration efficiency
• Live progress shown in the visualization UI

---

🏃 Deliverables

Artifacts are stored in SubmissionFiles/:

• PPT/ — final defense slides
• Video/ — demo videos

---

📋 Attribution & Thanks

• References and dependencies: BreezySLAM, PyRoboViz, matplotlib, numpy, pyserial, etc.
• Hardware and driver references: see Reference/ and Hardware/.
• Code and docs for academic/teaching use only.