> 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/editor/harnesses-and-function-links.md).

# Harnesses and function links

Connect parts with harnesses, choose the interface pair a harness carries, link functions and understand what makes two interfaces compatible

## Goal

Connect two parts so that the connection is complete and passes DRC, and understand the three layers every connection is made of.

## How connections are layered

{% stepper %}
{% step %}

### Harness

A **harness** is the connection between two parts on the canvas, like a cable between two components. You create one by dragging from one part to another.
{% endstep %}

{% step %}

### Interface link

Each harness carries one **interface link**: an interface on part A paired with a compatible interface on part B, for example the Nano's I2C master interface and the BME280's I2C slave interface.
{% endstep %}

{% step %}

### Function links

Inside the interface link, **function links** pair the individual signals: SDA to SDA, SCL to SCL. Each function is backed by a **resource** (a pin or port) on its part. See [Resource allocation](https://docs.protoboard.xyz/editor/resource-allocation.md).
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Think of it as: **harness** = cable, **interface link** = which connectors the cable joins, **function link** = one wire in the cable.
{% endhint %}

## Create and configure a harness

{% embed url="<https://cdn.protoboard.ai/docs/clip/harness-connect?title=Connect+two+parts+with+a+harness>" %}
Connect two parts with a harness
{% endembed %}

[Animated GIF](https://cdn.protoboard.ai/docs/clips/harness-connect-light.gif) · Steps:

1. Hover over the edge of a part until the orange handle appears, then drag to the other part. A grey harness labelled **UNKNOWN** appears and the Inspector opens for it.
2. Under **Interface selection**, open **Interface pair** and choose a pair, or let Protoboard pick the best compatible pair.
3. Protoboard matches the functions by name and assigns pins. The harness turns green when every required function is linked and assigned.
4. If some functions stay unlinked, open **Function Links** and click **Auto Assign**, or pick the pair and pin in each row.
5. Give the harness a name, for example `Left motor control`. The name shows on the canvas.

**Keyboard alternative:** select a part in the Inspector's object tree, activate **Create harness**, choose the other part and activate **Create**.

<figure><picture><source srcset="https://3535233690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHc6ZGiGpKHrs578383AS%2Fuploads%2Fgit-blob-7f9e1142644235edb8037e0688775be518133911%2Finspector-function-links-dark.png?alt=media" media="(prefers-color-scheme: dark)"><img src="https://3535233690-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHc6ZGiGpKHrs578383AS%2Fuploads%2Fgit-blob-40a9f63e0751b529e4bcc2be1a610ea9d28fabce%2Finspector-function-links-light.png?alt=media" alt="The Function Links panel of a harness, with rows pairing Side A and Side B functions and a resource picker on each side"></picture><figcaption><p>Function links with their pins.</p></figcaption></figure>

## Fan-out

One side of a harness can carry several instances of the same interface, so a single bus can reach several devices. Add instances with **+ add** next to the A or B interface. Each instance needs its own wiring and pins.

## What makes two interfaces compatible

Protoboard checks each interface pair against the part definitions:

| Check                                       | Example of a failure                                |
| ------------------------------------------- | --------------------------------------------------- |
| **Protocol type** matches                   | I2C on one side, SPI on the other                   |
| **Roles** pair up                           | Two I2C masters                                     |
| **Domain** matches                          | An electrical interface paired with a pneumatic one |
| **Electrical ranges** overlap               | A 5 V output into a 3.3 V-only input                |
| **Physical connector** fits, when specified | Two connectors of the same gender                   |

Role pairs are defined per protocol in the ProtoPart protocol spec: master and slave for I2C and SPI, host and device for USB and UART, output and input (or source and sink) for power, driver and actuator for DC motors, and so on. The full list is in [Interfaces and Harnesses](https://docs.protoboard.xyz/reference/interfaces-and-harnesses.md). Simple net-like connections, such as a wire to a terminal, accept any electrical interface.

## Harness colours

| Colour | State                | Meaning                                                  |
| ------ | -------------------- | -------------------------------------------------------- |
| Green  | Configured           | Every required function is linked and has a pin          |
| Yellow | Partially configured | The interface link exists but wiring or pins are missing |
| Grey   | Not configured       | No interface link yet                                    |
| Red    | Incompatible         | The interfaces can't connect                             |

In high contrast mode each state also has its own line pattern. The **HARNESS LEGEND** at the right of the canvas explains each state and its fix. See [How DRC works](https://docs.protoboard.xyz/validate-and-build/how-drc-works.md).

## Other harness actions

* Right-click a harness for **Auto-route this harness** and **Move source handle** or **Move target handle**.
* Remove a link inside a harness from the Inspector, or delete the whole harness with the Delete key.

## Common failures

<details>

<summary>The harness stays grey</summary>

No interface pair is chosen. Select the harness and pick one under **Interface selection**.

</details>

<details>

<summary>The harness is red</summary>

The pair is incompatible, or the two parts share no compatible interface ("No compatible interface pairs found"). Pick a different pair, add an adapter part such as a level shifter or regulator, or swap a part. See [Fixing DRC failures](https://docs.protoboard.xyz/validate-and-build/fixing-drc-failures.md).

</details>

<details>

<summary>The harness is yellow</summary>

A function has no pin or no partner. The Board Review issue names it. Use **Auto Assign**, or pick pins in [Resource allocation](https://docs.protoboard.xyz/editor/resource-allocation.md).

</details>

<details>

<summary>The interface I need isn't in the list</summary>

All instances of it are already used, or the part template doesn't define it. Check the part's **Interfaces** tab; to add one, see [Edit part templates](https://docs.protoboard.xyz/parts/edit-part-templates.md).

</details>

## Related pages

* [Resource allocation](https://docs.protoboard.xyz/editor/resource-allocation.md): which pin carries which signal
* [How DRC works](https://docs.protoboard.xyz/validate-and-build/how-drc-works.md): states and reasons
* [Interfaces and Harnesses](https://docs.protoboard.xyz/reference/interfaces-and-harnesses.md): protocols and roles reference
