Open Commissioning Assistant

The Open Commissioning Assistant is an application designed to facilitate engineering processes based on the Open Commissioning Framework. It specializes in implementing various plugins for virtual commissioning and optimizing TwinCAT project workflows.

The goal of this application is to keep it as simple as possible with a clean design and let it only do what it needs to do. It is currently optimized for a connection to a TwinCAT3 Shell. Supported Versions:

• TcXaeShell.DTE.15.0 (based on VS2017, TwinCAT v3.1.4024.x)
• TcXaeShell.DTE.17.0 (based on VS2022, TwinCAT v3.1.4026.x)

Target framework

• .NET 8.0

Used packages:

• OC.Assistant.Sdk, see nuget package
• OC.Assistant.Theme, see nuget package
• envdte, see nuget package
• Beckhoff.TwinCAT.Ads, see nuget package
• TCatSysManagerLib, see nuget package

Installation

Download the OC.Assistant.exe from the Release page and start it. .NET 8.0 is required to run the application.

Core Functionality

The application's primary functions are:

1. Generating and updating connected TwinCAT projects
2. Connecting external systems via plugins and make this data available to the TwinCAT project.

Handling TwinCAT Solutions

The File menu contains functions regarding TwinCAT Solutions:

• Connect: select and connect to a running TwinCAT Shell. The status of the connection and the mode of the connected TwinCAT System is diplayed in the bottom right corner.
• Open Solution: select an existing TwinCAT Solution which gets opened in a new TwinCAT Shell and connected to by the Assistant application
• Create Solution: create an empty TwinCAT solution preconfigured with the plc task and an empty configuration
• Open Config (readonly): Opens an existing configuration of a twincat project. This opens the plugin configurations in the Assistant and enables to start and stop them. it does not open a TwinCAT Shell, it connects to a running twincat system. therefore the configuration of the plugins cant be changed, making it readonly. this is commonly done when the engineering process of the twincat solution is finished so it is not required to have the solution explorer open.

Updating Projects

The Project menu contains functions to update the connected TwinCAT Solution. Note that this menu is only active when the Assistant is connected to a TwinCAT solution and this solution is in Config Mode.

• Recreate Project: Updates the conected TwinCAT project based on the current configuration. When the configuration includes device entries, this function automatically generates corresponding behavior models within the connected TwinCAT solution. Note that this function is automatically called when using the Update TwinCAT Project function of the Client component in the Open Commissioning Unity package, so in most cases this funcion does not need to be called via this menu.

• Recreate Plugins: Reads the plugin configurations from the current configuration and creates the correspondig GVLs in the connected TwinCAT project and creates their configuration interface in the Assistant application.

• Update Task: Generates Input and Output variables based on the Devices of the PLC Project in the Task of the connected TwinCAT solution and links those to the corresponding variables in the PLC Project. Note that the PLC Project needs to be build successfully before updating the task.

• Settings: Opens The Settings for the connected TwinCAT solution

• PlcName: specifies the name of the PLC project in the connected solution in which the device models should be generated in when using Update Project

• PlcTaskName: specifies the name of the Task in which the input and output variables should be generated in when using Update Task

• Task AutoUpdate: if checked, the TwinCAT task gets updated automatically with the new input and ouptut variables when the PLC Project is build.

Profinet

The Profinet menu provides the function to automatically scan for Profinet devices on a selected network interface and create corresponding Profinet device nodes in the connected TwinCAT solution. Note: When using it for the first time, the dsian.TcPnScanner tool has to be installed. This can be done via the Assistant application itself by clicking on Install dsian.TcPnScanner in the Profinet menu. After successful installation, the function Scan Profinet function becomes available.

To scan for Profinet devices:

1. Click "Scan Profinet"
2. Enter a name for the Profinet Node in TwinCAT
3. Select the network adapter for scanning (must have TwinCAT Real-Time driver installed)
4. Optionally, specify a .hwml file
5. Click "Start" to begin the scan

The scan will create Profinet nodes in the connected TwinCAT solution for each detected device.

Plugin System

Plugins enable the Assistant to connect to external systems such as PLCs, robot controllers, and other control data sources, making this data available to the TwinCAT solution via Global Variable Lists (GVLs).

There will be plugins for:

• Cyclic communication with various virtual PLCs
• Cyclic communication with various virtual Robot controllers
• Acyclic data handling (RecordData)
• Modbus Server and Client communication

[!NOTE] There are no plugins released for the public yet.

