Hardware Visualisation

Hardware Visualisation (Digital Twin)

The Hardware Visualisation screen (/hardware-twin) renders the saved automation topology read-only in 3D and overlays a live picture of equipment activity and handling-unit movement derived from the device-task feed — giving a real-time digital twin of the physical system without any extra backend instrumentation.

Backed by GET /api/flow/device-tasks (flow-orchestrator, port 8085), polled every 3 s. RBAC: ADMIN, SUPERVISOR, or OPERATOR role required.

Equipment state

The base scene is rendered using the same meshes as the Automation Topology Editor (two-tone conveyor ribbons, racked ASRS, sorter/workstation boxes, SCAN/QRY/DIV function-point markers and labels). Runtime state is shown as a clean overlay on top of the editor scene:

State	Overlay	Trigger
Idle	None — base mesh only	No active task seen in the current window
Running	Floating amber sphere above the equipment, pulsing in size and brightness	At least one active (REQUESTED/DISPATCHED) task on this equipment
Faulted	Floating red sphere above the equipment (steady)	Any FAILED task on this equipment in the current window
Selected	Lime floor ring below the equipment	User clicked the placement

Tote (handling-unit) markers

Active handling units are drawn as small square markers that travel between equipment anchors. For totes on or heading to the conveyor system, the marker glides along the conveyor centreline at a constant 3.2 m/s between anchors (ASRS → main-loop → station and back), making the ASRS → conveyor → workstation journey visible in real time. Totes at non-conveyor equipment (workstations, ASRS placements) settle on the top surface of that equipment's bounding box so they sit visibly above the solid mesh rather than inside it.

Equipment anchoring uses a family-based fallback when a device task does not carry an explicit equipmentId (which is the normal case for flow-dispatched tasks today): ASRS/AUTOSTORE/AMR tasks anchor on the storage placement; CONVEYOR tasks anchor on the longest-path conveyor (the main loop).

Tote state	Meaning
In-transit	Tote has an active CONVEY task dispatched to some equipment
Recirculating	Last sorter decision for this tote was RECIRCULATED; loops back to induct
Queued	Tote is queued at a GTP workstation waiting to be presented
Done	All tasks for this tote completed; marker fades and is removed

Stats bar

A bar across the top of the screen shows live aggregate counters derived from the current device-task window:

Counter	Description
In-transit	Totes with at least one active transport task
Queued	Totes queued at a workstation
Throughput/min	Completed tasks in the last 60 s
Recirculations	Sorter RECIRCULATED decisions in the current window
Faults	Equipment with at least one FAILED task

Level filter

When the topology spans multiple floor levels, a level selector in the header restricts the scene to a single level. All unrelated equipment and tote markers are hidden; the stats bar counts only the visible level.

Labels toggle

A Labels checkbox in the control bar (default off) shows or hides the text labels that float above each equipment placement and function-point marker:

Setting	Effect
Off (default)	All decorative overlays are hidden: equipment-code text, SCAN/QRY/DIV function-point cones/diamonds, and conveyor junction rings. Only the base 3D meshes, tote markers, and activity/state overlays remain. Maximum signal-to-noise at a glance.
On	Equipment codes appear above each placement; SCAN/QRY/DIV labels and cone/diamond glyphs appear above each function-point; conveyor junction rings are shown. Matches the Automation Topology Editor view.

The toggle does not affect the 3D geometry, tote markers, or activity/state overlay indicators.

Interactions

Action	Result
Click equipment	Opens a detail panel with the equipment's recent device tasks
Click tote marker	Opens the HU trace panel for that handling unit (same trace as Transport Overview#per-hu-transport-trace)
Click background / grid	Clears both selections
Left-drag	Orbit the camera
Right-drag	Pan
Scroll / middle-drag	Zoom

Implementation notes

• No backend changes — everything is derived client-side from the existing /api/flow/device-tasks feed, the static automation topology, and the master-data equipment library already used by other screens.
• The 3D scene (HardwareTwin3D) is code-split into its own Vite/three.js chunk and loaded lazily; it does not affect the initial bundle size of other screens.
• The twin reuses the editor's presentational components (EquipmentMesh, FunctionPointMarker) from AutomationTopology3D in read-only mode (no drag gizmos, no waypoint handles, all edit handlers are no-ops). Equipment classification (conveyor vs rack vs sorter) is driven by a one-time load of the master-data equipment library (listEquipment) per warehouse; if that load fails the scene still renders with coarser classification.

Related

Transport Overview · Equipment Integration · Goods-to-Person Stations · Services