Capabilities #

Capability (base)
├── InstrumentCapability    — adds channels, readback
└── ProductCharacteristic   — adds pin / pins / net / signal_group, datasheet_ref

# catalog/keysight_34461a.yaml or instruments/dmm.yaml
capabilities:
  - function: dc_voltage
    direction: input      # Instrument measures (receives signal)
    signals:
      voltage:
        range: {min: 0.0001, max: 1000, units: V}
        accuracy: {pct_reading: 0.0035, pct_range: 0.0006}
        resolution: {digits: 6.5}
 
  - function: dc_current
    direction: input
    signals:
      current:
        range: {min: 0.000001, max: 10, units: A}
 
  - function: resistance
    direction: input
    signals:
      resistance:
        range: {min: 0.01, max: 100000000, units: Ohm}

# catalog/keysight_e36312a.yaml or instruments/psu.yaml
 
# Top-level structured channels describe physical topology
channels:
  "1": {terminals: [hi, lo], connector: binding_post, ground: floating}
  "2": {terminals: [hi, lo], connector: binding_post, ground: floating}
 
capabilities:
  - function: dc_voltage
    direction: output     # Instrument sources (provides signal)
    signals:
      voltage:
        range: {min: 0, max: 30, units: V}
      current:
        range: {min: 0, max: 5, units: A}
    channels: ["1", "2"]  # References to top-level channel keys
 
  - function: dc_voltage
    direction: input      # Built-in readback meter
    readback: true        # Excluded from auto-matching
    signals:
      voltage:
        range: {min: 0, max: 30, units: V}
    channels: ["1", "2"]

Product Characteristic          Required Instrument Capability
─────────────────────          ────────────────────────────────
output_voltage (OUTPUT)   →    dc_voltage (INPUT) — need to measure
input_voltage (INPUT)     →    dc_voltage (OUTPUT) — need to source

Product (DUT)                    Instrument
────────────                     ──────────
 
output_voltage ────signal───►    DMM (measures dc_voltage)
   (OUTPUT)                      (INPUT)
 
                  ◄───power────  PSU (sources dc_voltage)
input_voltage                    (OUTPUT)
   (INPUT)

from litmus.matching.service import find_compatible_stations
from litmus.store import get_product
 
# Load by id (`get_product` looks up `products/<id>.yaml` from the project root).
# Use `load_product(Path(...))` when you have an explicit path on disk.
product = get_product("power_board")
matches = find_compatible_stations(product)   # takes the loaded Product object
 
for match in matches:
    print(f"{match.station_id}: {'Compatible' if match.compatible else 'Missing capabilities'}")

# Product characteristic
char = product.characteristics["output_voltage"]
# function: dc_voltage, direction: OUTPUT
 
# Matching wraps characteristics into CapabilityRequirement
# Direction stays as-is (OUTPUT) — pairing happens in capability_satisfies()
 
# Station instrument provides:
# function: dc_voltage, direction: INPUT, signals: {voltage: {range: 0-1000V}}
# → Function match ✓, Direction pair (OUTPUT↔INPUT) ✓, Range contains 3.3V ✓
# → MATCH!

# Function generator waveform shapes
- sine
- square
- triangle
- ramp
- pulse
- arbitrary
- noise
- dc

signals:
  voltage:
    range: {min: 0.1, max: 750, units: V}
    accuracy: {pct_reading: 0.07, pct_range: 0.02}  # default
    bands:
      - when:
          frequency: {min: 3, max: 5, units: Hz}
        accuracy: {pct_reading: 0.35, pct_range: 0.03}
      - when:
          frequency: {min: 5, max: 300, units: Hz}
        accuracy: {pct_reading: 0.07, pct_range: 0.02}
      - when:
          frequency: {min: 300, max: 300000, units: Hz}
        accuracy: {pct_reading: 0.14, pct_range: 0.05}
conditions:
  frequency:
    range: {min: 3, max: 300000, units: Hz}

# Structured channel topology (on catalog/instrument library):
channels:
  "1":
    label: "6V/5A Output"
    terminals: [hi, lo, sense_hi, sense_lo]  # Physical terminals
    connector: binding_post                   # Connector type
    ground: floating                          # Isolated from other channels
  "2":
    terminals: [hi, lo]
    connector: binding_post
    ground: floating
 
# On capabilities, channels is a plain list of keys:
capabilities:
  - function: dc_voltage
    direction: output
    channels: ["1", "2"]  # Which channels support this capability

catalog/keysight_34461a.yaml       ← Universal: "what can this MODEL do"
instruments/dmm_bench_001.yaml     ← Unit-specific: serial, calibration, catalog_ref
stations/bench_01.yaml             ← Project-local: role, driver, resource, catalog_ref

from litmus.matching.service import find_compatible_stations, check_station_compatibility
 
# Find all compatible stations (takes the loaded Product object)
matches = find_compatible_stations(product)
 
# Check specific station — takes id strings, returns dict | None
result = check_station_compatibility(product_id, station_id)
if result and not result["compatible"]:
    for cap in result["missing"]:
        print(f"Missing: {cap['direction']} {cap['function']}")

# Find all compatible stations
curl "http://localhost:8000/api/match?product_id=power_board"
 
# Check specific station
curl "http://localhost:8000/api/match?product_id=power_board&station_id=bench_1"

# instruments/temp_logger.yaml
instrument:
  type: temp_logger
  name: Custom Temperature Logger
 
channels:
  "T1": {terminals: [signal], connector: terminal_block, ground: shared}
  "T2": {terminals: [signal], connector: terminal_block, ground: shared}
  "T3": {terminals: [signal], connector: terminal_block, ground: shared}
  "T4": {terminals: [signal], connector: terminal_block, ground: shared}
  "T5": {terminals: [signal], connector: terminal_block, ground: shared}
  "T6": {terminals: [signal], connector: terminal_block, ground: shared}
  "T7": {terminals: [signal], connector: terminal_block, ground: shared}
  "T8": {terminals: [signal], connector: terminal_block, ground: shared}
 
capabilities:
  - function: temperature
    direction: input
    signals:
      temperature:
        range: {min: -200, max: 850, units: "°C"}
    channels: ["T1", "T2", "T3", "T4", "T5", "T6", "T7", "T8"]

Instrument catalog — what an instrument CAN do
──────────────────────────────────────────────
catalog_entry:
  id: keysight_34461a
  type: dmm
  channels:
    "1": {terminals: [hi, lo], connector: binding_post, ground: shared}
 
  capabilities:
    - function: dc_voltage        ─┐
      direction: input             │  Capability
      signals:                     │  (shared base class)
        voltage:                   │
          range: {min: 0, max: 1000, units: V}
          accuracy: {pct_reading: 0.0035}
          resolution: {digits: 6.5}
 
Product spec — what the DUT NEEDS tested
────────────────────────────────────────
id: power_board_v1
pins:
  VOUT: {name: "J1.3", net: "VOUT_3V3", role: signal}
 
characteristics:
  rail_3v3:
    function: dc_voltage          ─┐
    direction: output              │  ProductCharacteristic
    pin: VOUT                      │  (extends Capability)
    signals:                       │
      voltage:                     │
        value: 3.3                 │
        units: V                   │
    bands:                         │
      - when:                      │
          load: {min: 0, max: 1}   │
        accuracy: {pct_reading: 5.0}
 
Matching: dc_voltage OUTPUT ↔ dc_voltage INPUT
          3.3 V within 0–1000 V range
          0.0035% << 5% (instrument is more accurate)
          MATCH