MaConSim — User Manual

Version 1.0.0

Last updated: July 22, 2026

MaConSim GmbH

Table of Contents

1. Introduction
   • 1.1 What You Can Do with MaConSim
   • 1.2 Key Concepts
   • 1.3 Typical Workflow
2. System Requirements
3. Installation
   • 3.1 Windows
   • 3.2 macOS
   • 3.3 Linux
   • 3.4 Docker
   • 3.5 First Launch
4. License Activation
   • 4.1 Activating a License
   • 4.2 Changing the License Key
   • 4.3 Upgrading or Downgrading Your Subscription
   • 4.4 License Maintenance
5. Login and User Management
   • 5.1 Logging In
   • 5.2 Logging Out
   • 5.3 Creating User Accounts
   • 5.4 Deleting User Accounts
6. Plant Management
   • 6.1 Creating a Plant
   • 6.2 Selecting a Plant
   • 6.3 Editing and Deleting a Plant
   • 6.4 Exporting a Plant
   • 6.5 Importing a Plant
7. Create Resources
   • 7.1 Machines
     • 7.1.1 Creating a Machine
     • 7.1.2 Machine Status
     • 7.1.3 Editing and Deleting a Machine
   • 7.2 Simulation Scenarios
     • 7.2.1 Creating a Scenario
     • 7.2.2 Understanding Takt Time
     • 7.2.3 Editing and Deleting a Scenario
   • 7.3 Orders and Shop Floor Control (SFC)
     • 7.3.1 Understanding Orders and SFCs
     • 7.3.2 Orders
     • 7.3.3 Shop Floor Control (SFC)
   • 7.4 Nonconformance Codes (NC Codes)
   • 7.5 Tools
   • 7.6 Alerts
   • 7.7 Data Collections
8. Create References
   • 8.1 Connect Scenarios to Machines
   • 8.2 Order Queue Management
   • 8.3 Connect Alerts
   • 8.4 Connect Data Collections
   • 8.5 Connect NC Codes
   • 8.6 Connect Tools
9. Production Operator Dashboard
   • 9.1 Overview
   • 9.2 Filtering
   • 9.3 Starting Production
   • 9.4 Stopping Production
   • 9.5 Expanding an Order
   • 9.6 Recent Order History
10. Event Logs
    • 10.1 Order History
    • 10.2 Alert History
    • 10.3 NC Code Occurrences
11. Connectivity
    • 11.1 OPC UA
      • 11.1.1 Creating an OPC UA Tree
      • 11.1.2 OPC UA Tree Management
      • 11.1.3 NodeSet2 Import and Export
      • 11.1.4 Certificate Management
      • 11.1.5 OPC UA Node Management
      • 11.1.5.1 Adding Nodes
      • 11.1.5.2 Data Source Configuration
      • 11.1.5.3 Method Configuration
      • 11.1.5.4 Node References
      • 11.1.5.5 Live Value Display and Monitoring
      • 11.1.5.6 Editing and Deleting Nodes
      • 11.1.5.7 Typical Use Cases
    • 11.2 MQTT
      • 11.2.1 Creating a Broker Tree
      • 11.2.2 Starting and Stopping a Broker Tree
      • 11.2.3 Topic Tree and Add Topic Configuration
      • 11.2.3.1 Live Value Monitoring
      • 11.2.4 Data Source Configuration
12. License Plan Feature Matrix
13. REST API
    • 13.1 Accessing the API
    • 13.2 Usage Notes
14. Updating MaConSim
    • 14.1 Checking for Updates
    • 14.2 Downloading and Installing Updates
    • 14.3 Recommended Backup Before Updating
    • 14.4 Troubleshooting Update Issues
15. Troubleshooting
16. Help and Support

• 16.1 Opening the User Manual
• 16.2 Reporting a Bug or Contacting Support

1. Introduction

MaConSim (Machine Connectivity Simulator) is a desktop application for manufacturing plants. It lets you model your production environment, configure realistic machine simulations, manage production orders, and connect to external automation systems — all from a single interface.

Whether you are evaluating a new production line before it goes live, training operators on industrial automation workflows, or demonstrating factory automation to stakeholders, MaConSim lets you build a complete simulation without touching your real production systems.

1.1 What You Can Do with MaConSim

• Model your plant structure: Define plants, machines, and all associated resources to mirror your real factory layout.
• Simulate machine behavior: Configure production speed (takt time), scrap rates, alert frequencies, maintenance events, and tool consumption per machine.
• Manage production orders: Create orders with target quantities, break them into individual Shop Floor Control (SFC) units, and queue them to machines.
• Monitor production live: The Production Operator Dashboard shows real-time progress, machine status, active SFCs, and recent events for all running orders.
• Log events automatically: Alert occurrences, nonconformance codes, and order state transitions are recorded and available in the Event Logs.
• Connect to real systems: Expose simulation data to SCADA/DCS software via the built-in OPC UA server, or publish it to IoT platforms via MQTT.
• Integrate programmatically: Access all MaConSim functionality via REST API for test automation, CI/CD pipelines, or custom integrations with MES, SCADA, or other IoT systems.
• Back up and transfer configurations: Export a complete plant — including all machines, scenarios, orders, and connectivity settings — as a single portable YAML file.

1.2 Key Concepts

If you are new to industrial automation and control systems (e.g., MES, SCADA, DCS), the following table explains the core terms used throughout this manual:

1.3 Typical Workflow

A typical MaConSim setup follows this sequence:

1. Activate your license (first launch only) — Chapter 4
2. Create a plant — Section 6.1
3. Add machines to the plant — Section 7.1
4. Create simulation scenarios — Section 7.2
5. Connect scenarios to machines — Section 8.1
6. Create orders and SFCs — Section 7.3
7. Queue SFCs — Section 8.2
8. Start production on the dashboard — Chapter 9

Optionally, enrich the simulation by adding alerts, NC codes, tools, and data collections (Sections 7.4–7.7) and connecting them to machines (Sections 8.3–8.6).

Data is stored locally. MaConSim runs entirely offline. All plant data is stored in a local database on your computer. An internet connection is only required at startup for license validation.

2. System Requirements

Firewall: If you plan to use the OPC UA server or connect to an external MQTT broker, ensure the relevant ports are allowed through your operating system firewall and any corporate network firewall. See Section 15 (Troubleshooting) for guidance.

Anti-virus / Security software: Some security tools may flag or block MaConSim on first launch. If the application does not start, check whether it has been quarantined and add an exception for the MaConSim installation folder.

Data storage locations:

The database file is created automatically on first launch at the following path for your operating system:

Backup: The database file (desktop) or Docker volume (server) contains all your plant data. Back it up regularly by copying it to a safe location. You can also use the Plant Export feature (Section 6.4) to export individual plants as portable YAML files.

3. Installation

3.1 Windows

1. Download the installer: maconsim_0.1.0_x64-setup.exe
2. Double-click the installer to run it.

   Windows SmartScreen: Windows may show a "Windows protected your PC" message for newly published software. Click More info → Run anyway to proceed.

3. Follow the installation wizard and accept the license agreement.
4. Choose an installation folder (default: C:\Users\{username}\AppData\Local\MaConSim) and click Install.
5. Once complete, launch MaConSim from the Start Menu or the desktop shortcut.

Administrator rights: The Windows installer does not require administrator rights. MaConSim installs per-user into C:\Users\{username}\AppData\Local\MaConSim.

3.2 macOS

1. Download the disk image: maconsim_0.1.0_aarch64.dmg

   Apple Silicon only: The macOS build runs on Apple Silicon (M1 / M2 / M3 and later) only. Intel-based Macs are not supported.

2. Double-click the .dmg file to mount it.
3. Drag the MaConSim icon into your Applications folder.
4. On first launch, macOS Gatekeeper may show a warning that the app is unverified. To open it:
   • Right-click (or Control-click) the MaConSim icon in Applications.
   • Select Open from the context menu.
   • Click Open in the security dialog.
5. Launch MaConSim from Launchpad or the Applications folder.

No administrator rights required. Dragging the app to the Applications folder does not require elevated privileges. The app runs entirely from that location without any system-level installation.

3.3 Linux

