pikasTech-HWLAB/protocol/capabilities.md

Capability Model

Box hardware is described with resources and capabilities.

Resource

A box resource is a physical or simulated component that can be addressed by the gateway:

• board
• power supply
• serial port
• network port
• relay
• sensor
• simulator endpoint

Resources carry lifecycle state such as available, reserved, running, maintenance, or offline.

Capability

A capability describes an action or measurement exposed by a resource. Examples:

• power.cycle
• power.set_voltage
• serial.console
• network.link
• firmware.flash
• sensor.read

Capabilities declare:

• direction: input, output, or bidirectional
• value type: boolean, integer, number, string, object, or binary
• optional unit
• constraints for allowed values or ranges
• whether the operation mutates hardware state

Operation Binding

Hardware operations reference capabilities by capabilityId and resources by resourceId. Implementations must not infer a capability from a free-form operation name when a capability record exists.

Box Simulator Minimum Runtime

hwlab-box-simu exposes the L2 MVP simulator families through stable port names:

Family	Port	Direction	Value type
AI	AI1	input	number
AO	AO1	output	number
DI	DI1	input	boolean
DO	DO1	output	boolean
FREQ	FREQ1	bidirectional	number

The simulator reports these through GET /capabilities and supports direct POST /ports/read, POST /ports/write, and POST /invoke operations. The internal patch-panel-owned write surface is POST /internal/ports/write.

Box-simu must not use local loopback to copy an output to an input on another box. Cross-device delivery is patch-panel-owned; box-simu only accepts a local state update through the internal port API and records crossDevicePropagation: "patch-panel-only" with localLoopbackEnabled: false.

hwlab-gateway-simu reports registered box capabilities through GET /capabilities or POST /capabilities/report, accepts POST /register and POST /heartbeat, and forwards POST /invoke to the selected box simulator by resourceId or boxId.