> 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/user-guide/connections-and-compatibility.md).

# Connections & Compatibility

Connect parts with harnesses, link interfaces and functions, allocate resources, and understand compatibility rules.

## Goal

Understand how to wire parts together in Protoboard, what makes two parts compatible, and how to configure connections so they pass validation.

***

## How connections work

Connections in Protoboard use a layered model:

{% stepper %}
{% step %}

#### Harness (top level)

A **harness** is the logical connection between two parts. It is created by dragging from one part to another on the canvas. Think of it as the cable or wire bundle between two components.
{% endstep %}

{% step %}

#### Interface links (middle level)

Inside a harness, you create **interface links** that pair one interface from each part. For example, linking the I2C Master interface on a microcontroller to the I2C Slave interface on a sensor.
{% endstep %}

{% step %}

#### Function links (wire level)

Inside each interface link, you create **function links** that map individual signals. For example, connecting SCL to SCL and SDA to SDA within an I2C interface link.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
You can think of it as: **Harness** = cable, **Interface link** = connector pairing, **Function link** = individual wire.
{% endhint %}

***

## Creating and configuring a harness

{% stepper %}
{% step %}

#### Draw the connection

On the canvas, hover near the edge of a part until the dynamic handle appears. Drag from one part to another to create a harness.
{% endstep %}

{% step %}

#### Open the Inspector

Select the harness (click the colored line between parts). The Inspector panel shows the harness details.
{% endstep %}

{% step %}

#### Add interface links

In the Inspector, pair compatible interfaces from each part. Protoboard shows which interfaces can be linked based on protocol type and role.
{% endstep %}

{% step %}

#### Add function links

Within each interface link, map the individual functions (signals/pins). For example, connect TX to RX and RX to TX for a UART link.
{% endstep %}

{% step %}

#### Allocate resources

Map the part's internal **resources** to the interface functions. This tells Protoboard which physical pins or peripherals are being used. You can allocate manually or use **auto-allocate**.
{% endstep %}
{% endstepper %}

***

## Compatibility rules

Think of interface mapping as a matching problem: each required function needs a compatible resource with the right attributes. If power or logic levels don't line up, insert a part that adapts them (a level shifter, voltage regulator, or protocol converter).

For two interfaces to be linked, three conditions must be met:

{% columns %}
{% column %}

#### 1. Protocol type must match

Both interfaces must use the same protocol. You cannot link an I2C interface to a UART interface.

**Examples of protocol types:**

* I2C
* SPI
* UART
* Power
* GPIO
* CAN
* USB
  {% endcolumn %}

{% column %}

#### 2. Roles must be complementary

The two interfaces must have opposite roles:

| Role A           | Role B           |
| ---------------- | ---------------- |
| Master           | Slave            |
| Host             | Device           |
| Supply           | Return           |
| Output           | Input            |
| Transmitter      | Receiver         |
| Driver           | Motor / Actuator |
| {% endcolumn %}  |                  |
| {% endcolumns %} |                  |

### 3. Resources must be available and compatible

Each part must have unallocated resources that can support the connection. If all I2C peripherals on a microcontroller are already in use, you cannot create another I2C interface link from that part.

***

## Resource allocation

Resources are the internal capabilities of a part (physical pins, peripherals, power rails). **Resource allocation** maps these internal resources to the interface functions used in a connection.

{% tabs %}
{% tab title="Auto-allocate" %}
Click the **Auto-allocate** button in the Inspector to let Protoboard assign resources automatically. This is the fastest approach and works well for straightforward connections.

ProtoBot can also auto-allocate resources when creating connections on your behalf.
{% endtab %}

{% tab title="Manual allocation" %}
In the Inspector, expand the resource allocation section for a function link. Select which specific resource (e.g., GPIO pin 4, I2C peripheral 1) you want to assign to each function.

Use manual allocation when you need precise control over pin assignments or when auto-allocate picks a resource you want reserved for something else.
{% endtab %}
{% endtabs %}

***

## Harness visual feedback

Harnesses on the canvas are color-coded by their DRC (validation) status:

| Color     | Status                        | Meaning                                                                   |
| --------- | ----------------------------- | ------------------------------------------------------------------------- |
| **Green** | Configured                    | All interface links, function links, and resources are properly set up    |
| **Amber** | Partially configured          | Some connections exist but setup is incomplete                            |
| **Red**   | Not configured / Incompatible | No connections established, or a fundamental incompatibility was detected |

Harness labels display the **protocol type** (I2C, UART, Power, etc.) so you can identify connection types at a glance.

***

## Multi-domain connections

Protoboard is not limited to electrical connections. Harnesses can span multiple domains:

* **Electrical**: signal and power connections
* **Mechanical**: physical mounting and coupling
* **Thermal**: heat transfer paths
* **Pneumatic**: air pressure lines
* **Hydraulic**: fluid lines
* **Network**: data communication links

The same compatibility rules (protocol match, complementary roles, available resources) apply across all domains.

***

## Common failures

<details>

<summary>I linked two interfaces but the harness is still red</summary>

Creating an interface link is just the first step. You also need to add **function links** (wire-level connections) and **allocate resources**. Check the Inspector for incomplete items.

</details>

<details>

<summary>"Incompatible" error when linking two parts</summary>

Check that:

1. Both interfaces use the **same protocol type** (e.g., both I2C, not I2C and SPI)
2. The roles are **complementary** (e.g., Master and Slave, not Master and Master)

If the roles are wrong, edit the part template to correct the interface role.

</details>

<details>

<summary>Auto-allocate is not working</summary>

The part may not have enough free resources. Check whether other harnesses have already consumed the available resources. You may need to free up resources by removing another connection, or use a part with more available peripherals.

</details>

<details>

<summary>I do not see any compatible interfaces when creating an interface link</summary>

The two parts may not share any matching protocol types, or all matching interfaces may already be fully connected. Verify that both parts have interfaces defined with compatible protocols and roles.

</details>

***

## Related pages

* [Canvas Basics](/user-guide/canvas-basics.md): how to draw connections on the canvas
* [Validation (DRC)](/user-guide/validation-drc.md): check whether your connections pass validation
* [Fixing Errors](/user-guide/fixing-errors.md): resolve connection and compatibility issues
* [Parts: Add / Edit / Custom](/user-guide/parts-add-edit-custom.md): edit part interfaces and resources


---

# 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/user-guide/connections-and-compatibility.md?ask=<question>&goal=<endgoal>
```

`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.