1. Download the package for your distribution:
   • Debian/Ubuntu: maconsim_0.1.0_amd64.deb
   • Other distributions: maconsim_0.1.0_amd64.AppImage
2. Debian/Ubuntu — install the package:

   sudo dpkg -i maconsim_0.1.0_amd64.deb
   

3. AppImage — make it executable and run it:

   chmod +x maconsim_0.1.0_amd64.AppImage
   ./maconsim_0.1.0_amd64.AppImage
   

4. Launch MaConSim from your application menu or run maconsim in a terminal.

Administrator rights: Installing the .deb package requires sudo. The .AppImage variant does not — it runs directly from any location you have execute permissions on, with no system-wide installation.

3.4 Docker

MaConSim is also available as a Docker-based server deployment. This mode runs the backend and frontend as containers, using a PostgreSQL database. It is suited for headless or server environments, demos, and integration testing — no desktop installation required.

Distribution archive contents:

After downloading, you receive a compressed archive named maconsim-docker.zip.

Inside this archive, you will find one or more versioned Docker bundles (for example docker_v1.0.0.zip).

After extracting the latest versioned bundle, you should have a folder like:

docker_v1.0.0/
├── docker-compose.yml       # Orchestrates all services
├── maconsim-backend.tar     # Pre-built backend image (Rust REST API)
├── maconsim-frontend.tar    # Pre-built frontend image (nginx + React SPA)
└── THIRD_PARTY_LICENSE.txt

Prerequisites:

Docker Desktop on macOS / Windows already ships with Compose v2. On Linux, install the docker-compose-plugin package via your package manager.

Services:

The stack starts three containers:

External Client Access Ports

MaConSim exposes the following ports for external system integration:

Custom ports: To change these ports, edit the ports mapping in docker-compose.yml. Update both host and container port numbers.

Steps:

1. Extract the downloaded archive maconsim-docker.zip.

2. Open the extracted maconsim-docker folder and extract the latest versioned Docker bundle (for example docker_v1.0.0.zip).

3. Change the database password in .env: Open .env in a text editor and change the POSTGRES_PASSWORD value to a secure password of your choice:

   POSTGRES_PASSWORD=your_secure_password
   

   Required: The bundled .env file contains a placeholder value (changeme). You must replace it with a strong, unique password for security reasons. The application will refuse to start without a valid POSTGRES_PASSWORD.

4. Start MaConSim using the provided script for your operating system:

   • Windows: Double-click start.bat or run it from Command Prompt/PowerShell
   • macOS/Linux: Run ./start.sh (ensure it is executable: chmod +x start.sh)

   These scripts automatically load the pre-built Docker images (maconsim-backend.tar and maconsim-frontend.tar) and start all services in detached mode.

5. Open the application in your browser:

Alternative: Manual Startup If you prefer to run the commands manually instead of using the start scripts:

1. Open a terminal and navigate to the extracted version folder (example path on Windows):

   cd C:\Users\jasmi\Downloads\maconsim-docker\docker_v1.0.0
   

2. Load the pre-built Docker images:

   docker load -i maconsim-backend.tar
   docker load -i maconsim-frontend.tar
   

3. Start all services:

   docker compose up -d
   

4. Stop the application:

   # Stop containers — all data is preserved in volumes
   docker compose down
   
   # Stop AND delete all data (full reset)
   docker compose down -v
   

Useful commands:

# Follow live logs from all services
docker compose logs -f

# Follow logs from a specific service
docker compose logs -f backend
docker compose logs -f frontend

# Open an interactive psql shell in the database
docker compose exec db psql -U maconsim -d maconsim-db

# Check container status
docker compose ps

# Restart a single service
docker compose restart backend

Environment variables:

Backend (backend service):

Frontend (frontend service):

The frontend image has the backend URL baked in at build time. If you need to point it at a different host or port, contact support for a custom build.

Data persistence:

Your application data is stored in named Docker volumes and survives container restarts:

Use docker compose down -v only when you want a completely clean reset. Use the Plant Export feature (Section 6.4) to create portable YAML backups that survive a volume reset.

License validation: The backend container requires an internet connection (outbound HTTPS on port 443) for license validation at every startup, the same as the desktop application.

Docker permissions: On Linux, Docker commands typically require either sudo or membership in the docker group. Add your user to the group with sudo usermod -aG docker $USER and log out/in for the change to take effect. Docker Desktop on macOS and Windows handles permissions automatically.

3.5 First Launch

On first launch you will be prompted to activate your license before you can use the application. See Chapter 4 for the activation steps.

4. License Activation

4.1 Activating a License

On first launch, MaConSim displays the License Activation screen. You must activate a valid license before the application can be used.

Steps:

