pikasTech-HWLAB/protocol/box-simu-internal.md

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:

{
  "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.