MaConSim

german flag
english flag

MaConSim — User Manual

Version 0.1.0 MaConSim GmbH

Table of Contents

  1. Introduction
  2. System Requirements
  3. Installation
  4. License Activation
  5. Login and User Management
  6. Plant Management
  7. Create Resources
  8. Create References
  9. Production Operator Dashboard
  10. Event Logs
  11. Connectivity
  12. Plant Export and Import
  13. License Plan Feature Matrix
  14. Troubleshooting

1. Introduction

MaConSim (Machine Condition 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 MES 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.
  • 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 MES (Manufacturing Execution Systems), the following table explains the core terms used throughout this manual:

Concept Description
Plant The top-level container representing a factory or site. All resources and settings belong to a specific plant.
Machine A physical production asset within a plant (e.g. a CNC machine, press, or assembly station).
Scenario A named set of simulation parameters — takt time, scrap rate, alert rate, etc. — that defines a machine's simulated behavior. A machine can have multiple scenarios assigned; you select which one is active at runtime.
Order A production order with a target quantity and unit of measure.
SFC A Shop Floor Control unit — an individual work item within an order, representing a specific lot or serial unit that travels through a machine.
NC Code A nonconformance code identifying a specific type of quality deviation (e.g. "Dimension out of tolerance"). Logged automatically during simulation based on the configured NC rate.
Tool A physical tool used by a machine during production (e.g. a drill bit or cutting insert). Tool usage is tracked per takt when enabled.
Alert A named machine event type triggered during simulation (e.g. "Overtemperature"). Fired automatically based on the configured alert rate.
Data Collection A named measurement channel (e.g. temperature, pressure, cycle time) associated with a machine, published via OPC UA or MQTT.
OPC UA Tree A virtual OPC UA server instance that exposes simulation data to external OPC UA clients.
MQTT Broker A connection to an MQTT broker through which machine data is published as structured messages.

1.3 Typical Workflow

A typical MaConSim setup follows this sequence:

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

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

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

2. System Requirements

Component Requirement
Operating System Windows 10 (64-bit) or newer; macOS 11.0 (Big Sur) or newer (Apple Silicon / ARM64 only); Ubuntu 22.04 or newer (64-bit)
RAM 4 GB minimum, 8 GB recommended
Disk space 50 MB for the application; additional disk space required for plant data (database grows with usage — allow at least 100 MB free)
Display resolution 800 × 600 minimum
Internet connection Required at startup for license validation
Network ports Outbound HTTPS (443) for license validation; OPC UA: 4840 (default, configurable); MQTT: 1883 (default, configurable)

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 14 (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:

OS Path
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

Backup: The database file 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 12.1) 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.

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.

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.

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

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

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

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

Error Solution
No internet connection Check your network connection and try again.
License key invalid Verify you copied the key correctly. Whitespace and line breaks are stripped automatically when pasting.
License expired Contact MaConSim GmbH to renew your subscription.
License already in use Contact MaConSim GmbH to release or transfer the license to this machine.

Re-activating: If your license was renewed or transferred, click Re-activate on the error screen and enter your updated key.

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

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

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

5. Login and User Management

5.1 Logging In

  1. On the login screen, enter your Username and Password.
  2. Click Login.

If your credentials are incorrect, an error message is displayed. Passwords are case-sensitive. Contact your MaConSim administrator if you are unable to log in.

5.2 User Management

User management is accessible from the top navigation bar via the Users icon (shield icon). Here you can create and delete user accounts for anyone who needs access to MaConSim on this installation.

The user list displays all existing accounts with their username and email address.

Creating a user:

  1. Click Add User.
  2. Fill in the fields:
Field Requirement
Username Unique name used to log in (required)
Email Address Contact address for the account (required)
Password Minimum 6 characters (required)
  1. Click Create User.

The new user can immediately log in with their credentials.

Deleting a user: Click the trash icon next to a user in the list. Deleting a user does not affect any plant data they created.

License limit: The maximum number of user accounts is determined by your license plan (see Chapter 13). The Add User button is disabled when the limit is reached.

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:
Field Description
Name A unique display name for the plant (required)
Info A short subtitle or identifier, e.g. "Main Assembly Hall"
Description A longer description of the plant, its purpose, or production type
Location The physical address or site name
  1. Click Create Plant.

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

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.

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

6.3 Editing and Deleting a Plant

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

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

6.4 Exporting a Plant

Click the Download icon on a plant card to export the entire plant configuration as a YAML file. The file includes all machines, scenarios, orders, NC codes, tools, alerts, data collections, OPC UA trees, and MQTT brokers.

See Chapter 12 for full details on the export and import process.

6.5 Importing a Plant

Click Import Plant (top right of Plant Management) to restore a plant from a previously exported YAML file. The imported plant is added as a new entry — it does not overwrite existing plants.

License requirement: The Import Plant feature requires the importPlant entitlement. If the button is greyed out, your current plan does not include this feature. Contact MaConSim GmbH to upgrade.

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

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:
Field Description
Name Display name shown throughout the application (required)
Info A short subtitle or identifier, e.g. "Press Line A"
Description Detailed free-text description of the machine
Model The machine model designation, e.g. "DMG DMU 50"
Manufacturer The manufacturer's name, e.g. "DMG Mori"
Serial Number The physical serial number of the machine
Asset ID Your internal asset management identifier (for reference only — not processed by MaConSim)
Device Class Classification of the device type, e.g. "CNC Milling", "Robot Arm"
Device Revision Hardware revision or generation identifier
Status The initial operating status assigned when the machine is created
  1. 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:

Status Meaning
IDLE The machine is ready but no simulation is currently running on it
RUNNING The machine is actively processing a production order
MAINTENANCE The machine is in a simulated maintenance state, triggered by the scenario's maintenance probability
ERROR The machine has encountered a simulated error condition

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 and Deleting a Machine

  • Click the pencil icon on a machine entry to edit any of its fields.
  • Click the trash icon to delete a machine.

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

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

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, and one machine can have multiple scenarios — you select which one is active when starting production on the dashboard.

Navigate to a plant → Create Resources → Scenarios.

7.2.1 Creating a Scenario

  1. Click Add Scenario.
  2. Configure the simulation parameters:
Field Description Default
Name Scenario name (required) —
Scrap Rate Probability (0.0–1.0) of producing at least one defective part per takt. A value of 0.05 means a 5% chance of scrap per cycle. 0
Alert Rate Probability (0.0–1.0) of a machine alert being fired per takt. The specific alert is chosen randomly from those connected to the machine. 0
Maintenance Probability Probability (0.0–1.0) of the machine entering MAINTENANCE state per takt. 0
NC Rate Probability (0.0–1.0) of a nonconformance code being logged per takt. The specific NC code is chosen randomly from those connected to the machine. 0
Tool Logging When enabled, one tool usage event is recorded per takt for a randomly selected tool connected to the machine. Requires at least one tool to be connected and Tool Logging enabled. Off
Takt Time (ms) The nominal duration of one production cycle in milliseconds. 60,000 ms = 1 minute per cycle. 60,000
Takt Time Variance (ms) A random variation (±) applied to each takt. For example, a takt time of 60,000 ms with a variance of 5,000 ms means each cycle takes between 55,000 and 65,000 ms. 0
Parts per Takt Number of parts produced in each cycle. Increase this for machines that produce multiple units per cycle (e.g. an injection mould with 4 cavities → set to 4). 1
Mixed Yield/Scrap Possible When enabled, a single takt can produce both good and scrap parts simultaneously. When disabled, a takt is either entirely good or entirely scrap. Off
Scrap Handling Mode Continue: the machine keeps running after a scrap event. Stop: the machine halts after scrap and requires a manual restart on the dashboard. Continue
  1. 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, maintenance, 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 and Deleting a Scenario

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

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

7.3 Orders and Shop Floor Control (SFC)

7.3.1 Understanding Orders and SFCs

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

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

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

7.3.2 Orders

Navigate to a plant → Create Resources → Orders.

Creating an Order:

  1. Click Add Order.
  2. Fill in:
Field Description Default
Order Name A unique identifier for this order, e.g. "ORD-2026-001" (required) —
Unit of Measure The unit in which parts are counted, e.g. pcs, kg, m pcs
Target Quantity The total number of units this order requires 100
  1. Click Create Order.

Click the eye icon on an order to navigate directly to its SFCs.

Editing and Deleting Orders:

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

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

7.3.3 Shop Floor Control (SFC)

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

Creating an SFC:

  1. Click Add SFC.
  2. Fill in:
Field Description
Order The parent order this SFC belongs to (required)
SFC Number A unique identifier for this production unit, e.g. "SFC-001" or a serial number
Info Additional notes, instructions, or material references
Planned Quantity The number of parts this specific SFC is planned to produce
  1. Click Create SFC.

SFC Status Lifecycle:

SFCs move through the following statuses during their lifecycle:

Status Description
CREATED Initial state when first created — not yet queued or started
QUEUED Added to the machine's order queue, waiting to be processed
IN_PROGRESS Currently being processed by a machine
COMPLETED Successfully finished — all planned parts produced
SCRAPPED Rejected due to defects and will not be completed
ON_HOLD Temporarily paused, e.g. awaiting material or inspection
CANCELLED Cancelled before completion

Managing SFC Status:

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

Action Resulting Status When to use
Queue QUEUED Move the SFC into the order queue so it can be picked up by a machine
Complete COMPLETED Manually mark the SFC as finished
Scrap SCRAPPED Reject the SFC as a defective unit
Hold ON_HOLD Temporarily pause the SFC

7.4 Nonconformance Codes (NC Codes)

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

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

Navigate to a plant → Create Resources → NC Codes.

Creating an NC Code:

  1. Click Add NC Code.
  2. Fill in the fields:
Field Description
Name A descriptive name for the deviation type, e.g. "Surface Scratch" (required)
Code A short identifier, e.g. "Q-001" — used in reports and event logs (required)
Description Detailed explanation of what this nonconformance means
Category A grouping label to organize NC codes, e.g. "Dimensional", "Surface", "Assembly"
  1. 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 13).

