MetalFab UNS Simulator

MQTT-based Unified Namespace simulator for a multi-site metal fabrication company. 22 machines across 3 European sites, ISA-95 hierarchy, PackML state machines.

Quick Start

git clone https://github.com/SheetMetalConnect/metalfab-uns-simulator
cd metalfab-uns-simulator
docker compose up -d --build

Simulator publishes to umh/v1/metalfab/... on port 1883. Verify:

mosquitto_sub -t "umh/v1/metalfab/#" -v

Dashboards

Open dashboards/index.html in your browser. Connects to MQTT via WebSocket on port 8083.

Available dashboards:

• OEE Deep Dive — Single-machine A/P/Q breakdown, downtime Pareto, state timeline
• Factory Overview — All machines at a site with status, jobs, OEE
• Powder Coating Line — Zone tracking, RAL colors, process flow
• Warehouse — AGV fleet, inventory

MCP Server (Claude Desktop)

Connect Claude to the simulator for natural language queries. See mcp-server/README.md.

Control

# Change complexity level (0=paused, 1=sensors, 2=stateful, 3=ERP/MES, 4=full+DPP)
mosquitto_pub -t "metalfab-sim/control/level" -m "3"

# Enable/disable sites
mosquitto_pub -t "metalfab-sim/control/site/brasov" -m "1"
mosquitto_pub -t "metalfab-sim/control/site/roeselare" -m "0"

# Clear all retained data
mosquitto_pub -t "metalfab-sim/control/clear" -m "1"

# Watch simulator status
mosquitto_sub -t "metalfab-sim/#" -v

Local Development

pip install -e .
metalfab-sim run --level 3
metalfab-sim subscribe
pytest

Reference

• Topic Reference — complete namespace tree, data types, retention
• OEE Calculation — how Availability, Performance, Quality are computed
• Digital Product Passport — ESPR compliance, CO2 tracking
• Architecture — site layout, machine types, complexity levels

UMH Data Contracts

The simulator publishes data using two UMH data contract conventions:

_raw (all machines) — Unvalidated sensor data. Works out of the box with the starter kit's historian flow.

umh/v1/metalfab/{site}/{dept}/{machine}/_raw/{tag_name}   → bare value (85.5, "EXECUTE")

_energy-monitor_v1 (energy data) — Validated data contract example. Requires a matching data model in UMH Core.

umh/v1/metalfab/{site}/energy/main/_energy-monitor_v1/{tag_name}   → bare value (45.2)

Both publish alongside the existing Edge/, Line/, Dashboard/ topics used by the browser dashboards.

Use with UMH Core Stack

This simulator integrates with Luke's UMH Starter Kit — an opinionated, batteries-included UMH Core stack.

# From the UMH-Core-Stack repo
docker compose -f docker-compose.yaml -f examples/simulator/docker-compose.simulator.yaml up -d

Then deploy these flows via Management Console → Data Flows → Stand-alone:

Flow	File in starter kit	Purpose
Simulator Bridge	examples/simulator/flows/simulator_to_uns_bridge.yaml	Routes simulator data into UMH Core
Historian	examples/databridges/flows/historian.yaml	Persists _raw → TimescaleDB
Energy Historian	examples/simulator/flows/energy_historian.yaml	Persists _energy-monitor_v1 → TimescaleDB

End-to-end: Simulator → HiveMQ → UMH Core → historian → TimescaleDB → Grafana

License

MIT