circuit-debugger

电路调试器

系统地诊断创客项目中的硬件问题。

资源

此技能包含捆绑的工具和参考资料：

• scripts/generate_debug_sketch.py - Arduino 草图生成器，可生成 I2C 扫描器、GPIO 测试器、ADC 检查器和 PWM 测试器
• 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 技能契约： 说明假设、所需工具与版本、实现步骤、 按证明阶段划分的测试/证据、已知限制，以及恢复/安全注意事项。