User Manual

Version 1.3.0

Last updated: September 24, 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 Materials
   • 7.4 Orders and Shop Floor Control (SFC)
   • 7.4.1 Understanding Orders and SFCs
   • 7.4.2 Orders
   • 7.4.3 Shop Floor Control (SFC)
   • 7.5 Nonconformance Codes (NC Codes)
   • 7.6 Tools
   • 7.7 Alerts
   • 7.8 Data Collections
8. Create References
   • 8.1 Connect Scenarios to Machines
   • 8.2 Load Order to Machine
   • 8.3 Add Alerts to Machine
   • 8.4 Add Data Collections to Machine
   • 8.5 Add NC Codes to Machine
   • 8.6 Add Tools to Machine
   • 8.7 Connect Alerts to NC Codes
9. Advanced Database Features
   • 9.1 Database Triggers
   • 9.2 Custom Variables
10. Production Operator Dashboard
    • 10.1 Overview
    • 10.2 Running Orders Table
    • 10.3 Order Queue Table
    • 10.4 Filtering
    • 10.5 Starting Production
    • 10.6 Stopping Production
    • 10.7 Deleting an Order Process
    • 10.8 Expanding an Order
    • 10.9 Recently Completed Orders
11. Event Logs
    • 11.1 Order History
    • 11.2 Alert History
    • 11.3 NC Code Occurrences
    • 11.4 Tool Usage Log
12. Connectivity
    • 12.1 OPC UA
    • 12.1.1 Creating an OPC UA Tree
    • 12.1.2 OPC UA Tree Management
    • 12.1.3 NodeSet2 Import and Export
    • 12.1.4 Certificate Management
    • 12.1.5 OPC UA Node Management
    • 12.1.5.1 Adding Nodes
    • 12.1.5.2 Data Source Configuration
    • 12.1.5.3 Method Configuration
    • 12.1.5.4 Node References
    • 12.1.5.5 Live Value Display and Monitoring
    • 12.1.5.6 Editing and Deleting Nodes
    • 12.1.5.7 Typical Use Cases
    • 12.2 MQTT
    • 12.2.1 Creating a Broker Tree
    • 12.2.2 Starting and Stopping a Broker Tree
    • 12.2.3 Topic Tree and Add Topic Configuration
    • 12.2.3.1 Live Value Monitoring
    • 12.2.4 Data Source Configuration
13. Data Source Configuration
    • 13.1 Overview
    • 13.2 Data Source Types
    • 13.3 Database Reference Configuration
    • 13.3.1 Table and Column Selection (UI Position 1)
    • 13.3.2 JOIN Configuration (UI Position 2)
    • 13.3.3 Preview Rows of Tables (UI Position 3)
    • 13.3.4 Filter Conditions (UI Position 4)
    • 13.3.5 Sorting, Limit & Aggregation (UI Position 5)
    • 13.3.6 Formatting Options (UI Position 6)
    • 13.3.7 Live Preview (UI Position 7)
14. License Plan Feature Matrix
15. REST API
    • 15.1 Accessing the API
    • 15.2 Usage Notes
16. Updating MaConSim
    • 16.1 Checking for Updates
    • 16.2 Downloading and Installing Updates
    • 16.3 Recommended Backup Before Updating
    • 16.4 Troubleshooting Update Issues
17. Troubleshooting
18. Help and Support
    • 18.1 Opening the User Manual
    • 18.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.4
7. Queue SFCs — Section 8.2
8. Start production on the dashboard — Chapter 10