7.5 Tools

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

Navigate to a plant → Create Resources → Tools.

Creating a Tool:

  1. Click Add Tool.
  2. Fill in the fields:
Field Description
Name The tool's display name, e.g. "8mm Drill Bit" (required)
Description Additional details such as grade, specification, or coating
Part Number The tool's part or catalog number for reference
Max Uses The maximum number of production cycles (takts) this tool can be used before it is considered worn out. Set to 0 or leave blank for unlimited.
  1. Click Create.

Max Uses: Once a tool's usage count reaches the Max Uses 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 13).

7.6 Alerts

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

Navigate to a plant → Create Resources → Alerts.

Creating an Alert:

  1. Click Add Alert.
  2. Fill in the fields:
Field Description
Name A descriptive name for the alert type, e.g. "Overtemperature Warning" (required)
Severity The severity level of this alert type (required)
Description Details about the alert, its typical cause, or recommended operator action

Severity levels:

Severity Typical Use
INFO Informational events that require no immediate action
WARNING A condition that should be monitored
ERROR A fault condition requiring attention
CRITICAL A serious fault that may require an immediate production stop
  1. Click Create.

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 13).

To assign alerts to machines, see Section 8.3.

7.7 Data Collections

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

Navigate to a plant → Create Resources → Data Collections.

