How does compatibility work

Detailed run down on how compatibility is determined

Compatibility = same interface intent + matching attributes + a valid resource assignment.

ProtoParts expose two things: Resources and Interfaces. The validator joins them with a small set of checks to decide if parts can work together in a project.

---

Core concepts

ProtoPart

A part definition that groups one or more domains (electrical, mechanical, pneumatic, hydraulic, data).

Resource

An atomic endpoint inside a domain. Defined by one or more functions plus attributes. Examples:

• Electrical: power_output, ground, digital_io with logic levels, current limits, frequency ranges.

• Mechanical: shaft_keyed_5mm, mount_pattern_20mm, bearing_bore_8mm.

• Fluid: hose_4mm_pushfit, pressure_input, pressure_output with pressure and temperature ratings.

Notes:

• Each function has a direction such as source, receiver, or bidirectional.

• A resource can be marked shareable_with other functions when physically common (e.g., ground shared with power).

Interface

A named bundle that declares capability and wiring expectations:

• protocol: { "type": <enum>, "role": <enum> } (e.g., digital/output or digital/receiver)

• requires: list of required functions with counts and optional shareable_with hints

• constraints: hard rules like max_connections or requires_matching_voltage_domain

• Optional power_delivery, description, and aliases

If two parts implement the same interface with complementary roles and pass constraints, they are compatible.

---

Decision flow

1. Interface identity and role complement

   Interfaces must have the same id (or a declared alias) and complementary role values.

2. Cardinality

   Consumer requires must be satisfiable by provider resources and vice versa, including allowed sharing.

3. Type alignment inside the same domain

   Functions must be pairable (digital_io to digital_io, power_output to power_input, hose_4mm_pushfit to the same fitting type, etc.).

4. Hard attribute checks

   All required attributes fall within limits. Examples:

• Electrical: voltage range, current budget, logic level thresholds, PWM frequency

• Data: protocol, bitrate tolerance, address availability, required pull‑ups present

• Mechanical: bore size, pattern, fit class, envelope clearance

• Fluid: pressure rating, temperature range, medium compatibility

1. System checks

   Cross‑part totals and conflicts: power budget, thermal headroom, bus fanout, I²C/SPI address collisions, timing.

2. Soft preferences and scoring

   Non‑blocking preferences like noise limits, vendor, package. These adjust a score but do not fail the match.

Outcomes

• full_compatibility: all hard checks pass and a concrete assignment exists

• compatible_with_adapter: intent matches but an adapter is needed (e.g., level shifter, connector converter)

• incompatible: interface mismatch, role conflict, cardinality shortfall, or hard rule failure

---

Pin and port assignment

Treat resource hookup as a bipartite assignment problem. Build edges only where function and attributes are compatible. If a perfect matching exists that also satisfies hard constraints and cardinality, emit the mapping. Otherwise report the smallest adapter set that would complete the matching, if available.

---

Example: RC Servo 3‑wire

Intent

A controller provides 5 V power, ground, and a 50 Hz digital control signal. A servo consumes them.

Controller excerpt

{
  "metadata": {
    "id": "controller-x",
    "name": "Controller X",
    "type": "custom",
    "schema_version": "1.1.0",
    "definition_revision": "0.1.0"
  },
  "domains": [
    {
      "domain": "electrical",
      "resources": [
        {
          "id": "vout5",
          "functions": [
            { "name": "power_output", "direction": "source", "signal_class": "power" }
          ],
          "current_rating": { "source": { "max_continuous_mA": 2000 } }
        },
        {
          "id": "gnd0",
          "functions": [
            { "name": "ground", "direction": "bidirectional", "signal_class": "ground" }
          ]
        },
        {
          "id": "pwm0",
          "functions": [
            { "name": "digital_io", "direction": "source", "signal_class": "data" }
          ],
          "logic_levels": { "v_oh_min_V": 4.5, "v_ol_max_V": 0.4 },
          "frequency_hz": { "min": 40, "max": 400 }
        }
      ],
      "interfaces": [
        {
          "id": "rc_servo_3wire",
          "name": "RC Servo 3-wire",
          "protocol": { "type": "digital", "role": "output" },
          "requires": [
            { "function": "power_output", "count": 1 },
            { "function": "ground", "count": 1, "shareable_with": ["power_output"] },
            { "function": "digital_io", "count": 1 }
          ],
          "constraints": { "max_connections": 1, "requires_matching_voltage_domain": true },
          "power_delivery": { "max_voltage_V": 6.0, "max_current_mA": 800 },
          "description": "50 Hz PWM servo control. Pulse 1–2 ms."
        }
      ]
    }
  ]
}

Servo excerpt

{
  "metadata": { "id": "servo-sg90", "name": "Micro Servo SG90", "type": "actuator" },
  "domains": [
    {
      "domain": "electrical",
      "resources": [
        { "id": "vdd", "functions": [ { "name": "power_input", "direction": "sink", "signal_class": "power" } ] },
        { "id": "gnd", "functions": [ { "name": "ground", "direction": "bidirectional", "signal_class": "ground" } ] },
        { "id": "sig", "functions": [ { "name": "digital_io", "direction": "receiver", "signal_class": "data" } ],
          "logic_levels": { "v_ih_min_V": 3.0, "v_il_max_V": 0.8 } }
      ],
      "interfaces": [
        {
          "id": "rc_servo_3wire",
          "name": "RC Servo 3-wire",
          "protocol": { "type": "digital", "role": "receiver" },
          "requires": [
            { "function": "power_input", "count": 1 },
            { "function": "ground", "count": 1, "shareable_with": ["power_input"] },
            { "function": "digital_io", "count": 1 }
          ],
          "constraints": { "max_connections": 1, "requires_matching_voltage_domain": true },
          "description": "Expects 50 Hz PWM, 1–2 ms pulses."
        }
      ]
    }
  ]
}

Result

• Interface ID matches. Roles complement. Cardinality satisfied.

• Logic levels and PWM frequency compatible. Power budget checked via power_delivery and controller current rating.

• Valid mapping: { vout5 → vdd, gnd0 → gnd, pwm0 → sig }.

---

Adapters

Adapters are parts that present interface_A as a consumer and interface_B as a provider, translating attributes or connectors. The validator can propose a minimal adapter set when intent matches but attributes do not.

---

Versioning and inheritance

• Version interfaces with simple integers or semver. Mark backward‑compatible changes.

• Allow specific interfaces to implement more general ones (e.g., i2c_sensor implements i2c_device).

---

Units and normalization

Store numbers in normalized SI in the validator. Keep user‑facing units as metadata. Matching is always performed on normalized values, with converters for display and input.

---

Validator output shape

{
  "status": "full_compatibility",
  "mapping": {"vout5": "servo.vdd", "gnd0": "servo.gnd", "pwm0": "servo.sig"},
  "violations": [],
  "soft_nudges": ["noise_db exceeds preference by 3"],
  "alternatives": [
    {"with_adapter": "level_shifter_5v_to_3v3", "status": "full_compatibility"}
  ]
}

---