Optionally, enrich the simulation by adding alerts, NC codes, tools, and data collections (Sections 7.5–7.8) 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 17 (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 button 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 X 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
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.
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 14). 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 14).

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 Edit button on a plant card to edit its name, info, description, or location.
• Click the Delete button 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 button 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 (name, info, description, location)
• All machines
• All simulation scenarios (machine sims)
• Machine-scenario connections
• Nonconformance codes (NC codes) and machine assignments
• Tools and machine assignments
• Alerts and machine assignments
• Alert-NC code connections
• Data collections and machine assignments
• Orders
• SFCs (Shop Floor Collections)
• Materials
• OPC UA server configurations
• MQTT broker configurations and topics
• Trigger metadata (global triggers for the user)
• Custom variables

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 12.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 14).

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 Edit button on a machine entry to edit any of its fields.
• Click the Copy button on a machine entry to duplicate it with a new name.
• Click the Delete button 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 14).

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 Edit button on a scenario entry to edit its parameters. Changes take effect from the next takt.
• Click the Copy button on a scenario entry to duplicate it with a new name.
• Click the Delete button 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 14).

7.3 Materials

Materials define the raw materials, components, or products that flow through your production process. They serve as master data that can be referenced by orders and Shop Floor Control (SFC) units, enabling consistent material tracking across your plant.

Navigate to a plant → Create Resources → Materials.

Creating a Material:

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

3. Click Create Material.

The new material appears in the list, sorted alphabetically by material number.

Editing and Deleting Materials:

• Click the Edit button on a material entry to modify any of its fields.
• Click the Delete button to delete a material.

Warning: A material cannot be deleted if it is referenced by an existing order or SFC. You must first remove all references to the material before deletion.

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

7.4 Orders and Shop Floor Control (SFC)

7.4.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.4.2 Orders

Navigate to a plant → Create Resources → Orders. Click the View button 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 Edit button to edit an order’s name, info, unit, or target quantity.
• Click the Delete button to delete an order. All SFCs belonging to this order are also deleted.

Copying Orders:

• Click the Copy button 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 14).

7.4.3 Shop Floor Control (SFC)

Navigate to a plant → Create Resources → SFCs (or click the View button 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 Delete button
• 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.5 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 14).

7.6 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 Edit button to edit a tool’s name, description, usage count, or count mode.
• Click the Delete button 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 14).

7.7 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 Edit button to edit an alert’s name, description, or severity.
• Click the Delete button 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 14).

To assign alerts to machines, see Section 8.3.

7.8 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 Edit button to edit a data collection’s name, description, data type, or unit.
• Click the Delete button 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 14).

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 Delete button next to it. Removing a connection does not delete the scenario or the machine.

8.2 Load Order to Machine

Assign orders to a specific machine’s production queue. Queuing an order does not require a scenario to be connected — a machine without a scenario simply stays stopped until one is assigned in the Connect Scenarios tab.

Navigate to a plant → Create References → Load Order to Machine.

1. Select a Machine from the dropdown. Each machine shows its connected scenario (if any) or a "no scenario" warning.
2. The selected machine card displays its current scenario connection status.
3. To add an order:
   • Select an Order from the dropdown (only fully allocated orders are available)
   • Click Add
4. To remove an order, click the Delete button next to it.

Production Queue: The collapsible Production Queue section shows all queued orders with their position in the queue. The first order is highlighted with an "Up Next" badge, indicating it will be processed next.

SFC Production Queue: The collapsible SFC Production Queue section shows all queued SFCs for the selected machine. The first SFC is highlighted with an "In Process" badge.

Note: Orders can only be added to the queue if they are fully allocated (SFC planned quantities match the order target quantity). If an order has incomplete SFC allocation, it will be disabled in the dropdown with a message showing the current allocation vs. target.

8.3 Add Alerts to Machine

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 → Add Alerts to Machine.

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

To remove a connection, click the Delete button next to it.

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

8.4 Add Data Collections to Machine

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 → Add Data Collections to Machine.

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 Delete button next to it.

8.5 Add NC Codes to Machine

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 → Add NC Codes to Machine.

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 Delete button next to it.

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

8.6 Add Tools to Machine

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 → Add Tools to Machine.

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

To remove a connection, click the Delete button next to it.

8.7 Connect Alerts to NC Codes

Link alerts to nonconformance codes so that whenever an alert is active during production, each connected NC code is automatically recorded with the specified quantity.

Navigate to a plant → Create References → Alert–NC Code Connections.

