# fischertechnik-factory-twin [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/) [![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE) [![MQTT](https://img.shields.io/badge/MQTT-required-brightgreen.svg)](https://mosquitto.org/) 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 ```bash 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: ```bash # 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 ```bash ./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 ```bash ./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: ```bash 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 ```ini # 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 ```bash # 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/`: ```ini # 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 ```bash ./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 ```bash 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](LICENSE). It includes third-party resources licensed under: - [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) (Font Awesome Free) - [MIT License](https://opensource.org/licenses/MIT) (Bootstrap Icons) - [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) (PythonPDEVS) See [NOTICE.txt](NOTICE.txt) for attribution.