Skip to content

fischertechnik/Agile-Production-Simulation-24V-Dev

BranchesTags

Repository files navigation

fischertechnik APS (Agile Production Simulation) - Central Control Unit

This repository contains the central control unit for the fischertechnik APS (Agile Production Simulation), including:

  • Frontend - Angular-based dashboard for monitoring factory status, managing orders, and manual control.
  • Central Control - Main Node.js/TypeScript service that acts as the "brain". It manages global state, orchestrates FTS (AGV) routing, and coordinates production steps.
  • Node-RED - Middleware handling the translation between high-level MQTT commands and the low-level OPC UA protocol used by the PLC controllers.
  • MQTT Broker - Mosquitto broker serving as the central communication backbone for real-time data exchange between all components.

Note: This documentation is intended for developers with experience in the tooling used by this project, particularly Docker and Node.js. Familiarity with these technologies is expected to effectively understand and work with this system.

Table of Contents

Prerequisites & Setup

1. Docker (Required)

Docker is required to run the local containerized environment.

Note
The free license of Docker Desktop limits commercial use to specific educational scenarios and smaller companies.
We assume that you either:

  • Have a valid Docker Desktop license, or
  • Are using the Linux version (which can be installed in WSL2 or a virtual machine).

If you need assistance exploring alternative options, please contact us.

  • Windows:

    • Install: Follow the official instructions at Docker Desktop for Windows.
    • Config: We recommend using the WSL 2 backend.
    • Start: Launch "Docker Desktop" to start the engine.

  • Ubuntu:

2. Tools & Environment

Install the required tools using the commands below.

Note (Windows): Run winget commands in an Administrator PowerShell terminal. After tool installation, close that terminal and continue in a normal (non-admin) terminal opened in your working folder (for example, C:\Users\YOUR_NAME\Documents).

Tool Windows Command Ubuntu Command Notes
nvm (Version Manager) (Not applicable — use winget for Node) curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash && source ~/.bashrc Install nvm first on Linux.
Node.js 18.20.7 winget install --id OpenJS.NodeJS.18 --version 18.20.7 --exact nvm install 18.20.7 && nvm use 18.20.7 Includes npm. Tested on v18.20.7.
Git winget install --id Git.Git --exact sudo apt install -y git Version control.
OpenSSH Check first: ssh -V sudo apt install -y openssh-client Required for deployment scripts.

Verification

Ensure these commands return versions without errors in your terminal. Recommended minimum versions:

Note (Windows): If you just installed Node.js, close the terminal and open a new one before running the checks so PATH updates are applied.

docker --version   # >= 20.10
node -v            # 18.x (higher version should work, but are not tested)
npm -v             # >= 9.x 
git --version      # >= 2.30
ssh -V             # Any recent OpenSSH version

Development

1. Installation

Clone the repository and install dependencies used for development scripts.

Working directory: Before cloning, navigate to a workspace folder (for example, C:\Users\YOUR_NAME\Documents). Do not clone into system folders like C:\Windows\System32.

git clone <repository-url> ff-central-control-unit
cd ff-central-control-unit
npm run setup

Timing: npm run setup can take around 10 to 20 minutes on a typical machine.

2. Architecture

The following diagram illustrates how the development environment connects to the physical factory hardware. When running in Factory Mode (npm start), the local services replace the production services on the Raspberry Pi.

graph TB
    subgraph DevEnv [Developer Machine]
        direction TB
        Browser[Web Browser]
        
        subgraph Docker [Docker Compose]
            Frontend[Frontend App]
            CC[Central Control]
        end
    end

    subgraph RPi [Raspberry Pi - 192.168.0.100]
        direction TB
        MQTT[Mosquitto MQTT Broker]
        Hardware[TXT Controllers / Hardware]
        NR[Node-RED]
        
        subgraph Stopped [Stopped Production Services]
            ProdCC[Prod Central Control]
        end
    end

    SPS[SPS / PLC]

    %% Connections
    Browser -->|HTTP| Frontend
    Browser -->|WebSockets| MQTT
    
    CC <-->|MQTT| MQTT
    NR <-->|MQTT| MQTT
    Hardware <-->|MQTT| MQTT
    NR <-->|OPC-UA| SPS

    %% Styling
    classDef stopped fill:#999,stroke:#333,stroke-dasharray: 5 5;
    class ProdCC stopped;
    
    linkStyle default stroke-width:2px,fill:none,stroke:gray;
Loading

3. Start Application

The default development mode connects to the physical factory hardware.

  • Target: Physical Factory Hardware (Raspberry Pi at 192.168.0.100)
  • Prerequisite: Connect your PC to the factory Wi-Fi/Network. See Step 5 of Setup and commissioning of the Agile Production Simulation for WiFi setup instructions.
  • Docker Desktop: Make sure Docker Desktop is running and shows Engine running before you continue.
  • Command: 
    npm start
# Or to rebuild containers first:
npm run start:build
  • Behavior: Connects to the factory MQTT broker (192.168.0.100) and uses SSH to automatically stop conflicting containers on the Pi.
  • Important: Ensure your local factory layout configuration matches your physical factory.
  • Timing: The first npm start can take around 3 to 5 minutes. Wait for Compiled successfully before opening the UI.

No factory access? Use Local Mode: npm start -- local (see Appendix: Local Mode).

3.1 Access and Credentials

When running in factory mode, the start script will use SSH to stop conflicting services on the Raspberry Pi.

4. Access Services

Once started, access the development tools via your browser. Wait until you see Compiled successfully in the terminal before opening the URLs.