1. Select an Alert from the dropdown.
2. Check the NC Codes you want to connect (use Select All or Clear for quick selection).
3. Click Connect. If connecting multiple codes, a progress bar shows the completion status.

The active connections list displays all alert–NC code links, grouped by alert. Each entry shows the NC code, description, severity, and the configured quantity.

To remove a connection, click the Delete button next to it. This only removes the link, not the alert or NC code themselves.

Tip: Connect alerts to relevant NC codes to simulate realistic quality issues when specific alert conditions occur during production.

9. Advanced Database Features

The Advanced Database Features provide powerful tools for extending MaConSim’s data model and automating database operations. These features allow you to add custom data fields to entities and create automated responses to database changes.

Navigate to a plant → Advanced Database Features (top tab bar).

License requirement: Advanced Database Features require the appropriate database entitlement.

9.1 Database Triggers

Database triggers allow you to automatically execute SQL statements in response to specific database events such as INSERT, UPDATE, or DELETE operations on a table. This enables powerful automation without requiring external integration.

Key capabilities:

• Create and manage triggers: Define triggers with custom SQL that executes automatically when specified events occur
• SQL validation: Built-in validation ensures your trigger SQL is syntactically correct before saving
• Dialect support: Automatic adaptation for SQLite and PostgreSQL database syntax
• Target table selection: Associate triggers with specific tables from the available MaConSim data model
• Active/Inactive status: Enable or disable triggers without deleting them
• Example templates: Pre-configured SQL examples for common use cases on different tables

Common use cases:

• Automatically update related records when data changes (e.g., update machine status when an SFC completes)
• Enforce business rules and data validation beyond standard constraints
• Log changes to critical data for audit purposes
• Cascade updates across related tables

To create a database trigger:

1. Navigate to Advanced Database Features → Database Triggers (Global)
2. Click Create Trigger
3. Enter a Name and optional Description
4. Select the Target Table from the dropdown
5. Write or paste your trigger SQL in the editor
6. Click Validate SQL to check for syntax errors
7. Toggle Active to enable the trigger (enabled by default)
8. Click Save

The trigger editor provides:

• Example SQL: Load pre-configured examples for the selected table type
• Table browser: Preview actual table data and schema to help write accurate SQL
• Validation feedback: Clear error messages for SQL syntax issues
• Duplicate detection: Warning if a trigger with the same name already exists

9.2 Custom Variables

Custom Variables allow you to add custom data fields to MaConSim entities, extending the standard data model without modifying the core database schema. These fields can store additional information specific to your use case or organization.

Key capabilities:

• Flexible field types: Support for Text, Integer, Numeric, and Boolean data types
• Entity association: Attach custom fields to various entity types including Plants, Machines, Orders, Materials, Alerts, Data Collections, and NC Codes
• Global or scoped: Create global variables or scope them to specific entities
• Validation: Automatic validation based on the selected data type
• Search and filter: Quickly find custom variables by name or entity type

Common use cases:

• Add organization-specific metadata to machines (e.g., maintenance schedules, location codes)
• Extend order data with custom tracking fields (e.g., customer reference numbers, priority codes)
• Store additional material properties not covered by standard fields
• Track custom configuration parameters for alerts or data collections

To create a custom variable:

1. Navigate to Advanced Database Features → Custom Variables
2. Click Create Custom Variable
3. Select the Entity Type (e.g., Machine, Order, Plant, Global)
4. Enter the Field Name (must be unique within the entity scope)
5. Select the Value Type (Text, Integer, Numeric, or Boolean)
6. Enter the Field Value (must match the selected type)
7. Add an optional Description to document the field’s purpose
8. Click Save

The custom variable editor provides:

• Type-specific validation: Prevents invalid values (e.g., non-numeric input for Numeric type)
• Duplicate detection: Ensures field names are unique within their entity scope
• Entity filtering: View variables by specific entity type
• Search functionality: Quickly locate variables by name

10. 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.

10.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.