Creating a Data Collection:

  1. Click Add Data Collection.
  2. Fill in the fields:
Field Description
Name The name of the measurement channel, e.g. "Spindle Temperature" (required)
Unit The physical unit of the measurement, e.g. °C, bar, rpm, mm (required)
Description What is being measured, where on the machine, and its significance
  1. Click Create.

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 13).

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. One machine can have multiple scenarios assigned — for example, a "Normal Production" scenario and a "High Scrap Rate" scenario. You choose which one to use when starting production on the dashboard.

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. A machine can have multiple scenario connections.

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

8.2 Order Queue Management

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

Navigate to a plant → Create References → Order Queues.

The queue table shows all SFCs across the plant that are currently in QUEUED status, including their parent order and planned quantity.

To add an SFC to the queue, open the SFC list (Section 7.3.3) and use the Queue action on the desired SFC. Once queued, the SFC appears here and is ready to be picked up when production starts on the dashboard.

8.3 Connect Alerts

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

Navigate to a plant → Create References → Connect Alerts.

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

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

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

8.4 Connect Data Collections

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

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

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

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

8.5 Connect NC Codes

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

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

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

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

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

8.6 Connect Tools

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

Navigate to a plant → Create References → Connect Tools.

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

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

9. Production Operator Dashboard

The Production Operator Dashboard is the central control and monitoring view during an active simulation. It shows the live state of all order processes in the plant, lets you start and stop production per machine, and provides a real-time view of progress, active SFCs, and recent events.

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

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

