circuit-debugger

Q: How do I install circuit-debugger?

Run npx skills add https://github.com/wedsamuel1230/embedded-engineering-skills --skill circuit-debugger in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/circuit-debugger/ (personal) or .claude/skills/circuit-debugger/ (project).

Q: Which AI agents can use circuit-debugger?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Q: Is circuit-debugger safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Q: Who maintains circuit-debugger?

It is published by wedsamuel1230 in wedsamuel1230/embedded-engineering-skills. It has 278 recorded installs.

by wedsamuel1230Frontend & Design

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.

Installs: 278
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/wedsamuel1230/embedded-engineering-skills --skill circuit-debugger

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads circuit-debugger automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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:

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

Generate GPIO tester:

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

Generate all debug sketches:

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

Interactive mode:

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)

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

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

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

Take clear photos of your wiring
Draw a schematic (even hand-drawn)
List exact components with part numbers
Share your complete code
Describe what you expected vs what happened

References

See references/multimeter-guide.md for detailed measurement techniques
See references/common-mistakes.md for beginner pitfall gallery

Shared Output Contract

Use the shared Arduino skill contract: state assumptions, required tools and versions, implementation steps, tests/evidence by proof stage, known limitations, and recovery/security notes.

FAQ

What does the circuit-debugger skill do?

How do I install circuit-debugger?

Run npx skills add https://github.com/wedsamuel1230/embedded-engineering-skills --skill circuit-debugger in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/circuit-debugger/ (personal) or .claude/skills/circuit-debugger/ (project).

Which AI agents can use circuit-debugger?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is circuit-debugger safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains circuit-debugger?

It is published by wedsamuel1230 in wedsamuel1230/embedded-engineering-skills. It has 278 recorded installs.