10.2 Running Orders Table

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

10.3 Order Queue Table

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

10.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.

10.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.

10.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.

10.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.

10.8 Expanding an Order

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

• 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. The panel header displays a count overview (e.g., total: 11 / acknowledged: 0 / active: 11). You can acknowledge individual alerts by clicking the checkmark button, and clear them by clicking the X button. Acknowledged alerts show an "Ack" badge, while unacknowledged alerts show "Unack"
• NC Codes: All nonconformance events logged for this order process, showing NC code, description, quantity, occurrence timestamp, and severity badge

10.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 11.1) for complete historical data.

11. 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.

11.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.

11.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.

11.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.4 Tool Usage Log

Navigate to a plant → Event Logs → Tool Usage Log.

The Tool Usage Log tracks all tool usage events across machines with manual recording capabilities. The main table displays:

Additional Features:

• Record Tool Usage: Click the "Record Usage" button to manually log a new tool usage event
  • Select Tool from existing tools
  • Select Machine from existing machines
  • Set Quantity (minimum 1)
  • Add optional comment
• Delete individual tool usage entries with confirmation
• Empty state message when no tool usage entries exist
• Error handling with dismissible alerts

Use the tool usage log to track tool consumption, maintenance schedules, and correlate tool wear with quality issues.

12. Connectivity

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

12.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.

12.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):

UI Behavior Notes:

• User Authentication uses single-selection radio buttons — only one authentication method can be active at a time
• Security Policy dropdown automatically appears when Security Mode is set to Sign or SignAndEncrypt
• When Security Mode is changed to None, the Security Policy automatically resets to None
• For existing trees with Username authentication, a "View Current" button allows viewing stored credentials

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.

12.1.2 OPC UA Tree Management

Important: Any changes to OPC UA tree configurations or nodes require the server to be stopped first. Before editing a tree configuration, adding, editing, or deleting nodes: stop the server using the Stop button, make your changes, then restart the server using the Play button for the changes to take effect.

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

Table Features:

• Click any tree row to enter its Node Management view
• Hover over security badges to see the security mode details
• User token types are displayed directly in the table for quick reference

Actions available for each tree (6 action buttons):

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
• Port Conflict Detection: The system automatically checks if the port is already in use by another running server and prevents starting with an error message showing which tree is using the port
• Success and error messages are displayed temporarily when starting/stopping servers

Editing Trees:

• Click the Edit button 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

12.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 button 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 button 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

12.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: When creating or editing a tree with Certificate authentication, the X.509 Certificate Authentication section appears with the following features:

1. Upload Client Certificate:

   • Click the file input or drag-and-drop a certificate file
   • Supported formats: .der, .pem, .crt, .cer
   • Invalid file types trigger an error message
   • Uploaded certificates appear in the Trusted Certificates list
   • A loading spinner indicates upload progress

2. Trusted Certificates List:

   • Displays all currently trusted certificate filenames in a scrollable list
   • Each certificate filename is shown in monospace font for clarity
   • Each certificate can be deleted individually using the Delete button
   • Deleting a certificate removes it from the trusted store
   • The list updates automatically after upload or deletion

UI Indicators:

• Loading state shown while certificates are being loaded
• Success messages confirm successful uploads and deletions

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

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

12.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 Indicators: Objects (📦), Variables (🔢), Methods (⚙️), Views (👁️) with color coding
• 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

View Switcher Tabs: MaConSim provides two different views for managing OPC UA nodes:

When to use each view:

• Instances: For creating your actual production data model (machines, sensors, status variables, etc.)
• Type Definitions: For creating custom types that can be reused across multiple instances (e.g., a "MachineType" that defines a standard machine structure)

Tree Navigation:

• Click the chevron buttons (▶️/▼) to expand or collapse individual nodes
• Use Expand All and Collapse All buttons to control tree visibility for the entire hierarchy
• Hover over nodes to see additional actions (Add Child, Edit, Delete, etc.)
• Node icons help identify node types at a glance

