Interfaces and Harnesses

How parts declare connection intent through interfaces, how harnesses bundle them, and the protocol compatibility rules that make it all work.

Interfaces and harnesses are the connection layer of Protoboard. An interface is a single, typed connection point declared by a part. A harness is the logical cable that groups every interface link between two parts into one bundle. Together they let Protoboard automatically discover which parts can talk to each other, allocate the right physical resources, and flag mismatches before you build anything.

Core Concepts

What Is an Interface?

An interface is a template for exactly one connection between two devices. It declares:

Protocol: what language it speaks (e.g., i2c, power, pneumatic).
Role: which side of the conversation it is on (e.g., master vs slave).
Required functions: which physical resource capabilities it needs (e.g., i2c_sda x1, i2c_scl x1).

The golden rule: 1 interface = 1 connection. One interface goes between exactly two devices. If signals always travel together on one physical connector, that is one interface. If any wire could reasonably be routed to a different destination, split it into a separate interface.

What Is a Harness?

A harness is the single logical cable between two parts. When you drag a connection on the canvas, Protoboard creates a harness and then discovers which interfaces on each side are compatible. Compatible pairs become interface links inside the harness.

To the user a harness looks like one line in the system diagram. Under the hood it carries all the mapped signals, power rails, or fluid channels between those two parts.

What Is a Function Link?

Within an interface link, each required function on one side is matched to a required function on the other side. These individual pairings are function links. For example, an I2C interface link contains two function links: one for SDA and one for SCL.

The Protocol + Role System

Two interfaces can connect only when:

Their protocol.type values are identical (case-sensitive string match).
Their protocol.role values form a compatible pair.

Protocol Types by Domain

Protocol Type

Typical Roles

Topology

Notes

power

input / output, source / sink

Point-to-point

Generic power delivery.

dc_power

input / output, source / sink

Point-to-point

Explicit DC power.

digital

transmitter / receiver, output / input, peer / peer

Point-to-point

Single digital signal.

gpio

input / output, peer / peer

Point-to-point

General purpose I/O.

pwm

transmitter / receiver, output / input

Point-to-point

Pulse-width modulation.

analog

transmitter / receiver, output / input

Point-to-point

Analog signal.

i2c

master / slave

Bus

2-wire, up to ~8 devices typical.

spi

master / slave

Multi-drop w/ SS

4-wire (MOSI, MISO, SCK, SS).

uart

host / device, peer / peer

Point-to-point

Serial TX/RX.

can

peer / peer

Bus

CAN-H / CAN-L differential.

usb

host / device

Point-to-point

D+, D-, GND, VBUS.

ethernet

host / device, peer / peer

Point-to-point

Physical Ethernet (TXD, RXD).

brushless_3phase

driver / motor

Point-to-point

3 phases (A, B, C).

dc_motor

driver / actuator

Point-to-point

Motor +/-.

servo_control

controller / actuator

Point-to-point

PWM servo signal.

quadrature

encoder / receiver

Point-to-point

A/B channels.

swd_debug

debugger / target

Point-to-point

SWDIO + SWCLK.

Protocol Type

Typical Roles

Notes

threaded_connection

mounting_point, structural_support, panel_mount

Screws, bolts, standoffs.

clip_connection

mounting_point, structural_support, panel_mount

Snap-fit, clip-on.

mechanical_connection

mounting_point, structural_support, cable_anchor

General mechanical.

mechanical_attachment

mounting_point, structural_support

Simple attachment.

mechanical_rotation

shaft, driver

Rotating couplings.

mechanical_spline

shaft, driver

Spline couplings.

arduino_uno_shield

shield, arduino

Arduino form-factor.

pi hat

shield, host

Raspberry Pi HAT.

Protocol Type

Typical Roles

Notes

thermal_connection

thermal_source, thermal_sink

Heat transfer path.

Protocol Type

Typical Roles

Notes

pneumatic

supply, return, exhaust, control, sensing, filter, regulator, valve, reservoir

Compressed air systems.

hydraulic

supply, return, control, sensing, filter, regulator, valve, reservoir

Hydraulic oil systems.

vacuum

supply, return, exhaust, sensing, filter, regulator, valve, reservoir

Vacuum systems.

gas_supply

supply, return, sensing, regulator, valve, filter, reservoir

Gas delivery.

liquid_supply

supply, return, sensing, regulator, valve, filter, reservoir

Liquid delivery.

drain

return, exhaust

Drain outlet.

vent

exhaust

Atmospheric vent.

Protocol Type

Typical Roles

Notes

ethernet

bridge, access_point, client, peer

Layer 2/3 networking.

