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 ケーブル、ブートローダー、ボードの選択を確認してください

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

症状	最初に確認する項目	次に確認する項目	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 スキル契約を使用してください。 前提条件、必要なツールとバージョン、実装手順、証明段階ごとのテスト／証拠、 既知の制限事項、復旧／セキュリティに関する注記を明記してください。