12.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
   • View: Visual organization node for grouping related nodes in the address space

2. Basic Node Information:

   • Namespace: Numeric namespace identifier (default: 2)
   • Identifier Type: NodeId identifier type. Available options:

   Type	Label	Description
   s	String	String identifier (e.g., MyNode) — default
   i	Numeric	Numeric identifier (e.g., 12345)
   g	GUID	GUID identifier (e.g., {6B29308F-...})
   b	ByteString	ByteString identifier (Base64 encoded)

   • 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 Python Script or Low-Code Flow to define the method logic
   • Method Language: Set to ‘python’ for Python-based methods
   • See Method Configuration below for detailed instructions on creating method nodes

12.1.5.2 Data Source Configuration

For detailed instructions on data source configuration, see Section 13. The same data source types and configuration options are available for both OPC UA and MQTT connectivity.

12.1.5.3 Method Configuration

Method Source Options:

When creating a Method node, you must choose how the method logic is defined:

• Python Script: Write method logic using Python code. Full flexibility with access to allowed standard library modules and system capabilities via host.call().
• Low-Code Flow: Define method logic visually by connecting capability calls and data transformations on a canvas. No coding required.

Python Runtime Requirements:

Method nodes (both Python Script and Low-Code Flow) require Python 3.x to be installed and available on your system:

• The Python executable must be in your system PATH or configured via the MES_PYTHON environment variable
• MaConSim automatically checks Python availability when opening the node form

If Python is not available:

• Both Python Script and Low-Code Flow method sources are disabled
• An alert message explains the issue and provides resolution hints
• Existing Python methods can still be edited (but not validated or tested)

If Python is available:

• Runtime version information is displayed
• All method source options are enabled

Creating Python Script Methods:

1. Select Method as the node type
2. Choose Python Script as the method source
3. Write your method logic in the script editor

Function Requirements:

• Define a single Python function
• Use type hints for parameters and return value
• Supported parameter types: int, float, str, bool
• Supported return types: int, float, str, bool, tuple[…]
• Function name is used as the method identifier (auto-fills browse name and display name)

Example:

def calculate_area(radius: float) -> float:
    import math
    return math.pi * radius ** 2

Real-time Validation: As you type, the system validates your script (with a short delay to avoid excessive checking):

• Valid scripts show a green confirmation with parsed signature
• Invalid scripts show red error messages
• Validation errors auto-dismiss after 5 seconds
• Function signature (name, parameters, return type) is extracted and displayed

Quick Examples: Jumpstart your method development with pre-built examples:

• Circle area calculation (uses math module)
• Get machine by id (uses host.call to query database)
• Add order to machine (uses host.call to modify simulation state)
• Set machine status (uses host.call to control machine state)

Click any example to insert its code into the editor automatically.

Capability Palette: Browse and insert system capabilities directly into your script:

1. Click Capabilities to expand the palette
2. Browse available host.call() capabilities
3. Click a capability to insert a code snippet at your cursor position

This provides easy access to system functions like database queries, machine control, and simulation state modifications.

Available OPC UA Nodes Browser: Discover existing OPC UA nodes to reference in your method:

1. Click Available OPC UA Nodes to expand
2. Select a tree from the dropdown (current tree or sibling trees)
3. Browse the node table showing ID, Name, Type, and Node Identifier
4. Use the displayed Node Identifier (e.g., ns=2;s=Temperature) to reference nodes in your capability calls

Available Database Tables Browser: Preview database table contents to understand data structure:

1. Click Available Database Tables to expand
2. Select a table from the dropdown
3. View table rows in a preview grid
4. Reference table names, column names, and values in your method logic

Allowed Python Modules: The following standard library modules are available for import:

• math, datetime, json, re, itertools, functools, decimal, fractions, statistics, random

Test Execution: Verify your method works before saving:

1. Enter test values for each parameter (input fields match the parameter types)
2. Click Run Test
3. View results including:
   • Success/failure indicator
   • Execution time in milliseconds
   • Output values with their types