power_over_ethernet

bridge, access_point, client

PoE with power + data.

wifi

access_point, client, peer

Wireless LAN.

bluetooth

master, slave, peer

BT Classic and BLE.

mqtt, http, https, ssh

client, server, peer

Application-layer protocols.

modbus, profinet, ethercat

master, slave, coordinator

Industrial protocols.

Role Compatibility Pairs

Two interfaces connect when their roles form a recognized pair. The table below covers all built-in pairings grouped by domain.

Electrical Role Pairs

Role A

Role B

Used By

output

input

power, digital, gpio, pwm, analog

source

sink

power, dc_power

transmitter

receiver

digital, pwm, analog, quadrature

master

slave

i2c, spi, bluetooth

host

device

uart, usb, ethernet

peer

uart, can, digital, gpio, ethernet

driver

motor

brushless_3phase, bipolar_stepper_phases

driver

actuator

dc_motor, stepper_motor, stepper_pulse_dir

controller

actuator

servo_control

encoder

receiver

quadrature

sensor

receiver

hall_encoder

debugger

target

swd_debug

transceiver

antenna

nfc_antenna

Mechanical Role Pairs

Role A

Role B

Used By

shaft

driver

mechanical_rotation, mechanical_spline

shield

arduino

arduino_uno_shield

shield

host

pi hat

Thermal Role Pairs

Role A

Role B

Used By

thermal_source

thermal_sink

thermal_connection

Fluid Role Pairs

Role A

Role B

Used By

supply

return

pneumatic, hydraulic, vacuum, gas_supply, liquid_supply

supply

control

pneumatic, hydraulic

supply

exhaust

vacuum

regulator

supply

All fluid protocols

valve

supply

All fluid protocols

Network Role Pairs

Role A

Role B

Used By

bridge

ethernet

bridge

client

ethernet, power_over_ethernet

access_point

client

ethernet, wifi, power_over_ethernet

peer

ethernet, wifi

master

slave

bluetooth

Role aliases exist. The protocol spec normalizes common variants automatically: controller -> master, target -> slave, serial -> uart, can_bus -> can. But in your definition files, prefer the canonical names listed above.

How Connections Work: Step by Step

Harness creation

When you connect two parts on the canvas, Protoboard creates a harness, the logical bundle between them.

Interface discovery

The engine loads both part definitions and extracts every interface from every domain.

Compatibility matrix

Every interface on part A is compared against every interface on part B. A pair is compatible when their protocol.type matches and their role values form a recognized pair.

Resource feasibility check

For each compatible pair, the engine checks whether enough unallocated resources exist on both sides to satisfy the requires arrays.

Auto-linking

Compatible pairs with available resources are automatically linked inside the harness. Each link maps specific resource functions on one side to resource functions on the other.

Resource allocation

The allocation engine binds physical resources to the linked functions. A resource claimed by one interface link is no longer available for others (unless shareable_with allows it).

Resource Allocation Model

Exclusive by Default

When an interface claims a resource for a function, that resource is exclusively allocated; no other interface can use it. This is the safe default and matches how most physical pins work.

Shareable Resources

Some resources legitimately serve multiple functions simultaneously. The shareable_with field unlocks this:

{
  "id": "rj45_port_1",
  "functions": [
    { "name": "ethernet_port", "shareable_with": ["poe_power_source"] },
    { "name": "poe_power_source", "shareable_with": ["ethernet_port"] }
  ]
}

Here a single RJ45 jack can carry both Ethernet data and PoE power at the same time. Both functions list each other in shareable_with, so a network interface and a power interface can both claim this resource.

Allocation Rules

One resource = one function at a time (unless shareable). The allocation engine finds resources by function name. When an interface requires multiple functions, it searches for a separate resource for each one. Bundling multiple pins into one resource will cause allocation failures.

Scenario

Correct Approach

I2C bus (SDA + SCL)

Two resources: one with i2c_sda, one with i2c_scl.

3-phase motor (A, B, C)

Three resources: phase_a, phase_b, phase_c.

Pin with multiple alternate functions

One resource with multiple functions (mutually exclusive).

PoE port (data + power on same jack)

One resource with shareable_with between functions.

Multi-Domain Interfaces

Some real-world connections span multiple domains. A Power-over-Ethernet switch, for example, needs interfaces in both the electrical and network domains.

When an interface spans domains, reuse the same protocol identifier in each relevant domain. This keeps allocation synchronized. If the protocol (e.g., power_over_ethernet) does not exist in the protocol spec yet, request it from the ProtoPart team or add it yourself before using it in component files.

Interface Constraints

`max_instances`

