fischertechnik-factory-twin

fischertechnik-factory-twin

This project provides a digital twin of the Fischertechnik Training Factory 9V, consisting of two interconnected components:

1. Simulator (simulator/)
   A DEVS-based simulation engine that models the behavior of the factory and publishes MQTT messages. It can operate standalone or in hybrid mode alongside real factory data.

2. Dashboard (dashboard/)
   A Flask-based web application that serves as a real-time control center. It visualizes data from the real factory, the simulator, or both. It includes WebSocket integration, an MQTT bridge, and dynamic dashboard modes (monitor, simulation, hybrid).

Each sub-project has its own Python virtual environment and set of dependencies.

---

Requirements

• Python 3.10 (required)
• Mosquitto MQTT broker running on localhost:1883

⚠️ This project was developed and tested using Python 3.10.
It may not work correctly on older versions due to features like ordered dictionaries and recent library versions.

---

Getting Started

1. Clone the Repository

git clone https://msdl.uantwerpen.be/git/anthony/fischertechnik-factory-twin.git
cd fischertechnik-factory-twin

2. Start the MQTT Broker (Mosquitto)

Make sure a Mosquitto MQTT broker is running on your machine. The simulator expects it to be available at localhost (127.0.0.1) on the default port (1883).

If you have Mosquitto installed locally, you can start it using:

# On most Linux systems:
sudo systemctl start mosquitto

# Or manually:
mosquitto

You can verify it's running by checking localhost:1883 or using an MQTT client like MQTT Explorer.

3: Run the dashboard

./run_dashboard.sh

This will:

• Create a virtual environment in dashboard/venv/ if it doesn't exist

• Install Flask and other required packages

• Start the dashboard web server (accessible locally in your browser on https://localhost:5000)

4. Run the simulator

./run_sim.sh

This will:

• Create a virtual environment in simulator/venv/ if it doesn't exist

• Install dependencies from requirements.txt

• Launch the DEVS simulator in realtime-mode

Environment Configuration

Both the dashboard and simulator use a .env file to configure MQTT broker addresses and logging settings. These files are automatically loaded when the app runs.

Each subproject (dashboard/ and simulator/) contains its own .env file.

How to configure

1. Copy the example file in each subproject:

   cp dashboard/.env.example dashboard/.env
   cp simulator/.env.example simulator/.env
   

2. Edit the values as needed

Each .env file is automatically loaded at runtime by the corresponding Python code. No additional changes to launch scripts are required.

Variable	Description
MQTT_REAL_HOST	IP or hostname of the real factory's MQTT broker
MQTT_REAL_PORT	Port number of the real broker (default 1883)
MQTT_SIM_HOST	IP or hostname of the simulation MQTT broker
MQTT_SIM_PORT	Port number of the simulation broker (default 1883)
LOGGING	Set to 1 to enable debug logging (optional)

Example .env file

# Real system MQTT broker
MQTT_REAL_HOST=192.168.0.10
MQTT_REAL_PORT=1883

# Simulation MQTT broker
MQTT_SIM_HOST=127.0.0.1
MQTT_SIM_PORT=1883

# Logging (0 or 1)
LOGGING=0

Reminder: The .env file is duplicated across both dashboard/ and simulator/ — keep them in >sync if you make changes.

Testing Without the Real Factory

If the physical Fischertechnik factory is offline, you can still run a full end-to-end demo by spinning up a second Mosquitto broker that pretends to be the “real” system.

1 Start an additional broker on port 1884

# Start a second Mosquitto instance (on Linux/macOS)
mosquitto -p 1884 -v &

Or use a separate terminal window. This lets you simulate real factory messages independently from the simulation broker (which runs on 1883).

2 Configure both brokers via .env

Edit the .env file in both dashboard/ and simulator/:

# Simulated MQTT broker (used for internal DEVS comms + dashboard visualizations)
MQTT_SIM_HOST=127.0.0.1
MQTT_SIM_PORT=1883

# Real factory MQTT broker (used to inject real-world-like events)
MQTT_REAL_HOST=127.0.0.1
MQTT_REAL_PORT=1884

# Optional logging toggle
LOGGING=0

3 Run the components as usual

./run_sim.sh         # Connects to both brokers (1883 + 1884)
./run_dashboard.sh   # Connects to both brokers (1883 + 1884)

This setup gives you:

Port	Role	Used by
1883	Simulation broker	Simulator ✅ (internal messages) Dashboard ✅ (monitoring + visualization)
1884	“Fake real factory” broker	Simulator ✅ (real events injection) Dashboard ✅ (monitoring)

The simulator uses 1883 for simulation-specific MQTT commands (like simulation/ctrl/..., visualization output, etc.), and 1884 to receive simulated “real factory” messages like new workpiece arrivals or workpiece orders.

Project Structure

fischertechnik-factory-twin/
├── simulator/        # DEVS simulation engine
├── dashboard/        # Flask web dashboard
├── run_sim.sh        # Root-level launcher for the simulator
├── run_dashboard.sh  # Root-level launcher for the dashboard
├── LICENSE
├── NOTICE.txt
└── README.md

License

This project is licensed under the Apache License 2.0.

It includes third-party resources licensed under:

• CC BY 4.0 (Font Awesome Free)
• MIT License (Bootstrap Icons)
• Apache 2.0 (PythonPDEVS)

See NOTICE.txt for attribution.