4. Errors are displayed with helpful messages
5. Test results auto-dismiss after 5 seconds

Creating Low-Code Flow Methods:

1. Select Method as the node type
2. Choose Low-Code Flow as the method source
3. Define your method’s inputs and outputs
4. Build the logic on the flow canvas

Defining Inputs:

1. Each input has a name and type (int, float, str, bool)
2. Click Add Input to add more parameters
3. Click the trash icon to remove an input

Defining Outputs:

1. Each output has a name and type (int, float, str, bool)
2. At least one output is required (default: "result" of type bool)
3. Click Add Output to add more return values
4. Click the trash icon to remove an output (cannot remove the last one)

Flow Node Types:

Every low-code flow consists of nodes connected together. Each flow must start with a Start node (automatically created with your method’s input parameters) and must end with a Return node (which defines the output values).

Available node types (accessed via the Add step button on any node):

• Start: The entry point of your flow. Automatically created based on your method’s input parameters. Each input appears as a data source handle that can be wired to other nodes.

• Capability Call: Invokes a system capability (function). Select from available capabilities, provide arguments (literals or variable references), and optionally name an output variable to store the result.

• Branch (if / else): Implements conditional logic. Define a condition using comparison operators (==, !=, <, <=, >, >=) or logical operators (and, or, not), then specify different step sequences for the then (true) and else (false) branches.

• For Each: Iterates over a list. Provide a list (literal or variable reference) and a variable name for the current item, then define the loop body steps that execute for each item.

• Set Variable: Creates or updates a named variable. Specify a variable name and a value (literal or reference to another variable/output). The variable can be used by subsequent nodes.

• Return: The exit point of your flow. Map each of your method’s output parameters to a value (literal or variable reference). Required — flows without a Return node are invalid.

Creating Connections:

1. Drag from an output handle (right side of a node) to an input handle (left side of another node)
2. Or use the dropdown next to each input field to select a variable/value
3. The canvas validates that all required inputs are wired

Testing Flow Methods:

1. Define test values for inputs (if any)
2. The flow is automatically validated when you save
3. Invalid flows show error messages (e.g., unwired inputs, missing Return step)

Tip: The flow canvas is ideal for users who prefer visual programming over writing code. It provides the same functionality as Python scripts but with a more intuitive interface.

Testing Methods Without Starting a Server:

You can test method nodes directly without starting an OPC UA server:

1. In the OPC UA Node Management tree view, find your method node
2. Click the Play button (Play icon) next to the method node
3. The "Test Call Method" dialog opens

Using Test Call Method:

1. Input fields are automatically populated based on the method’s parameter definitions
2. Enter values for each input argument
3. Click Call to execute the method in-process
4. View results including:
   • Success/failure indicator
   • Execution time
   • Output values with their types

Note: This feature allows rapid testing during development without requiring an OPC UA client connection or running server. It uses the same Python runtime and method logic that would be invoked by an OPC UA client.

12.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

12.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)
• An indicator shows whether the value is live or static

Real-time Value Updates:

• The UI updates node values every second to display current data
• Live values are read directly from the running OPC UA server’s address space
• When the server is stopped, values fall back to the database-stored current value
• Database-referenced and simulation nodes update automatically when their source data changes

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)

12.1.5.6 Editing and Deleting Nodes

Editing Nodes:

1. Click the Edit button 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 Delete button next to any node
2. The node and all its children will be deleted permanently
3. Deletion cannot be undone

12.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

12.2 MQTT

MaConSim can publish machine simulation data to MQTT brokers.

Navigate to a plant → Connectivity → MQTT.

12.2.1 Creating a Broker Tree

1. Click Add Broker Tree.
2. Configure:

3. Click Add Broker Tree.

12.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.

12.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 indicators for parent nodes and signal-type indicators 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).

12.2.3.1 Live Value Monitoring

MaConSim provides real-time monitoring of MQTT topic values:

• Live Value Updates: The UI updates topic values every 2 seconds to display 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