Installation

1. Move the plugin folder into the directory of the OC.Assistant.exe.
2. Start the OC.Assistant.exe application.
3. The Assistant will automatically search through all subdirectories for *.plugin files and load any compatible plugin assemblies.
4. Once loaded, the plugin will be available for use within the Assistant.

Usage

1. Create a new instance of a plugin using the + button
2. Configure the plugin instance with required data
3. Upon successful loading, the assistant generates a GVL for the plugin's interface
4. The generated variables become available for use in TwinCAT

Configuration File

The OC.Assistant.xml file in the project folder of the TwinCAT solution serves as the base for generating objects in the TwinCAT solution. It gets created the first time the Assistant connects to the solution. This configuration includes all plugin connections and devices of the project for which behavior models should be generated

The plugin connection section is populated by adding plugins via the Assistant application itself. The device section is populated by using the "Update TwinCAT Project" function of the Client component in the Unity package.

This is an example configuration file containing a Plugin configuration and Devices:

<?xml version="1.0" encoding="utf-8"?>
<Config>
  <TaskAutoUpdate />
  <Plugins>
    <Plugin Name="PLC1" Type="PlcSimAdvanced" IoType="Address">
      <Parameter>
        <AutoStart>true</AutoStart>
        <PlcName>PLC_1</PlcName>
        <Identifier>1</Identifier>
        <CycleTime>10</CycleTime>
        <InputAddress>0-1023</InputAddress>
        <OutputAddress>0-1023</OutputAddress>
      </Parameter>
      <InputStructure />
      <OutputStructure />
    </Plugin>
  </Plugins>
  <Project>
    <Hil />
    <Main>
      <Group Name="Devices">
        <Group Name="Cylinders">
          <Device Name="Cylinder_1" Type="FB_Cylinder" />
          <Device Name="Cylinder_2" Type="FB_Cylinder" />
          <Device Name="Cylinder_3" Type="FB_Cylinder" />
          <Device Name="Cylinder_4" Type="FB_Cylinder" />
        </Group>
        <Group Name="Drives">
          <Device Name="Drive_Position" Type="FB_Drive" />
          <Device Name="Drive_Simple" Type="FB_Drive" />
          <Device Name="Drive_Speed" Type="FB_Drive" />
        </Group>
        <Group Name="Interactions">
          <Device Name="Button" Type="FB_Button" />
          <Device Name="Lamp" Type="FB_Lamp" />
          <Device Name="Lock" Type="FB_Lock" />
          <Device Name="Panel_1" Type="FB_Panel" />
          <Device Name="Toggle" Type="FB_Button" />
        </Group>
        <Group Name="SensorsAnalog">
          <Device Name="SensorAnalog_1" Type="FB_SensorAnalog" />
          <Device Name="SensorAnalog_2" Type="FB_SensorAnalog" />
          <Device Name="SensorAnalog_3" Type="FB_SensorAnalog" />
        </Group>
        <Group Name="SensorsBinary">
          <Device Name="SensorBinary_1" Type="FB_SensorBinary" />
          <Device Name="SensorBinary_2" Type="FB_SensorBinary" />
          <Device Name="SensorBinary_3" Type="FB_SensorBinary" />
        </Group>
      </Group>
    </Main>
  </Project>
</Config>

Contributing

We welcome contributions from everyone and appreciate your effort to improve this project. We have some basic rules and guidelines that make the contributing process easier for everyone involved.

Submitting Pull Requests

1. For non-trivial changes, please open an issue first to discuss your proposed changes.
2. Fork the repo and create your feature branch.
3. Follow the code style conventions and guidelines throughout working on your contribution.
4. Create a pull request with a clear title and description.

After your pull request is reviewed and merged.

[!NOTE] All contributions will be licensed under the project's license.

Code Style Convention

Please follow these naming conventions in your code:

Guidelines for Contributions

• Keep changes focused: Submit one pull request per bug fix or feature. This makes it easier to review and merge your contributions.
• Discuss major changes: For large or complex changes, please open an issue to discuss with maintainers before starting work.
• Commit message format: Use the semantic-release commit message format.
• Write clear code: Prioritize readability and maintainability.
• Be consistent: Follow existing coding styles and patterns in the project.
• Include tests: It is recommended to add or update tests to cover your changes.
• Document your work: Update relevant documentation, including code comments and user guides.

We appreciate your contributions and look forward to collaborating with you to improve this project!