PLCnext Extensions

Extensions of the runtime can be integrated into a system in the form of an app. With a PLCnext Extension, the runtime can be extended by the following elements:

A process dependent on the runtime (process)
A component (component)
A Shared Library (library), which usually belongs to a component

PLCnext Extensions are integrated by including Acf config files when the runtime is started. An Acf configuration file can contain any number of entries or extensions of the three element types listed above. The overall layout of configuration file is as follows:

<?xml version="1.0" encoding="UTF-8"?>
  <AcfConfigurationDocument
     xmlns="http://www.phoenixcontact.com/schema/acfconfig"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.phoenixcontact.com/schema/acfconfig.xsd"
     schemaVersion="1.0" >
     <Processes></Processes>
     <Libraries></Libraries>
     <Components></Components>
  </AcfConfigurationDocument>

Note:

A list with all the environment variables used and their definitions can be found HERE.
All paths can be specified as either absolute (e.g. $ARP_PATH_APPS_ACTIVE_DIR$/<App Identifier>/Runtime/RuntimeBinaryFile) or relative to the storage location of the ACF configuration file unless stated otherwise.
In addition, an Acf settings file is required to start a process and will be illustrated in the following sections. All following template files for PLCnext Extensions are available on GitHub HERE.

Template Acf settings/configuration files

The following demo Acf settings/configuration files can be used as templates to extend the runtime.

Template Acf settings file

An example file for the Acf settings file (required to start a process, DemoDefault.acf.settings available on GitHub HERE):

<?xml version="1.0" encoding="UTF-8"?>
  <AcfSettingsDocument
     xmlns="http://www.phoenixcontact.com/schema/acfsettings"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.phoenixcontact.com/schema/acfsettings.xsd"
     schemaVersion="1.0" >
     <RscSettings path="$ARP_PATH_SYSTEM_DIR$/System/Settings/Rsc.settings"/>
     <LogSettings logLevel="Debug" logDir="$ARP_PATH_APPS_DATA_DIR$/<App Identifier>/Logs" />
     <EnvironmentVariables>
         <EnvironmentVariable name="ARP_PATH_BINARY_DIR" value="/usr/lib" />
     </EnvironmentVariables>
  </AcfSettingsDocument>

This file contains among other definitions:

RscSettings "path" (optional): Absolute path to the RSC settings file on the controller.
LogSettings "logdir" (optional): Path for storing the log data of the runtime process. The following element of the path is entered by the app developer:
- <App Identifier>: Identifier of the corresponding app.
EnvironmentVariables: The environment variables are exported on the process start and can be used within the process and within its components and libraries.

Template Acf configuration (Process Extension)

An example file for the Acf configuration file for a Process Extension (DemoPlcnextProcessTemplate.acf.config available on GitHub HERE):

<?xml version="1.0" encoding="UTF-8"?>
  <AcfConfigurationDocument
     xmlns="http://www.phoenixcontact.com/schema/acfconfig"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.phoenixcontact.com/schema/acfconfig.xsd"
     schemaVersion="1.0" >
     <Processes>
        <Process name="<Process Name>"
           binaryPath="<Process Binary Path>"
           workingDirectory="$ARP_PATH_APPS_DATA_DIR$/<App Identifier>"
           args="<Acf settings path>"/>
     </Processes>
     <Libraries>
        <Library name="Arp.Plc.AnsiC.Library"
                   binaryPath="$ARP_PATH_BINARY_DIR$/libArp.Plc.AnsiC.so" />
     </Libraries>
     <Components>
        <Component
           name="Arp.Plc.AnsiC"
           type="Arp::Plc::AnsiC::AnsiCComponent"
           library="Arp.Plc.AnsiC.Library" process="<Process Name>">
      <Settings path="" />
     </Component>
     <Component name="Arp.Plc.DomainProxy.IoAnsiCAdaption"
              type="Arp::Plc::Domain::PlcDomainProxyComponent"
              library="Arp.Plc.Domain.Library" 
              process="<Process Name>">
      <Settings path="" />
     </Component>
     </Components>
  </AcfConfigurationDocument>

The runtime is started in a process. The configuration of the runtime process includes:

"Process name":

Name of the runtime process: Replaces the field "<Runtime Name>"

"binaryPath":

Relative path (from the storage location of the Acf configuration file) to the executable binary file of the runtime, which is to be started as process

"workingDirectory":

Absolute path to the working directory of the runtime process. The following element of the path is entered by the app developer:

