# Box Simulator Internal Runtime Contract

`hwlab-box-simu` is the local simulator endpoint used by L2/L3 smoke tests. It
is not a substitute for real DEV hardware.

## Ports

The simulator exposes these ports through `GET /status`:

| Port | Direction | Value Type |
| --- | --- | --- |
| `uart0` | bidirectional | string |
| `eth0` | bidirectional | object |
| `gpio0` | bidirectional | boolean |
| `DO1` | output | boolean |
| `DI1` | input | boolean |
| `AO1` | output | number |
| `AI1` | input | number |
| `FREQ_OUT1` | output | number |
| `FREQ_IN1` | input | number |

The L3 patch-panel sync loop uses `DO1`, `DI1`, `AO1`, `AI1`, `FREQ_OUT1`, and
`FREQ_IN1`. Cross-device propagation must be `patch-panel-only`; local loopback
is not accepted as a substitute.

## Write Contract

`POST /ports/write` accepts:

```json
{
  "port": "DI1",
  "value": true,
  "source": "res_boxsimu_runtime_1",
  "sourcePort": "DO1",
  "propagatedBy": "hwlab-patch-panel"
}
```

The response always includes whether the write was accepted, the box id, the
port, the stored value, and the patch-panel propagation constraints. When the
write came through `hwlab-patch-panel`, `GET /status` preserves
`source`, `sourcePort`, and `propagatedBy` on the target port.