Config Package

A Config Package contains the configuration files for a motorcortex application

Introduction

In general, a motorcortex application requires configuration files that contain application and system specific parameters; for example the values of software parameters or the configuration of the EtherCAT bus.

Config Packages can be Deployed from motorcortex.io to your controller. The parameters are loaded by the application when it starts or used while it is running. An application may also modify parameters and save them to the configuration files, for instance calibration values of some sensor. The updated configuration files can therefore also be Fetched from the controller and uploaded to motorcortex.io. When they are uploaded to the portal, they will receive a new timestamp, so you can keep track of changes.

When a config package is Deployed, it will be installed in /etc/motorcortex/apps-available/{config_package_name+timestamp} and a link to this folder will be created /etc/motorcortex/config, so the startup service knows which application to start.

Common Config Package Structure

Motorcortex applications follow the following structure for their configuration:

├── motorcortex.conf           # executable command line
├── config.json                # application startup parameters
├── linking.json               # defines links between parameters
├── license.pem                # license file
├── control
│   ├── control.xml            # application parameter values
│   └── persistence.bin        # persistent parameter values
├── io
│   └── master.xml             # Bus (EtherCAT)  configuration
└── user
    └── parameters.json        # user parameter definitions

In the following sections the configuration files are described in more detail. The example files are taken from the motorcortex application generator plugin for CLion (see developing-control-applications).

motorcortex.conf

motorcortex.conf is a startup file that is loaded by the start service (e.g. when you run sudo motorcortex start), that determines which executable needs to be run and what command-line parameters should be passed to this executable.

Below is an example of the contents of motorcortex.conf.

EXECUTABLE_PATH="/usr/local/bin/"                # path of the executable
EXECUTABLE=my_motorcortex_app                    # executable name
OPTIONS="-c /etc/motorcortex/config/config.json" # command line options

config.json

In config.json the main application configuration is determined. For instance in what mode the system should be run, where other configuration files can be found and how Tasks shall be configured.

Below is an example of a config.json:

{
  "Mode": "Production",
  "Path": {
    "Fieldbus": "io/master.xml",
    "Control": "control/control.xml",
    "Log": "/var/www/motorcortex/log",
    "UserParameters": "user/parameters.json",
    "Link": "linking.json",
    "License": "license.pem"
 },
  "Server": {
    "Default": {
      "URL": "wss://*:5568:5567",
      "Direction": "listen",
      "Login": "disable",
      "Certificate": "/etc/ssl/certs/motorcortex.pem"
    }
  },
  "Realtime": {
    "Isolate": [0, 1],
    "Allocate": 16
  },
  "Task": {
    "Control_task": {
      "Sched": "Realtime",
      "Cpu": [0],
      "Prio": 80,
      "Dt": 1000
    },
    "Fieldbus_task": {
      "Sched": "Realtime",
      "Cpu": [1],
      "Prio": 80,
      "Dt": 1000
    },
    "Logger_task": {
      "Sched": "Normal",
      "Dt": 1000
    },
    "Comm_task": {
      "Sched": "Normal",
      "Dt": 1000
    },
    "Logic_task": {
      "Sched": "Normal",
      "Dt": 1000
    }
  }
}

A commonly used setting in config.json is the “Mode”. This can be set to “Simulation” or “Production”. In “Simulation” the application can be run without having hardware. Hardware is then simulated by a simulation Module.

{
    "Mode": "Simulation",
...

linking.json

In linking.json links between different parameters can be defined. This way you can communicate date from one Module to another Module. This works also across Tasks.

You should of course only link parameters that have the same type and size on both ends of the link. Also you cannot link something to an output (as Destination); an output can only be a Source.

The json schema that contsains all possible options you can download here: linking.schema.json.

{
  "Version": "1.0.0",
  "Groups": [
    {
      "Name": "LinkExample",
      "SystemMode": "All",
      "Links": [
        {
          "Source": {
            "Path": "root/Control/boolOutput"
          },
          "Destination": {
            "Path": "root/Logic/boolInput"
          }
        }
      ]
    },
    {
      "Name": "Simulation",
      "SystemMode": "Simulation",
      "Links": [
        {
          "Source": {
            "Path": "root/Simulator/doubleOutput"
          },
          "Destination": {
            "Path": "root/Control/doubleInput"
          }
        }
      ]
    }
  ]
}

license.pem

Although motorcortex components run about 30 minutes without a license (for testing purposes), to use motorcortex components in production you require a license. After you have purchased a license for your application components you will receive a license file that needs to be installed in the configuration folder. Make sure that the license file is named correctly according to the License setting in your config.json file.

control.xml and persistance.bin

In the control folder there are in general two files: control.xml and persistence.bin. control.xml contains control parameters which can be adjusted by the user. persistance.bin contains the values of parameters that are defined to be of type PARAMETER_PERSISTENT in your application. These parameters are continually saved during system operations, for instance a parameter that counts running hours of a system, that continues counting also after the system has been switched off; or if a system has relative encoders, their absolute values are continually saved, such that after a restart calibration is not required.

io/master.xml

master.xml contains the EtherCAT bus configuration. This file is created by using Motorcortex-ECAT.

user/parameters.json

In parameters.json parameters can be added to a motorcortex application without recompiling the application. This is useful when external processes or devices need to write data into a motorcortex application. For instance a vision system can use the Motorcortex API to write coordinates of an object into the UserParameters. THe robot application can then use these coordinates in a robot program.

Below is an example of a parameters.json file:

{
    "Version": "1.0",
    "Children": [
        {
            "Name": "IO",
            "Children": [
                {
                    "Name": "Gripper1",
                    "Type": "int32[1],parameter_volatile",
                    "Value": 0
                },
                {
                    "Name": "Gripper2",
                    "Type": "int32[1],parameter_volatile",
                    "Value": 1
                }
            ]
        },
        {
            "Name": "Branch2",
            "Children": [
                {
                    "Name": "branch2Param1",
                    "Type": "int32[3],input",
                    "Value": [2,3,4,5,6]
                },
                {
                    "Name": "branch2Param2",
                    "Type": "int32[3],input"
                },
                {
                    "Name": "subbranch1",
                    "Children": [
                        {
                            "Name": "branch2subbranch1Param1",
                            "Type": "char[11],parameter_volatile",
                            "Value": "Hello world"
                        },
                        {
                            "Name": "branch2subbranch1Param2",
                            "Type": "int,parameter_volatile",
                            "Value": 123
                        }
                    ]
                }
            ]
        },
        {
            "Name": "moduleParam1",
            "Type": "double[6],input",
            "Value": [
                1.34,
                2.23,
                3.5675,
                4.0034,
                5.5677,
                6.2345
            ]
        },
        {
            "Name": "moduleParam2",
            "Type": "bool,input"
        }
    ]
}

Last modified April 8, 2022: updated docs (ad5eed15)