circuit-debugger（电路调试器）

Circuit Debugger

Systematic approach to diagnosing hardware issues in maker projects.

Resources

This skill includes bundled tools and references:

• scripts/generate_debug_sketch.py - Arduino sketch generator for I2C scanner, GPIO tester, ADC checker, PWM tester
• references/measurement-procedures.md - Comprehensive multimeter and oscilloscope guide

Quick Start

Generate I2C scanner:

uv run --no-project scripts/generate_debug_sketch.py --i2c --output i2c_scanner.ino

Generate GPIO tester:

uv run --no-project scripts/generate_debug_sketch.py --gpio --pins 2,3,4,5 --output gpio_test.ino

Generate all debug sketches:

uv run --no-project scripts/generate_debug_sketch.py --all

Interactive mode:

uv run --no-project scripts/generate_debug_sketch.py --interactive

Trigger Phrases

• "My circuit doesn't work"
• "Component is getting hot"
• "No power to the board"
• "Sensor not responding"
• "Intermittent/random failures"
• "Works sometimes, not others"

Debugging Protocol

Phase 1: Power System Check (Do First!)

Visual Inspection (30 seconds)

□ Check for smoke, burn marks, or melted plastic
□ Verify power LED on microcontroller is lit
□ Look for loose wires or cold solder joints
□ Confirm correct polarity on polarized components (LEDs, caps, diodes)

Multimeter Tests (Set to DC Voltage)

Test Point              | Expected Value  | If Wrong
------------------------|-----------------|------------------
VCC to GND on MCU       | 3.3V or 5V      | Check regulator, power source
Sensor VCC pin          | Match datasheet | Check wiring, broken trace
Motor driver VCC        | Logic + Motor V | Separate supplies needed?
Battery terminals       | Rated voltage   | Dead/discharged battery

Common Power Issues:

Phase 2: Ground Continuity

Critical Rule: All grounds must be connected together.

Multimeter: Set to CONTINUITY (beep mode)

Test these pairs - ALL should beep:
□ Arduino GND ↔ Sensor GND
□ Arduino GND ↔ Motor driver GND
□ Arduino GND ↔ Display GND
□ Arduino GND ↔ Power supply negative
□ All breadboard GND rails connected

Ground Problems Cause:

• Erratic sensor readings
• I2C/SPI communication failures
• Motors behaving randomly
• Displays showing garbage

Phase 3: Signal Verification

Digital Signals (Set multimeter to DC Voltage)

// Add this debug code to verify pin states
void debugPins() {
    Serial.println("=== Pin States ===");
    Serial.print("D2: "); Serial.println(digitalRead(2) ? "HIGH" : "LOW");
    Serial.print("D3: "); Serial.println(digitalRead(3) ? "HIGH" : "LOW");
    // Add more pins as needed
}

Expected Readings:

I2C Troubleshooting:

// Run this I2C scanner first
#include <Wire.h>

void setup() {
    Serial.begin(115200);
    Wire.begin();

    Serial.println("I2C Scanner");
    for (uint8_t addr = 1; addr < 127; addr++) {
        Wire.beginTransmission(addr);
        if (Wire.endTransmission() == 0) {
            Serial.print("Found device at 0x");
            Serial.println(addr, HEX);
        }
    }
}
void loop() {}

Phase 4: Component Isolation

The Divide-and-Conquer Method:

1. Disconnect ALL external components
2. Verify MCU works alone (blink LED)
3. Add ONE component at a time
4. Test after EACH addition
5. When failure occurs, problem is last added component

Component-Specific Tests:

LEDs:

□ Correct polarity? (long leg = anode = positive)
□ Current limiting resistor present? (330Ω-1kΩ typical)
□ Test LED alone with battery + resistor
□ PWM pin? Try digitalWrite first

Motors/Servos:

□ Never connect directly to MCU pin (use driver!)
□ Separate power supply for motors
□ Flyback diode on DC motors
□ Check stall current vs driver rating

Sensors:

□ Correct operating voltage (3.3V vs 5V!)
□ Level shifter needed for mixed voltage?
□ Decoupling capacitor (100nF) near VCC pin
□ Pull-up resistors for I2C (4.7kΩ typical)

Phase 5: Software vs Hardware

Quick Software Test:

// Minimal test - does the MCU even run?
void setup() {
    pinMode(LED_BUILTIN, OUTPUT);
    Serial.begin(115200);
    Serial.println("MCU is alive!");
}

void loop() {
    digitalWrite(LED_BUILTIN, HIGH);
    delay(500);
    digitalWrite(LED_BUILTIN, LOW);
    delay(500);
    Serial.println("heartbeat");
}

Quick Reference: Common Failures

Multimeter Quick Guide

Measurement    | Setting      | Probes
---------------|--------------|------------------
DC Voltage     | V⎓ (20V)     | Red=signal, Black=GND
Continuity     | ))) or Ω     | Either direction
Resistance     | Ω            | Component out of circuit!
Current        | A or mA      | IN SERIES (break circuit)

When to Ask for Help

If after this protocol you still can't find the issue:

1. Take clear photos of your wiring
2. Draw a schematic (even hand-drawn)
3. List exact components with part numbers
4. Share your complete code
5. Describe what you expected vs what happened

References

• See references/multimeter-guide.md for detailed measurement techniques
• See references/common-mistakes.md for beginner pitfall gallery