9.1 Overview

An order process is the combination of a machine running a specific order at runtime. When you start production, you are starting an order process on a specific machine using a chosen scenario. The dashboard lists one row per order process.

Each row shows:

Column Description
Order Name The name of the production order
Target Quantity Total parts the order requires
Machine The machine assigned to this order process
Machine State Live status badge: IDLE, RUNNING, MAINTENANCE, or ERROR
Progress A progress bar showing produced parts vs. target quantity
Actions Play (▶) and Stop (■) buttons to control the simulation

9.2 Filtering

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

9.3 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 SFC in the queue for the order (Section 8.2).
  3. On the dashboard, click Play (▶) next to the order process.
  4. If the machine has multiple scenarios connected, select which scenario to use.
  5. The machine status changes to RUNNING and the progress bar begins advancing with each takt.

9.4 Stopping Production

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

9.5 Expanding an Order

Click the chevron (▶) next to an order row to expand it and see:

  • Active SFCs: The SFCs currently being processed, with their individual status and progress.
  • Recent Alerts: The most recent alert events triggered on this machine for this order process.
  • Recent NC Code Occurrences: The most recent nonconformance events logged during this order process.

9.6 Recent Order History

The bottom section of the dashboard shows the last 20 completed or cancelled order events across all machines in the plant. This gives a quick at-a-glance overview of recent production results without navigating to the Event Logs.

10. Event Logs

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

Navigate to a plant → Event Logs.

10.1 Order History

Navigate to a plant → Event Logs → Order History.

Shows a complete chronological log of all order state transitions. Each entry includes:

  • Timestamp: When the event occurred
  • Order Name: The order affected
  • Machine: The machine on which the event occurred
  • Event Type: The type of state transition (e.g. Started, Completed, Cancelled)

Use the order history to track the full lifecycle of each production run, identify orders that were cancelled or restarted, and calculate actual production durations.

License requirement: Requires the orderHistory entitlement.

10.2 Alert History

Navigate to a plant → Event Logs → Alert History.

Shows all alert events triggered during simulation. Each entry includes:

  • Timestamp: When the alert was triggered
  • Machine: The machine that generated the alert
  • Alert Name: The type of alert (as defined in Section 7.6)
  • Severity: The severity level (INFO, WARNING, ERROR, CRITICAL)

Use the alert history to analyze the frequency and distribution of machine alerts over time, and to validate that your scenario parameters produce a realistic event rate.

License requirement: Requires the alertHistory entitlement.

10.3 NC Code Occurrences

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

Shows all nonconformance events logged during simulation. Each entry includes:

  • Timestamp: When the nonconformance was logged
  • Machine: The machine on which it occurred
  • NC Code: The code and name of the nonconformance type
  • SFC: The Shop Floor Control unit being processed when the event occurred

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

License requirement: Requires the ncCodeHistory entitlement.

11. Connectivity

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

11.1 OPC UA

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

Navigate to a plant → Connectivity → OPC UA.

11.1.1 Creating an OPC UA Tree

  1. Click Add OPC UA Tree.
  2. Configure:
Field Description Default
Name Display name —
Server Address Bind address 0.0.0.0
Server Port Port number 4840
Security Mode None / Sign / SignAndEncrypt None
Security Policy None / Basic256Sha256 / Aes128Sha256RsaOaep / etc. None
User Token Type Anonymous / Username / Certificate Anonymous
Role Observer / Operator / Engineer / Admin Observer
  1. Click Create.