1. Enter your license key in the input field. Your key is provided by MaConSim GmbH after purchase or free trial registration. It is typically a long alphanumeric string.
2. Click Activate License.
3. MaConSim contacts the license server (https://api.maconsim.com) to validate the key. This requires an active internet connection.
4. On success, the application proceeds to the login screen. Your license is now stored locally.

Subsequent launches: After successful activation, the license key is stored locally. On every subsequent launch, MaConSim validates it automatically in the background. You will only see the activation screen again if the license expires or becomes invalid.

Important: MaConSim revalidates your license every 24 hours. An active internet connection is required at least once every 24 hours to continue using the application. If you cannot connect to the license server within this period, the application will stop functioning until a connection is restored. There is no offline mode beyond this 24-hour window.

If activation fails: An error message is displayed with the reason. Common causes and solutions:

Re-activating: If your license was renewed or transferred, click Retry or Enter a Different License Key on the error screen and enter your updated key. For detailed server error messages, click Show details on the error screen.

4.2 Changing the License Key

If you need to replace your current license — for example because you upgraded to a new plan, transferred the license to a different account, or received a replacement key — you can do so directly from within the application without reinstalling.

Steps:

1. Log in and open the License Info panel by clicking the License Info button in the top navigation bar.
2. Click the Key icon (🔑) next to the active license status badge. An input field appears inline.
3. Enter your new license key.
4. Press Enter or click Activate.
5. MaConSim contacts the license server to validate the new key. This requires an active internet connection.
6. On success, the new license replaces the previous one. The panel updates immediately to show the new plan, expiry date, and license ID.

Note: Changing the license key fully replaces the previous key. The old key is removed from local storage and only the new key is retained.

If the activation fails: An error message is shown below the input field. Correct the key and try again, or click the ✕ button to cancel and keep the existing license.

License ID: Your Keygen license UUID is displayed in the License Info panel and can be copied to the clipboard for support requests.

4.3 Upgrading or Downgrading Your Subscription

MaConSim does not offer an automated direct plan switch. To move to a different subscription tier (e.g. Basic → Premium or Premium → Basic), follow these steps:

1. Purchase the new subscription tier at maconsim.com/licenses-pricing/ — the same page where your current subscription was bought.
2. After purchase, you will receive a new license key by email.
3. Enter the new key in MaConSim using the Change License Key feature — see Section 4.2.
4. Cancel your old subscription via the Paddle customer portal.

Important billing notes:

• No cancellation deadline: You can cancel your existing subscription at any time, even on the last day of the current billing period. Cancellation takes effect at the end of that period.
• Immediate billing start: Your new subscription’s billing period begins immediately upon purchase, regardless of when you enter the license key or start using the application.
• Parallel subscriptions: Between the date of your new purchase and the expiry of your old subscription, both are active and billed in parallel. You decide when to cancel the old one and when to buy the new one — MaConSim cannot merge, credit, or pro-rate the two billing periods.

4.4 License Maintenance

Machine Binding

MaConSim uses machine fingerprinting to tie your license to a specific computer:

• Desktop installations: The license is bound to your machine’s hardware fingerprint. You can free the machine slot by using the Deactivate this machine button in the License Info panel.
• Docker/container deployments: Use a fixed "server" fingerprint and do not consume a per-machine slot from your license.

Note: If your license has a machine limit and you see the "Machine limit exceeded" error, you must deactivate an unused machine or upgrade to a plan with more machine slots.

Deactivating a Machine

To free a machine slot and move your license to a different computer:

1. Open the License Info panel (top navigation bar → License Info button)
2. Click the Deactivate this machine button (monitor icon with X)
3. A confirmation dialog appears explaining that the license will be removed from this machine and the activation slot will be freed
4. Click Confirm Deactivation to proceed
5. The application will reload and return to the activation screen
6. You can now activate the license on a different machine

Note: This feature is only available for desktop installations (Windows, macOS, Linux).

Monitoring Your License

Open the License Info panel (top navigation bar → License Info button) to view:

• Status badge: Visual indicator showing Active (green), Expiring Soon (amber, when <7 days remaining), or Expired (red)
• Plan name: Your subscription tier (e.g., Free Trial, Basic, Premium) as defined in your license metadata
• License ID: Your unique Keygen license UUID — click the copy button (📋) to copy it to the clipboard for support requests
• Expiration date: When your license expires (displayed as "Never" for non-expiring licenses)
• Days remaining: Countdown to expiration

When your license is expiring soon (<7 days), an amber warning banner appears in the License Info panel with a link to renew your subscription. When expired, a red alert banner appears.

Error Details

If license validation fails, the error screen displays a user-friendly message. For technical troubleshooting, click Show details to reveal the raw server response message.

Firewall configuration: Ensure outbound HTTPS connections to api.maconsim.com on port 443 are allowed through your firewall for license validation to work.

5. Login and User Management

5.1 Logging In

1. On the login screen, you first see a list of all existing users with their username and email address.
2. Click on a user to select them.
3. Enter your Password on the next screen.
4. Click Login.

If your password is incorrect, an error message is displayed. Passwords are case-sensitive. If you are unable to log in, verify you are selecting the correct user account and entering the right password.

5.2 Logging Out

To log out of MaConSim:

1. Click the Logout button in the top navigation bar (appears as a red button with a logout icon).
2. You will be returned to the login screen.

5.3 Creating User Accounts

User accounts can be created directly from the login screen:

1. On the login screen, click Create New Account.
2. Fill in the fields:

3. Click Create Account.
4. The new user can immediately log in with their credentials.

5.4 Deleting User Accounts

User accounts can also be deleted from the login screen:

1. On the login screen, select a user.
2. Click Delete Account.
3. Confirm the deletion in the dialog that appears.

Important: Deleting a user also deletes the plant data they created. This action cannot be undone.

License limit: The maximum number of user accounts is determined by your license plan (see Chapter 12). User creation is blocked when the limit is reached. Feature entitlements are determined by your license plan, not by individual user accounts.

6. Plant Management

A Plant represents a physical production site — a factory, a workshop, or a manufacturing cell. All resources in MaConSim (machines, orders, scenarios, connectivity settings, etc.) belong to a specific plant. You can create multiple plants to model separate sites or independent test environments.

Navigate to Plant Management from the main navigation bar.

6.1 Creating a Plant

1. Click Add Plant.
2. Fill in the fields:

3. Click Create Plant.

The new plant appears as a card on the Plant Management screen.

License limit: The maximum number of plants is determined by your license plan (see Chapter 12).

6.2 Selecting a Plant

Click on a plant card to open it. You are taken into the plant view, where all tabs and sections — machines, orders, connectivity, event logs, and the Production Operator Dashboard — relate exclusively to that plant. The currently selected plant name is displayed in the header section for easy reference.

Use the main navigation bar to return to Plant Management and switch between plants.

6.3 Editing and Deleting a Plant

• Click the pencil icon on a plant card to edit its name, info, description, or location.
• Click the trash icon to delete a plant.

Warning: Deleting a plant permanently removes all resources associated with it — machines, scenarios, orders, SFCs, NC codes, tools, alerts, data collections, OPC UA trees, and MQTT brokers. This action cannot be undone.

6.4 Exporting a Plant

The plant export feature allows complete plant configurations to be transferred between installations or used as backups.

1. On the Plant Management screen, click the Download icon on a plant card.
2. A file will be downloaded to your browser’s default download folder, named plant-{plant-name}-export.filetype.

The export includes:

• Plant details
• All machines
• All simulation scenarios
• Machine-scenario connections
• Orders
• SFCs
• NC codes and machine assignments
• Tools and machine assignments
• Alerts and machine assignments
• Data collections and machine assignments
• OPC UA server configurations
• MQTT broker configurations and topics

Security note: MQTT broker passwords are omitted from the export for security reasons and must be re-entered after import.

Note: OPC UA nodes and references can be exported and imported separately via NodeSet2 XML format (see Section 11.1.3).

6.5 Importing a Plant

License requirement: The importPlant entitlement must be enabled. Contact MaConSim GmbH if the button is greyed out.

1. On the Plant Management screen, click Import Plant (top right of Plant Management).
2. A file chooser opens — select a export file.
3. The plant and all its resources are created in the database.
4. The plant list refreshes automatically.

The imported plant is added as a new entry — it does not overwrite existing plants.

License limit: The maximum number of plants is determined by your license plan (see Chapter 12).

7. Create Resources

Navigate to a plant → Create Resources to manage all production resources within that plant.

7.1 Machines

Machines represent the physical production assets within your plant — CNC machines, presses, assembly stations, welding robots, or any other piece of equipment you want to model or simulate.

Navigate to a plant → Create Resources → Machines.

7.1.1 Creating a Machine

1. Click Add Machine.
2. Fill in the fields:

3. Click Create Machine.

Asset ID, Device Class, and Device Revision are free-text fields intended for integration with your asset management or ERP system. MaConSim stores these values for reference but does not process them.

7.1.2 Machine Status

Every machine displays a live status badge reflecting its current state based on ISA-95/PackML standards:

Note: Additional ISA-95/PackML states (STARTING, COMPLETING, COMPLETE, HELD, SUSPENDED, ABORTED, ABORTING, CLEARING) will be available in future releases.

The status changes automatically during simulation based on the active scenario’s parameters. It is also set initially when creating a machine.

7.1.3 Editing, Copying, and Deleting a Machine

• Click the pencil icon on a machine entry to edit any of its fields.
• Click the copy icon on a machine entry to duplicate it with a new name.
• Click the trash icon to delete a machine.

Warning: Deleting a machine removes all its associated connections (scenarios, alerts, NC codes, tools, data collections) and any event history recorded for it. Orders and SFCs that were queued to this machine are not deleted but will lose their machine assignment.

License limit: The maximum number of production machines is determined by your license plan (see Chapter 12).

7.2 Simulation Scenarios

A Scenario defines the simulated behavior of a machine during production. It specifies how fast the machine produces parts, how often defects occur, how frequently alerts are raised, and more. One scenario can be connected to multiple machines, but one machine can only have one scenario.

Navigate to a plant → Create Resources → Scenarios.

7.2.1 Creating a Scenario

1. Click Add Scenario.
2. Configure the simulation parameters:

3. Click Create Scenario.

7.2.2 Understanding Takt Time

Takt time is the heartbeat of the simulation. It controls how often the machine completes one production cycle. After each takt, the simulator evaluates all configured probabilities (scrap, alert, NC code) and increments the produced-parts counter by the Parts per Takt value.

Example: Takt time of 30,000 ms (30 s), 2 parts per takt, scrap rate 0.10:

• The machine produces 2 parts every 30 seconds.
• Roughly 10% of takts will generate a scrap event.
• At this rate, 100 parts are produced in approximately 25 minutes.

Set the takt time to match the real cycle time of the machine you are modeling.

7.2.3 Editing, Copying, and Deleting a Scenario

• Click the pencil icon on a scenario entry to edit its parameters. Changes take effect from the next takt.
• Click the copy icon on a scenario entry to duplicate it with a new name.
• Click the trash icon to delete a scenario. All machine connections to this scenario are also removed.

License limit: The maximum number of scenarios is determined by your license plan (see Chapter 12).

7.3 Orders and Shop Floor Control (SFC)

7.3.1 Understanding Orders and SFCs

An Order is a production job with a defined target quantity — it answers the question: "How many pieces of this product do we need to make?"

An SFC (Shop Floor Control unit) is an individual work item within an order — a specific production lot, a serial unit, or a batch that physically travels through a machine. Think of SFCs as the individual "tickets" that accompany material on the shop floor.

• One order can contain many SFCs.
• Each SFC has its own planned quantity, lifecycle status, and history.
• When production runs on the dashboard, SFCs from the queue are processed in sequence.

7.3.2 Orders

Navigate to a plant → Create Resources → Orders. Click the eye icon on an order to navigate directly to its SFCs.

Creating an Order:

1. Click Add Order.
2. Fill in:

3. Click Create Order.

Editing and Deleting Orders:

• Click the pencil icon to edit an order’s name, info, unit, or target quantity.
• Click the trash icon to delete an order. All SFCs belonging to this order are also deleted.

Copying Orders:

• Click the copy icon to duplicate an order. The new order will have the same parameters as the original, with "(Copy)" appended to the Order Name and Info field.

License limit: The maximum number of orders is determined by your license plan (see Chapter 12).

7.3.3 Shop Floor Control (SFC)

Navigate to a plant → Create Resources → SFCs (or click the eye icon on an order to go directly to that order’s SFCs).

The SFC table displays the following columns: SFC Number (with Serial Number), Order, Material, Status, Step progress, Quantity (Planned / Yield / Scrap), Priority, and Created date.

Filtering SFCs:

• Use the Order dropdown to filter SFCs by a specific order
• View allocation information showing how many units are allocated vs. remaining for each order

Creating an SFC:

1. Click Add SFC.
2. Fill in:

3. Click Create SFC.

Auto-Generate SFCs: For efficient creation of multiple SFCs:

1. Click Auto-Generate SFCs button
2. Select the order for which to generate SFCs
3. Specify the number of SFCs to create
4. Optionally customize the SFC number prefix
5. The system automatically:
   • Calculates the remaining capacity for the selected order
   • Distributes the remaining quantity evenly across the specified number of SFCs
   • Shows warnings if the quantity doesn’t divide evenly
   • Prevents generation if the order is fully allocated

Capacity Validation: When creating SFCs manually or through auto-generation, the system validates that the planned quantity does not exceed the remaining capacity of the parent order. If an order is fully allocated, no new SFCs can be created for it.

SFC Status Lifecycle:

SFCs move through the following statuses during their lifecycle:

Managing SFC Status:

Use the action buttons to manually change an SFC’s status:

Additional SFC Management:

• Delete individual SFCs using the trash icon
• Delete all SFCs for an order using the delete button when filtered by a specific order
• View production progress through the Step column showing current step vs. total steps
• Track quantities with planned, yield, and scrap quantities for each SFC

7.4 Nonconformance Codes (NC Codes)

NC Codes are predefined quality deviation categories. When a machine triggers a nonconformance event during simulation (based on the NC rate configured in the scenario), one of the NC codes connected to that machine is randomly selected and logged in the event history.

NC codes allow you to analyze which defect types occur most frequently, on which machines, and during which orders.

Navigate to a plant → Create Resources → NC Codes.

Creating an NC Code:

1. Click Add NC Code.
2. Fill in the fields:

3. Click Create.

Note: An NC code must be connected to a machine before it can be logged during simulation. See Section 8.5.

License limit: The maximum number of NC codes is determined by your license plan (see Chapter 12).

7.5 Tools

Tools represent physical tooling items used by a machine during production — for example, drill bits, milling cutters, cutting inserts, or punches. When tool logging is enabled in a scenario, MaConSim records one tool usage event per takt, helping you track tool consumption over production runs.

Navigate to a plant → Create Resources → Tools.

Creating a Tool:

1. Click Add Tool.
2. Fill in the fields:

3. Click Create.

Editing and Deleting Tools:

• Click the pencil icon to edit a tool’s name, description, usage count, or count mode.
• Click the trash icon to delete a tool.

Max Usage Limit: Once a tool’s usage count reaches this limit, it will appear as exhausted in reports. This helps simulate realistic tool lifecycle management.

Note: A tool must be connected to a machine and Tool Logging must be enabled in the active scenario for usage to be tracked. See Section 8.6.

License limit: The maximum number of tools is determined by your license plan (see Chapter 12).

7.6 Alerts

Alerts define types of machine events that can be triggered automatically during simulation — for example, temperature warnings, vibration alarms, pressure drops, or door-open signals. When a machine fires an alert event (based on the alert rate in the scenario), one of the alert types connected to that machine is randomly selected and logged.

Navigate to a plant → Create Resources → Alerts.

Creating an Alert:

1. Click Add Alert.
2. Fill in the fields:

Severity levels:

3. Click Create.

Editing and Deleting Alerts:

• Click the pencil icon to edit an alert’s name, description, or severity.
• Click the trash icon to delete an alert.

Note: An alert must be connected to a machine before it can be triggered during simulation. See Section 8.3.

License limit: The maximum number of alerts is determined by your license plan (see Chapter 12).

To assign alerts to machines, see Section 8.3.

7.7 Data Collections

Data Collections define named measurement channels associated with a machine — for example, spindle temperature, hydraulic pressure, vibration level, or cycle time. They represent the data points that MaConSim can publish externally via OPC UA or MQTT during simulation.

Navigate to a plant → Create Resources → Data Collections.

Creating a Data Collection:

1. Click Add Data Collection.
2. Fill in the fields:

3. Click Create.

Editing and Deleting Data Collections:

• Click the pencil icon to edit a data collection’s name, description, data type, or unit.
• Click the trash icon to delete a data collection.

Note: A data collection must be connected to a machine before it is active in simulation output. See Section 8.4. When connected, simulated values for this channel are available via OPC UA and MQTT if connectivity is configured.

License limit: The maximum number of data collections is determined by your license plan (see Chapter 12).

8. Create References

References are the links between resources. Creating a machine is not enough on its own — you must explicitly connect scenarios, alerts, NC codes, tools, and data collections to machines for them to be active during simulation. This design allows the same resource (e.g. an alert type "Overtemperature") to be reused across many machines without duplication.

Navigate to a plant → Create References.

8.1 Connect Scenarios to Machines

A scenario must be connected to a machine before you can run a simulation on that machine. Each machine can have only one scenario connected at a time. To change a machine’s scenario, first remove the existing connection and then connect a different scenario.

Navigate to a plant → Create References → Connect Scenarios.

1. Select a Machine from the dropdown.
2. Select a Scenario from the dropdown.
3. Click Connect.

The connection appears in the list below. Each machine can have only one active scenario connection.

To remove a connection, click the trash icon next to it. Removing a connection does not delete the scenario or the machine.

8.2 Order Queue Management

The order queue is the list of SFCs waiting to be processed by machines. Before production can start on a machine, at least one SFC must be in the QUEUED state.

Navigate to a plant → Create References → Order Queues.

The queue shows orders assigned to each machine-scenario connection. Expand a connection to see its order queue.

To add an order to the queue, select it from the dropdown and click Add Order. To remove an order from the queue, click the trash icon next to it.

Note: Orders can only be added to the queue if they are fully allocated (SFC planned quantities match the order target quantity).

8.3 Connect Alerts

Alert types must be connected to a machine before they can be triggered during simulation. Only connected alert types can fire on that machine. When an alert event occurs, the simulator selects one randomly from all alerts connected to the machine.

Navigate to a plant → Create References → Connect Alerts.

1. Select the Machine from the dropdown.
2. Select the Alert from the second dropdown.
3. Click Connect.

To remove a connection, click the trash icon next to it.

Tip: Connect multiple different alert types to a machine to simulate a realistic mix of event types.

8.4 Connect Data Collections

Data collection channels must be connected to a machine before their values are tracked and published. Only connected channels appear in OPC UA and MQTT output for that machine.

Navigate to a plant → Create References → Connect Data Collections.

1. Select the Machine from the dropdown.
2. Select the Data Collection from the second dropdown.
3. Click Connect.

To remove a connection, click the trash icon next to it.

8.5 Connect NC Codes

NC code types must be connected to a machine before they can be logged during simulation. When a nonconformance event fires, the simulator selects randomly from all NC codes connected to that machine.

Navigate to a plant → Create References → Connect NC Codes.

1. Select the Machine from the dropdown.
2. Select the NC Code from the second dropdown.
3. Click Connect.

To remove a connection, click the trash icon next to it.

Tip: Connect multiple NC codes reflecting different failure modes to get a realistic distribution of nonconformance events.

8.6 Connect Tools

Tools must be connected to a machine before tool usage events can be logged during simulation. Tool Logging must also be enabled in the active scenario. When a tool event fires each takt, the simulator selects randomly from the tools connected to that machine and increments its usage counter.

Navigate to a plant → Create References → Connect Tools.

1. Select the Machine from the dropdown.
2. Select the Tool from the second dropdown.
3. Click Connect.

To remove a connection, click the trash icon next to it.

9. Production Operator Dashboard

The Production Operator Dashboard is the central control and monitoring view during an active simulation. It provides a real-time view of all order processes in the plant, allows starting and stopping production per machine, and displays progress, queue status, and recent events.

Navigate to a plant → Production Operator Dashboard (top tab bar).

License requirement: The Production Operator Dashboard requires the productionOperatorDashboard entitlement.

9.1 Overview

An order process is the combination of a machine running a specific order at runtime. The dashboard is organized into three main sections:

• Summary Cards: Display counts for In Progress, Pending, Recently Completed, and Total Orders
• Running Orders: Currently executing order processes with live progress updates
• Order Queue: Pending order processes waiting to be started
• Recently Completed Orders: The last 5 completed orders with a link to view full history

The dashboard auto-refreshes every second to provide real-time updates on all order processes.

9.2 Running Orders Table

The Running Orders table shows order processes that are currently being executed. Each row displays:

9.3 Order Queue Table

The Order Queue table shows pending order processes that are waiting to be started. Each row displays:

9.4 Filtering

Use the machine filter multi-select dropdown in the header to restrict the view to one or more specific machines. This is useful in large plants with many machines running simultaneously. Filtering does not stop or affect any running simulations — it changes only what is displayed.

9.5 Starting Production

To start a simulation on a machine:

1. Ensure the machine has at least one scenario connected (Section 8.1).
2. Ensure there is at least one order process in the queue for the machine.
3. On the dashboard, click Play (▶) next to the order process in the Order Queue table.
4. The machine status changes to EXECUTE and the progress bar begins advancing with each takt.

Note: If a machine has no simulation connection configured, the dashboard will prevent starting the order.

9.6 Stopping Production

Click Stop (■) next to a running order process in the Running Orders table to stop the simulation. The machine status returns to IDLE. Progress already recorded is retained — you can restart later and production will continue from where it left off.

9.7 Deleting an Order Process

Click the Delete (🗑) button next to a pending order process in the Order Queue table to remove it. You will be prompted to confirm the deletion.

9.8 Expanding an Order

Click the chevron (▶) next to any order row (running or pending) to expand it and see detailed information:

• SFCs: All SFCs associated with this order, showing SFC number, yield quantity vs. planned quantity, unit of measure, last produced timestamp, and status badge
• Alerts: All alert events triggered for this order process, showing alert name, message, occurrence timestamp, severity badge, and acknowledgment status
• NC Codes: All nonconformance events logged for this order process, showing NC code, description, quantity, occurrence timestamp, and severity badge

9.9 Recently Completed Orders

The Recently Completed Orders section shows the last 5 completed orders across all machines in the plant. This provides a quick at-a-glance overview of recent production results. Click View All History to navigate to the Order History page (Section 10.1) for complete historical data.

10. Event Logs

The Event Logs provide a permanent record of all production activity in the plant. Unlike the dashboard (which shows live and recent data), the Event Logs store the full history for the life of the plant and can be used for quality reporting and process analysis.

Navigate to a plant → Event Logs.

The Event Logs section contains three main areas:

• Order History: Complete log of all completed production orders
• Alert History: Record of all alert events with management capabilities
• NC Code Occurrences: Tracking of all nonconformance events

Each log provides detailed views of historical production activity.

10.1 Order History

Navigate to a plant → Event Logs → Order History.

The Order History displays a complete log of all completed production orders with archived SFC snapshots. The main table shows:

Expanded Order Details: Click the chevron (▶) next to any order to expand it and see:

• Summary Cards: Yield percentage, Cycle Time in seconds, Number of SFCs, Good Parts count
• SFC Snapshots at Completion: Detailed table showing each SFC’s state at order completion:
  • SFC Number (with replacement indicator for rework SFCs)
  • Material
  • Status badge
  • Planned quantity
  • Yield quantity
  • Scrap quantity
  • Current step / Total steps
  • Started: Timestamp when this SFC was started
  • Completed: Timestamp when this SFC was completed

Additional Feature:

• Delete individual history entries with confirmation

License requirement: Requires the orderHistory entitlement.

10.2 Alert History

Navigate to a plant → Event Logs → Alert History.

The Alert History shows all alert events triggered during simulation with management capabilities. The main table displays:

Additional Features:

• Record Alert: Click the "Record Alert" button to manually log a new alert occurrence
  • Select Alert type from existing alerts
  • Select Machine
  • Set Severity level
  • Add optional message
• Alert Management Actions:
  • Acknowledge: Mark an unacknowledged alert as acknowledged
  • Clear Alert: Clear an active alert
  • Delete: Remove alert history entry permanently
• Empty state message when no alerts exist
• Error handling with dismissible alerts

Use the alert history to analyze the frequency and distribution of machine alerts over time, validate scenario parameters, and ensure alerts are properly acknowledged and cleared.

License requirement: Requires the alertHistory entitlement.

10.3 NC Code Occurrences

Navigate to a plant → Event Logs → NC Code Occurrences.

The NC Code Occurrences log tracks all nonconformance events with recording capabilities. The main table displays:

Additional Features:

• Record NC Code Occurrence: Click the "Record Occurrence" button to manually log a new nonconformance event
  • Select NC Code from existing codes
  • Select Machine
  • Set Quantity (minimum 1)
  • Add optional comment
• Delete individual occurrence entries with confirmation
• Empty state message when no NC code occurrences exist
• Error handling with dismissible alerts

Use the NC code log to identify which defect types occur most frequently, on which machines, and correlated with which orders — supporting quality analysis and process improvement.

License requirement: Requires the ncCodeHistory entitlement.

11. Connectivity

Navigate to a plant → Connectivity to configure OPC UA and MQTT integrations with external systems.

11.1 OPC UA

MaConSim includes an embedded OPC UA server that can expose machine simulation data to external MES/SCADA/DCS systems.

Navigate to a plant → Connectivity → OPC UA to access the OPC UA Tree Management interface.

11.1.1 Creating an OPC UA Tree

The OPC UA Tree Management interface displays all existing OPC UA trees in a table view with their configuration and security status.

To create a new OPC UA tree:

1. Click Add OPC UA Tree.
2. Configure the tree settings in the dialog:

3. Security Configuration (expandable section):

Security Mode Options:

• None – No security, messages sent in plain text
• Sign – Messages are signed but not encrypted
• SignAndEncrypt – Messages are signed and encrypted (recommended for production)

Security Policy Options:

• None – No cryptographic security
• Basic128Rsa15 – Legacy (DEPRECATED since OPC UA 1.04)
• Basic256 – Legacy (DEPRECATED since OPC UA 1.04)
• Basic256Sha256 – Compatible with older clients
• Aes128Sha256RsaOaep – Modern, good performance (recommended)
• Aes256Sha256RsaPss – Highest security level

User Authentication Options:

• Anonymous – No authentication required
• UserName – Authenticate with username and password
• Certificate – Authenticate with X.509 certificate
• IssuedToken – Authenticate with OAuth/JWT token

4. Click Create to save the tree.

Note: When selecting Certificate authentication, you can upload trusted client certificates (.der, .pem, .crt, or .cer files) and manage the trusted certificate list directly in the tree creation dialog.

11.1.2 OPC UA Tree Management

The OPC UA Tree Management table displays all trees with the following information:

• Tree name and description
• Server address and port (e.g., localhost:4840)
• Security configuration summary
• Creation date
• Available actions

Actions available for each tree:

• Start/Stop Server – Play (▶) button starts the server, Stop (■) button stops it
• Edit – Pencil icon to modify tree configuration
• Export NodeSet2 XML – Download button to export the tree as NodeSet2 XML
• Import NodeSet2 XML – Upload button to import a NodeSet2 XML file
• Copy – Copy button to duplicate the tree with a new name
• Delete – Trash icon to delete the tree (with confirmation)

Starting and Stopping Servers:

• Click Play (▶) on an OPC UA tree to start the server
• Click Stop (■) to stop it
• Server state is indicated by color-coded badges:
  • Yellow "No Security" badge for unsecured servers
  • Green "Encrypted" badge for SignAndEncrypt mode
  • Blue "Signed" badge for Sign mode
• The system prevents starting servers on ports already in use by other running trees
• Success and error messages are displayed temporarily when starting/stopping servers

Editing Trees:

• Click the pencil icon to modify any tree configuration
• Change basic settings, security configuration, or authentication credentials
• For trees with username authentication, you can view current credentials using the "View Current" button

Tree Navigation:

• Click on any tree row to enter the node management view for that tree
• Use the back arrow to return to the tree list

11.1.3 NodeSet2 Import and Export

Import NodeSet2 XML: You can import an OPC UA NodeSet2 XML file to pre-populate the node tree:

1. Click Import NodeSet2 (upload icon) on an OPC UA tree from the tree list
2. Confirm the action (importing will replace the tree’s current nodes and references)
3. Select the .xml file from your file system
4. The import summary will show the number of nodes created, references created, and namespace URIs processed

Export NodeSet2 XML:

1. Click Export NodeSet2 (download icon) on an OPC UA tree from the tree list
2. A save dialog will appear with a suggested filename based on the tree name
3. Choose the destination and save the .xml file
4. A success message will confirm the export location

11.1.4 Certificate Management

When using Sign or SignAndEncrypt security modes, certificates are managed automatically.

Certificate Storage:

• On Windows: C:\Users\{username}\AppData\Roaming\com.maconsim.app\pki\
• Certificate files are stored with extensions: .der, .pem, .crt, or .cer

Managing Trusted Certificates:

1. When creating or editing a tree with Certificate authentication, the X.509 Certificate Authentication section appears
2. Upload Client Certificate:
   • Click the file input or drag-and-drop a certificate file
   • Supported formats: .der, .pem, .crt, .cer
   • Uploaded certificates appear in the Trusted Certificates list
3. Trusted Certificates List:
   • Shows all currently trusted certificate filenames
   • Each certificate can be deleted individually using the trash icon
   • Deleting a certificate removes it from the trusted store

Note: Server certificates are generated automatically when using security modes other than None.

License requirement: OPC UA functionality requires the opcUaServer or opcUaClient entitlement.

11.1.5 OPC UA Node Management

After creating an OPC UA tree, click on it to access the Node Management interface. This displays the tree structure with all nodes and allows you to add, edit, and organize nodes.

Node Management Interface Features:

• Tree View: Hierarchical display of all nodes with expand/collapse controls
• Live Value Display: Variable nodes show their current values with live/static indicators
• Node Type Icons: Objects (purple), Variables (blue), Methods (orange)
• Simulation Badges: Variables with simulation configs show their simulation mode
• Server Controls: Start/Stop server buttons are available in the node view
• Chart Preview: For simulation variables, a live chart button appears for real-time visualization

Tree Navigation:

• Click the chevron icons (▶/▼) to expand or collapse nodes
• Use Expand All and Collapse All buttons to control tree visibility
• Hover over nodes to see additional actions

11.1.5.1 Adding Nodes

To add a root node (for empty trees):

1. Click Add Node button
2. The system automatically selects Object type for root nodes

To add a child node:

1. Navigate to the parent node in the tree
2. Hover over the parent node to reveal the Add Child button
3. Click Add Child or click Add Node for a root-level node

Node Creation Dialog:

1. Select Node Type (required):

   • Object: Container node for hierarchical organization (e.g., machines, subsystems)
   • Variable: Data value node that OPC UA clients can read/subscribe to
   • Method: Executable function node that clients can invoke

2. Basic Node Information:

   • Namespace: Numeric namespace identifier (default: 2)
   • Identifier Type: NodeId identifier type (s=String, i=Numeric, g=GUID, b=ByteString)
   • Identifier: Unique identifier within the namespace (required)
   • Browse Name: Programmatic name used for browsing (required)
   • Display Name: Human-readable name (optional)
   • Description: Optional node description
   • Node Class: OPC UA node class (auto-populated based on type)

3. For Variable Nodes:

   • Data Type: Select from available OPC UA data types (String, Int32, Int64, Float, Double, Boolean, DateTime, ByteString)
   • Access Level: Read, Write, or Read/Write permissions
   • Units: Optional unit of measurement (e.g., °C, bar, rpm)
   • Update Interval: Polling interval in milliseconds (default: 1000ms)

4. For Method Nodes:

   • Executable: Enable/disable method execution
   • User Executable: User-specific execution permissions
   • Method Source: Choose between predefined templates or custom Python script
   • Python Script: For custom methods, write Python functions with typed parameters
   • Method Language: Set to ‘python’ for Python-based methods

11.1.5.2 Data Source Configuration

For Variable nodes, configure the Value Source (data source type):

Data Source Options:

• Static Value: Set a fixed value that remains constant until manually changed
• Database Reference: Automatically sync with a database table field
• Simulation: Dynamically generate values using a simulation configuration

Configuring Static Value:

1. Select Static Value as the Value Source
2. Enter the fixed value in the node’s Current Value field
3. The value will be published at the configured update interval

Configuring Database Reference:

1. Select Database Reference as the Value Source
2. Choose a Table from available database tables
3. Select a Row from the chosen table
4. Choose a Column from the table schema
5. The OPC UA node will automatically update when the database field changes
6. Data types are auto-mapped from SQLite types to OPC UA types:
   • SQLite INTEGER → OPC UA Int32
   • SQLite REAL/FLOAT/DOUBLE → OPC UA Double
   • SQLite BOOLEAN → OPC UA Boolean
   • SQLite BLOB → OPC UA ByteString
   • Other types → OPC UA String

Configuring Simulation:

1. Select Simulation as the Value Source
2. Choose an existing Simulation Configuration from the dropdown, or create a new one
3. Available simulation modes:
   • Sine: Generates sine wave values with configurable amplitude, frequency, and phase
   • Sawtooth: Generates sawtooth wave values
   • Random: Generates random values within specified boundaries
   • Linear: Generates linearly changing values
4. For each mode, configure parameters like min/max values, rate, behavior (wrap/bounce/clamp), etc.
5. Variables with sine, sawtooth, or random simulation modes show a Live Chart button for real-time visualization

11.1.5.3 Method Configuration

Using Method Templates:

1. Select Method as the node type
2. Choose Template as the method source
3. Select from available predefined method templates
4. The form will auto-populate with template details (identifier, browse name, display name, description)

Creating Custom Python Methods:

1. Select Method as the node type
2. Choose Python as the method source
3. Write a Python function with the following requirements:
   • Must be a single function definition
   • Function name becomes the method identifier
   • Parameters are parsed to determine input arguments
   • Return type is detected automatically
4. The system validates the script in real-time and displays:
   • Function signature (name, parameters, return type)
   • Validation errors (if any)
5. Python Runtime:
   • The system checks Python runtime availability automatically
   • Shows runtime version and status information
6. Test Execution:
   • Enter test values for each parameter
   • Click Test Method to execute the function with test inputs
   • View execution results and timing information

11.1.5.4 Node References

Node references define how nodes are linked in the OPC UA address space for browsing and semantic structure.

Available Reference Types:

• Organizes: Hierarchical organization relationship
• HasComponent: Functional component relationship (common for machine parts)
• HasProperty: Property/attribute relationship (common for metadata)
• HasTypeDefinition: Type definition relationship
• HasSubtype: Inheritance relationship
• HasModellingRule: Modelling rule relationship
• HasEncoding: Encoding relationship
• HasDescription: Description relationship
• GeneratesEvent: Event generation relationship

Reference Behavior:

• Hierarchical references (Organizes, HasComponent, HasProperty) create parent-child relationships in the tree view
• Non-hierarchical references describe semantic relationships without affecting tree position
• When adding a child node under a parent, MaConSim automatically creates a HasComponent reference
• References can be customized to reflect your modeling intent

Practical Guidelines:

• Use Object nodes with Organizes or HasComponent to structure systems and subsystems
• Use Variable nodes with HasComponent for operational signals or HasProperty for descriptive attributes
• Use Method nodes with HasComponent when they belong to a specific subsystem

11.1.5.5 Live Value Display and Monitoring

Live Value Indicators:

• Variable nodes display their current values in the tree
• Values are color-coded:
  • Green badge: Live value from running OPC UA server
  • Amber badge: Static value (server not running or value not updated)
• Values are truncated if longer than 8 characters (hover to see full value)
• A activity icon indicates whether the value is live or static

Real-time Polling:

• Node values are polled every second (1000ms) when the server is running
• Live values are read directly from the OPC UA address space
• Static values fall back to the database-stored current value

Chart Preview:

• For simulation variables with supported modes (sine, sawtooth, random), a chart button appears
• Click the Live Chart button to open a real-time visualization
• Chart shows value changes over a configurable time window (default: 60 seconds)

11.1.5.6 Editing and Deleting Nodes

Editing Nodes:

1. Click the pencil icon next to any node to edit its properties
2. Modify any node configuration (type, identifiers, data source, etc.)
3. For database references, changing the table/row/column will update the data source
4. Click Save to apply changes and refresh the tree

Deleting Nodes:

1. Click the trash icon next to any node
2. The node and all its children will be deleted permanently
3. Deletion cannot be undone

11.1.5.7 Typical Use Cases

Expose Machine Status:

1. Add an Object node for the machine
2. Add Variable nodes for each status aspect (Running, Idle, Error)
3. Set data source to Database Reference and link to machine status fields
4. Use Boolean data type for status flags

Publish Sensor Data:

1. Add Object nodes to organize sensors by type or location
2. Add Variable nodes for each sensor reading
3. Set data source to Database Reference and link to data collection channels
4. Configure appropriate data types (Float for temperatures, Int32 for counts, etc.)
5. Set units for better client interpretation

Simulate Dynamic Data:

1. Add Variable nodes for dynamic values
2. Set data source to Simulation
3. Choose simulation mode (sine for oscillating values, random for variable data, etc.)
4. Configure simulation parameters (min/max values, frequency, etc.)
5. Monitor values in real-time using the live chart

Organize Complex Systems:

1. Use Object nodes to create a hierarchical structure matching your plant
2. Group related variables and methods under appropriate parent objects
3. Use meaningful reference types to indicate relationships
4. Set descriptive display names and descriptions for all nodes

Create Custom Actions:

1. Add Method nodes to expose custom functionality
2. Use Python methods for complex logic or calculations
3. Use method templates for predefined common operations
4. Configure input/output arguments as needed
5. Test methods using the built-in test execution feature

11.2 MQTT

MaConSim can publish machine simulation data to MQTT brokers.

Navigate to a plant → Connectivity → MQTT.

11.2.1 Creating a Broker Tree

1. Click Add Broker Tree.
2. Configure:

3. Click Add Broker Tree.

11.2.2 Starting and Stopping a Broker Tree

• Click Play (▶) to start the broker runtime.
• Click Stop (■) to stop it.
• The broker row and detail view show a Running/Stopped state badge.
• In the topic tree view, use the Start Broker/Stop Broker buttons to control the broker state.

11.2.3 Topic Tree and Add Topic Configuration

After creating a broker tree, open it to manage the Broker Topic Tree. Topics are shown as a hierarchical tree derived from slash-separated topic paths, with folder icons for parent nodes and signal-type icons for leaf topics.

You can add topics from:

• The main Add Topic button,
• A folder node (Add Topic under a path prefix),
• A leaf node (Add to create a sibling topic).
• Topics can be organized in a hierarchical folder structure using slash-separated paths.

Add Topic Configuration:

1. Open a broker tree.
2. Click Add Topic.
3. Configure the topic with the following fields:

4. Optionally configure an inline data source directly in the topic dialog using the embedded data source selector.
5. Click Create Topic.

Topic path conventions:

MQTT topic paths are slash-separated strings. A common convention for machine data is:

{plant}/{machine}/{data-channel}

For example:

• factory-berlin/press-1/spindle-temperature
• site-a/cnc-3/vibration-level

Each topic must be a fully specified path. Use path segments to build a clear hierarchy.

Topics can be removed via the topic row action (Delete topic).

11.2.3.1 Live Value Monitoring

MaConSim provides real-time monitoring of MQTT topic values:

• Live Value Polling: Topic values are automatically polled every 2 seconds to show current data
• Visual Indicators: Current field values are displayed in the topic tree as badges showing the field count and values
• Simulation vs Static: Simulation-based values show green indicators, while static/database values show blue indicators
• Multi-field Display: Topics with multiple data sources show the total field count and first field value with a tooltip showing all field values
• Status Badges: Each topic displays its signal type, QoS level, retain status, and enabled/disabled state

11.2.4 Data Source Configuration

Each topic can publish one or more fields, where each field is defined by a data source configuration.

Open Data Source Configuration:

1. In the topic tree, click the database icon on a topic (Configure data sources).
2. The dialog shows existing data sources for that topic in a table format.
3. Add a new source with Add Data Source to open the data source selector.

Data Source fields:

Source Type: Static Value (static)

• Enter the constant Static Value that will be published.
• MaConSim publishes this constant value at the configured topic publish interval.

Source Type: Database Reference (database)

• Select the Table from available database tables.
• Select the specific Row from the chosen table.
• Select the Column containing the data to publish.
• MaConSim resolves and publishes the referenced cell value, updating automatically when the database value changes.

Source Type: Simulation (simulation)

• Select an existing Simulation Configuration from the dropdown.
• If needed, click New Config to create a new simulation configuration.

Create Simulation Config (from MQTT Data Source):

1. In Simulation Configuration, click New Config.
2. Set a name and optional description for the configuration.
3. Choose Simulation Mode (linear, random, sine, sawtooth).
4. Choose Behavior (clamp, wrap, bounce) to control how the simulation handles boundary values.
5. Set mode-specific parameters:

Linear Mode:

• Rate (units/second) *: Constant rate of change (e.g., 1.0 for +1°/s)
• Minimum Value: Lower bound (optional, prevents values below this threshold)
• Maximum Value: Upper bound (optional, prevents values above this threshold)

Random Mode:

• Minimum Value: Lower bound of random range
• Maximum Value: Upper bound of random range
• Noise Factor: Intensity of random fluctuations

Sine Wave Mode:

• Mathematical formula: f(x) = a · sin(b·x + c) + d
• a – Amplitude *: Peak value (maximum deviation from center)
• b – Frequency (Hz) *: Cycles per second (where b = 2π · frequency)
• c – Phase Offset: Phase shift in radians
• d – Vertical Offset *: Center value (baseline around which the wave oscillates)

Sawtooth Mode:

• Frequency (Hz) *: Cycles per second
• Minimum Value: Lower bound of the sawtooth wave
• Maximum Value: Upper bound of the sawtooth wave
• Phase Offset: Phase shift in radians

6. Save the config and select it for the data source.

You can attach multiple data sources to one topic. The topic payload is built from all configured field mappings.

12. License Plan Feature Matrix

The following table shows the features available per plan. For the latest pricing and plan details, visit the MaConSim website:

https://maconsim.com/licenses-pricing/

Exact limits are embedded in your license key and enforced automatically. Plan details on the website are always up to date.

13. REST API

MaConSim provides a REST API in its Docker version only that exposes all frontend functionality for programmatic access. This allows you to integrate MaConSim into test automation frameworks, CI/CD pipelines, or external MES/SCADA systems.

Important: The REST API is only available when running MaConSim via Docker. It is not accessible in the Windows, macOS, or Linux desktop versions.

Key characteristics:

• Local access only: The REST API is designed for local clients only. No authentication is required as the API is not intended to be exposed to the internet.
• Complete coverage: Every interaction available in the MaConSim frontend is also available through the REST API.
• Automatic documentation: Full API documentation with interactive testing is available via Swagger UI.

Use cases:

• Automated testing of MES functionalities that require a machine simulation environment
• CI/CD pipeline integration for automatic testing before updates (MES, SCADA, or other IoT systems)
• Custom integrations with external systems
• Batch operations and automation scripts

13.1 Accessing the API

Swagger UI (Recommended): Open http://localhost:8080/swagger-ui#/ in your browser to explore all available endpoints interactively. Swagger UI provides:

• Complete list of all endpoints
• Detailed parameter documentation
• Try-it-out functionality
• Request/response examples

OpenAPI Specification: Download the machine-readable specification at /api-docs/openapi.json. This can be used for:

• API client code generation
• Integration with API documentation tools
• Automated testing frameworks

Base URL: Docker deployment: http://localhost:8080

13.2 Usage Notes

Request Format: All endpoints use HTTP POST with a JSON request body.

Example request:

curl -X POST http://localhost:8080/api/get_plants \
  -H "Content-Type: application/json" \
  -d '{}'

Response Format:

• Success: JSON with result data
• Error: JSON with error message and HTTP error code

CORS: Cross-Origin Resource Sharing is configured to allow requests from any origin, making it easy to integrate from any local application.

Example: Export a Plant via API

# Export plant with ID 1
curl -X POST http://localhost:8080/api/export_plant_yaml \
  -H "Content-Type: application/json" \
  -d '{"plant_id": 1}' \
  --output plant-export.yaml

14. Updating MaConSim

MaConSim provides built-in functionality to check for and download new versions of the application.

14.1 Checking for Updates

1. Click the Updates button in the top navigation bar (header section)
2. MaConSim contacts the update server (https://api.maconsim.com/api/latest-version) to check if a newer version is available
3. If your current version is up-to-date, a confirmation message appears briefly
4. If a newer version is available, a notification banner appears displaying:
   • The available version number
   • Your current version number
   • A Download update button

Automatic checks: MaConSim automatically checks for updates once per session, approximately 3 seconds after you log in.

14.2 Downloading and Installing Updates

1. When an update is available, click Download update in the notification banner

2. The update installer is downloaded to your Downloads folder and automatically opened:

   • Windows: The EXE installer typically runs automatically; if it doesn’t, navigate to your Downloads folder and run the installer manually
   • macOS: The DMG file is mounted automatically
   • Linux: The AppImage or .deb package is opened with your system’s default handler

3. Follow the installer prompts to complete the installation:

   • The installer will typically offer to remove the previous version
   • Your existing configuration and plant data are preserved in the database

4. After installation completes, launch MaConSim as you normally would

Note: The update process is the same across all platforms — download the new installer from within the app, then run it to upgrade.

14.3 Recommended Backup Before Updating

Before updating, it is strongly recommended to create backups:

1. Export all plants using the Plant Export feature (Section 6.4)
2. Export OPC UA NodeSet2 XML files for any OPC UA trees you’ve configured (Section 11.1.3)
3. Backup your database file manually (optional but recommended):
   • Copy MaConSim.db from its location (see Section 2 for paths)

Why backup? While updates are designed to preserve your data, having backups ensures you can restore your configuration if any issues occur during the update process.

14.4 Troubleshooting Update Issues

If the application fails to start after updating:

1. First try: Simply restart MaConSim — the database is typically preserved during normal updates

2. If problems persist, you may need to reset the database:

   • Close MaConSim completely
   • Navigate to the database file location for your OS (Section 2):
     • Windows: C:\Users\{username}\AppData\Roaming\com.maconsim.app\MaConSim.db
     • macOS: ~/Library/Application Support/com.maconsim.app/MaConSim.db
     • Linux: ~/.local/share/com.maconsim.app/MaConSim.db
   • Rename the file to MaConSim.db.bak (this preserves it as a backup)
   • Launch MaConSim — a fresh database will be created
   • You will need to:
     • Reactivate your license (have your license key ready)
     • Create a new user account (Section 5.3)
     • Re-import your exported plants (Section 6.5)
     • Re-import your OPC UA NodeSet2 files if applicable

Important: Deleting the database file will permanently remove any data that was not exported. The Plant Export feature (Section 6.4) is the recommended way to back up your data.

If the update button doesn’t appear or doesn’t work:

• Verify your internet connection is active
• Check that outbound HTTPS connections to api.maconsim.com on port 443 are not blocked by your firewall
• The update server might be temporarily unavailable — try again later

15. Troubleshooting

Application shows "License validation failed" on startup

• No internet connection: The license server must be reachable at startup. Check your network and try restarting MaConSim.
• Firewall blocking outbound connection: Ensure MaConSim is allowed to make outbound HTTPS connections through your firewall.
• License expired: Contact MaConSim GmbH to renew your subscription.
• License recently renewed or transferred: Click Re-activate on the error screen, enter your updated license key, and try again.

"Import Plant" button is greyed out

The Plant Import feature requires the importPlant entitlement, which is not included in the Free Trial. Contact MaConSim GmbH to upgrade to a Basic or Premium plan.

A button shows "Limit reached"

You have reached the maximum number of that resource type allowed by your plan. Options:

• Delete unused items of that type to free up capacity.
• Contact MaConSim GmbH to upgrade your plan.

See Chapter 12 for the limits per plan.

Simulation does not start when clicking Play

Ensure the following prerequisites are met:

• The machine has at least one scenario connected (Section 8.1).
• There is at least one SFC in the queue for the order (Section 8.2).
• The machine is not already in a RUNNING state for another order process.

Produced parts count does not increase

• Verify the Takt Time in the scenario is not set too high (e.g. milliseconds vs. minutes: 3,600,000 ms = 1 hour).
• Check that the machine is in RUNNING state and not stuck in MAINTENANCE or ERROR.
• The takt time is always in milliseconds: 60,000 = 1 minute, 3,600,000 = 1 hour.

Alerts, NC codes, or tools are not appearing in simulation output

Resources must be explicitly connected to the machine:

• Alerts → Section 8.3
• NC Codes → Section 8.5
• Tools → Section 8.6 (also requires Tool Logging to be enabled in the active scenario)

OPC UA server fails to start

• No OPC UA nodes created: The OPC UA tree must contain at least one node before the server can start. Navigate to Connectivity → OPC UA, select your tree, and add nodes using the Add Node button (Section 11.1.5.1).
• Port in use: Another application (or another OPC UA tree in MaConSim) is already using the configured port. Change the port number in the OPC UA tree configuration.
• Firewall blocking the port: Ensure the configured port (default 4840) is allowed through Windows Firewall. Add an inbound rule for the port in Windows Defender Firewall settings.
• Certificate error (Sign/SignAndEncrypt mode): Try stopping the server, deleting the PKI directory, and restarting. MaConSim will regenerate the certificates.

MQTT broker connection fails

• Wrong host or port: Verify the broker hostname/IP and port exactly match your MQTT broker’s configuration.
• Authentication: If your broker requires credentials, check that the username and password are entered correctly (case-sensitive).
• TLS misconfiguration: Try disabling TLS first to isolate the issue. If TLS is required, ensure the broker’s certificate is valid.
• Broker not running: Verify the MQTT broker is running and accessible from the MaConSim machine, e.g. using an MQTT client tool such as MQTT Explorer.
• Firewall: Check that the configured port (default 1883, or 8883 for TLS) is not blocked.

Docker deployment issues

Database error on startup

The database file may be corrupted. To reset it:

1. Close MaConSim completely.
2. Navigate to the database file:
   • Windows: C:\Users\{username}\AppData\Roaming\com.maconsim.app\MaConSim.db
   • macOS: ~/Library/Application Support/com.maconsim.app/MaConSim.db
   • Linux: ~/.local/share/com.maconsim.app/MaConSim.db
3. Rename the file to MaConSim.db.bak as a backup.
4. Relaunch MaConSim. A fresh, empty database is created automatically.
5. Re-import any plants you previously exported (Section 6.5).

Warning: Deleting or replacing the database permanently removes all plant data that was not exported. Back up your plant data regularly using the Plant Export feature (Section 6.4).

16. Help and Support

16.1 Opening the User Manual

A Help button is available in the header section of the application, indicated by a question mark icon. Clicking this button opens the MaConSim User Manual in your default web browser, providing quick access to complete documentation for all application features.

16.2 Reporting a Bug or Contacting Support

A Support button is available in the header section of the application, indicated by a lifebuoy icon. This button allows you to report bugs or contact support directly from within the application.

To report a bug or contact support:

1. Click the Support button in the header
2. A dialog appears with the following fields:

3. Fill in the required information and click Submit
4. A confirmation message appears when your ticket has been successfully submitted

Requirements: An active license and an internet connection are required to submit a support ticket.

© 2026 MaConSim GmbH. All rights reserved. Public documentation for MaConSim users.