> For the complete documentation index, see [llms.txt](https://docs.protoboard.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.protoboard.xyz/tutorials-and-examples/common-drc-failures.md).
# Common DRC Failures
Intentionally broken builds that teach you how to diagnose and fix common DRC failures.
## Goal
Learn to read DRC output by studying **intentionally broken builds**. Each scenario sets up a specific failure, shows what the DRC reports, and walks through the diagnosis and fix. After this tutorial, you'll recognize these failures on sight and know how to resolve them.
{% hint style="info" %}
**Time:** About 20 minutes to work through all scenarios. **What you need:** A free Protoboard account. You can build each scenario on the same board or create separate boards.
{% endhint %}
{% hint style="warning" %}
**This tutorial is different.** Instead of building something that works, you'll build things that are *broken on purpose*. Most of the time spent on a real project goes into diagnosing and fixing issues, not producing a clean build on the first try.
{% endhint %}
***
## Quick reference: DRC states
Before diving into the failures, here's what each DRC state means:
| State | Color | Meaning |
| ------------------------- | ----- | -------------------------------------------------------- |
| **CONFIGURED** | Green | All connections properly set up; nothing to fix |
| **PARTIALLY\_CONFIGURED** | Amber | Some connections exist but the setup is incomplete |
| **NOT\_CONFIGURED** | Red | A harness or interface link exists but nothing is mapped |
| **INCOMPATIBLE** | Red | Fundamental mismatch; these parts can't connect this way |
***
## Failure 1: Voltage mismatch
### The scenario
You connect a 5V device to a 3.3V-only sensor that can't tolerate higher voltages.
{% stepper %}
{% step %}
### Set up the broken build
1. Place an **Arduino Uno Rev3** on the canvas (operates at 5V logic)
2. Place an **SCD40** CO2 sensor on the canvas (3.3V only, no onboard level shifting)
3. Create a harness from the Arduino's **5V power output** to the SCD40's **power input**
{% endstep %}
{% step %}
### What DRC shows
Run DRC. You should see:
**INCOMPATIBLE** (red) on the power harness.
The DRC message will indicate a **voltage domain mismatch**: the Arduino's 5V output exceeds the SCD40's maximum input voltage rating.
{% endstep %}
{% step %}
### Diagnosis
The SCD40 is a 3.3V device. Unlike the BME280 breakout (which has onboard level shifting and accepts 3-5.5V), the SCD40 expects 3.3V power and logic levels. Connecting it directly to a 5V rail could damage the sensor in real hardware.
Protoboard catches this by comparing voltage domains: the Arduino's 5V output domain doesn't overlap with the SCD40's acceptable input range.
{% endstep %}
{% step %}
### The fix
{% tabs %}
{% tab title="Add a voltage regulator" %}
Place an **MCP16251T** regulator between the Arduino and the SCD40. Configure the regulator's output for 3.3V. Now the power chain is: Arduino 5V to regulator input, regulator 3.3V output to SCD40 power input.
{% endtab %}
{% tab title="Use the Arduino" %}
The Arduino Uno Rev3 has a 3.3V output pin (limited to \~50mA). If the SCD40's current draw is within that limit, you can connect the Arduino's 3.3V power domain to the sensor instead of the 5V domain. Adjust the harness interface link accordingly.
{% endtab %}
{% tab title="Use a different sensor" %}
Replace the SCD40 with the **BME280** breakout, which accepts 3-5.5V thanks to its onboard regulator and level shifters. The DRC will show CONFIGURED because the voltage domains overlap.
{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}
***
## Failure 2: Protocol mismatch
### The scenario
You try to connect an I2C controller to an SPI peripheral, two completely different communication protocols.
{% stepper %}
{% step %}
### Set up the broken build
1. Place an **Arduino Uno Rev3** on the canvas
2. Place a **BME280** sensor on the canvas
3. Create a harness between them
4. In the interface link, try to pair the Arduino's **I2C master** interface with the BME280's **SPI slave** interface (instead of the BME280's I2C slave interface)
{% endstep %}
{% step %}
### What DRC shows
Run DRC. You should see:
**INCOMPATIBLE** (red) on the data harness.
The DRC message will indicate a **protocol type mismatch**: I2C and SPI are fundamentally different protocols with different signal structures.
{% endstep %}
{% step %}
### Diagnosis
I2C uses two wires (SCL + SDA) with addressing. SPI uses four wires (MOSI, MISO, SCLK, CS) with chip select. These protocols are not interchangeable; the signals, timing, and addressing schemes are completely different. Protoboard enforces that the protocol type must match on both sides of an interface link.
{% endstep %}
{% step %}
### The fix
Select the harness, open the Inspector, and change the interface link. Pair the Arduino's **I2C master** interface with the BME280's **I2C slave** interface (not SPI). Both interfaces use the same protocol, so Protoboard will find them compatible.
{% hint style="info" %}
**Good to know:** The BME280 breakout supports both I2C and SPI. If you actually want to use SPI, pair the Arduino's **SPI master** interface with the BME280's **SPI slave** interface. Just make sure both sides are the same protocol.
{% endhint %}
{% endstep %}
{% endstepper %}
***
## Failure 3: Role conflict
### The scenario
You connect two I2C masters together, two devices that both want to control the bus.
{% stepper %}
{% step %}
### Set up the broken build
1. Place an **Arduino Uno Rev3** on the canvas
2. Place a **Raspberry Pi 5** on the canvas
3. Create a harness between them
4. Pair the Arduino's **I2C master** interface with the Raspberry Pi's **I2C master** interface
{% endstep %}
{% step %}
### What DRC shows
Run DRC. You should see:
**INCOMPATIBLE** (red) on the I2C harness.
The DRC message will indicate a **role conflict**: both devices are configured as I2C masters.
{% endstep %}
{% step %}
### Diagnosis
I2C is a master/slave protocol. The master initiates communication and drives the clock (SCL). Two masters on the same bus need special multi-master arbitration, which most simple setups don't support. Protoboard enforces complementary roles: master must connect to slave (device), not master to master.
This same rule applies across all protocols:
* **I2C:** master connects to slave
* **SPI:** controller connects to peripheral
* **Power:** supply connects to return (input)
* **Motor:** driver connects to motor
* **UART:** transmitter connects to receiver
{% endstep %}
{% step %}
### The fix
{% tabs %}
{% tab title="Change one device" %}
If you genuinely need the Arduino and Raspberry Pi to communicate, use a protocol where their roles are complementary. For example, use **UART** where one device is the transmitter and the other is the receiver. Or use **SPI** where one is the controller and the other is the peripheral.
{% endtab %}
{% tab title="Use a shared bus with a sensor" %}
If the real goal is to have both MCUs read the same sensor, place a **BME280** (I2C slave) on the board and connect each MCU to it separately. This creates two valid master-to-slave connections instead of one invalid master-to-master connection. (Note: only one master can use the bus at a time without multi-master support.)
{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}
***
## Failure 4: Missing resource allocation
### The scenario
You create a harness and interface link, but don't allocate the physical resources (pins) needed to carry the signals.
{% stepper %}
{% step %}
### Set up the broken build
1. Place an **Arduino Uno Rev3** on the canvas
2. Place a **BME280** sensor on the canvas
3. Create a harness between them
4. Create the interface link (I2C master to I2C slave)
5. **Don't** allocate specific Arduino pins to the I2C functions; leave the resource allocation empty
{% endstep %}
{% step %}
### What DRC shows
Run DRC. You should see:
**PARTIALLY\_CONFIGURED** (amber) on the I2C harness.
The DRC message will indicate that **resources are not allocated**: the logical connection exists, but no physical pins have been assigned to carry the signals.
{% endstep %}
{% step %}
### Diagnosis
An interface link says "these two interfaces should be connected." Function links say "this signal maps to that signal." But **resource allocation** says "this specific pin on the Arduino carries the SCL signal." Without allocation, Protoboard knows what you want to do but can't verify that the hardware can actually do it.
Concretely:
* **Interface link** = "I want I2C between Arduino and BME280"
* **Function links** = "SCL maps to SCL, SDA maps to SDA"
* **Resource allocation** = "Arduino pin A5 carries SCL, pin A4 carries SDA"
All three layers need to be complete for a CONFIGURED result.
{% endstep %}
{% step %}
### The fix
Select the harness, open the Inspector, and look for the resource allocation section. Assign the Arduino's pins:
* **A4** to SDA function
* **A5** to SCL function
Alternatively, ask ProtoBot: "Allocate I2C resources on my Arduino."
Re-run DRC. The harness should now show **CONFIGURED** (green).
{% endstep %}
{% endstepper %}
***
## Failure 5: Bus capacity exceeded
### The scenario
You connect too many devices to a single I2C bus, exceeding the bus's capacity or creating address conflicts.
{% stepper %}
{% step %}
### Set up the broken build
1. Place an **Arduino Uno Rev3** on the canvas
2. Place multiple I2C sensors: **BME280**, **VL53L0X**, **LSM6DS3TR-C**, **MLX90614**, **MAX30102**, and **SCD40**
3. Connect all six sensors to the Arduino's I2C bus by creating individual harnesses from the Arduino to each sensor
4. Try to allocate all of them to the same I2C peripheral on the Arduino
{% endstep %}
{% step %}
### What DRC shows
Run DRC. You may see:
* **DRC warnings** about bus capacitance or device count limits
* **PARTIALLY\_CONFIGURED** (amber) if some sensors share the same default I2C address (address conflict)
* The DRC may also flag **resource contention** if too many devices demand more current than the bus can source
{% endstep %}
{% step %}
### Diagnosis
The I2C bus has practical limits:
* **Electrical:** Bus capacitance increases with each device and wire length, eventually degrading signal quality
* **Addressing:** Each device needs a unique 7-bit address. Some sensors have fixed addresses or limited address options. If two devices share the same address, they'll collide
* **Current:** The I2C pull-up resistors must source enough current for all devices on the bus
Protoboard's DRC catches these issues by tracking how many devices are allocated to each bus and checking for address conflicts.
{% endstep %}
{% step %}
### The fix
{% tabs %}
{% tab title="Split across multiple buses" %}
If your MCU supports multiple I2C peripherals, split the sensors across different buses. The Arduino Uno only has one hardware I2C bus, but a **Teensy 4.1** or **Arduino Mega 2560** have multiple I2C peripherals.
{% endtab %}
{% tab title="Use an I2C multiplexer" %}
Add an I2C multiplexer (create as a blank part if needed) to expand one I2C bus into multiple isolated channels. This solves both address conflicts and capacitance issues.
{% endtab %}
{% tab title="Change sensor addresses" %}
Some sensors (like the BME280) allow you to change their I2C address via a configuration pin. If two sensors conflict, check whether one of them supports an alternate address.
{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}
***
## Quick diagnosis guide
When you see a DRC failure, use this table to narrow down the cause:
{% columns %}
{% column %}
### Red flags (INCOMPATIBLE)
| Symptom | Likely cause |
| ---------------------------- | --------------------------------------------------------- |
| Power harness turns red | Voltage domain mismatch |
| Data harness turns red | Protocol mismatch or role conflict |
| "Incompatible roles" message | Two masters, two slaves, or other non-complementary roles |
| "Protocol mismatch" message | I2C paired with SPI, UART paired with I2C, etc. |
| {% endcolumn %} | |
{% column %}
### Amber flags (PARTIALLY\_CONFIGURED)
| Symptom | Likely cause |
| ------------------------- | ----------------------------------------------- |
| "Resources not allocated" | Pins not assigned to functions |
| "Missing function links" | Interface link exists but signals aren't mapped |
| "Address conflict" | Two I2C devices share the same address |
| "Incomplete power path" | GND or VCC function link is missing |
| {% endcolumn %} | |
| {% endcolumns %} | |
***
## Common failures
I fixed the issue but DRC still shows the old error
Make sure you **re-run the DRC** after making changes. The validation doesn't auto-refresh, so you need to click the Board Review icon again (or the refresh button in the validation panel) to re-scan.
DRC shows multiple errors and I don't know where to start
Start with **INCOMPATIBLE** (red) errors first; these are fundamental issues that block everything else. Once red errors are resolved, move to **PARTIALLY\_CONFIGURED** (amber) issues, which are usually about completing the configuration. Finally, address any warnings.
I can't reproduce a specific failure from this tutorial
Make sure you're creating the interface links exactly as described. Auto-detect may choose the correct interface link (preventing the failure). To force a specific bad pairing, manually select the wrong interface in the Inspector rather than relying on auto-detect.
ProtoBot fixed my issue but I don't understand what it changed
After ProtoBot makes changes, select each harness and review the interface link details in the Inspector. Compare what's there now with what you had before. Understanding the fix is more valuable than just having it work.
***
## Key takeaways
1. **Voltage domains must overlap.** The output voltage range must fall within the input's acceptable range.
2. **Protocol types must match.** You can't bridge I2C and SPI without an adapter.
3. **Roles must complement.** Master connects to slave, driver connects to motor, supply connects to return.
4. **Resources must be allocated.** Logical connections need physical pin assignments.
5. **Buses have capacity limits.** Too many devices cause address conflicts, signal degradation, or current overload.
6. **Run DRC often.** It catches these issues before you buy parts and solder wires.
***
## Next steps
* [**Fixing Errors**](/user-guide/fixing-errors.md): How to resolve DRC issues step by step
* [**Connections & Compatibility**](/user-guide/connections-and-compatibility.md): How Protoboard evaluates compatibility
* [**Rulesets and Severity**](/reference/rulesets-and-severity.md): Understand the rules behind each DRC check
* [**Error Code Catalog**](/reference/error-code-catalog.md): Look up specific error codes and their meanings
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.protoboard.xyz/tutorials-and-examples/common-drc-failures.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.