Service URL Description
Frontend http://localhost:4200 The Angular web interface (Hot Reload enabled)
Node-RED http://192.168.0.100:1880 Visual flow editor for factory logic
MQTT Broker 192.168.0.100:1883 Connect with MQTT Explorer. See MQTT Protocol Docs.
MQTT WebSocket ws://192.168.0.100:9001 WebSocket access to MQTT broker.

5. Development Workflow

Project Structure:

ff-central-control-unit/
├── central-control/    # Backend service (Node.js)
├── frontend/          # Frontend application (Angular)
├── nodeRed/           # Node-RED flows and config
├── common/            # Shared code and protocols
├── mosquitto/         # MQTT broker configuration
├── docs/              # Project documentation
├── examples/          # Example scenarios and configurations
├── scripts/           # Build and deployment scripts
├── raspberrypi/       # Raspberry Pi system configuration and service files
├── docker-compose.yml # Development environment configuration
├── docker-compose-prod.yml # Production environment configuration
└── package.json       # Root package dependencies

Working with Services:

  • View Logs:
    • All: docker compose logs -f
    • Specific: docker compose logs -f frontend

MQTT Communication: By default, the development environment connects to the factory's MQTT broker. Monitor MQTT messages using MQTT Explorer:

  • Host: 192.168.0.100
  • Port: 1883
  • User/Pass: default / default

For topic structure, message payloads, and module-specific examples, see MQTT Protocol Docs.

Testing Changes

This development workflow allows you to make code changes and quickly test them against the real hardware.

Tip: After restarting the backend or deploying new logic, you will likely need to reset the factory state and re-dock the FTS to ensure a clean starting point.

Local Only: If you are developing without hardware, see Appendix: Local Mode. In that mode, you must simulate factory MQTT messages manually to trigger state changes.

Deployment to Hardware

For full details, including manual deployment steps, autostart configuration, and hybrid development, see the Deployment Guide.

Authentication

The deployment scripts use SSH. You will be prompted for the password multiple times.

  • User/Pass: ff22 / ff22+
  • IP: 192.168.0.100

Automated Deployment

Option 1: Deploy All (Standard) Build and deploy all services to the Raspberry Pi.

Note: The compilation process (npm run docker:build) involves cross-compiling for ARM architecture via QEMU emulation. This step can take a considerable amount of time (up to 40 min) to complete depending on your system performance.

npm run docker:build
npm run docker:deploy -- ff22@192.168.0.100

Option 2: Selective Deploy (Faster) Deploy only specific services to save time.

# Example: Deploy only central-control
npm run docker:build -- userdev central
npm run docker:deploy -- ff22@192.168.0.100 userdev central

Available service names: central, frontend, nodered

Troubleshooting

General Issues

  • Containers won't start: Ensure Docker Desktop is running
  • Port conflicts: Check if ports 4200, 1883, 1880, 9001 are available
  • Build failures: Try docker system prune -a to free up space

For deployment-specific errors (SSH, host keys), see DEPLOYMENT.md.

Service Issues

  • Frontend not loading: Check docker compose logs frontend
  • MQTT connection errors: Verify broker is running: docker compose ps
  • Modules not responding: See central-control/README.md for protocol details

Reset Environment

npm stop
docker compose rm -f
npm start

Reset Raspberry Pi (Factory Services)

Warning: This will restore the Raspberry Pi services to the repository version and restart them.

npm run docker:reset -- ff22@192.168.0.100

If you are prompted for credentials, use the SSH details in Authentication.

Module States

The Central Control Unit assigns these states to factory modules:

  • BLOCKED - Module is paused, has errors, or loaded workpiece without action
  • BUSY - Module is executing an action
  • READY - Module available for new orders (specific or any)
  • OFFLINE - Module not connected

For detailed MQTT protocol and module communication, see MQTT Protocol Docs.

Additional Documentation

Official fischertechnik Resources

Contributing

See CONTRIBUTING.md for commit conventions and development guidelines.

License

See LICENSE file for details.

Appendix: Local Mode

If you do not have access to the physical factory or want to work in an isolated environment, you can run in Local Mode.

  • Target: Local Simulation Only
  • Prerequisite: None (Isolated environment).
  • Command: 
    npm start -- local
  • Behavior: Starts a local Docker container for MQTT. Ideal for UI work or logic testing without hardware.
    • Note: Since there is no hardware, you must send manual MQTT messages to emulate factory modules.
    • Important: Ensure your local factory layout configuration matches your simulation needs.
  • Access: 
graph TB
    subgraph DevEnv [Developer Machine]
        direction TB
        Browser[Web Browser]
        Manual["Manual MQTT Injection (MQTT Explorer)"]
        
        subgraph Docker [Docker Compose]
            Frontend[Frontend App]
            CC[Central Control]
            NR["Node-RED (Factory Logic)"]
            LocalMQTT[Local Mosquitto MQTT]
        end
    end

    %% Connections
    Browser -->|HTTP| Frontend
    Browser -->|WebSockets| LocalMQTT
    
    CC <-->|MQTT| LocalMQTT
    NR <-->|MQTT| LocalMQTT
    Manual -->|MQTT| LocalMQTT

    linkStyle default stroke-width:2px,fill:none,stroke:gray;
Loading

About

Agile Production Simulation 24V for Developers

www.fischertechnik.de/en/products/industry-and-universities/training-models/569289-agile-production-simulation-24v

Topics

docker mqtt node-red fischertechnik truescript

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors 1

Languages