Skip to main content
skill CX Codex

circuit-debugger — Claude Code skill for circuit diagnosis

The circuit-debugger skill for Claude Code guides checks of power, grounds, and signals in Arduino, ESP32, and RP2040 circuits. It helps trace faults such as an unresponsive sensor or an overheating component.

MIT 298 installs ★ 33 updated 2026-10-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add wedsamuel1230/embedded-engineering-skills --skill circuit-debugger -a claude-code
Open on GitHub

What circuit-debugger does

The skill guides circuit diagnosis in stages: measure supply voltage, test ground continuity, verify signals, then isolate components one at a time. Its checks cover I2C, LEDs, motors, and sensors, and help distinguish a software fault from a hardware problem.

A bundled script, scripts/generate_debug_sketch.py, creates sketches for I2C scanning and GPIO, ADC, or PWM tests. For an I2C scan, run uv run --no-project scripts/generate_debug_sketch.py --i2c --output i2c_scanner.ino. Power the circuit down before continuity or resistance measurements; do not bridge domains designed to stay isolated.

What it helps with

  • trace a board with no power
  • check whether devices respond on an I2C bus
  • find a floating signal on a pin
  • identify which added component causes a failure
  • separate firmware issues from hardware faults

Example prompts for the agent

  • Walk me through checking the power and ground connections on my ESP32 circuit.
  • Generate a sketch to scan for I2C devices and save it as i2c_scanner.ino.
  • Help me diagnose an unresponsive sensor by checking its power, wiring, and signals.

How to install circuit-debugger

1Skills CLI (Vercel)

npx skills add wedsamuel1230/embedded-engineering-skills --skill circuit-debugger -a claude-code

2Manually: put the files in place

~/.claude/skills/circuit-debugger/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/circuit-debugger/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about circuit-debugger

How do I install circuit-debugger in Claude Code?

Run npx skills add wedsamuel1230/embedded-engineering-skills --skill circuit-debugger -a claude-code. The skill file is at ~/.claude/skills/circuit-debugger/SKILL.md.

What does circuit-debugger do?

It guides hardware troubleshooting for Arduino, ESP32, and RP2040 circuits, including power, ground, signal, and component checks.

How can I generate an I2C scanner sketch?

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

Source text

SKILL.md · MIT
---
name: circuit-debugger
description: |
  Systematic hardware debugging guide for Arduino/ESP32/RP2040 circuits. Use when user reports: circuit not working, components getting hot, no power, intermittent failures, unexpected behavior, sensor not responding, LED not lighting, motor not spinning. Guides through power checks, continuity testing, signal tracing, and component isolation using multimeter techniques.
metadata: {triggers: "circuit failure, no power, hot component, sensor not responding, multimeter"}
---

# 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:**
```bash
uv run --no-project scripts/generate_debug_sketch.py --i2c --output i2c_scanner.ino
```

**Generate GPIO tester:**
```bash
uv run --no-project scripts/generate_debug_sketch.py --gpio --pins 2,3,4,5 --output gpio_test.ino
```

**Generate all debug sketches:**
```bash
uv run --no-project scripts/generate_debug_sketch.py --all
```

**Interactive mode:**
```bash
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:**
| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| No voltage anywhere | Disconnected power, blown fuse | Check continuity from source |
| Low voltage (< 4V when expecting 5V) | Overloaded supply, bad regulator | Reduce load, check current draw |
| Voltage drops under load | Undersized power supply | Calculate total current, upgrade PSU |
| Reverse polarity | Swapped wires | Check all connections, may have damaged components |

### Phase 2: Ground Continuity

**Check the design:** Non-isolated logic normally needs a shared reference.
Preserve intentional isolation; do not bond isolated/high-voltage domains just
to satisfy a continuity test. Power down before continuity/resistance tests.

```
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)**
```cpp
// 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:**
| Signal Type | HIGH | LOW | Floating (Bad!) |
|-------------|------|-----|-----------------|
| 5V Logic | 4.5-5.5V | 0-0.5V | 1-3V unstable |
| 3.3V Logic | 2.8-3.6V | 0-0.3V | 0.8-2V unstable |

**I2C Troubleshooting:**
```cpp
// 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 Problem | Check |
|-------------|-------|
| No devices found | SDA/SCL swapped? Pull-ups present? Correct address? |
| Address conflict | Two devices same address? Check AD0/AD1 pins |
| Intermittent | Weak pull-ups (try 4.7kΩ), long wires, noise |

### 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:**
```cpp
// 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");
}
```

| If This Works | If This Fails |
|---------------|---------------|
| Hardware likely OK, check your code | Check USB cable, bootloader, board selection |

## Quick Reference: Common Failures

| Symptom | First Check | Second Check | Third Check |
|---------|-------------|--------------|-------------|
| Nothing works | Power supply | USB cable | Board selection in IDE |
| Gets hot | Short circuit | Reversed polarity | Overcurrent |
| Works then stops | Power brownout | Overheating | Memory leak |
| Erratic behavior | Floating inputs | Missing grounds | Noise/interference |
| I2C fails | Pull-ups | Address | Wire length |
| Motor jerky | Power supply | PWM frequency | Driver current |

## 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](references/multimeter-guide.md) for detailed measurement techniques
- See [references/common-mistakes.md](references/common-mistakes.md) for beginner pitfall gallery

## Shared Output Contract

Use [the shared Arduino skill contract](../../docs/arduino-skill-contract.md):
state assumptions, required tools and versions, implementation steps,
tests/evidence by proof stage, known limitations, and recovery/security notes.

© wedsamuel1230 · MIT · wedsamuel1230/embedded-engineering-skills

Similar skills

All skills for Testing and QA →

From the same set19

The whole set →
arduino-project-builder arduino-project-builder turns requirements into a complete Arduino project: firmware, sensors, actuators, networking, power. Useful when you need a working scaffold, not a snippet. CX Codex +1 588installs arduino-code-generator arduino-code-generator generates embedded C++ patterns for UNO, ESP32, and RP2040, covering sensor filtering, button debouncing, non-blocking timing, and data storage. CX Codex +1 460installs error-message-explainer error-message-explainer explains compiler, upload, boot, power, and runtime failures in Arduino and embedded projects. Use it when an IDE or board error needs a board-specific recovery plan. CX Codex +1 206installs enclosure-designer enclosure-designer turns a request for a board case into an OpenSCAD model: it pins down measurements, places connector cutouts and picks wall thickness for the conditions. CX Codex +1 189installs power-budget-calculator power-budget-calculator estimates total power draw and battery lifespan for Arduino, ESP32, and RP2040 boards. Evaluates sleep cycles and recommends battery capacity. CX Codex +1 178installs datasheet-interpreter datasheet-interpreter pulls pinout, I2C address, timing figures and register map out of a component datasheet PDF, so you can wire the module without writing a driver first. CX Codex +1 173installs bom-generator bom-generator builds bills of materials for Arduino, ESP32, and RP2040 projects with parts, quantities, suppliers, price estimates, and compatibility warnings. CX Codex +1 164installs battery-selector battery-selector picks the cell chemistry and charging circuit for an Arduino, ESP32 or RP2040 project, from battery type down to runtime maths. CX Codex +1 163installs

Project sponsors

Companies that keep this analytics open