🐭 Autonomous Maze-Solving MicroMouse Robot

### 🤖 ATmega328P Embedded C Project with Dual Feedback Control **Complete Robotics Design & Implementation** *Left-Hand Rule Algorithm • PID Wall Following • Encoder Fusion Control*

![GitHub repo size](https://img.shields.io/github/repo-size/Ravinx001/MicroMouse?style=for-the-badge) ![GitHub stars](https://img.shields.io/github/stars/Ravinx001/MicroMouse?style=for-the-badge) ![GitHub forks](https://img.shields.io/github/forks/Ravinx001/MicroMouse?style=for-the-badge) ![GitHub issues](https://img.shields.io/github/issues/Ravinx001/MicroMouse?style=for-the-badge)

--- ## 🎯 Project Overview An **autonomous maze-solving robot** built from scratch using an ATmega328P microcontroller (Arduino Nano). This MicroMouse navigates through unknown mazes using the **left-hand rule algorithm**, combining ultrasonic sensor feedback with motor encoder data for precise movement control. The robot features a **dual feedback control system** that fuses: - **PID-based wall following** using 3 HC-SR04 ultrasonic sensors - **Encoder-based dead reckoning** for accurate turns and straight-line tracking **Goal:** Design and build a fully autonomous robot capable of navigating and solving standard maze configurations without human intervention.

🎬 Final assembled MicroMouse robot ready for maze navigation

--- ## 🎬 Demo Video

[![MicroMouse Demo](https://img.youtube.com/vi/mDKhOKRyAyE/maxresdefault.jpg)](https://youtube.com/shorts/mDKhOKRyAyE) **[▶️ Watch on YouTube](https://youtube.com/shorts/mDKhOKRyAyE)** *Click the image above or watch the MicroMouse autonomously navigate through a maze using the left-hand rule algorithm*

--- ## 🚀 Getting Started ### Quick Start Guide Follow these steps to build and run your own MicroMouse: ```mermaid flowchart LR A[1️⃣ Clone Repo] --> B[2️⃣ Assemble Hardware] B --> C[3️⃣ Print Chassis] C --> D[4️⃣ Wire Components] D --> E[5️⃣ Flash Code] E --> F[6️⃣ Calibrate] F --> G[🎉 Run!] ``` ### Step 1: Clone the Repository ```bash git clone https://github.com/Ravinx001/MicroMouse.git cd MicroMouse ``` ### Step 2: Gather Components Ensure you have all components from the [Bill of Materials](#-bill-of-materials-bom): - Arduino Nano (ATmega328P) - TB6612FNG motor driver - 2× N20 gear motors with encoders - 3× HC-SR04 ultrasonic sensors - 7.4V LiPo battery - Wheels and caster ### Step 3: Print the Chassis 1. Download [`body_3D_design/micromouse_body_3d_design.stl`](body_3D_design/micromouse_body_3d_design.stl) 2. Print with **PLA/PETG**, 0.2mm layer height, 25% infill 3. Allow 4+ hours for printing ### Step 4: Wire the Electronics Connect components according to the [Pin Configuration](#-pin-configuration) table: | **Connection** | **Arduino Pin** | |----------------|-----------------| | Left Motor PWM | D5 | | Right Motor PWM | D3 | | Motor Driver STBY | D8 | | Left Ultrasonic TRIG/ECHO | A4/A5 | | Front Ultrasonic TRIG/ECHO | D9/D10 | | Right Ultrasonic TRIG/ECHO | D11/D12 | | Left Encoder A/B | A0/A1 | | Right Encoder A/B | A2/A3 | ### Step 5: Install Toolchain & Flash **Windows:** ```bash # Install WinAVR or AVR Toolchain # Download from: https://www.microchip.com/mplab/avr-support/avr-and-arm-toolchains-c-compilers # Update COM port in Makefile notepad Makefile # Change PORT = COM3 to your port # Build and flash make build make flash ``` **Linux/macOS:** ```bash # Install AVR toolchain sudo apt install gcc-avr avr-libc avrdude # Debian/Ubuntu brew install avr-gcc avrdude # macOS # Update port and flash # Linux: PORT = /dev/ttyUSB0 # macOS: PORT = /dev/cu.usbserial-* make build make flash ``` ### Step 6: Calibrate Encoders ```bash # Flash calibration program make calibrate # Open Serial Monitor at 9600 baud # Manually rotate each wheel one full revolution # Note the tick count displayed # Update TICKS_PER_REVOLUTION in include/config.h ``` ### Step 7: Test & Run! 1. Place robot at maze entrance 2. Power on - wait for 3-second countdown 3. Watch it solve the maze autonomously! ### 🔧 First-Time Tuning Checklist | **Check** | **Action** | |-----------|------------| | ☐ Motors spin correctly | Both wheels forward when expected | | ☐ Sensors read distances | Open Serial Monitor, verify L/F/R readings | | ☐ 90° turns are accurate | Adjust `TURN_90_COMPENSATION` if needed | | ☐ Wall following is smooth | Tune PID gains if oscillating | > 💡 **Tip:** Start with the robot in a simple straight corridor before testing in a full maze! --- ## ✨ Key Features & Capabilities ### 🧭 **Left-Hand Rule Maze Solving** Implements the classic wall-following algorithm with priority-based decision making: - **Priority 1:** Turn LEFT if left wall is absent - **Priority 2:** Go FORWARD if path is clear - **Priority 3:** Turn RIGHT if right wall is absent - **Priority 4:** Turn AROUND (180°) at dead ends ### 🎛️ **Dual Feedback Control System** Advanced sensor fusion combining two independent control mechanisms: - **Encoder Feedback (40%):** Quadrature encoders for precise positioning - **Wall PID Control (60%):** Real-time distance regulation from walls ### 📡 **Triple Ultrasonic Sensing** Three HC-SR04 sensors provide 180° environmental awareness: - Left, Front, and Right wall detection - Range: 2cm to 400cm with ±3mm accuracy - 100ms update rate with exponential smoothing filter ### ⚡ **High-Performance Motor Control** TB6612FNG dual H-bridge driver with PWM speed control: - Independent speed control for differential steering - Active braking capability for precise stops - Hardware timer-based PWM generation --- ## 🛠️ Hardware Architecture

| **Component** | **Part Number** | **Function** | |---------------|-----------------|--------------| | **Microcontroller** | ATmega328P (Arduino Nano) | Main processing unit @ 16MHz | | **Motor Driver** | TB6612FNG | Dual H-bridge motor control | | **Motors** | N20 DC Gear Motors (x2) | Differential drive propulsion | | **Ultrasonic Sensors** | HC-SR04 (x3) | Wall distance measurement | | **Encoders** | Quadrature Encoders (x2) | Wheel position feedback | | **Power** | 7.4V LiPo Battery | Portable power source | | **Voltage Regulator** | AMS1117-5V | 5V logic level regulation |

### 📊 System Block Diagram ```mermaid flowchart TB subgraph POWER["⚡ Power Supply"] BAT[🔋 7.4V LiPo Battery] REG[AMS1117 5V Regulator] BAT --> REG end subgraph SENSING["📡 Sensor Array"] LEFT[HC-SR04 Left] FRONT[HC-SR04 Front] RIGHT[HC-SR04 Right] ENCL[Left Encoder] ENCR[Right Encoder] end subgraph PROCESSING["🧠 Processing Unit"] MCU[ATmega328P
16MHz] PID[PID Controller] MAZE[Maze Solver
Left-Hand Rule] FUSION[Sensor Fusion
40% Enc + 60% Wall] end subgraph ACTUATION["⚙️ Motor Control"] DRIVER[TB6612FNG
Motor Driver] MOTORL[Left Motor] MOTORR[Right Motor] end REG -->|5V| MCU LEFT --> MCU FRONT --> MCU RIGHT --> MCU ENCL --> MCU ENCR --> MCU MCU --> PID MCU --> MAZE PID --> FUSION FUSION --> DRIVER MAZE --> DRIVER DRIVER --> MOTORL DRIVER --> MOTORR BAT -->|7.4V Direct| DRIVER ``` --- ## 🧠 Software Architecture ### Control Flow Diagram ```mermaid flowchart TD START([🚀 System Start]) --> INIT[Initialize Peripherals
UART, Timers, GPIO, PWM] INIT --> SENSORS[Initialize Sensors
& Encoders] SENSORS --> DELAY[3 Second Countdown] DELAY --> LOOP{Main Control Loop} LOOP --> READ_SENS[Read Ultrasonic
Sensors @ 100ms] READ_SENS --> READ_ENC[Read Encoder
Counts] READ_ENC --> WALL_STATE{Determine
Wall State} WALL_STATE -->|Both Walls| CENTER[Center Between
Walls PID] WALL_STATE -->|Left Only| FOLLOW_L[Follow Left
Wall PID] WALL_STATE -->|Right Only| FOLLOW_R[Follow Right
Wall PID] WALL_STATE -->|No Walls| STRAIGHT[Encoder-Only
Straight Drive] WALL_STATE -->|Front Wall| DECISION[Maze Decision
Required] CENTER --> FUSION[Sensor Fusion
Enc 40% + Wall 60%] FOLLOW_L --> FUSION FOLLOW_R --> FUSION STRAIGHT --> ENC_ONLY[Encoder
Correction Only] FUSION --> MOTORS[Apply Motor
Speeds] ENC_ONLY --> MOTORS DECISION --> CHECK{Check
Openings} CHECK -->|Left Open| TURN_L[Turn Left 90°] CHECK -->|Front Clear| FWD[Continue Forward] CHECK -->|Right Open| TURN_R[Turn Right 90°] CHECK -->|Dead End| TURN_180[Turn Around 180°] TURN_L --> MOTORS FWD --> MOTORS TURN_R --> MOTORS TURN_180 --> MOTORS MOTORS --> LOOP ``` ### Maze Solving State Machine ```mermaid stateDiagram-v2 [*] --> FORWARD: Start FORWARD --> LEFT_OPEN: Left sensor > threshold FORWARD --> FRONT_BLOCKED: Front sensor < threshold FORWARD --> FORWARD: Continue straight LEFT_OPEN --> WAIT_DELAY: Debounce 500ms WAIT_DELAY --> TURN_LEFT: Opening confirmed WAIT_DELAY --> FORWARD: False positive TURN_LEFT --> FORWARD: Turn complete FRONT_BLOCKED --> CHECK_LEFT: Stop & sense CHECK_LEFT --> TURN_LEFT: Left open CHECK_LEFT --> CHECK_RIGHT: Left blocked CHECK_RIGHT --> TURN_RIGHT: Right open CHECK_RIGHT --> TURN_180: Dead end TURN_RIGHT --> FORWARD: Turn complete TURN_180 --> FORWARD: Turn complete note right of WAIT_DELAY MAZE_OPENING_DELAY prevents false triggers end note ``` --- ## 📌 Pin Configuration

### Motor Driver (TB6612FNG) | **Arduino Pin** | **ATmega328P** | **TB6612FNG** | **Function** | |-----------------|----------------|---------------|--------------| | D7 | PD7 | AIN1 | Left Motor Direction 1 | | D6 | PD6 | AIN2 | Left Motor Direction 2 | | D5 | PD5 (OC0B) | PWMA | Left Motor PWM Speed | | D4 | PD4 | BIN1 | Right Motor Direction 1 | | D2 | PD2 | BIN2 | Right Motor Direction 2 | | D3 | PD3 (OC2B) | PWMB | Right Motor PWM Speed | | D8 | PB0 | STBY | Standby (Active HIGH) | ### Ultrasonic Sensors (HC-SR04) | **Sensor** | **TRIG Pin** | **ECHO Pin** | |------------|--------------|--------------| | Left | A4 (PC4) | A5 (PC5) | | Front | D9 (PB1) | D10 (PB2) | | Right | D11 (PB3) | D12 (PB4) | ### Quadrature Encoders | **Encoder** | **Phase A** | **Phase B** | |-------------|-------------|-------------| | Left Motor | A0 (PC0) | A1 (PC1) | | Right Motor | A2 (PC2) | A3 (PC3) |

--- ## 📦 3D Printed Body A custom chassis was designed in **Autodesk Fusion 360** to house all components securely.

Custom 3D-printed chassis design in Fusion 360

### Design Features: - ✅ Integrated motor mounts with vibration dampening - ✅ Precise sensor mounting angles for optimal detection - ✅ Battery compartment with secure fit - ✅ Easy access for programming and debugging - ✅ Ventilation slots for electronics cooling ### Printing Specifications: | **Parameter** | **Value** | |---------------|-----------| | Material | PLA or PETG | | Layer Height | 0.2mm | | Infill | 25% | | Supports | Yes (for motor mounts) | | Print Time | ~4 hours | **[📥 Download STL File](body_3D_design/micromouse_body_3d_design.stl)** **[📥 Download Fusion 360 Source](body_3D_design/micromouse_body_3d_design.f3d)** --- ## ⚙️ Build & Flash Instructions ### Prerequisites - **AVR-GCC Toolchain** (avr-gcc, avr-objcopy, avrdude) - **Arduino Nano** or compatible ATmega328P board - **USB-to-Serial driver** (CH340 for clone Nanos) ### Build Commands ```bash # Clone the repository git clone https://github.com/Ravinx001/MicroMouse.git cd MicroMouse # Build the project make build # Check memory usage (critical - RAM near capacity!) make size # Flash to Arduino Nano (update COM port in Makefile first) make flash # Clean build artifacts make clean # Run encoder calibration tool make calibrate ``` ### ⚠️ Important: COM Port Configuration Before flashing, update the `PORT` variable in [Makefile](Makefile): ```makefile # Windows: COM3, COM4, etc. # Linux: /dev/ttyUSB0, /dev/ttyACM0 # Mac: /dev/cu.usbserial-* PORT = COM3 ``` ### Memory Usage | **Memory** | **Used** | **Available** | **Usage** | |------------|----------|---------------|-----------| | Flash | ~12KB | 32KB | ~37% | | RAM | ~1.8KB | 2KB | ~90% ⚠️ | > ⚠️ **Warning:** RAM usage is near capacity. Avoid adding large buffers or arrays. --- ## 🔧 Configuration & Tuning All tunable parameters are centralized in [`include/config.h`](include/config.h). ### Key Parameters ```c // Motor Speeds #define MOTOR_SPEED 110 // Base forward speed (0-255) #define TURN_SPEED 80 // Turning speed (0-255) // PID Gains #define PID_KP 1.2f // Proportional gain #define PID_KI 0.03f // Integral gain #define PID_KD 0.6f // Derivative gain // Wall Following #define TARGET_WALL_DISTANCE 8 // Target distance from walls (cm) #define FRONT_STOP_DISTANCE 15 // Stop when front wall closer (cm) // Maze Detection #define MAZE_LEFT_THRESHOLD 20 // Opening detection threshold (cm) #define MAZE_OPENING_DELAY 500 // Debounce delay (ms) // Control Fusion Weights #define ENCODER_WEIGHT 0.4f // Encoder contribution #define WALL_WEIGHT 0.6f // Wall PID contribution ``` ### Tuning Guide | **Problem** | **Solution** | |-------------|--------------| | Robot oscillates/wobbles | Reduce `PID_KP` or increase `PID_KD` | | Drifts on straight paths | Increase `ENCODER_CORRECTION_GAIN` | | Turns overshoot | Increase `TURN_90_COMPENSATION` | | Turns undershoot | Decrease `TURN_90_COMPENSATION` | | False turn triggers | Increase `MAZE_OPENING_DELAY` | | Too slow reaction | Decrease `CONTROL_PERIOD_MS` | 📚 **Detailed tuning guide:** See [CONFIG_PARAMETERS_GUIDE.md](CONFIG_PARAMETERS_GUIDE.md) --- ## 📊 Technical Specifications

| **Specification** | **Value** | **Notes** | |-------------------|-----------|-----------| | **Microcontroller** | ATmega328P | 16MHz, 32KB Flash, 2KB RAM | | **Operating Voltage** | 5V Logic | 7.4V battery input | | **Motor Voltage** | 6-7.4V | Direct from battery | | **Sensor Range** | 2-400cm | HC-SR04 ultrasonic | | **Encoder Resolution** | 356 ticks/rev | Quadrature decoding | | **Control Loop Rate** | 20Hz | 50ms period | | **Sensor Update Rate** | 10Hz | 100ms period | | **Turn Accuracy** | ±5° | Encoder-controlled | | **Max Speed** | ~30cm/s | At MOTOR_SPEED=110 | | **Dimensions** | ~12×10×8cm | LxWxH approximate | | **Weight** | ~200g | Including battery |

--- ## 📁 Project Structure ``` MicroMouse/ ├── 📄 README.md # This file ├── 📄 LICENSE # MIT License ├── 📄 Makefile # Build system ├── 📄 CONFIG_PARAMETERS_GUIDE.md # Detailed tuning guide ├── 📄 TURN_CONFIG_SIMPLIFIED.md # Turn calibration guide │ ├── 📂 src/ # Source files │ ├── main.c # Main control loop & maze logic │ ├── motors.c # TB6612FNG motor driver │ ├── sensors.c # HC-SR04 ultrasonic sensors │ ├── uart.c # Serial communication │ └── utils.c # Timing utilities (millis, micros) │ ├── 📂 include/ # Header files │ ├── config.h # ⚙️ ALL tunable parameters │ ├── motors.h # Motor driver interface │ ├── sensors.h # Sensor interface │ ├── uart.h # UART interface │ └── utils.h # Utility functions │ ├── 📂 samples/ # Example implementations │ ├── 90_turning_and_wall_following/ # Turn + wall follow demo │ └── optimized_wall_following_with_ultrasonic/ # PID tuning demo │ ├── 📂 arduino_codes/ # Arduino IDE versions │ └── wall_following_tune.ino # Wall following tuning sketch │ ├── 📂 body_3D_design/ # Chassis design files │ ├── micromouse_body_3d_design.f3d # Fusion 360 source │ ├── micromouse_body_3d_design.stl # 3D printable STL │ └── micromouse_body_3d_design.PNG # Design preview │ ├── 📂 photos/ # Build documentation │ └── final_view_of_micro_mouse.jpeg # Finished robot photo │ ├── 📂 video/ # Demo videos │ └── Micro Mouse Full Video.mp4 # Full operation demo │ ├── 📂 build/ # Compiled output (generated) │ └── 📂 .github/ # GitHub configuration └── copilot-instructions.md # AI coding assistant guide ``` --- ## 🔄 Control Algorithm Deep Dive ### PID Wall Following ```mermaid flowchart LR subgraph INPUT SP[Setpoint
8cm target] PV[Process Variable
Actual distance] end subgraph PID["PID Controller"] E[Error
SP - PV] P[P Term
Kp × error] I[I Term
Ki × ∫error] D[D Term
Kd × d/dt error] SUM((Σ)) end subgraph OUTPUT CORR[Correction
-40 to +40] ML[Left Motor
Speed ± correction] MR[Right Motor
Speed ∓ correction] end SP --> E PV --> E E --> P E --> I E --> D P --> SUM I --> SUM D --> SUM SUM --> CORR CORR --> ML CORR --> MR ``` ### Sensor Fusion Algorithm ```mermaid flowchart TD subgraph ENCODERS["Encoder Feedback"] EL[Left Encoder
Ticks] ER[Right Encoder
Ticks] DIFF[Tick Difference
L - R] ENC_CORR[Encoder Correction
diff × gain] end subgraph WALLS["Wall PID Feedback"] SENS[Ultrasonic
Sensors] FILTER[Low-Pass
Filter α=0.6] PID_CALC[PID
Calculation] WALL_CORR[Wall Correction] end subgraph FUSION["Sensor Fusion"] WEIGHT[Weighted Sum
40% Enc + 60% Wall] TOTAL[Total Correction] end EL --> DIFF ER --> DIFF DIFF --> ENC_CORR SENS --> FILTER FILTER --> PID_CALC PID_CALC --> WALL_CORR ENC_CORR -->|× 0.4| WEIGHT WALL_CORR -->|× 0.6| WEIGHT WEIGHT --> TOTAL TOTAL --> MOTORS[Motor Speeds] ``` --- ## 🐛 Troubleshooting

| **Problem** | **Possible Cause** | **Solution** | |-------------|--------------------|--------------| | Robot doesn't move | STBY pin LOW | Check D8 is HIGH after `motors_enable()` | | Erratic sensor readings | Electrical noise | Add 0.1µF caps near sensor VCC pins | | Turns are inaccurate | Wrong encoder count | Run `make calibrate` and update `TICKS_PER_REVOLUTION` | | Robot drifts left/right | Encoder polarity | Check encoder wiring or swap A/B phases | | Oscillates in corridor | PID gains too high | Reduce `PID_KP` or increase `PID_KD` | | Misses wall openings | Threshold too low | Increase `MAZE_LEFT_THRESHOLD` | | False opening detection | Delay too short | Increase `MAZE_OPENING_DELAY` | | Won't compile | Missing toolchain | Install avr-gcc and avr-libc | | Flash fails | Wrong COM port | Update `PORT` in Makefile | | RAM overflow | Too many variables | Remove debug strings, optimize buffers |

### Serial Debug Output Connect at **9600 baud** to view real-time status: ``` ENC L:1234 R:1230 D:4 | BOTH L:7cm R:8cm ENC L:1280 R:1278 D:2 | LEFT L:6cm >>> TURNING LEFT 90° <<< Turn complete! Ticks: 287 (Target: 282) ``` --- ## 🛒 Bill of Materials (BOM)

| **Qty** | **Component** | **Specification** | **Notes** | |---------|---------------|-------------------|-----------| | 1 | Arduino Nano | ATmega328P, CH340 | Or compatible clone | | 1 | TB6612FNG Module | Dual H-Bridge | Handles 1.2A/channel | | 2 | N20 Gear Motors | 6V, 100-300 RPM | With encoder mount | | 2 | Quadrature Encoders | ~360 PPR | Magnetic or optical | | 3 | HC-SR04 | Ultrasonic sensor | 2-400cm range | | 1 | 7.4V LiPo Battery | 300-500mAh | 2S configuration | | 1 | AMS1117-5V | Voltage regulator | Or LM7805 | | 2 | Wheels | 42mm diameter | Fits N20 shaft | | 1 | Caster Wheel | Ball or swivel | Rear support | | - | Jumper Wires | Various | For connections | | - | 3D Printed Chassis | PLA/PETG | See design files |

--- ## 📚 Learning Outcomes This project demonstrates proficiency in: - ✅ **Embedded C Programming** - Direct register manipulation, ISRs, hardware timers - ✅ **Control Systems** - PID implementation, sensor fusion, state machines - ✅ **Algorithm Design** - Left-hand rule maze solving, decision trees - ✅ **Electronics Integration** - Motor drivers, sensor interfaces, power management - ✅ **3D CAD Design** - Fusion 360 parametric modeling - ✅ **Build Systems** - Makefile-based compilation and flashing - ✅ **Technical Documentation** - Comprehensive project documentation --- ## 🤝 Contributing Contributions are welcome! Areas for improvement: - [ ] Flood-fill algorithm implementation - [ ] Speed run optimization after maze learning - [ ] IR sensor alternative to ultrasonic - [ ] Bluetooth/WiFi telemetry - [ ] PCB design for cleaner integration - [ ] OLED display for status ### How to Contribute 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/FloodFill`) 3. Commit changes (`git commit -m 'Add flood-fill algorithm'`) 4. Push to branch (`git push origin feature/FloodFill`) 5. Open a Pull Request --- ## 📄 License This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details. --- ## 📞 Contact & Support **Project Maintainer** 📧 Email: [rav.business.lak@gmail.com](mailto:rav.business.lak@gmail.com) 🐙 GitHub: [@Ravinx001](https://github.com/Ravinx001) 💼 LinkedIn: [Ravindu Amarasekara](https://www.linkedin.com/in/ravindu-amarasekara/) **Community** 💬 Discussions: Use GitHub Discussions for questions 🐛 Issues: Report bugs via GitHub Issues ---

### 🐭 **From Code to Maze Mastery** 🐭 ### 🌟 **Where Algorithms Meet Real-World Robotics** 🌟 ⭐ **Star this repository if you found it helpful!** ⭐ **Built with ❤️ for the Robotics & Maker Community**