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.