Config Package
10 minute read
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 (Application mode), 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 data 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
.
All possible linking.json
options are explained in the 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"
}
}
]
}
]
}
Inside the linking.json
you can create multiple "Groups"
, a group contains a "Name"
and information about the action like: "links"
and/or "setParameters"
. With the "systemMode"
you can specify for which Application mode
this group should be active. If you want to disable
or enable
groups from the linking.json
, you can use the "Enable":
function.

#Version
You can apply a version
to your linking.json
with "Version":
, check out linking.schema.json
how to to set up your versioning.
#Group
You can create
your own "Group":
, to assign a link or set a parameter.
#Name
Each group contains a "Name":
in here you can specify a name to your liking.
#SystemMode
Inside the config.json
you can define the Application Mode
, per mode, different links can be created in the linking.json
. For each group the "systemMode":
can be defined (All
, Production
or Simulation
) with the "systemMode"
, you can specify in which Application Mode
the group is active:
Application Mode | SystemMode |
---|---|
Production |
All or Production |
Simulation |
All or Simulation |
#Enable
With the "Enable":
flag you can enable or disable the current group, this is done by defining a True
, or False
statement.
#SetParameters
SetParameters
are used to change the the "Value":
of the specified "Path":
.
Parameter | Description |
---|---|
"Value": |
Here you can specify any type of Value that you want to assign to the Path . |
"Force": |
Here you can specify if you want to Force the value, to the Path , This can either be True or False . |
"Path": |
Here you can specify the Path , to which the Value is written. (path example: root/.../... ) |
"Index": |
Here you can specify the Index expressed as number , index 0 is equal to the the first element in a array[0]. |
"Length": |
Here you can specify the Length of elements expressed as a number . Example: If the "Index": 1 , with "Length": 2 , you will write only Index 1 and 2 to the Destination . |
Example: In case the software requires a physical hardware input like a E-stop if the application is in simulation
mode. You can override these E-stop values by defining a setParameter
for the specific estop_button path
. A open E-stop, gives a false
statement, that is why, the assigned value is true
, and forced
to true
, else after deploying the linking.json, the estop_button turns to false because of the not connected hardware.
"Name": "Simulation",
"SystemMode": "Simulation",
"SetParameters":
{
"Path": "root/Logic/:busToState/estop_buttons_channel1",
"Value": [
true,
true,
true,
true,
true,
true,
true,
true
],
"Force": true
}

#Links
"Links":
are used to link the source
to a destination
, or an destination to a source, it is not possible to link multiple destinations to a source. But it is possible to link an source to multiple destinations.
In the "Source":
and "Destination":
: you fill in your preferred path (root/.../...
). To the Source
you can specify information like: "Gain":
, "Offset":
, "Index":
, "Length":
and for the Destination
only a "Index":
and "Length"
.
Parameter | Description |
---|---|
"Source": |
Here you can specify the Path of the Source that you want to link to the Destination . |
"Destination": |
Here you can specify the path of the destination . |
"Gain": |
Here you can specify the Gain which is multiplied with Source , to get a new Destination value. |
"Offset": |
Here you can specify the Offset applied to the Destination . |
"Index": |
Here you can specify the Index expressed as number , index 0 is equal to the the first element in a array[0]. |
"Length": |
Here you can specify the Length of elements expressed as a number . Example: If the "Index": 1 , with "Length": 2 , you will write only Index 1 and 2 to the Destination . |
Note
The order of information sending to the Destination
is first the Offset
, after which the Source incl. Gain
is added.
"Name": "Joystick",
"SystemMode": "All",
"Enable": true,
"Links": [
{
"Gain": 1.0,
"Offset": 0.0,
"Source": {
"Path": "root/Joystick1/axes",
"Index": 4,
"Length": 1
},
"Destination": {
"Path": "root/Control/hostInJointVelocity",
"Index": 0
}
}
]

The json schema that contains all possible options you can download here: linking.schema.json.
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. The created user parameters are visible in de desk-tool under the tree path: root/UserParameters/.../...
.
{
"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"
}
]
}

DataTypes
The [x] specified after each dataType defines how many rows the array contains, except for string
and char
the [x] indicates respectively the letter and character size.
DataType | Definition | Example |
---|---|---|
int/int32/int64[x] | Numeric data type for numbers without fractions | -707, 0, 707 |
uint[x] | Positive numeric data type for numbers without fractions | 0, 7, 707 |
float[x] | Numeric data type for numbers with fractions | -707.07, 0.7, 707.00 |
char[x] | Single letter, digit, punctuation mark, symbol, or blank space | a, 1, ! |
string[x] | Sequence of characters, digits, or symbols—always treated as text | hello, +1-999-6 |
bool[x] | True or false values | 0(false), 1 (true) |
Value
A parameter can contain an initial "Value":
that is loaded each time during system initialization. If no value is assigned the default value = 0
. Assigning no value provides the option to write a value of control.xml, linking.json or persistent.bin
depended on the parameterType.
ParameterTypes
ParameterType | Description. |
---|---|
INPUT | In this parameter type a value can be written, for example Via DESK-tool or when linked to a other parameter via linking.json. Input data cannot be stored, only during start-up, data is retrieved from parameter.json or linking.json. |
OUTPUT | This parameter type is read-only, in linking.json you can link an input to an output parameter. Output data cannot be stored, only during start-up data is retrieved from parameter.json or linking.json. |
PARAMETER | This parameter type is used to configure the system. Parameters are retrieved from the parameter.json or control.xml during start-up. This parameter can be read and written that can be saved via desk-tool to the control.xml. |
PARAMETER_VOLATILE | This parameter type is used to configure the system. Parameters are retrieved from the parameter.json or linking.json during start-up. This parameter can be read and written, the parameter_volatile can not be stored. |
PARAMETER_PERSISTENT | This parameter type is used to configure the system. Parameters are retrieved from the persistent.bin during start-up. This parameter can be read and written, the last value of this parameter is automatically stored in the persistent.bin. |