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)

マルチメーターでのテスト（DC 電圧に設定）

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：信号の検証

デジタル信号（マルチメーターを DC 電圧に設定）

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

想定される測定値：

信号の種類	HIGH	LOW	フローティング（異常！）
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 が入れ替わっていませんか？ プルアップ抵抗はありますか？ アドレスは正しいですか？
アドレスの競合	2 つのデバイスで同じアドレスを使用していませんか？ 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 ケーブル、ブートローダー、ボードの選択を確認してください

クイックリファレンス：よくある不具合

症状	最初の確認項目	2 番目の確認項目	3 番目の確認項目
何も動作しない	電源	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 スキル仕様に従ってください。 前提条件、必要なツールとバージョン、実装手順、証明段階ごとの テスト／証拠、既知の制限事項、復旧／セキュリティに関する注意事項を示してください。