Skip to main content

​
Hardware Issues

​
Motors Not Spinning

Symptoms: Motors don’t spin, no soundPossible Causes:
  1. Power not connected to motor driver
  2. Enable pins (R_EN, L_EN) not HIGH
  3. PWM signal not reaching driver
  4. Motor driver damaged
Solutions:
// Verify enable pins are HIGH
digitalWrite(R_EN, HIGH);
digitalWrite(L_EN, HIGH);

// Test PWM output
ledcWrite(channel, 128);  // 50% duty cycle

// Check voltage at motor terminals with multimeter
Quick Test:
  • Disconnect motors from driver
  • Measure voltage at driver output terminals
  • Should see voltage changing with PWM
Solutions:
  1. Swap motor wires (+ and -)
  2. Or invert direction in code: 
    // Before
digitalWrite(MOTOR_DIR1, HIGH);
digitalWrite(MOTOR_DIR2, LOW);

// After (inverted)
digitalWrite(MOTOR_DIR1, LOW);
digitalWrite(MOTOR_DIR2, HIGH);
Causes: Insufficient power, loose connectionsSolutions:
  1. Check battery voltage (should be > 10V for 3S)
  2. Tighten all power connections
  3. Add capacitors across motor terminals (100nF)
  4. Check motor driver heat (may be thermal shutdown)
  5. Reduce PWM frequency if too high

​
Encoder Issues

​
Encoder Count Not Changing

Debug Steps:
void setup() {
    Serial.begin(115200);

    // Test encoder pins directly
    pinMode(ENCODER_A, INPUT);
    pinMode(ENCODER_B, INPUT);

    // Print pin states
    while (true) {
        Serial.print("A: ");
        Serial.print(digitalRead(ENCODER_A));
        Serial.print(" B: ");
        Serial.println(digitalRead(ENCODER_B));
        delay(100);
    }
}
Expected: Values should change when motor rotatesIf no change:
  1. Check encoder power (5V or 3.3V)
  2. Verify wiring: A → GPIO 34, B → GPIO 35, GND, VCC
  3. Test with external encoder (swap to confirm)
  4. Check if encoder damaged (resistance between pins)
Cause: Channel B not connected or wrong pinSolutions:
  1. Verify Channel B wiring
  2. Confirm pin_b is input-only pin (ESP32: 34-39)
  3. Swap A and B channels if reversed
Solutions:
  1. Add 0.1µF capacitor across encoder A and B
  2. Use shielded cable for encoder
  3. Keep encoder wires away from motor power
  4. Add pull-up resistors (10kΩ) if needed
  5. Implement software debouncing: 
    volatile unsigned long last_interrupt_time = 0;

void IRAM_ATTR encoder_isr() {
    unsigned long interrupt_time = millis();
    if (interrupt_time - last_interrupt_time > 5) {  // 5ms debounce
        // Process encoder
        last_interrupt_time = interrupt_time;
    }
}

​
ESP32 / Embedded Issues

​
Upload Failed

Solutions:
  1. Windows: Install CP2102 or CH340 USB driver
  2. macOS: 
    brew install --cask silicon-labs-vcp-driver
  3. Linux: Add user to dialout group 
    sudo usermod -a -G dialout $USER
# Logout and login
  4. Check USB cable (must be data cable, not charge-only)
  5. Try different USB port
Solutions:
  1. Hold BOOT button while clicking Upload
  2. Press EN (reset) button, then try upload
  3. Lower upload speed in platformio.ini: 
    upload_speed = 115200  # Instead of 921600
  4. Check ESP32 power (LED should be on)
Cause: Insufficient power supplySolutions:
  1. Use external 5V power (not USB)
  2. Add bulk capacitor (1000µF) near ESP32 VIN
  3. Don’t draw too much current from 3.3V pin
  4. Power motors from separate supply

​
ROS2 Issues

​
Node Not Starting

Error: Package 'mecanum_control' not foundSolutions:
  1. Build package: 
    cd ~/ros2_ws
colcon build --packages-select mecanum_control
  2. Source workspace: 
    source install/setup.bash
  3. Add to ~/.bashrc to auto-source: 
    echo "source ~/ros2_ws/install/setup.bash" >> ~/.bashrc
Error: Executable 'motor_controller' not foundSolutions:
  1. Verify entry_points in setup.py: 
    entry_points={
    'console_scripts': [
        'motor_controller = mecanum_control.motor_controller:main',
    ],
},
  2. Rebuild: 
    colcon build --packages-select mecanum_control
source install/setup.bash
Solutions:
  1. Add dependency to package.xml: 
    <exec_depend>geometry_msgs</exec_depend>
  2. Install Python dependencies: 
    sudo apt install python3-numpy python3-scipy
  3. Use rosdep: 
    rosdep install --from-paths src --ignore-src -r -y

​
Topic/Communication Issues

Debug:
# Check if topic exists
ros2 topic list

# Check publishers
ros2 topic info /scan

# Echo topic
ros2 topic echo /scan
If no data:
  1. Verify publisher node is running: ros2 node list
  2. Check topic name (case-sensitive!)
  3. Verify QoS compatibility
Error: Could not transform from 'map' to 'base_link'Solutions:
  1. Check TF tree: 
    ros2 run tf2_tools view_frames
# Opens frames.pdf
  2. Verify all frames are published
  3. Check robot_state_publisher is running
  4. Ensure static transforms are published

​
Robot Won’t Navigate

Cause: Controller parameters not tunedSolutions: Reduce gains in nav2_params.yaml:
controller_server:
  ros__parameters:
    FollowPath:
      max_vel_x: 0.3      # Reduce from 0.5
      max_vel_theta: 0.5  # Reduce rotation speed
      xy_goal_tolerance: 0.15  # Increase tolerance
      yaw_goal_tolerance: 0.25

​
Power & Battery Issues

Causes:
  1. Battery low voltage cutoff triggered
  2. Fuse blown
  3. Loose power connection
Solutions:
  1. Check battery voltage with multimeter
    • 3S LiPo: Minimum 9.0V (3.0V/cell)
    • Replace/recharge if < 10V
  2. Inspect fuse continuity
  3. Tighten all power connections
  4. Add LiPo voltage alarm (buzzer at 3.3V/cell)
Cause: Voltage drop under loadSolutions:
  1. Use fresh/charged battery
  2. Upgrade to higher capacity battery
  3. Reduce wire resistance (thicker gauge)
  4. Check for corrosion on connectors
  5. Measure voltage at motor driver under load

​
Quick Diagnostic Checklist

1

Power

  • Battery voltage > 10V
  • All power LEDs on
  • No loose connections
2

Connectivity

  • ESP32 serial connected
  • ROS2 nodes running: ros2 node list
  • Topics publishing: ros2 topic hz /scan
3

Sensors

  • LiDAR spinning and publishing
  • Encoders counting
  • IMU data valid
4

Control

  • Velocity commands received
  • Motors responding
  • Wheels moving in correct direction

​
Next Steps

FAQ

Frequently asked questions and answers

Debugging Guide

Systematic debugging methodology

Getting Help

Where to ask for assistance

Resources

Additional documentation and tutorials