Troubleshooting Guide

Q: Motors not moving after power-on?

Possible Causes:

• Power not connected or voltage insufficient
• A4988 driver not properly inserted
• Motor enable pin (ENABLE) wired incorrectly

Solutions:

1. Use multimeter to check 12V power supply voltage
2. Check if A4988 indicator LED is on
3. Send M17 to manually enable motors
4. Check if GPIO4 (ENABLE) is wired correctly

Q: A4988 overheating?

Causes: Current limit set too high

Solution:

1. Power off immediately
2. Install heat sink
3. Adjust A4988 potentiometer (counterclockwise to reduce current)
4. Reference current formula: Vref = I × 8 × Rs (Rs=0.1Ω)
5. For NEMA17 (1.5A): Vref ≈ 1.2V

Q: Vacuum pump not working?

Check Items:

• Relay wiring correct (input, VCC, GND)
• Relay indicator LED lights up when sending M3
• Pump power connection correct (12V)
• Test pump directly connected to power supply

Q: Poor suction effect?

Possible Causes:

• Air leak in pneumatic tubing connections
• Solenoid valve damaged
• Suction cup worn out

Solutions:

1. Check all tubing connections, ensure tight fit
2. Manually test valve (should click when energized)
3. Replace aged suction cup

Q: Abnormal mechanical noise?

Check:

• Ball joints properly installed, not too tight/loose
• Gear meshing correct, no missing teeth
• Motor mounting screws tight
• No interference with other components during arm movement

Q: Serial port connection failed?

Solution:

1. Check port number: Open Device Manager → Ports (COM & LPT) to confirm correct COM port
2. Install driver: Download CP2102 or CH340 driver
3. Close other programs: Ensure Arduino IDE or other serial tools are not occupying the port
4. Replug USB: Try different USB port

Q: Python dependency error?

# Upgrade pip
python -m pip install --upgrade pip

# Clear cache and reinstall
pip cache purge
pip install -r requirements.txt --force-reinstall

# If specific library fails (e.g., opencv)
pip install opencv-python==4.8.0.74

Q: Camera not recognized?

Check:

• Windows Settings → Privacy → Camera permissions enabled for Python
• Test camera with Windows Camera app
• Modify VideoCapture(0) to VideoCapture(1) or 2

Q: Firmware upload failed?

Check:

1. Board selection correct: ESP32 Dev Module
2. Port selection correct
3. Hold BOOT button while uploading (if auto-reset fails)
4. Reduce upload speed: 115200 → 57600

Q: GUI won't start?

# Verify Python version
python --version  # Must be 3.10

# Verify PySide6
python -c "import PySide6; print(PySide6.__version__)"

# If error, reinstall
pip uninstall PySide6
pip install PySide6

Q: Robot arm position inaccurate?

Possible Causes:

• Arm length parameters incorrect
• Step loss occurred
• Motor current too low

Solutions:

1. Re-measure arm lengths: Use calipers to measure, update robotGeometry.cpp
2. Increase current limit: Slightly turn A4988 potentiometer clockwise
3. Reduce acceleration: Decrease F value in GCode (e.g., G1 X10 F500)

Q: Movement stuttering or non-uniform?

Check:

• Ball joints too tight (manual rotation should be smooth)
• A4988 microstep setting (recommended 16 microsteps)
• Mechanical friction in arms (lubricate ball joints)

Q: Out of range error?

Cause: Target coordinates beyond workspace

Workspace limits:

• Radial: R ≈ 100mm (center to XY plane distance)
• Z-axis: -320mm ~ -140mm (relative to base)

Solution: Check target coordinates within limits

Q: Homing inconsistent position each time?

Check:

1. If using limit switches, check if triggered reliably
2. If using HOME_STEPS, ensure motors don't skip steps
3. Add mechanical end stops for consistent reference

Q: YOLOv8 detection inaccurate?

Optimization:

• Improve lighting: Avoid strong shadows, use uniform lighting
• Calibrate camera: Run checkerboard calibration to correct distortion
• Adjust confidence threshold: In code: model(frame, conf=0.5)
• Train custom model: Collect your object dataset for training

Q: Coordinate transformation large error?

Re-calibration Steps:

1. Re-mark 4 or more calibration points on workspace
2. Accurately record pixel and physical coordinates
3. Regenerate homography_matrix.npy
4. Verify with known position objects

Q: Video stream lagging?

Optimization:

# Reduce resolution
cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)
cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)

# Lower frame rate
cap.set(cv2.CAP_PROP_FPS, 15)

# Use smaller YOLOv8 model
model = YOLO('yolov8n.pt')  # nano (fastest)