<App Identifier>: Identifier of the corresponding app

"args":

An optional field. In this example, the relative path (from the location of the Runtime binary file) to the .acf.settings file is passed. E.g. Default.acf.settings or ../settings/Default.acf.settings. Thus, the absolute path to the Acf settings file can be easily determined by the runtime process without knowledge of the app identifiers.

See the following code snapshot of the Sample Runtime main process)
Components: needed components. E.g. AnsiCComponent and PlcDomainProxyComponent must be loaded if access to PLC via AnsiC-Api is needed.

Note: Relative paths are used here to simplify configuration. The app developer has the free choice of how to specify his paths. These can also be specified as absolute paths. E.g. $ARP_PATH_APPS_ACTIVE_DIR$/<identifier>/Runtime/Runtime.ExeBinary. It is easiest to have all runtime files in the same directory (see "Demo application" at the end).

The configuration file also contains the required libraries and components. This example shows libraries/components that are already on the device.

See Demo Runtime App (Process).

Template Acf configuration (Component Extension)

An example file for the Acf configuration file for a component extension (DemoPlcnextComponentTemplate.acf.config available on GitHub HERE):

<?xml version="1.0" encoding="UTF-8"?>
<AcfConfigurationDocument
   xmlns="http://www.phoenixcontact.com/schema/acfconfig"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.phoenixcontact.com/schema/acfconfig.xsd"
   schemaVersion="1.0" >
   <Libraries>
     <Library name="<Library Name>" binaryPath="<Library Path>" />
   </Libraries>
   <Components>
     <Component name="<Component Name>"
                           type="<Component type>"
                           library="<Library Name>"
                           process=""
                           condition="<Support Con>">
       <Settings path="<Settings Path>" />
     </Component>
   </Components>
  </AcfConfigurationDocument>

The configuration of the library of the component contains:

"name":

Name of the library: Replaces the field "<Library Name>"

"binaryPath":

Relative path (from the storage location of the Acf configuration file) to the library file of the component.

The configurations of the component contain:

"name":

Name of the component (taking the namespace into account)

"type":

Component type as shown in the example

"library":

Name of the previously configured library

"condition":

Condition for starting the component (optional)

"Settings path":

Relative path (from the location of the Acf configuration file) to the settings file of the component (optional)

As already mentioned, any combination of PLCnext Extensions of components and processes in a .acf.config file is possible.

Note: Serious errors in a child process (runtime process) such as a "segmentation fault" or configuration/parsing errors in the .acf.config/.acf.settings files cause the complete runtime to crash during loading or runtime.

Necessary additions in the app description file for plcnextextensions

If the optional JSON object "plcnextextensions" is present in the app description file, the AppManager knows that at least one PLCnext Extension is inside the app.

The "plcnextextensions" entry is structured as follows:

"plcnextextensions":
  [
     {
        "acfconfigpath" : "<Path to acf.config file 1>"
     },
     {
        "acfconfigpath" : "<Path to acf.config file 2>"
     },    
     {
        "acfconfigpath" : "<Path to acf.config file [n]>"
     }
  ]

"acfconfigpath":

Specifies the local path to the Acf configuration file of the daemon in the app container.

Steps to create and integrate PLCnext Extensions

Create the PLCnext Extensions:

Program your PLCnext Extensions (processes, libraries, components).
If necessary, license your PLCnext Extensions.
Build your PLCnext Extensions using the PLCnext Software Development Kit.
Test your PLCnext Extensions.

Integrate the PLCnext Extensions to your app:

The files you are going to need are:
- The Acf configuration files mentioned in the app_info.json
- All binaries, shared libraries and settings files referenced from the configuration file.
If they are on your PC, it is easiest to copy all these with an SFTP client into your app folder on the controller.
Add the optional app part "plcnextextensions" (“Necessary additions in the app description file for plcnextextensions”) for the shared libraries in your app description file.

Specifications and restrictions

An app container can contain several PLCnext Extensions.
Several PLCnext Extensions may be active simultaneously in the system as long as they have no inconsistent configurations.
PLCnext Extensions are activated/deactivated when you start/stop the app.
The activation/deactivation of a PLCnext Extension requires a restart of the firmware.

Required app components:

Persistent memory

Demo Runtime App (Process)

The general task or function of the demo runtime:

Read process data (in this case three simple counter variables) from the IEC 61131 runtime eCLR and write them to a log file
The appropriate PLCnext Engineer project is required for this. This is made available in the demo app container at the end of this section