11.1.2 Starting and Stopping the OPC UA Server

  • Click Play (▶) on an OPC UA tree to start the server.
  • Click Stop (■) to stop it.
  • The server state badge shows Running or Stopped.

11.1.3 NodeSet2 Import

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

  1. Click Import NodeSet2 on an OPC UA tree.
  2. Select the .xml file.
  3. The import summary will show nodes created, updated, or skipped.

11.1.4 Certificate Management

When using Sign or SignAndEncrypt security modes, certificates are managed automatically and stored in:

C:\Users\{username}\AppData\Roaming\com.maconsim.app\pki\

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

11.1.5 Adding Nodes and Data Source Configuration

After creating an OPC UA tree, you can build a custom node structure to expose simulation data or custom logic to external OPC UA clients.

To add a node:

  1. Expand the desired OPC UA tree in the Connectivity → OPC UA section.
  2. Click Add Node at the desired location in the node tree (root or under an existing node).
  3. In the dialog, choose the Node Type:
    • Object: A container node that can hold Variables, Methods, or other Objects. Use Objects to organize your address space hierarchically (e.g., by machine, subsystem, or logical grouping).
    • Variable: A data value node. Variables can be linked to simulation data (e.g., machine status, data collection channels) or set to a static/manual value. Variables are what OPC UA clients typically read or subscribe to.
    • Method: An executable function node. Methods can be invoked by OPC UA clients to trigger actions or workflows (e.g., reset a counter, start a simulation). Method support may require additional configuration.
  4. Enter a Display Name and (optionally) a Node ID. If left blank, a Node ID is generated automatically.
  5. For Variable nodes, configure the Data Source:
    • Static Value: Set a fixed value (number, string, boolean, etc.) for the variable.
    • Database Reference: Link the variable to a value stored in the MaConSim database.
    • Simulation: Link the variable to simulation-driven runtime values.
  6. Set the Data Type (e.g., Int32, Float, Boolean, String) for Variable nodes.
  7. Click Create to add the node to the tree.

Simulation (Value Source) and Create Simulation Config: When Simulation is selected as the value source, you can define how the runtime value is generated.

  1. In the variable editor, choose Simulation as Value Source.
  2. Click Create Simulation Config.
  3. Configure the simulation behavior (for example signal profile, update interval, and value boundaries/options shown in your UI).
  4. Save the simulation config.
  5. Save the variable.

After saving, the variable value is generated from the configured simulation profile while the OPC UA tree/server is running.

Node References: Node references define how nodes are linked in the OPC UA address space. They are essential for browsing and semantic structure in OPC UA clients.

  • Hierarchical references (for example Organizes, HasComponent, HasProperty) create parent-child relationships and determine where a node appears in the tree.
  • Non-hierarchical references (for example HasTypeDefinition, HasModellingRule, or custom references) describe semantic relationships without changing tree position.
  • When adding a node under an existing parent in the UI, MaConSim typically creates a matching hierarchical reference automatically.
  • If reference editing is available, choose a reference type that reflects your modeling intent (for example: use HasComponent for functional parts, HasProperty for metadata-like values).

Practical guideline: Use Object nodes with Organizes or HasComponent to structure systems and sub-systems, then attach Variable nodes via HasComponent or HasProperty depending on whether the value represents an operational signal or a descriptive attribute.

Editing and Deleting Nodes:

  • Click the pencil icon next to a node to edit its properties, data source, or type (where allowed).
  • Click the trash icon to delete a node and all its children.

Typical Use Cases:

  • Expose machine status: Add a Variable node linked to a machine's status (e.g., RUNNING/IDLE/ERROR).
  • Publish sensor data: Add Variable nodes for each data collection channel (e.g., temperature, pressure) and link them to the simulation.
  • Organize by machine: Use Object nodes to group all variables and methods for each machine.
  • Custom commands: Add Method nodes to allow OPC UA clients to trigger actions in the simulation (if supported).

11.2 MQTT

MaConSim can publish machine simulation data to MQTT brokers.

Navigate to a plant → Connectivity → MQTT.

11.2.1 Creating a Broker Configuration

  1. Click Add Broker.
  2. Configure:
