Skip to content

Hardware Visualisation

Jump to bottom
openwcs-docs-agent edited this page Jun 11, 2026 · 23 revisions

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 glide between the equipment their successive device tasks ran on. Motion is approximate — the trace records named waypoints (induct → convey → sort → station), not continuous belt position — so markers are tweened between equipment anchors rather than tracking a precise physical location.

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) Equipment-code names and SCAN/QRY/DIV type labels are hidden — only the 3D meshes and cone/diamond glyphs are visible. Reduces visual noise at a glance.
On Equipment codes appear above each placement; SCAN/QRY/DIV labels appear above each function-point cone. Matches the Automation Topology Editor view.

The toggle does not affect the 3D geometry, tote markers, or overlay state indicators — only the <Html> text overlays are gated.

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

openWCS — open-source Warehouse Control System · summarized from build.md & docs/AS-BUILT.md (the repo docs are authoritative).

openWCS

Design

Flows

Reporting & Dashboards

Operations

Clone this wiki locally