I2c Bringup Diagnostician

I2C Bringup Diagnostician

Use this skill when the sensor or device should be on the bus, but the I2C path is still not trustworthy.

Resources

• references/bringup-flow.md - ordered I2C fault-isolation workflow
• references/scanner-vs-library.md - what to do when the scanner finds the device but the library still fails
• references/esp32-and-board-quirks.md - ESP32-family and board-specific caveats
• ../../docs/board-support/uno-r4-family.md - Uno R4 family board notes when relevant

When to Use

Use this skill when the request includes:

• "no I2C devices found"
• scanner finds the address but the library cannot initialize the device
• two I2C devices conflict or one disappears
• ESP32 pin, bus, or second-channel confusion
• pull-up, wire-length, or voltage-level questions
• obviously wrong sensor values after basic detection succeeds

Workflow

1. Establish the basic failure shape:

• no scanner detection -> open references/bringup-flow.md
• scanner detects but library fails -> open

references/scanner-vs-library.md

• ESP32-family multi-bus or pin issue -> open

references/esp32-and-board-quirks.md 2. Confirm the electrical basics before library swapping:

• power
• common ground
• SDA and SCL mapping
• pull-ups
• logic level compatibility

3. Only after the bus is electrically plausible, check address, device mode, and library expectations. 4. If the board is Uno R4 family and the failure involves board-specific I2C or support questions, also open ../../docs/board-support/uno-r4-family.md.

Core Rules

• Scanner success does not prove the library is using the device correctly.
• Library failure does not prove the sensor is dead.
• Bus voltage, pull-ups, and pin mapping must be explicit before changing code

blindly.

• For ESP32-family boards, pin choices and multi-bus assumptions are not always

portable across variants.

Verification

• Confirm whether the scanner sees the expected address.
• Confirm whether a minimal register or identification read works.
• Confirm whether the failing behavior tracks a board family, bus instance, or

library rather than the sensor alone.

• Confirm whether the final fix survives repeated scans and actual sensor reads.

Integration

• Pair with circuit-debugger for deeper hardware isolation.
• Pair with datasheet-interpreter when the correct address, power, or timing

details are not known.

• Pair with arduino-code-generator when the user needs a minimal test sketch or

a cleaned-up bus probe.

I2C Bringup Flow

Use this reference when nothing on the bus is behaving yet.

Step 1: Basic Electrical Plausibility

Check:

• device power
• common ground
• correct SDA and SCL pins
• pull-ups present where needed
• logic voltage compatibility

If these are unknown, do not move to library debugging yet.

Step 2: Minimal Detection

Run a minimal scanner or equivalent probe.

Possible results:

• nothing found
• one address found
• multiple addresses found
• intermittent detection

Step 3: Interpret The Result

Nothing Found

Suspect:

• swapped pins
• missing power or ground
• wrong bus instance
• missing pull-ups
• incompatible level or dead module

Address Found

Move to minimal device interaction before jumping into full application code.

Intermittent Detection

Suspect:

• weak pull-ups
• long or noisy wires
• unstable power
• board-specific bus behavior

ESP32 And Board Quirks

Use this reference when the I2C behavior depends on board family rather than only the sensor.

ESP32 Family

Watch for:

• non-portable default pins across variants
• assumptions about a second I2C bus
• differences between board families even when similar code worked elsewhere
• core-version-specific behavior

If multi-bus or variant behavior is involved, capture the exact board and core version before assuming wiring fault.

Known Diagnostic Questions

• which ESP32 family is this exactly?
• which pins are assigned to each bus?
• is the same sketch known to work on a different ESP32 variant?
• did the behavior change after a core update?

Uno R4 Family

Uno R4 is not a generic ESP32-style board. If the user is conflating board families or bus assumptions, open ../../docs/board-support/uno-r4-family.md and reset the board-specific expectations first.

Scanner Sees Device But Library Fails

Use this reference when the address appears on the bus but the library says the device cannot be found or returns nonsense data.

What Scanner Success Proves

• the device answered at an address
• the bus is at least partially alive

What Scanner Success Does Not Prove

• correct device identity
• correct power mode
• correct register access sequence
• correct library assumptions
• healthy sensor readings

Next Checks

• verify the expected address from datasheet or board docs
• verify the library matches the exact device variant
• try a minimal identification or register read
• check if the sensor requires startup delay, mode configuration, or a different

voltage environment

Common Causes

• compatible-looking breakout with wrong or damaged sensor
• library written for a variant with different registers
• wrong initialization sequence
• bus present but sensor returning invalid data