Field Description Default
Name Display name of the broker tree —
Description Optional notes for this broker tree —
Broker Host Broker hostname or IP address localhost
Broker Port MQTT TCP port 1883
WebSocket Port Optional MQTT-over-WebSocket port —
Username / Password Optional login credentials —
Client ID MQTT client identifier used by MaConSim Auto-generated
Keep Alive (seconds) Keep-alive interval for the client connection 60
Max Buffer Size Internal message buffer size 10000
Max Connections Maximum concurrent connections 1000
Birth Topic / Birth Message Optional online-status publish message when connecting —
Last Will Topic / Last Will Message Optional offline-status message if the client disconnects unexpectedly —
Authentication Toggle to require username/password auth Off
TLS/SSL Enable encrypted MQTT connections Off
Enabled Enable/disable this broker configuration On
  1. Click Create.

11.2.2 Starting and Stopping a Broker

  • Click Play (▶) to start the broker runtime.
  • Click Stop (■) to stop it.
  • The broker row and detail view show a Running/Stopped state badge.

11.2.3 Topic Tree and Add Topic Configuration

After creating a broker, open it to manage the Broker Topic Tree. Topics are shown as a hierarchical tree derived from slash-separated topic paths.

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

Add Topic Configuration:

  1. Open a broker tree.
  2. Click Add Topic.
  3. Configure:
Field Description Default
Topic Path Full MQTT topic path (slash-separated) —
Signal Type Message category (status, telemetry, event, alarm, metrics, command) telemetry
QoS Level MQTT QoS level (0, 1, 2) 1
Publish Interval (ms) Publish cadence for this topic 1000
Retain Message Broker retains the last message for new subscribers Off
Enabled Topic active/inactive state On
  1. Optionally configure an inline data source directly in the topic dialog.
  2. Click Create Topic.

Topic path conventions:

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

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

For example:

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

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

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

11.2.4 Data Source Configuration

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

Open Data Source Configuration:

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

Data Source fields:

Field Description
Field Name JSON key in the published payload (required)
Source Type Static Value, Database Reference, or Simulation
Info Optional context/description for the mapping

Source Type: Static Value

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

Source Type: Database Reference

  • Select Table.
  • Select Row.
  • Select Column.
  • MaConSim resolves and publishes the referenced cell value.

Source Type: Simulation

  • Select a Simulation Configuration.
  • If needed, click New Config to create one.

Create Simulation Config (from MQTT Data Source):

  1. In Simulation Configuration, click New Config.
  2. Set a name/description.
  3. Choose Simulation Mode (linear, random, sine, sawtooth).
  4. Choose Behavior (clamp, wrap, bounce).
  5. Set mode-specific parameters (for example min/max, rate, amplitude, frequency, phase offset, noise factor).
  6. Save the config and select it for the data source.

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

12. Plant Export and Import

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

12.1 Exporting a Plant

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

The export includes:

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

12.2 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.
  2. A file chooser opens — select a .yaml or .yml export file.
  3. The plant and all its resources are created in the database.
  4. The plant list refreshes automatically.

13. 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/

Feature Free Trial Basic Premium
Users 1 3 Unlimited
Software Updates ✓ ✓ ✓
Technical Support — ✓ within 48 h (Mon–Fri 9–17) ✓ within 12 h (Mon–Fri 9–17)
Plants 1 3 Unlimited
Production Machines 2 10 Unlimited
Production Scenarios 1 10 Unlimited
Production Orders 1 10 Unlimited
NC Codes 3 10 Unlimited
Tools 2 10 Unlimited
Alerts 2 10 Unlimited
Data Collections 2 10 Unlimited
OPC UA (Server/Client) ✓ ✓ ✓
MQTT Broker ✓ ✓ ✓
Production Operator Dashboard ✓ ✓ ✓
History (Orders, NC Codes, Alerts) ✓ ✓ ✓
Plant Import — ✓ ✓

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

14. Troubleshooting

Application shows "License validation failed" on startup

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

"Import Plant" button is greyed out

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

A button shows "Limit reached"

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

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

See Chapter 13 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:

OPC UA server fails to start

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

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 12.2).

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 12.1).

© 2026 MaConSim GmbH. All rights reserved. This document is confidential and intended for licensed customers only.