circuit-debugger

电路调试器

系统性诊断创客项目中硬件问题的方法。

资源

此技能包含捆绑的工具和参考文档：

• scripts/generate_debug_sketch.py - 用于 I2C 扫描器、GPIO 测试器、ADC 检查器、PWM 测试器的 Arduino 草图生成器
• references/measurement-procedures.md - 全面的万用表和示波器指南

快速开始

生成 I2C 扫描器：

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

生成 GPIO 测试器：

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

生成所有调试草图：

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

交互模式：

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

触发短语

• "我的电路不工作"
• "元件发烫"
• "板子没有供电"
• "传感器无响应"
• "间歇性/随机故障"
• "有时能工作，有时不能"

调试协议

阶段 1：电源系统检查（首先执行！）

目视检查（30 秒）

□ 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)

万用表测试（设置为直流电压）

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

常见电源问题：

症状	可能原因	修复方法
任何地方都无电压	电源断开、保险丝熔断	检查从电源到负载的连通性
电压过低（期望 5V 时低于 4V）	电源过载、稳压器损坏	减小负载，检查电流消耗
负载下电压下降	电源功率不足	计算总电流，升级电源
极性反接	接线交换	检查所有连接，可能已损坏元件

阶段 2：接地连续性

关键规则： 所有地线必须连接在一起。

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

接地问题会导致：

• 传感器读数异常
• I2C/SPI 通信失败
• 电机行为异常
• 显示器显示乱码

阶段 3：信号验证

数字信号（将万用表设置为直流电压）

// 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
}

预期读数：

信号类型	高电平	低电平	浮空（异常！）
5V 逻辑	4.5-5.5V	0-0.5V	1-3V 不稳定
3.3V 逻辑	2.8-3.6V	0-0.3V	0.8-2V 不稳定

I2C 故障排除：

// 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() {}

I2C 问题	检查事项
未找到设备	SDA/SCL 是否接反？是否有上拉电阻？地址是否正确？
地址冲突	两个设备地址相同？检查 AD0/AD1 引脚
间歇性故障	上拉电阻过弱（尝试 4.7kΩ）、导线过长、噪声

阶段 4：元件隔离

分而治之的方法：

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

特定元件测试：

LED：

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

电机/舵机：

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

传感器：

□ 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)

阶段 5：软件与硬件

快速软件测试：

// 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");
}

如果这能工作	如果这失败
硬件可能正常，检查你的代码	检查 USB 线缆、引导加载程序、开发板选择

快速参考：常见故障

症状	第一项检查	第二项检查	第三项检查
什么都不工作	电源	USB 线缆	IDE 中的开发板选择
发烫	短路	极性反接	过流
工作后停止	电源电压跌落	过热	内存泄漏
行为异常	浮空输入	缺少接地	噪声/干扰
I2C 失败	上拉电阻	地址	导线长度
电机抖动	电源	PWM 频率	驱动器电流

万用表快速指南

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)

何时寻求帮助

如果按照此协议操作后仍无法找到问题：

1. 拍摄清晰的接线照片
2. 绘制原理图（即使是手绘的）
3. 列出确切的元件及其型号
4. 分享你的完整代码
5. 描述你的预期与实际发生的情况

参考文档

• 详细的测量技术参见 references/multimeter-guide.md
• 初学者常见错误图集参见 references/common-mistakes.md

共享输出契约

使用共享 Arduino 技能契约： 说明假设、所需工具和版本、实现步骤、 按验证阶段划分的测试/证据、已知限制以及恢复/安全注意事项。