The app description for the PLCnextSampleRuntime app is as follows:

{
     "plcnextapp": {
        "name": "Plcnext Sample Runtime Extension App",
        "identifier": "60000102000196",
        "version": "1.0",
        "target": "AXC F 2152",
        "minfirmware_version": "19.0.0",
        "manufacturer": "PhoenixContact",
     },
     "engineerapp": {
        "folder": "/arp/PCWE/"
     },
     "datastorage": {
        "persistentdata": true,
        "temporarydata" : true
     },
     "plcnextextensions" :
     [
        {
           "acfconfigpath": "/SampleRuntime/PLCnextSampleRuntime.acf.config"
        }
     ]
  }

The following sources for the demo plcnext runtime extension app are available on GitHub HERE.

App container folder:
- App description file: app_info.json
- The folder SampleRuntime with:
  - Required Acf configuration file PLCnextSampleRuntime.acf.config
  - Required Acf settings file Default.acf.settings
  - Binary file of the Runtime PLCnextSampleRuntime
- The app_info.json file of the app
- The PLCnext Engineer PCWE project folder with the appropriate solution in the arp folder.
Sources folder:
- Eclipse project with C++ source files of the runtime process in the PLCnextSampleRuntime folder. The Eclipse project is based on the demo SampleRuntime on GitHub (Initial Commit) and was modified accordingly for the demo app. The new SampleRuntime version on GitHub is extended with more functions such as license check via PLCnext License Manager (ILicenseStatusService).
- PLCnext Engineer Solution project AXCF_CSampleRuntime_Counter.pcwex.
Demo App container file: PlcnextSampleRuntime.app

After starting the app, the system is restarted. Then the PlcnextRuntime is running and its process can be seen in the Linux process list (using htop linux process manager):

The permanent writing of the counter values can be observed in the PLCnextSampleRuntime-log file:

Note: All binaries are for the AXC F 2152 controller and only executable on this controller.

Note: The identifiers used in the app descriptions of the illustrated demo applications have only demo values. The app identifier generated in the PLCnext Store on app creation must be used!

Demo Component App

Note:

First the Wbm component is used for demonstrating. This must be replaced by a corresponding demo component after its completion.

In the Demo Component App the Wbm component is installed into the system via a PlcnextExtensions app part. To test this, all files and entries of the Wbm component would have to be removed from the target. Therefore, make sure to back them up in advance:

The Wbm library: /usr/lib/libArp.Services.Wbm.so
The entry for the Wbm component from /etc/plcnext/device/Libraries.acf.config
The entry for the Wbm component from /etc/plcnext/device/MainProcess.acf.config

The app description for the WbmComponentApp is structured as follows:

  "plcnextapp": {
        "name": "Wbm Component App",
        "identifier": "60000020000023",
        "version": "123.456",
        "target": "AXC F 2152",
        "minfirmware_version": "19.3.0",
        "manufacturer": "PhoenixContact",
     },
     "datastorage": {
        "persistentdata": true,
        "temporarydata" : false
     },
     "plcnextextensions" :
     [
        {
           "acfconfigpath": "/wbm/WbmComponent.acf.config"
        }
     ]
  }

The corresponding WbmComponent.acf.config file is structured as follows:

<?xml version="1.0" encoding="UTF-8"?>
  <AcfConfigurationDocument
     xmlns="http://www.phoenixcontact.com/schema/acfconfig"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.phoenixcontact.com/schema/acfconfig.xsd"
     schemaVersion="1.0" >
     
     <Libraries>
          <Library name="Arp.Services.Wbm.Library"
              binaryPath="libArp.Services.Wbm.so" />
     </Libraries>
     <Components>
     <Component name="Arp.Services.Wbm"
                           type="Arp::Services::Wbm::WbmComponent"
                           library="Arp.Services.Wbm.Library"
                           process=""
                           condition="$ARP_WBM_SUPPORT$">
        <Settings path="" />
      </Component>
     </Components>
  </AcfConfigurationDocument>

The following sources for the demo plcnext wbm component extension app are available on GitHub HERE.

App container folder:
- App description file: app_info.json
- Binary of the Wbm component shared library: wbm/libArp.Services.Wbm.so
- Required Acf configuration file WbmComponent.acf.config
Demo app container file: WbmPlcnextComponent.app

Support in the firmware

The PLCnext Extensions app part type is supported in the firmware from version 19.3.0.