Limits how many times the device can instantiate this interface. Use only when the hardware itself imposes a limit beyond what resources would allow.

Example

Reason

MCU with 1 I2C controller

max_instances: 1 on the I2C master interface.

MCU with 2 UART peripherals

max_instances: 2 on the UART interface.

Sensor with 8 analog channels

Let the system calculate from resources; no max_instances needed.

`max_connections`

Limits how many other parts can connect to a single interface instance. This is about electrical, structural, or protocol load limits.

Example

Value

Reason

I2C bus

8

Capacitance limits.

Power output

10

Current sharing.

SPI chip select

1

One device per SS line.

Voltage Domain Matching

When requires_matching_voltage_domain is true, both sides of a connection must reference power domains with overlapping voltage ranges. This prevents connecting a 3.3V sensor directly to a 12V output.

Common Interface Patterns

Master side (e.g., Arduino Nano):

{
  "id": "i2c_master",
  "protocol": { "type": "i2c", "role": "master" },
  "requires": [
    { "function": "i2c_sda", "count": 1 },
    { "function": "i2c_scl", "count": 1 }
  ],
  "constraints": { "max_connections": 8, "requires_matching_voltage_domain": true }
}

Slave side (e.g., BME280 sensor):

{
  "id": "i2c_slave",
  "protocol": { "type": "i2c", "role": "slave" },
  "requires": [
    { "function": "i2c_sda", "count": 1 },
    { "function": "i2c_scl", "count": 1 }
  ],
  "constraints": { "requires_matching_voltage_domain": true }
}

Compatibility: master pairs with slave. Both require the same functions, so function links map i2c_sda to i2c_sda and i2c_scl to i2c_scl.

Master side:

{
  "id": "spi_master",
  "protocol": { "type": "spi", "role": "master" },
  "requires": [
    { "function": "spi_mosi", "count": 1 },
    { "function": "spi_miso", "count": 1 },
    { "function": "spi_sck", "count": 1 },
    { "function": "spi_ss", "count": 1 }
  ]
}

Slave side:

{
  "id": "spi_slave",
  "protocol": { "type": "spi", "role": "slave" },
  "requires": [
    { "function": "spi_mosi", "count": 1 },
    { "function": "spi_miso", "count": 1 },
    { "function": "spi_sck", "count": 1 },
    { "function": "spi_ss", "count": 1 }
  ]
}

{
  "id": "uart_host",
  "protocol": { "type": "uart", "role": "host" },
  "requires": [
    { "function": "uart_tx", "count": 1 },
    { "function": "uart_rx", "count": 1 }
  ]
}

Pairs with:

{
  "id": "uart_device",
  "protocol": { "type": "uart", "role": "device" },
  "requires": [
    { "function": "uart_tx", "count": 1 },
    { "function": "uart_rx", "count": 1 }
  ]
}

Note: UART TX on one side connects to RX on the other; the function link handles the crossover.

{
  "id": "power_output",
  "protocol": { "type": "power", "role": "output" },
  "requires": [
    { "function": "power_output", "count": 1 },
    { "function": "ground", "count": 1 }
  ],
  "constraints": { "max_connections": 10 },
  "power_delivery": {
    "max_voltage_V": 5,
    "max_current_mA": 800
  }
}

Pairs with any power / input interface.

Supply side (compressor or regulator output):

{
  "id": "air_supply",
  "protocol": { "type": "pneumatic", "role": "supply" },
  "requires": [
    { "function": "pressure_port", "count": 1 }
  ],
  "system_pressure_bar": 6.9
}

Return side (actuator input):

{
  "id": "air_input",
  "protocol": { "type": "pneumatic", "role": "return" },
  "requires": [
    { "function": "return_port", "count": 1 }
  ]
}

Best Practices

Use standard protocol types. Custom protocol names will not match any existing parts. If you need a new protocol, add it to protocol-spec-vX.X.X.json or request it from the ProtoPart team.

Treat the physical connector as the boundary. One plug or cable = one interface. If any pin group could be separated, split it now.
Define both high-level and low-level interfaces. A motor control interface (2 digital + 1 PWM) can coexist with separate digital and PWM interfaces on the same resources.
Use specific roles, not generic ones. "input" / "output" is far better than "connection".
Let the system calculate instances. Only set max_instances when the hardware itself limits the count beyond what resources allow.
Keep interfaces fully specified. Include direction, voltage constraints, protocol timing, and mechanical keying where applicable.
One resource per allocatable unit. Never wrap multiple wires into a single resource.

PreviousProtoPart Schema

NextRulesets and Severity

Last updated 6 months ago