# 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`.