12.2.4 Data Source Configuration

For detailed instructions on configuring data sources, see Section 13. This section applies to both OPC UA and MQTT connectivity.

13. Data Source Configuration

The Data Source Configuration system provides the foundation for connecting MaConSim simulation data to external systems via OPC UA and MQTT. This chapter documents the shared configuration options available for both connectivity types, with a focus on the comprehensive Database Reference capabilities including JOIN functionality.

Note: The same data source types and configuration options are available for both OPC UA Variable nodes (Section 12.1.5.2) and MQTT topics (Section 12.2.4).

13.1 Overview

Data sources define where the values for OPC UA variables or MQTT topic fields come from. MaConSim supports three fundamental data source types:

• Static Value: Fixed values that remain constant until manually changed
• Database Reference: Dynamic values linked to real-time data from the MaConSim database
• Simulation: Dynamically generated values using various simulation modes (sine, random, etc.)

The Database Reference type offers the most flexibility and power, allowing you to create complex queries with JOINs, filters, sorting, and aggregation to extract exactly the data you need from your plant database.

13.2 Data Source Types

For Variable nodes in OPC UA, the data source type is configured via the Value Source dropdown. For MQTT topics, each field within a topic has its own Source Type configuration.

13.3 Database Reference Configuration

The Database Reference configuration provides a visual query builder that allows you to create sophisticated database queries without writing SQL manually. The configuration interface is organized in a specific order that follows the natural flow of building a query.

13.3.1 Table and Column Selection (UI Position 1)

The first step in building a database reference query is selecting the source data.

Table Selection:

• Choose from all available database tables in the Table dropdown

Column Selection:

• After selecting a table, choose a specific column from the Column dropdown
• Each column entry displays the column name and its data type (e.g., machine_name (String))
• Only columns from the selected table are available

13.3.2 JOIN Configuration (UI Position 2)

The JOIN Configuration allows you to combine data from multiple tables to create comprehensive queries that span across different entities in your plant.

Adding JOINs:

1. Expand the JOINs section by clicking the JOINs button
2. Click Add JOIN to add your first join condition
3. Up to 4 JOINs can be configured per query

JOIN Types:

ON Condition Builder: The visual builder provides an intuitive interface for creating JOIN conditions:

1. Left Table/Column: Select the column from your primary or previously joined table
2. Operator: Choose the comparison operator (typically = for JOINs)
3. Right Table/Column: Select the column from the table you are joining

The builder uses dropdowns for table and column selection, ensuring only valid combinations are available.

Table Aliases:

• Optionally assign a short alias to each joined table
• Aliases make queries more readable and manageable
• When configured, column references in the query will use the format alias.column instead of table.column
• Example: Join the orders table with alias o → columns become o.order_name, o.target_quantity

Column Selection with JOINs:

• After adding JOINs, the Column dropdown includes entries from all joined tables
• Columns are displayed in table.column format (or alias.column if aliases are defined)
• This allows you to select values from any table in your JOIN chain

Example JOIN Configuration: To create a query that gets the alert name of an alert, that occured on a specific machine:

1. Select primary table: alerts
2. Select column: name
3. Add JOIN: INNER JOIN with alert_history table
4. ON Condition: machines.id = alert_history.alert_id

You now have access to the alert names of the alerts that occured.

13.3.3 Preview Rows of Tables (UI Position 3)

The Preview Rows feature allows you to inspect the data in your selected tables before building complex queries, helping you understand the available data and verify your selections.

Target Table Preview:

• Click Preview rows of tables to open the preview dialog
• View sample data from your primary (target) table
• The preview shows the first 10 rows with all columns visible

JOIN Table Previews:

• For each configured JOIN, a separate preview is available
• View sample data from each joined table to verify the join will work as expected
• Identify the correct columns to use in your ON conditions

13.3.4 Filter Conditions (UI Position 4)

Filter conditions allow you to restrict the query results to specific subsets of data based on column values.

Adding Filter Conditions:

1. Expand the Filter Conditions section
2. Click Add Condition to create your first filter
3. Combine multiple conditions using AND/OR connectors

Available Operators:

Special Operators:

• is one of: Enter a comma-separated list of values (e.g., IDLE,EXECUTE,STOPPED)
• between: Enter two values separated by to (e.g., 10 to 100 or 2024-01-01 to 2024-12-31)
• contains: Performs case-insensitive substring matching

Combining Conditions:

• Use the AND/OR toggle to specify how conditions should be combined
• Conditions are evaluated in the order they are listed
• Complex logic can be built by nesting conditions with appropriate connectors

Example Filter Configuration: To find active orders on a specific machine:

1. Column: machine_id, Operator: =, Value: 5
2. Connector: AND
3. Column: status, Operator: is one of, Value: IN_PROCESS,QUEUED

13.3.5 Sorting, Limit & Aggregation (UI Position 5)

This section allows you to control the order, quantity, and aggregation of query results.

Sorting:

• Sort Column: Select which column to sort by
• Sort Order: Choose Ascending (A→Z, 0→9) or Descending (Z→A, 9→0)

Limit & Offset:

• Limit: Maximum number of rows to return (enter 0 for no limit)
• Offset: Number of rows to skip before starting to return rows
• Use Limit and Offset together for pagination of large result sets

Aggregation Functions: For numeric columns, you can apply aggregation functions to compute summary values:

Latest Entry Preset:

• Click Latest Entry to automatically configure the query for retrieving the most recent row
• This preset sets: Sort by primary key or timestamp column, Descending, Limit = 1
• Useful for getting the current status or latest reading from a sensor

Example Aggregation: To get the total parts produced by a specific machine:

1. Select table: sfcs
2. Select column: yield_quantity
3. Add filter: machine_id = 5
4. Aggregation: SUM

13.3.6 Formatting Options (UI Position 6)

Formatting options allow you to customize how the query result is presented and formatted.

Prefix and Suffix:

• Prefix: Text to add before the value (e.g., Machine: )
• Suffix: Text to add after the value (e.g., °C or pcs)
• Useful for adding units, labels, or contextual information

Default Value:

• Specify a fallback value to use when the query returns no rows
• Example: Set default to N/A or 0 to ensure a value is always published
• Prevents empty or NULL values from being published to external systems

Override Data Type:

• Force the output to a specific data type for OPC UA compatibility
• Useful when the database column type needs to be converted to match OPC UA type requirements
• Available types: String, Int32, Int64, Float, Double, Boolean, DateTime

Example Formatting: To display a temperature value with proper units:

• Prefix: (empty)
• Suffix: °C
• Default Value: 0
• Override Data Type: Float

13.3.7 Live Preview (UI Position 7)

The Live Preview panel provides real-time feedback on your query configuration, allowing you to see the result as you build it.

Preview Panel:

• Displays the current query result based on your configuration
• Shows the actual value that will be published
• Updates automatically as you change parameters

Live Updates:

• The preview refreshes every time a configuration parameter changes
• See immediate feedback on how JOINs, filters, sorting, and aggregation affect the result
• No need to save and test separately

Error Messages:

• Invalid configurations display clear error messages
• Common errors include missing table/column selections, invalid JOIN conditions, or syntax issues
• Error messages guide you to the specific problem that needs correction

Summary Badges:

• The preview area displays summary badges showing:
  • Selected table
  • Selected column
  • Number of active filters
  • Number of JOINs configured
  • Aggregation function applied
• This provides a quick overview of your current configuration

Tip: Use the Live Preview extensively while building complex queries to catch issues early and verify your configuration produces the expected results.

14. 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.

15. 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

15.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

15.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

16. Updating MaConSim

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

16.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.

16.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.

16.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 12.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.

16.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

17. Troubleshooting

17.1 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.

17.2 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 14 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 12.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).

18. Help and Support

18.1 Opening the User Manual

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

18.2 Reporting a Bug or Contacting Support

A Support button is available in the header section of the application. 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.