This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Motorcortex Tools

Vectioneer has created multiple tools that help significantly with developing control applications. The following chapters will provide motde detailed information of working with these tools.

Motorcortex.io Motorcortex Desk Motorcortex Grid

1 - Motorcortex.io

A explanation for using the motorcortex.io portal.

Motorcortex.io is the platform where you manage and configure your Motorcortex Projects and machines using packages. this chapter will explain how to use motorcortex.io and how to manage and configure the software packages for your application.

1.1 - Portal Basics

A explanation how to browse trough and use the motorcortex.io portal.

For The Motorcortex.io Portal you will need a user account. You can request a trail and make a account on motorcortex.io.

After login to motorcortex.io you will enter the main page.

On the left you will find the Main Menu where you have the options to

  • Go to your Projects page. In this page you will find al your projects

  • Go to the Store page. In the store you can find free templates or buy binary packages for your application.

  • Use the Motorcortex Desk tool. If you have a controller connected you can click this button to connect to your controllers Motorcortex Desk. More about Motorcortex Desk you can find in Motorcortex Desk.

  • Use the Motorcortex Grid tool. if you want to make changes to the current Graphical User Interface(GUI) of your controller using Motorcortex Grid. More about Motorcortex Desk you can find in Motorcortex Grid.

  • Get information on how to work with Motorcortex by consulting to the documentation website that you are reading from right now.

  • Consult other Motorcortex Users on the Support Forum.

Projects Page

In the projects page you will find all your projects. You can download and save every project on your own PC.

On the Top of the projects page you can upload projects stored on your pc and create new projects. pressing the Create project button will bring you to the Create Poject screen. Here you can choose a name and version of your project.

Opening a project will show you the `Packages and files that you have in this project. There are 3 kinds of packages needed for a Motorcortex Application:

  • A Grid Package you will find more information about the Grid Package chapter.
  • A Binary Package you will find more information about the Binary Package chapter.
  • A Config package you will find more information about the Config Package chapter.

These packages can be added by Uploading or by clicking create packages in the right menu.

1.2 - Project Packages

A explanation how to use and reconfigure project packages.

Every Project has packages that are used for your Motorcortex application. A project can have multiple packages, a controller/machine can only have one package of every type. This way is it possible to have different versions and configurations of every machine. there are 3 types of packages:

  • Grid packages
  • Binary packages
  • Config packages

In this section will explain what for these packages are used and how to configure them.

Grid Package

A grid package is used for a Graphical User Interface the grid package consists of a couple of files and directories

3D directory

This is where you store the 3d model of your application.

In this directory you will find a .gltf file this is you model. The standard modeling tool used is Blender if you want to learn how to create a 3d model for your Motorcortex application make sure to take a look at 3D Mmodels

There is also a config.json file this file jou can adjust the scene and linking of your 3d model.

Config directory

In the config directory you will find the gui configuration. this mainly consists of indication for the machine errors and states.

In the Errors directory you can find .html files that are the errors shown in the GUI.

Img directory

In the img directory you can store the images that you want to be displayed in your GUI. these can be .svg, png, .jpg.

Safety directory

GUI.grid

The gui.grid is the file you generate when making a GUI using Motorcortex Grid.

Binary Package

In the binary packages you keep

Config Package

Control Directory

IO Directory

Mech Directory

Sctipts

User

Config.json

Licence.pem

Linking.json

motorcortex.conf

2 - Motorcortex-DESK

A explanation of how to work with Motorcortex Desk

Introduction

MotorCortex-Desk is a web-based application that can be used to visualize signals and parameters of a MotorCortex control system in real-time and it allows parameters to be changed or signals to be overridden. It is a very valuable tool when tuning or debugging a system’s behavior.

⚠ Using MotorCortex-Desk all parameters of the running control system are accessible and may be modified. Changing parameters may cause unpredictable or unstable machine behavior and may cause danger to personnel or cause damage to the machine or its surroundings. The tool should only be used by system experts that have detailed knowledge of the system and that know what the impact of parameter changes is.

Log-in

MotorCortex-Desk can be accessed via 2 locations:

  1. on Motorcortex.io: here is always the latest version of Motorcortex-Desk available. However you will require an internet connection and log-in.
  2. on your local controller: in cases there is no internet connection. However, the Motorcortex-Desk version might be totally up to date.

Log-in page on Motorcortex.io

  1. Open your browser and go to motorcortex.io and click on Log in.

  1. Go to the menu on the left and click on Control-Desk.

  2. The Motorcortex Desk login page will now open in a new tab in your browser.

Log-in page on local controller

  1. Open your browser and go to [Controller IP address]:8000, per default 192.168.2.100:8000

Log-in fields

The Motorcortex desk is protected by a login because the user can manipulate signals and behaviour of the control system.

  1. Server Address: The IP address of the controller (Host), per default 192.168.2.100. Optionally the request port and subscribe port can be defined. If nothing is filled-in for these ports, the default of 5568/5567 will be used.
  2. 🔒/🔓: Option to choose a secure (🔒) or unsecure connection (🔓). Default is secure.
  3. Login: If nothing is used, “guest” will be used as account. Default administrator account is “admin”.
  4. Password: If nothing is used, “guest” will be used as password. Default administrator password is “vectioneer”.

Screen lay-out

After loging in the Motorcortex Control Desk will show. The Desk screen consists out of 4 main parts:

  1. Parameter Tree: The parameter three holds all of the singals in the system and you can manually search for each signal and select these to show in the trace overvieuw.
  2. Search Bar: In the search bar you can search for signals inside the Parameter Tree.
  3. Trace Overview: A container of all parameters selected in the Parameter Tree
  4. Plot Window: A visualisation of the selected signals in the Trace Overvieuw.

Icons meanings

In Motorcortex-Desk the following icons are used:

Icon Description
Folder
Input: In this parameter type a value can be written. A typical use is an sensor.
Output: This parameter type is read-only. A typical use is a set point value. The value is calculated within the MOTORCORTEX and shall not be overwritten.
Parameter: This is parameter type that is used to configure the system. Typical uses are motor parameters and system constants.Parameters are retrieved from the parameter list during start-up. If the user changes a value and wants to use in the future, he has to save the list before rebooting/switching off the controller. A parameter can be read and written.
Persistent: these are values that contain process data that is continuously updated and will be retained through application restarts. Typical applications are running ours or amount of produced products.
Save/Download:
Upload:
Zoom:
Drag view:
Zoom-fit: Scale axes to view all signals.
Snap-single: Snap cursor to closest trace point.
Snap-multi: Snap cursor to time axis and show corresponding cursors on all visible signals.
Settings: Opens the settings window, in here you can adjust the Frequency divider. E.g. a value of 10 will show every 10th sample.
Start recording: This will start a data trace of all plotted signals with Frequency divider.
Stop recording: Stops the data trace, follewed by a download of a .csv file.
Disconnect: Disconnects Desk from the controller and brings you back to the login screen.

Parameter Tree

In a MOTORCORTEX application all control objects are organized in a tree structure; the Parameter Tree. The Parameter Tree contains a snapshot of all the inputs, outputs and internal data of the control objects at the current time.

MOTORCORTEX has a tree structure in which the data objects are published. Each task or objects inside a task can create their own subtree (folder). Objects can be nested. In a general control application there are usually a “Logic”, “Control” and also “EtherCAT” folders that represent the data of different tasks. In the EtherCAT folder you will find the configured EtherCAT slave devices.

The names of the folders are configurable and the application developer can change these, but it is good practice to stick to some convention.

Inside the folders the data of the associated object is contained. MOTORCORTEX currently supports the following datatypes: boolean, integer, double or binary (e.g. a c-struct). Also arrays of the same datatype are supported. Array elements start at index 0 (zero).

A parameter can be found by typing in its name in the Search bar. It is also possible to search for a part of the name by using a “*".

  • Using an “*” in front will show everything ending with the search term.
  • A “*” behind the search term will show everything beginning with the search term.
  • “*Searchterm*” will show everything with “Searchterm” in it.

Useful search terms are:

Search term Description
*actual* Actuele sensor values or derivatives of that (e.g. speeds and accelerations).
*target* Setpoints to the actuators.
*position* Positions.
*velocity* Velocities.
*raw* Raw sensor values. Raw sensor values can also be found in the fieldbus map (most times EtherCAT). Conversion of raw sensor values is normally done in the folder “Control”.
*WindowDetector*, *high*, *low*, *tooHigh*, *tooLow* Errors, alarms, faults.

Tracing Signals

Adding traces

  1. Adding traces from parameter tree: A parameter from the Parameter Tree can be added to a trace by double clicking on it. After that the signal will become bold in the Parameter Tree and will appear in the Trace Overview on the bottom left.
  2. Loading traces from a file: It is also possible to load a preconfigured .json file with parameters into the Trace Overview. This can be done by clicking in the Trace Overview on the upload button and afterwards selecting the desired .json file.
    NOTE: the current trace signals will be replaced by the signals from the .json file.
  3. Saving traces to a file: To save all signals from the Trace Overview, press the 💾 save button in the Trace Overview. After this a window will be shown where the name of the file can be defined. If nothing is filled in, the name will be “parameters.json”. As soon the download button is pressed, your webbrowser will automatically download the file.
  4. Removing a trace: This is easily done by clicking on the behind the signal in the Trace Overview.

Plotting signals

The signal will be plotted if the tick box in front of the signal name in the trace overview is ticked. The signal will appear in the Plot Window. At the bottom of the Plot Window is an overview of all plotted signals. The colored line in front of the signal matches with the signal line color in the plot.

Changing axis

In order to keep overview, it is possible to split the signals over 4 different Y-axes, each with their own ranges. This is especially handy when plotting Boolean and Integer values simultaneously. The current axis is displayed directly behind the signal name and is per default “Y1”. It can be changed by clicking on it and selected. The axis are in the far right of the Plot Window, with the individual axis name at below them.

X-Y plot

In some case it can be convenient to not have the time on the X-axis, but a certain signal, e.g. for resistance plots. In order to use a signal as X-axis, select the axis value (e.g. Y1) and select X1.
NOTE: only 1 signal can be used as X axis.

Scaling signals

It is possible to scale signals by pressing on the ⚙ cog button behind the signal in the Trace Overview. Motorcortex-Desk contains many standard conversions, but it is also possible to define a custom forumula.

Measuring

Make and save data traces

Before a data trace is started, all desired signals should be selected (and thus being plotted in the Plot Window). To start the tracing, click on the ▶️ RECORD button. To stop the tracing, click on the ⏹ STOP button. After the trace will be straight away be downloaded to your computer. The format is a .csv file, which can be opened in a text editor, but also in Microsoft Excel, Python or Matlab.

Changing values

Modifying a parameter value

A parameter can be changed in two locations:

  1. In the parameter tree by clicking on the value. This will open an input field where you can type the new value. The value will be taken over as soon as enter is pressed.
  2. By clicking on the input field behind the signal and its actual value and type the new value. The value will be taken over as soon as enter is pressed.

NOTE: MotorCortex-Desk accepts calculations and values from the math.js library and will directly fill-in the resulting values. So typing “cos(pi/2)” will result into a value of 0.

⚠ Changing parameters may cause unpredictable or unstable machine behavior and may cause danger to personnel or cause damage to the machine or its surroundings.

Saving and loading parameter sets

It is possible to save and load parameter list. In this way a functional configuration can be backed-up and reloaded easily.

  1. Saving the parameter set To save the (changed) parameter files to the Motion Controller, click in the top right of the Parameter Window on the 💾 save button . If no name is specified, the file will directly overwrite “control.xml” located on the motion controller in the folder /etc/motorcortex/config/control.
    The controller will by default load control.xml at start-up. If the parameters are changed, but list is NOT saved, the unchanged control.xml will be loaded the next time the software is restarted.

⚠ If no file name is specified the original parameter file “control.xml” will be overwritten, without any backup of the old file. Any wrong filled in parameters will be also automatically loaded after the next reboot of system.

Changing parameters may cause unpredictable or unstable machine behavior and may cause danger to personnel or cause damage to the machine or its surroundings.

The user is advised to save the current “control.xml” before overwriting the file.

  1. Loading a parameter set To upload a parameter parameter file from your computer, click on the upload button in the top right of the Parameter Window. Any new values will be straight away applied. Make sure that your system is in a safe state before uploading and keep a copy of the original parameter file.

⚠ Changing parameters during operation may cause unpredictable or unstable machine behavior and may cause danger to personnel or cause damage to the machine or its surroundings.

Make sure that the system is in a safe condition and cannot start by itself.

The user is advised to save the current “control.xml” before uploading the file.

Overriding inputs and outputs

Sometimes it is needed to temporary overwrite an input or output (e.g. to test an output). This can be done by ticking the checkbox behind the signal, both in the Tracing Overview as in the Parameter tree. The signal will than become orange and will not change unless the user removes the overwrite or will fill in a different value.

An example is below: the enable of jointReferenceGenerator controls the enable of all 6 signalGenerators. If the enable of signalGenerator01 has to be disabled, while the rest have to stay enabled, an overwrite has to be applied to signalGenerator01/enable

⚠ Changing signal values during operation may cause unpredictable or unstable machine behavior and may cause danger to personnel or cause damage to the machine or its surroundings.

Make sure that trained personnel is operating MotorCortex-Desk and the system is or can be quickly put in a safe state (e.g. by pressing the emergency button that is within reach).

NOTE: Overriding inputs is not possible when the input is written to from inside the block. The value that is sent to the application is then immediately overwritten by the application itself.

NOTE: Overwritten values are shown in orange, but if the folder is closed, you will not see it anymore. If the sofware is restarted, all overwritten values are gone.

3 - Motorcortex-ECAT

With Motorcortex-ECAT you can configure your EtherCAT Devices

Introduction

Motorcortex ECAT is a web-based application that is used to configure your EtherCAT devices for Motorcortex. The Motorcortex ECAT tool generates a .xml file that is used inside the parameter tree.

Screen Layout

The Motorcortex-ECAT build environment screen layout contains the following main elements:

  • Top Menu Bar The Top Menu Bar is where you can manage your settings and also Fetch and Deploy your .xml files.
  • Domains Configuration Panel In the Domains Configuration Panel you configure the domais of your EtherCat devices.
  • Device Configuration Panel In the Device Configuration Panel you can configure your EtherCAT devices.

3.1 - Top Menu Bar

With Motorcortex-ECAT you can configure your EtherCAT Devices

Top Menu Bar

On the top of the Motorcortex-ECAT screen you will find the Top Bar. In this bar you wil find the folowing buttons:

Button Description
Gear The gear button will open the Top Bar drop down menu.
Connection Pressing the Connection button will open the connection settings.
Add Devices With the Add Devices button the add devices menu will open.
New Configuration The New Configuration button will empty the current configuration.
Load Configuration With the Load Configuration button you can upload a locally saved configuration .xml file.
Download Configuraton With the Download Configuration button you will download the current configuration to your local machine.
Dark Mode This beautiful switch will turn on Dark Mode.
Fetch Pressing the Fetch button will download the current configuration from the connected controller.
Deploy Pressing the Deploy button will Upload the current configuration from the connected controller.

3.2 - Domains Configuration Panel

Explanation of the Domains Configuration Panel

Domains Configuration Panel

On the left of the Motorcortex-ECAT screen you will find the Domains Configuration Panel. In this panel you can configure the domains of your EtherCAT devices.

Ethercat devices have to be placed inside of Domains. A Domain is an group of EtherCAT slaves (physical cluster of EtherCAT modules). For your project you can make use of one single domain, or multiple domains. An advantage multiple domains, is that every domain is separate and can (if configured properly) be disconnected and reconnected (hot-plug), while other devices in other domains that remain connected are still operational. Beside hot-plug capability domains also keep your structure more clear.

Adding devices

To add a new device you can click the button or add devices from the Top Bar dropdown. After this the Add devices menu will pop up.

From the Add Devices menu you can you can add Ethercat devices in several ways.

Tab Description
From Scan In the From Scan tab When connected to a Motorcortex controller with Ethercat devices connected, you can scan the EtherCAT bus for devices that are connected by pressing the button.
From Configuration In the From Configuration Tab you can add Ethercat devices from a previous configuration by pressing the button.
From Description Files In the From Description Files Tab you can add devices by uploading the ESI files provided by the component manufacturer by pressing the button.
Manually In the Manually tab It is also possible to add Devices manually by pressing the button. The device menu will popup here you can fill in the device data and hit save.

Domains

After having devices added the Domains Configuration Panel should look like this.

You can change the name of the domain to whatever name you like. By pressing the Checkbox you can include or exclude the domain from the EtherCAT message, this means that this domain will not be used for your application.

Devices

The number infront of a device is the device alias number, this number is normally used as the device position in the EtherCAT bus. By pressing the Checkbox you can include or exclude the device from the EtherCAT message, this means that this device will not be used for your application.

3.3 - Device Configuration Panel

With Motorcortex-ECAT you can configure your EtherCAT Devices

Device Configuration Panel

In the middle of the Motorcortex-ECAT screen you will find the Device Configuration Panel. With this panel you can configure your devices. A device has multiple tabs:

Tab Description
rxPDO A Proces Data Object (PDO) present the Inputs and Outputs of a node device to the EtherCAT master and are updated every cycle. RxPDO’s are received by a node and are used maily to control device Outputs.
txPDO A Proces Data Object (PDO) present the Inputs and Outputs of a node device to the EtherCAT master and are updated every cycle. RxPDO’s are transmitted by a node and are used maily to read device Inputs.
rxSDO A Service Data Object (SDO) present device parameters and are only updated via the ethercat mailbox request. RxSDO’s are received by the node device and are used for writable parameters.
txSDO A Service Data Object (SDO) present device parameters and are only updated via the ethercat mailbox request. TxSDO’s are send by the node device and are used for readable parameters.
Distributed Clock .
Info .
Startup .

rxPDO

In the rxPDO tab you can configure the rxPDO’s from your device.

Field Description
Here you fill in the PDO index defined by the device manufacturer.
Here you can define the group of this PDO within the device in the parametertree.
This is where you can change the name of the PDO .
With this checkbox you can choose to include/exclude this PDO from the EtherCAT message.
With this button you can choose to make this PDO visible in the parameter tree.
Pressing this button will show a dropdown with more options.
The Add Link button will ad a link for this PDO.
The Add PDO will add a new PDO for this device.
The Add Entry button will ad a Entry for this device.
With the delete button you will delete this PDO.

txPDO

In the txPDO tab you can configure the txPDO’s from your device.

Field Description
Here you fill in the PDO index defined by the device manufacturer.
Here you can define the group of this PDO within the device in the parametertree.
This is where you can change the name of the PDO .
With this checkbox you can choose to include/exclude this PDO from the EtherCAT message.
With this button you can choose to make this PDO visible in the parameter tree.
Pressing this button will show a dropdown with more options.
The Add Link button will ad a link for this PDO.
The Add PDO will add a new PDO for this device.
The Add Entry button will ad a Entry for this device.
With the delete button you will delete this PDO.

rxSDO

In the rxSDO tab you can configure the rxSDO’s from your device.

Field Description
Here you define the SDO type, this can either be CoE (CANopen over EtherCAT) or SoE (Servo drive over Ethercat).
Here you can define the group of this SDO within the device in the parametertree.
This is where you can change the name of the SDO .
Here you fill in the SDO entry index defined by the device manufacturer.
Here you can define the group of this SDO entry within the device in the parametertree.
Here you fill in the SDO entry index defined by the device manufacturer.
The data type of a SDO entry can be defined here this can be: Not set, Bit, Bool, Int, Uint, Float, Double.
The data lengt of a SDO entry can be defined here.
This is where you can change the name of the SDO entry.
Pressing this button will show a dropdown with more options.
The Add SDO will add a new SDO for this device.
The Add Entry button will ad a Entry for this device.
With the delete button you will delete this SDO.

txSDO

In the rxSDO tab you can configure the rxSDO’s from your device.

Field Description
Here you define the SDO type, this can either be CoE (CANopen over EtherCAT) or SoE (Servo drive over Ethercat).
Here you can define the group of this SDO within the device in the parametertree.
This is where you can change the name of the SDO .
Here you fill in the SDO entry index defined by the device manufacturer.
Here you can define the group of this SDO entry within the device in the parametertree.
Here you fill in the SDO entry index defined by the device manufacturer.
The data type of a SDO entry can be defined here this can be: Not set, Bit, Bool, Int, Uint, Float, Double.
The data lengt of a SDO entry can be defined here.
This is where you can change the name of the SDO entry.
Pressing this button will show a dropdown with more options.
The Add SDO will add a new SDO for this device.
The Add Entry button will ad a Entry for this device.
With the delete button you will delete this SDO.

Distributed Clock

In the Distributed Clock tab you can configure the distributed clock for your device.

Field Description
With this button you will enable Distributed clock synchronization mode for this application.
In the assign active field you fill in the HEX number defined in the ESI file of the Device. It tels this specific device to activate the the distributed clock.
Here you fill in the time between Sync0 events in nano seconds.
Here you fill in the shift time between Sync0 events in nano seconds.
Here you fill in the time between Sync1 events in nano seconds.
Here you fill in the shift time between Sync1 events in nano seconds.

Info

In the info tab the device information is displayed.

Startup

COE Configuration

Field Description
.
.
.
.
.
.
.
Pressing this button will show a dropdown with more options.
The Add Entry button will ad a Entry for this device.
With the delete button you will delete this SDO.

SOE Configuration

Field Description
.
.
.
.
.
.
.
Pressing this button will show a dropdown with more options.
The Add Entry button will ad a Entry for this device.
With the delete button you will delete this SDO.

3.4 -

EtherCAT slaves configuration

Introduction

MOTORCORTEX is a Hard-Realtime Control System with an integrated high-speed communication system. It is especially designed to allow easy and high-performance interaction with the control system from any client platform and with many supported programming languages.

This document will explain how to link EtherCAT slave devices to a MOTORCORTEX application.

Configuring EtherCAT slaves requires a number of steps:

  1. scan the EtherCAT bus and generate a topology file;
    the topology file is used by MOTORCORTEX to create the correct format of EtherCAT messages, such that all slave devices and their data objects can be addressed.
  2. configure each input or output for each device and link it to the MOTORCORTEX application.
  3. create special configurations for some more complex devices, such a servo-controllers or configurable i/o cards. This step is not always required.

MOTORCORTEX and EtherCAT basics

MOTORCORTEX

In a MOTORCORTEX application all control objects are organized in a tree structure; the Parameter Tree. The Parameter Tree contains a snapshot of all the inputs, outputs and internal data of the control objects at the current time.

MOTORCORTEX has a tree structure in which the data objects are published. Each task or objects inside a task can create their own subtree (folder). Objects can be nested. In a general control application there are usually a “Logic”, “Control” and also “EtherCAT” folders that represent the data of different tasks. In the EtherCAT folder you will find the configured EtherCAT slave devices.

The names of the folders are configurable and the application developer can change these, but it is good practice to stick to some convention.

Inside the folders the data of the associated object is contained. MOTORCORTEX currently supports the following datatypes: boolean, integer, double or binary (e.g. a c-struct). Also arrays of the same datatype are supported. Array elements start at index 0 (zero).

To view the tree structure use the MOTORCORTEX-Desk tool.

EtherCAT Domains/Groups

It is possible to divide the EtherCAT IOs in separate domains.

A Domain is an group of EtherCAT slaves (physical cluster of EtherCAT modules). Each domain has a dedicated XML file. An advantage different domains, is that every domain is separate and can (if configured properly) be disconnected and reconnected (hot-plug), while other devices in other domains that remain connected are still operational. Beside hot-plug capability domains also keep your structure more clear.

Per domain, groups (and subgroups) can be created. Typically each EtherCAT slave is assigned to a name and/or group. In that case the slave will appear in MOTORCORTEX-Desk as a dedicated folder.
Optionally it is possible to create subfolders for data objects (e.g. if the user prefers to separate inputs and outputs). This is all for a clear structure, functionally all data objects from one domain can also be dumped together.

Sending Information over EtherCAT

The information sent and received over the EtherCAT network consists (among others) of data packages of the following types: PDOs and SDOs.

PDO stands for Process Data Object. This is cyclic data that is send or received during every EtherCAT broadcast. Examples are: status of switches and lights, actuator setpoints and actual values.

SDO stands for Service Data Object. This is in data that is normally only send during start-up or during an event. Examples are: motor parameters, sensor configuration and (drive) error information.

The configuration of the SDOs on an EtherCAT module can be send via a mailbox file. There are two file types: CANopen over EtherCAT (CoE) and Sercos over EtherCAT (SoE, sometimes also called Servo over EtherCAT). The structure of the file is very similar for both types. The EtherCAT module manufacturer decides which type is used.

There are also other types of information that can be send over EtherCAT (e.g. File over EtherCAT (FoE), EtherNet over EtherCAT (EoE)), but this is out of scope of this document that will only focus on adding EtherCAT slaves to the MOTORCORTEX software.

Parameter Types in MOTORCORTEX:

This subsection shortly describes how the different parameter types can be used in combination with EtherCAT.

The MOTORCORTEX structure has the following parameter types:

  • Input: In this parameter type a value can be written. A typical use is an sensor. In the EtherCAT configuration file the sensor value will be linked to an input. However it is possible to also write this value an input into EtherCAT output. An input is typically linked to a PDO. In MOTORCORTEX Desk an input is depicted as:

  • Output: this parameter type is read-only. A typical use is a set point value. The value is calculated within the MOTORCORTEX and shall not be overwritten. Therefore this value can only be linked to an EtherCAT output, but never to an EtherCAT input. An output is typically linked to a PDO. In MOTORCORTEX Desk an output is depicted as:

  • Parameter: This is parameter type that is used to configure the system. Typical uses are motor parameters and system constants.Parameters are retrieved from the parameter list during start-up. If the user changes a value and wants to use in the future, he has to save the list before rebooting/switching off the controller. A parameter can be read and written. However due to its character, it will be used mostly in combination with SDOs. In MOTORCORTEX Desk an parameter is depicted as:

  • Persistent: these are values that contain process data that is continuously updated and will be retained through application restarts. Typical applications are running ours or amount of produced products. In MOTORCORTEX Desk an persistent is depicted as:

Configuring EtherCAT Topology

Introduction

The EtherCAT Topology contains information about which devices are in a network and how they are connected. Each slave device will receive an ID that is determined by its place in the topology. With this ID the application can address the device and send information to an receive information from the device.

In an EtherCAT network a single message is sent that passes by all devices and is returned back to the Master. Each device takes its own information from this message and inserts data back into the message as it passes. The Master needs to know the topology before it can build the correct message, containing data for all the slaves.

MOTORCORTEX is capable of using different EtherCAT Master stacks. By default the EtherLab (https://etherlab.org/) Master is used. The tools to scan the EtherCAT topology are provided as part of the EtherLab driver. MOTORCORTEX is compatible with the topology files generated by the EtherLab tools.

Scanning available slaves

Connect all slaves to the EtherCAT Network. Also the slaves that you want to hot-plug later.

Log in to the controller (via SSH) and type the following (on some systems it may be required to use sudo to execute the command with root privileges):

ethercat slaves

This command should output the connected EtherCAT slaves, for instance:

0 0:0 PREOP + EK1100 EtherCAT Coupler (2A E-Bus)
1 0:1 PREOP + EL1018 8K. Dig. Eingang 24V, 10�s
2 0:2 PREOP + EL2008 8K. Dig. Ausgang 24V, 0.5A
3 0:3 PREOP + EL3104 4K. Ana. Eingang +/-10V Diff.
4 0:4 PREOP + EL4134 4K. Ana. Ausgang -10/+10V. 16bit
5 0:5 PREOP + EL3174 4K. Ana. Eingang +/-10V Diff., +/-20mA SingleEnded, 16bit

Above you see 6 slaves with ID’s 0 through 5 being detected. EtherCAT starts numbering of slaves at 0.

Check if all slaves are present. If slaves are missing, check the EtherCAT connection and if the slave is powered.

Create/update EtherCAT Topology

First make a copy of the current topology (via filezilla or via the terminal, see below)

cd /etc/motorcortex/config/io
cp topology.xml topology_backup_YYYY_MM_DD.xml

To write the new topology type the following in the terminal.

sudo ethercat xml > topology.xml

The exact content of the topology.xml file will not be discussed in this document, since it is complex and not needed for this document. If the user is curious, he is encouraged to open the file in a text editor and view the content. The file should not be modified by hand.

Careless changing of topology.xml can result that the whole application will not work anymore. Therefore always first make a backup before changes are made.

Linking EtherCAT Slaves to MOTORCORTEX signals

In this chapter the inputs and outputs of the EtherCAT devices will be linked to MOTORCORTEX parameters. These links are located in a PDO file (or more PDO files in case of multiple domains).

Creating slave configurations and linking signals to MOTORCORTEX (pdo.xml)

With the Slaves connected and the topology.xml file generated and installed, follow the following procedure to create a slave configuration:

Create a file called /etc/motorcortex/config/io/pdo.xml and copy the text below into it. The filename is determined in the MOTORCORTEX Application and depends on the programmer’s choice. This is the most basic version of a slave configuration file, where all inputs and outputs from all (most) slaves are mapped to the MOTORCORTEX application. The file first defines a Domain and links a topology file to this domain. topology.xml is the file generated in Scanning available slaves. The option MapAll=1 maps all the inputs and outputs of slave devices and generates default names. Devices that do not have simple inputs or outputs may not be mapped with MapAll.

<?xml version="1.0"?>
<Domain File="topology.xml" MapAll="1"></Domain>

Restart the MOTORCORTEX server application (sudo may require the user’s password)

sudo /etc/init.d/motorcortex restart

Go to MOTORCORTEX-Desk via your browser and log in:

http://192.168.2.100:8000
Server address: 192.168.2.100
Username: admin
Password: vectioneer

Go to the folder root/EtherCAT, here you will find subfolders of the EtherCAT devices.
The order of the devices is alphabetical.
The slave ID is the last part of the device name.

Adding information to slaves

As a reminder of which slaves are present it is handy to copy the slave list that was shown as part of the procedure in Scanning available slaves in your pdo.xml file. This way you can quickly look up which devices are present and what their ID is.

<!--
0 0:0 PREOP + EK1100 EtherCAT Coupler (2A E-Bus)
1 0:1 PREOP + EL1018 8K. Dig. Eingang 24V, 10�s
2 0:2 PREOP + EL2008 8K. Dig. Ausgang 24V, 0.5A
3 0:3 PREOP + EL3104 4K. Ana. Eingang +/-10V Diff.
4 0:4 PREOP + EL4134 4K. Ana. Ausgang -10/+10V. 16bit
5 0:5 PREOP + EL3174 4K. Ana. Eingang +/-10V Diff., +/-20mA SingleEnded, 16bit
-->

In the pdo.xml file, all devices can have their own section with configuration parameters. The devices are identified with a <Device Id="X"> tag, where the Id is the EtherCAT ID that refers to the device. Each device can be given a Group and a Name property. The Group specifies a subfolder when the device is created in MOTORCORTEX, and is optional. If the Group is omitted, the device will be created in the current Domain.

<?xml version="1.0"?>
<!--
0  0:0  PREOP  +  EK1100 EtherCAT Coupler (2A E-Bus)
1  0:1  PREOP  +  EL1018 8K. Dig. Eingang 24V, 10�s
2  0:2  PREOP  +  EL2008 8K. Dig. Ausgang 24V, 0.5A
3  0:3  PREOP  +  EL3104 4K. Ana. Eingang +/-10V Diff.
4  0:4  PREOP  +  EL4134 4K. Ana. Ausgang -10/+10V. 16bit
5  0:5  PREOP  +  EL3174 4K. Ana. Eingang  +/-10V Diff., +/-20mA SingleEnded, 16bit
-->

<Domain File="topology.xml">
    <!--device 0, EK1100-->
    <Device Id="1" Group="Group1" Name="01-EL1018-01" MapAll="1">
    </Device>
    <Device Id="2" Group="Group1" Name="02-EL2008-01" MapAll="1">
    </Device>
    <Device Id="3" Group="Group2" Name="03-EL3104-01" MapAll="1">
    </Device>
    <Device Id="4" Group="Group2" Name="04-EL4134-01" MapAll="1">
    </Device>
    <Device Id="5" Group="Group2" Name="05-EL3174-01" MapAll="1">
    </Device>
</Domain>

to check the result:

Save the file

/etc/MOTORCORTEX/config/io/pdo.xml, 

restart MOTORCORTEX

sudo/etc/init.d/motorcortex restart 

log in on MOTORCORTEX-Desk (http://192.168.2.100:8000)

See if you can already see the individual inputs and outputs.

Linking a digital input to a MOTORCORTEX parameter

Normally each Slave device has a number of Inputs or Outputs. These signals can be linked to a signal in the MOTORCORTEX Parameter Tree. EtherCAT inputs write data to the Parameter Tree and can only be linked to parameters that allow write access (Inputs and Parameters); it is not possible to link an EtherCAT input to an Output signal. Check the MOTORCORTEX-Desk to see what the type of the parameter is you would like to link to.

Consider the example pdo.xml below.

<!--
<?xml version="1.0"?>
<!--
0  0:0  PREOP  +  EK1100 EtherCAT Coupler (2A E-Bus)
1  0:1  PREOP  +  EL1018 8K. Dig. Eingang 24V, 10�s
2  0:2  PREOP  +  EL2008 8K. Dig. Ausgang 24V, 0.5A
3  0:3  PREOP  +  EL3104 4K. Ana. Eingang +/-10V Diff.
4  0:4  PREOP  +  EL4134 4K. Ana. Ausgang -10/+10V. 16bit
5  0:5  PREOP  +  EL3174 4K. Ana. Eingang  +/-10V Diff., +/-20mA SingleEnded, 16bit
-->

<Domain File="topology.xml">
    <!--device 0, EK1100-->

    <Device Id="1" Name="01-EL1018-01">
    <Pdo Entry="6000:01" Name="input_01">
       <Link>root/Control/dummyBool</Link>
    </Pdo>
    </Device>

    <Device Id="2" Name="02-EL2008-01">
    </Device>

    <Device Id="3" Name="03-EL3104-01">
    </Device>

    <Device Id="4" Name="04-EL4134-01">
    </Device>

    <Device Id="5" Name="05-EL3174-01">
    </Device>
</Domain>

In this example, the EtherCAT Slave with ID 1 is a digital input module EL1018, that has 8 digital inputs. The input is a Process Data Object (PDO) and can be configured with the <Pdo> tag. The Entry property specifies where the PDO can be found on the device. The Entry consist of the index (hex) and subindex (two digits, leading zeros). The indices and sub-indices of the signals can be found in the documentation of the device provided by the manufacturer or can be derived from the contents of the topology.xml file.

In the topology.xml file the index and subindex for this particular type of device can be found in the <Entry> section of the device.

...
    <Device>
        <Type ProductCode="#x03fa3052" RevisionNo="#x00120000">EL1018</Type>
        <Name><![CDATA[EL1018 8K. Dig. Eingang 24V, 10�s]]></Name>
        <Sm Enable="1" StartAddress="#x1000" ControlByte="#x0" DefaultSize="1" />
        <TxPdo Sm="0" Fixed="1" Mandatory="1">
            <Index>#x1a00</Index>
            <Name>Channel 1</Name>
            <Entry>
                <Index>#x6000</Index>
                <SubIndex>1</SubIndex>
                <BitLen>1</BitLen>
                <Name>Input</Name>
                <DataType>BOOL</DataType>
            </Entry>
        </TxPdo>
        <TxPdo Sm="0" Fixed="1" Mandatory="1">
            <Index>#x1a01</Index>
            <Name>Channel 2</Name>
...

In this case, the first input of this device is located at index 6000 and subindex 1. To set the index and subindex of the input we use the Entry property:

<Pdo Entry="6000:01" Name="input_01">

Using the name property, the input is named “input_01”. This name will be used when the device is added to the MOTORCORTEX Parameter Tree. In this case the input can be found in the tree: /root/EtherCAT/00-EL1018-01/input_01

To link a value to the MOTORCORTEX application use the <Link> tag. The path to link to can be found by opening the MOTORCORTEX-Desk and browsing to the appropriate value in the tree. How to create a MOTORCORTEX application see

!!TBD!! G0110-0200-01-MAN-[Developing Motorcortex Applications in C++ (Server)](#Developing Motorcortex Applications in C++ (Server)).


...
    <Device Id="1" Name="00-EL1018-01">
        <Pdo Entry="6000:01" Name="input_01">
            <Link>root/Control/dummyBool</Link>
        </Pdo>
    </Device>
...

to check the result:

Save the file

/etc/MOTORCORTEX/config/io/pdo.xml, 

restart MOTORCORTEX

sudo/etc/init.d/motorcortex restart 

log in on MOTORCORTEX-Desk (http://192.168.2.100:8000)

If now the input is made high, the value the input is linked to (in this case root/Control/dummyBool) will go to 1.

Linking a digital output

It is also possible to place a boolean value in an output. EtherCAT outputs can be linked to MOTORCORTEX Inputs, Outputs and Parameters.

<?xml version="1.0"?>
<!--
...
-->
<Domain File="topology.xml">
    <!--device 0, EK1100-->

    <Device Id="1" Name="01-EL1018-01">
    <Pdo Entry="6000:11" Name="input_01">
       <Link>root/Control/dummyBool</Link>
    </Pdo>
    </Device>

    <Device Id="2" Name="02-EL2008-01">

    <Pdo Entry="7000:01" Name="output_01">
       <Link Invert="1">root/Control/dummyBool</Link>
    </Pdo>

    <Pdo Entry="7010:01" Name="output_02">
       <Link>root/Control/module_state</Link>
    </Pdo>

    </Device>

    <Device Id="3" Name="03-EL3104-01">
    </Device>

    <Device Id="4" Name="04-EL4134-01">
    </Device>

    <Device Id="5" Name="05-EL3174-01">
    </Device>
</Domain>

Besides adding the dummyBool to the output, we also added Invert="1". This means when digital input 1 is 1/true, output 2 will be 0/false (and vice versa). Output 2 is selected by Entry="7010:01". This value already showed up when we used MapAll="1". For the correct entry, look in to the documentation of the EtherCAT slave, typically under the subheading input data or output data. Last to demonstrate that it is also possible to write an integer to a digital output, the state of the MOTORCORTEX Logic is written to output 3.

Analog inputs

Each analog device has it’s own measuring range and unit. This means that every device has its own conversion. Where for a PT100-temperature module as the EL3201, the temperature is passed through as a value x10 (thus 31.4°C is transmitted as 314), for many others it is a value of 2^x for the full range. The EL3104 for instance has a full range of -10..10V with 16 bits resolution. The EL3104 uses an UINT16 (unsigned integer) value to represent -10..10V, this means that 0 = -10V and 65536 = +10V. In the configuration file however we can map the UINT16 value to an INT16 value, which is signed. This means that now 0V = 0, 10V = 2¹⁵-1 (since we start at 0) and -10V is -2¹⁵.

<?xml version="1.0"?>
<!--
...
-->
<Domain File="topology.xml">
    <!--device 0, EK1100-->
    <Device Id="1" Name="01-EL1018-01">
    <Pdo Entry="6000:01" Name="input_01">
       <DataType>INT16</DataType>
       <Link>root/Control/dummyBool</Link>
    </Pdo>
    </Device>
    <Device Id="2" Name="02-EL2008-01">
    <Pdo Entry="7010:01" Name="input_02">
       <DataType>INT16</DataType>
       <Link Invert="1">root/Control/dummyBool</Link>
    </Pdo>
    </Device>
    <Device Id="3" Name="03-EL3104-01">
    <Pdo Entry="6020:11" Group="Analog Inputs" Name="analog_input_03">
       <DataType>INT16</DataType>
       <Link Divide="3276.8">root/Control/dummyDouble</Link>
    </Pdo>
    </Device>
    <Device Id="4" Name="04-EL4134-01">
    </Device>
    <Device Id="5" Name="05-EL3174-01">
    </Device>
</Domain>

The slave uses some datatype that is also specified in the topology.xml file. Using the <DataType> tag the datatype can be changed to a more convenient format. In general it is used to convert from unsigned integer values to signed integers. So the slave for instance uses UINT16 as a type, with values in the range 0..65536, using <DataType>INT16</DataType>, it can be converted to a INT16 with a range of -32768..32767. So the value of 0 corresponds to 0.00V for instance in a -10V..10V input card.

Above a -10…10V value will be read-in on slave 4 (id=3), input 4. Note the Divide="3276.8". This scales the ‑2¹⁵…2¹⁵-1 back to -10…10V. This is done to easy cross-check the incoming voltage in case of troubleshooting. Another item introduced over here is Group="Analog Inputs". Since this module has only analog inputs, the subgroup that is now created is rather useless, but in EtherCAT module that have multiple types of inputs and or outputs (like drives), it results in a organized structure that allows quicker navigation.

Note: it is good practice to first link the analog input of the sensor to an input double that has the measuring unit (in this case Volt).

Analog outputs

<?xml version="1.0"?>
<!--
...
-->

<Domain File="topology.xml">
    <!--device 0, EK1100-->

    <Device Id="1" Name="01-EL1018-01">
    <Pdo Entry="6000:11" Name="input_01">
       <DataType>INT16</DataType>
       <Link>root/Control/dummyBool</Link>
    </Pdo>
    </Device>
    <Device Id="2" Name="02-EL2008-01">
    <Pdo Entry="7010:01" Name="input_02">
       <DataType>INT16</DataType>
       <Link Invert="1">root/Control/dummyBool</Link>
    </Pdo>
    </Device>
    <Device Id="3" Name="03-EL3104-01">
    <Pdo Entry="6020:11" Name="analog input 03">
       <DataType>INT16</DataType>
       <Link Divide="3276.8">root/Control/dummyDouble</Link>
    </Pdo>
    </Device>
    <Device Id="4" Name="04-EL4134-01">
    <Pdo Entry="7030:01" Name="analog output 04">
       <DataType>INT16</DataType>
       <Link Gain="3276.8" GainOffset="3276.8">root/Control/dummyDouble</Link>
    </Pdo>
    </Device>
    <Device Id="5" Name="05-EL3174-01">
    </Device>
</Domain>

Above the value of root/Control/dummyDouble is used to write to an analog output. The value of ‑10…10V is scaled back to the appropriate INT16 value by using Gain="3276.8", but on top of that the voltage is increased with 1V by using GainOffset="3276.8".

Start-up files and SDOs

Some EtherCAT devices are configurable through Service Data Objects (SDO’s); depending on how they are configured, they have different behavior. For instance the Beckhoff EL3174 Analog input module can be configured for different input types, e.g. current or voltage.

These devices can be configured by adding a <MailBox> tag, that points to a startup file that contains the desired configuration of the device. These setting are applied when the device is started.

The format of the startup files is determined by the type of slave device. Some devices use CAN over EtherCAT (CoE) for configuration, others use SERCOS over EtherCAT (SoE).

<?xml version="1.0"?>
<!--
...
-->

<Domain File="topology.xml">
    <!--device 0, EK1100-->

    <Device Id="1" Name="01-EL1018-01">
    <Pdo Entry="6000:01" Name="input_01">
       <DataType>INT16</DataType>
       <Link>root/Control/dummyBool</Link>
    </Pdo>
    </Device>
    <Device Id="2" Name="02-EL2008-01">
    <Pdo Entry="7010:01" Name="input_02">
       <DataType>INT16</DataType>
       <Link Invert="1">root/Control/dummyBool</Link>
    </Pdo>
    </Device>
    <Device Id="3" Name="03-EL3104-01">
    <Pdo Entry="6020:11" Name="analog input 03">
       <DataType>INT16</DataType>
       <Link Divide="3276.7">root/Control/dummyDouble</Link>
    </Pdo>
    </Device>
    <Device Id="4" Name="04-EL4134-01">
    <Pdo Entry="7030:01" Name="analog output 04">
       <DataType>INT16</DataType>
       <Link Gain="3276.7" Gainoffset="1">root/Control/dummyDouble</Link>
    </Pdo>
    </Device>
    <Device Id="5" Name="05-EL3174-01">
    <Mailbox File="05-EL3174-01_startup.xml"/>
    <Pdo Entry="6000:11" Name="analog input 01">
       <DataType>INT16</DataType>
       <Link Divide="3051.8" Index="0">root/Control/dummyDoubleArray</Link>
    </Pdo>
    </Device>
</Domain>

Above you can see that Divide="3051.8" is smaller, due to the larger measuring range of the EL3174. Also is the value placed into the first index (Index="0") of the array dummyDoubleArray.

To create the startup file, create a file in /etc/MOTORCORTEX/config/io called 05-EL3174-01_startup.xml.

<?xml version="1.0" encoding="ISO-8859-1"?>
<EtherCATMailbox>
    <CoE>
    <InitCmds>

        <InitCmd>
            <Transition>PS</Transition>
            <Comment><![CDATA[Input Type]]></Comment>
            <Timeout>0</Timeout>
            <Ccs>1</Ccs>
            <Index>32781</Index>
            <SubIndex>17</SubIndex>
            <Data>0200</Data> <!-- -10..+10V  -->
<!--                <Data>0200</Data> <!-- -10..+10V  -->-->
<!--                <Data>0E00</Data> <!--   0..+10V  -->-->
<!--                <Data>1100</Data> <!-- -20..+20mA -->-->
<!--                <Data>1200</Data> <!--   0..+20mA -->-->
<!--                <Data>1300</Data> <!--   4..+20mA -->-->
<!--                <Data>1400</Data> <!--   4..+20mA (NAMUR) -->-->
        </InitCmd>

        <InitCmd>
            <Transition>PS</Transition>
            <Comment><![CDATA[Input Type]]></Comment>
            <Timeout>0</Timeout>
            <Ccs>1</Ccs>
            <Index>32797</Index>
            <SubIndex>17</SubIndex>
<!--                <Data>0200</Data> <!-- -10..+10V  -->-->
<!--                <Data>0E00</Data> <!--   0..+10V  -->-->
<!--                <Data>1100</Data> <!-- -20..+20mA -->-->
<!--                <Data>1200</Data> <!--   0..+20mA -->-->

            <Data>1300</Data> <!--   4..+20mA -->
<!--                <Data>1400</Data> <!--   4..+20mA (NAMUR) -->-->
        </InitCmd>

        <InitCmd>
            <Transition>PS</Transition>
            <Comment><![CDATA[Input Type]]></Comment>
            <Timeout>0</Timeout>
            <Ccs>1</Ccs>
            <Index>32813</Index>
            <SubIndex>17</SubIndex>
            <Data>0200</Data> <!-- -10..+10V  -->
<!--                <Data>0200</Data> <!-- -10..+10V  -->-->
<!--                <Data>0E00</Data> <!--   0..+10V  -->-->
<!--                <Data>1100</Data> <!-- -20..+20mA -->-->
<!--                <Data>1200</Data> <!--   0..+20mA -->-->
<!--                <Data>1300</Data> <!--   4..+20mA -->-->
<!--                <Data>1400</Data> <!--   4..+20mA (NAMUR) -->-->
        </InitCmd>

        <InitCmd>
            <Transition>PS</Transition>
            <Comment><![CDATA[Input Type]]></Comment>
            <Timeout>0</Timeout>
            <Ccs>1</Ccs>
            <Index>32829</Index>
            <SubIndex>17</SubIndex>
            <Data>0200</Data> <!-- -10..+10V  -->
<!--                <Data>0200</Data> <!-- -10..+10V  -->-->
<!--                <Data>0E00</Data> <!--   0..+10V  -->-->
<!--                <Data>1100</Data> <!-- -20..+20mA -->-->
<!--                <Data>1200</Data> <!--   0..+20mA -->-->
<!--                <Data>1300</Data> <!--   4..+20mA -->-->
<!--                <Data>1400</Data> <!--   4..+20mA (NAMUR) -->-->

        </InitCmd>

    </InitCmds>
    </CoE>
</EtherCATMailbox>

Mapping an SDO to the MOTORCORTEX Tree

It is also possible to map SDO’s to the MOTORCORTEX Parameter Tree, so they can be updated at runtime. For this to work, the SDO’s have to be configured using the <sdo> tag, so they are included in the EtherCAT communication. This is done by adding them to the device configuration in the pdo.xml.

<?xml version="1.0"?>
<!--\\
...
-->
<!--
<Domain File="topology.xml">
    <!--device 0, EK1100-->
<Device Id="1" Name="01-EL1018-01">
    <Pdo Entry="6000:01" Name="input_01">
       <DataType>INT16</DataType>
       <Link>root/Control/dummyBool</Link>
    </Pdo>
</Device>
<Device Id="2" Name="02-EL2008-01">
    <Pdo Entry="7010:01" Name="output_02">
       <DataType>INT16</DataType>
       <Link Invert="1">root/Control/dummyBool</Link>
    </Pdo>
</Device>
<Device Id="3" Name="03-EL3104-01">
    <Pdo Entry="6020:11" Name="analog input 03">
       <DataType>INT16</DataType>
       <Link Divide="3276.7">root/Control/dummyDouble</Link>
    </Pdo>
</Device>
<Device Id="4" Name="04-EL4134-01">
    <Pdo Entry="7030:01" Name="analog output 04">
       <DataType>INT16</DataType>
       <Link Gain="3276.7" Gainoffset="1">root/Control/dummyDouble</Link>
    </Pdo>
</Device>
<Device Id="5" Name="05-EL3174-01">
    <Mailbox File="05-EL3174-01_startup"/>
    <Pdo Entry="6000:11" Name="analog input 01">
       <DataType>INT16</DataType>
       <Link Divide="3051.8" Index="0">root/Control/dummyDoubleArray</Link>
    </Pdo>
    <Pdo Entry="6000:7" Name="Fault channel 1">
    </Pdo>
    <Pdo Entry="6010:7" Name="Fault channel 2">
    </Pdo>
    <Pdo Entry="6020:7" Name="Fault channel 3">
    </Pdo>
    <Pdo Entry="6030:7" Name="Fault channel 4">
    </Pdo>
    <Sdo Entry="800d:11" Size="2" Group="SDOs" Name="Input Type channel 1">          
       <DataType>INT16</DataType>
    </Sdo>
    <Sdo Entry="801d:11" Size="2" Group="SDOs" Name="Input Type channel 2"> 
       <DataType>INT16</DataType>
    </Sdo>

Now that the SDO is mapped it can be changed by using for instance the MOTORCOREX-Desk. IN case of the EL3174 analog input card, entering a value of 20 (decimal, it corresponds to hex 14), the module will use the 4…20mA input range. Changing the value to 2 (which is also hex 2), will change the input back to -10…10V. The values correspond to the content of the mailbox file. In the example configuration above the EL3174’s fault signals (PDO’s) are also mapped to MOTORCORTEX. When the channel is now configured for 4..20mA and no cable is connected to the input the “Fault channel 1” signal will become high (because when no cable is connected the input signal will be out of the sensor range). Also a red led will turn on the input module, indicating the fault.

Note that SDOs are still not updated cyclically. They only are updated via a mailbox command. MOTORCORTEX sends a mailbox update request package automatically when a SDO value is changed through the Parameter Tree. A read action of all SDOs can also be triggered by triggering the read_sdos input of the Domain in the Parameter Tree (setting it to a value of “1”). If this is done through the MOTORCORTEX-Desk, setting the read_sdos to 1 will not be visible; the server application immediately resets it back to “0” when the request is received.

If the recover_sdo parameter is set to 1, an SDO read request is automatically sent during startup and recovery of a lost connection.

Advanced EtherCAT configuration

EtherCAT Domain Errors

The MOTORCORTEX Parameter Tree also shows if a Domain has an error. The error output becomes true if there is an error. And error can be cause by a domain being disconnected or a problem with a slave in this domain.

There are two parameters that can be configured to change the behavior of the error output:

  • error_delay_sec; time is seconds before the error output becomes true (1) after an error is detected
  • no_error_delay_sec; time in seconds the error output becomes false (0) after the error is resolved.

EtherCAT slave Status

An EtherCAT slave module has different states. Every state allows different functions to be accessible or executable. The EtherCAT master can switch the slaves to different states.

The following EtherCAT Slave States are defined:

  • Init (INIT)
  • Pre-Operational (PREOP)
  • Safe-Operational (SAFEOP)
  • Operational (OP)
  • Bootstrap (BOOT)

For information on the meaning of the states see “EtherCAT and EtherCAT-P Slave Implementation Guide".

The slaves current state can be checked by issueing the following command on the controller:

ethercat slaves

The response of this command should be similar to:

0  0:0  OP  +  EK1100 EtherCAT Coupler (2A E-Bus)
1  0:1  OP  +  EL1018 8K. Dig. Eingang 24V, 10�s
2  0:2  OP  +  EL2008 8K. Dig. Ausgang 24V, 0.5A
3  0:3  OP  +  EL3104 4K. Ana. Eingang +/-10V Diff.
4  0:4  OP  +  EL4134 4K. Ana. Ausgang -10/+10V. 16bit
5  0:5  OP  +  EL3174 4K. Ana. Eingang  +/-10V Diff., +/-20mA SingleEnded, 16bit

where the third column shows the EtherCAT slave state.

When a MOTORCORTEX control application starts it will put all the slaves into Operational state.

!! TBD Distributed Clocks !!

!! TBD FsoE slaves !!

4 - Motorcortex-GRID

A explanation of how to work with Motorcortex Grid

Introduction

Motorcortex Grid is a web-based application that is used to create a custom GUI’s (graphical user interface) for your application. A GUI can be saved as a .grid file. Changing a .grid file has to be done using Motorcortex Grid with acces to motorcortex.io.

⚠ Using MotorCortex-grid all parameters of the running control system are accessible and may be modified. Changing parameters may cause unpredictable or unstable machine behavior and may cause danger to personnel or cause damage to the machine or its surroundings. The tool should only be used by system experts that have detailed knowledge of the system and that know what the impact of parameter changes is.

Quick Video - creating an HMI in under 2 minutes

Screen Layout

The Motorcortex-GRID build environment screen layout contains the following main elements:

  • Widget Library: In the Widget Library you can select the components (Widgets) you would like to add to your Screens.
  • Top Menu Bar In the Navigation bar you can open the library, preview your GUI and check your connection.
  • Properties Panel In the Properties Panel you set the properties of your Widgets and Screens.
  • Screens Area A user interface may have multiple screens. Each screen may contain Widgets.

4.1 - Top Menu Bar

A explanation of how to work with Motorcortex Grid

The Top Menu Bar

On the top of the application you can find The Top Menu Bar contains a couple of buttons that are used to create a GUI.

Button Description
Library Shows the Widget Library
Parameters Shows the Parameter Tree of your connected Machine. This button will not be available when you are not connected to a Machine.
Undo Undo your last action
Redo Redo your previous action
Deploy Deploy this GUI to a Machine. See Deploying a GUI
Preview Open the current GUI in Preview mode
Connection Here you can edit your current Machine connection. See Connection Pop-up

Deploying a GUI

If you press the Deploy button in the Top Menu Bar a new window is opened where you can enter the ip address of the Machine you would like to deploy this GUI to. Pressing the Deploy Button will start the deploy action. When the GUI is deployed, the system also checks of the current GRID release on the Machine is up-to-date. If a newer version of GRID is available, you have the option to update the GRID release on the Machine.

Deployment-Menu

Connection Pop-up

In the connection menu you can set up the connection with your Machine.

Connection-Menu

Bar Description
Host The Machine’s IP address.
Request Port to use for the Request/Reply connection (default 5568)
Subscribe Port ti use for the Subscribe connection (default 5567).
Username The User Name used to log in to the Machine
Password Your Passowrd
Secure Check this checkbox is you want to use secure connection (your browser will need the certificate that matches your Machine (server) certificate to be able to connect)

4.2 - Properties Panel

A explanation of how to work with Motorcortex Grid

The Properties Panel

On the right side of the application you will find the Properties Panel, this is where you configure all your grid elements. The Properties Panel also changes with each selected element in the grid. per default and by clicking the grid the Properties Panel will show the following menus:

Button Description
Client Connection Settings Will open and collapse Client connection settings menu.
Errors Will open and collapse Errors settings menu.
States Will open and collapse States settings menu.
Logs Will open and collapse Logs settings menu.
Screen Will open and collapse Screen settings menu.
Raster Will open and collapse Raster settings menu.

Client Connection Settings

In the Client Connection Settings menu you can set up the connection with your controller.

Client Connection Settings

Bar Description
IP address bar In the IP address bar you have to fill in your controllers local IP.
Request In the Request bar you fill in your Request/Reply channel port number by default this value is 5568.
Reveive In the Reveive bar you fill in your Publish/Subscribe channel port number by default this value is 5567.
Username In the User name bar you fill in your user name.
Password In the Password bar you fill in your password.
Secure With the Secure check box you can realize a secure connection.
Autologin With the auto-login check box you make the controller automatically re-login every time you connect.

Errors

In the Errors Settings menu you can manage the visualization of your errors. These settings are used in the Error handler located in The Grid.

Client Connection Settings

Bar Description
Errors Path Bar In the Path bar you select the path in the parameter tree to your error handler parameter. Per default this parameter is root/Logic/activeErrors.
Errors Acknowledge Bar In the Acknowledge bar you can select the path in the parameter tree to your acknowledge parameter. Per default this parameter is root/Logic/guiFaultAcknowledge.
Error Codes Bar In the Error codes bar you can select the .json file with your error codes.
Definitions Bar In the Definitions bar you can select the folder containing the error definitions.

Error Codes

The Error Parameter provides a Error number. This number can be linked to a file .json file created by the user to show text. Below is a template that gives an example of a errors.json file:

{
  "0": "SYSTEM_OK",
  "100": "WA_SYSTEM_WARNING",
  "101": "WA_REALTIME_VIOLATION",
  "500": "ES_SYSTEM_ERROR",
  "700": "SD_SYSTEM_ERROR",
}

This section will not cover how to set up a system error structure.
Learn how to create .json files in motorcortex.io here

Error Definitions

It is also possible to give definitions to errors. This can be done by putting .html files in the selected Errors folder. a template for the .html files inside this folder is given below:

{
<h1>100: Warning System Warning</h1>

<h2>Description</h2>
<p>Generic System Level Warning (used only for debug purposes)</p>
<!--
<h2>Cause</h2>
<ol>
<li>To Be Determined</li>
</ol>

<h2>Remedy</h2>
<ol>
<li>To Be Determined</li>
</ol>
-->
}

It is recommended to also put a deafault.html file inside the Errors folder for debugging purposes:

<h1>No error description available.</h1>
<p>Please consult the troubleshooting manual for more information.</p>

States

In the Client Connection Settings menu you can manage the visualization of your system states.

States

Bar Description
Path In the Path bar you select the path in the parameter tree to your state parameter. Per default this parameter is root/Logic/state.
State Codes In the State Codes bar you place the .json file with your state codes.

State Codes

The state parameter provides a state number. This number can be linked to a .json file file created by the user to show text. Below is a template that gives an example of a states.json file:

{
  "0": "INIT_S",
  "1": "OFF_S",
  "2": "DISENGAGED_S",
  "4": "ENGAGED_S",
  "7": "ESTOP_OFF_S",
}

This section will not cover how to set up a system state structure.
Learn how to create .json files in motorcortex.io here

Logs

the log keeps track of what is going on in the system and can be used for debugging purposes.

logs

Bar Description
Path In the Path bar you select the path in the parameter tree to your log parameter. Per default this parameter is root/Logic/logOut.

Screen

In the Screen Settings menu you can manage the visualization of your screens a GUI can have multiple screens.

Screen

Bar Description
Title In the Title bar you can change the title of your screen.
Start screen In the Start Screen bar you can choose the initial start screen.
delete With the Delete button you can delete a screen. A message will make you confirm deletion.
Visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your screen show up. Per default no path screen will always make a screen show up. It is not possible to change visibility for the start screen.
Slot
Freq divider In the frequency divider you can adjust the screen update rate. The initial value freq divider value is 100.
Group with a Group you can specify a group of parameters used for this screen. For you will find more information about this Here
W In the Width screen you can define the with of all screens. The initial value for the width is 800.
H In the Height screen you can define the with of all screens. The initial value for the Height is 600.
Foreground In the Foreground color you can select the color you want for the foreground of your grid in hex value. The initial value for the hex value is #323c4e.
Background in the Background color you can select the color you want for the Background of your grid in hex value. The initial value for the hex value is #28303e.

Raster

In the Raster Settings menu you can manage the visualization of your raster to aid in placing components.

Raster

Bar Description
Color In the Raster color you can select the color you want for the Raster of your grid in hex value. The initial value for the hex value is #3c475d. The raster does not show up in a finished GUI.
W In the Width bar you can define the width the raster. The initial value for the width is 30.
H In the Height bar you can define the Height the raster. The initial value for the Height is 30.
Show With the Show check box you can make the raster visual.
Snap With the Snap check box you can make the components inside the grid snap to the raster.

4.3 - Screens

Create highly interactive user interfaces.

Motorcortex-GRID is a tool to design and deploy highly interactive Human-Machine interfaces (HMI) for MOTORCORTEX applications. GRID has many visualization Widgets that can be placed on a Screen. A HMI can have multiple Screens, that are accessible via the top menu bar.

Screens

The User interface is organized into Screens. A Screen provides a canvas to place your Widgets on. Available Screens are shown in the Top Bar, you can click on the top bar to select the desired Screen.

Widgets can be dragged and dropped onto a Screen from the Library. Properties of the Screen or the selected widget are shown on the right.

Bar Description
Add Screen Button With the Add screen button you can add screens to your GUI.
Edit Screen Button With the Edit Screen Position button you can change the order of your screens.
Screen Button By clicking the screen button the selected screen will be shown.
Time Indicator The Time Indicator will show the controller time. You can find how to change the controller time here.
State Indicator The State Indicator will show the Machine State.
Error Handler Button The Error Handler button will Expand and Collapse the Error Handler screen.

Error Handler Screen

The Error Handler Screen will show the system errors and system logs.

Error Handler Screen

Bar Description
Errors System errors will show up here. Errors can be defined by the user. See Errors Codes to learn how to create your own error codes.
Acknowledge By pressing the acknowledge button the user has confirmed and resolved the error.
Logs Here you can see the system logs.

4.4 - Widget Library

A explanation of how to work with Motorcortex Grid

The Widget Library

On the left side of the grid application you will find the Widget Library.

Widget Description
vButton Will add a Button to the Grid
vSwitch Will add a Switch to the Grid
vLight Will add a Indicator Light to the Grid
vLabel Will add a Label to the Grid
box Will add a 3D image to the Grid
vMiniPlot Will add a mini plot to the Grid
vDataPlot Will add a data plot to the Grid
vDivider Will add a divider to the Grid
vOutput Will add a Output to the Grid
vRange Will add a Range slider to the Grid
vInput Will add a Input to the Grid
vImage Will add a Image to the Grid
vHtml Will add a HTML object to the Grid
vFileList Will add a File list to the Grid
vMeter Will add a Meter indicator to the Grid
vJoystick Will add a Joy-stick to the Grid
vGeometry Will add a Geometry to the Grid
vProgram Will add a menu to create a program to the Grid
vCamera Will add a camera screen to the Grid

Input Widgets

Input widgets are used to change parameters in the parameter tree to control your system.

⚠ Using Motorcortex-grid all parameters of the running control system are accessible and may be modified. Changing parameters may cause unpredictable or unstable machine behavior and may cause danger to personnel or cause damage to the machine or its surroundings. The tool should only be used by system experts that have detailed knowledge of the system and that know what the impact of parameter changes is.

Button

When a Button is selected the Inputbox on the right of the screen will start showing the button properties.

Button
Button Settings

Bar Description
PATH This is where you configure the linkage of the parameter you want to manipulate.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches. The raw parameter is called x
label The text inside the button can be changed by changing the label text.
value on The on value can be changed by the user to create a Binary button or set a parameter to a decimal number. Per default buttons are binary.
value Off The on value can be changed by the user to create a Binary button or set a parameter to a decimal number in the off position. Per default buttons are binary.
send Rate The Send Rate determines how many times per second a signal will be send from the button.
font Size The font size determines the size of the text inside the element. This also determines the height of the button.
background The color of the button can be changed by changing the background color.
sticky The Sticky check box makes it possible to create a button that can be only used when the parameter does not change this is handy if a reply of a action is needed.
width The Width of a element is defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

Switch

When a switch is selected the Inputbox on the right of the screen will start showing the switch properties.

Switch
Switch Settings

Bar Description
PATH This is where you configure the linkage of the parameter you want to manipulate.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
value on The on value can be changed by the user to create a Binary button or set a parameter to a decimal number. Per default buttons are binary.
value Off The on value can be changed by the user to create a Binary button or set a parameter to a decimal number in the off position. Per default buttons are binary.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

Range

When a Range is selected the Inputbox on the right of the screen will start showing the range properties.

Range
Range Settings

Bar Description
PATH This is where you configure the linkage of the parameter you want to manipulate.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here.
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
FILTER
gain With the gain you can define the gain for the range slider.
offset With the offset you can define a offset for the range slider.
unit Here you can define the units shown in the range slider.
label Here you can define the label/name of your range
min The Min Value is the minimum value that can be selected within the range.
max The Min Value is the maximum value that can be selected within the range.
step The Step size determines the size of steps within the range.
decimals The decimals you can choose how many decimals are shown within the range.
update on The update on options make it possible to update the selected value within the range directly on movement or on release.
width The Width of a element is defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

Joystick

When a joystick is selected the Inputbox on the right of the screen will start showing the range properties.

Joystick
Joystick Settings

Bar Description
PATH HORIZONTAL This is where you configure the linkage of the parameter you want to manipulate.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here.
PATH VERTICAL This is where you configure the linkage of the parameter you want to manipulate.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here.
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
direction With the direction options you can select what kind of joystick you prefer: only horizontal, only vertical, or for both directions.
send Rate The Send Rate determines how many times per second a signal will be send from the Joystick.
nudge Horizontal A nudge is a arrow on the outside of the joystick. With this bar you can determine the value the joystick will send when pressing a horizontal nudge.
nudge Vertical A nudge is a arrow on the outside of the joystick. With this bar you can determine the value the joystick will send when pressing a vertical nudge.
deadzone The dead zone is the zone of the joystick were it will not respond when dragging it.
radius The radius of the joystick determines the size of the joystick.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

Input

When a input is selected the Inputbox on the right of the screen will start showing the range properties.

Input
Input Settings

Bar Description
PATH This is where you configure the linkage of the parameter you want to manipulate.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here.
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
FILTER
gain With the gain you can define the gain for the input.
offset With the offset you can define a offset for the input.
unit Here you can define the units shown in the input.
step The step size determines the step size of the + and - button in the Input.
font Size The font size determines the size of the text inside the element.
font Weight The min value is the minimum value that can be selected within the range.
line Height The Line height determines the height of the input box.
decimals The amount of decimals shown can be determined by changing this value.
min The min value is the minimal value possible for this input. If no value is defined there is no minimal value.
max The max value is the maximum value possible for this input. If no value is defined there is no maximum value.
width The Width of a element is defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

Output Widgets

Light

When a input is selected the Inputbox on the right of the screen will start showing the range properties.

Light
Light Settings

Bar Description
PATH This is where you configure the linkage of the parameter you want to manipulate.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here.
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
label The text shown in a element can be changed by changing the label.
font Size The text size of a label can be changed by the font size.
line Height The Line height determines the height of the light box.
color On The color when the light is on is determined in this color box.
color Off The color when the light is off is determined in this color box.
width The Width of a element is defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

Meter

Meter
Meter Settings

Bar Description
PATH This is where you configure the linkage of the parameter you want to manipulate.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here.
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
orientation The meter can be oriented Horizontally or Vertically.
show Value The value inside of the meter can be shown continuously by checking the Show Value check box.
decimals The amount of Decimals of the shown value is determined here.
size The size of the meter can be defined here.
MIN
input For the input you can determine if it is either a static value or a path.
value Here you determine what the minimum value of the brake is.
color Here you determine the color of the meter brake.
show Label The show label check box makes it possible to show the minimum value of a brake.
BREAK 1
input For the input you can determine if it is either a static value or a path.
value Here you determine what the minimum value of the brake is.
color Here you determine the color of the meter brake.
show Label The show label check box makes it possible to show the minimum value of a brake.
BREAK 2
input For the input you can determine if it is either a static value or a path.
value Here you determine what the minimum value of the brake is.
color Here you determine the color of the meter brake.
show Label The show label check box makes it possible to show the minimum value of a brake.
BREAK 3
input For the input you can determine if it is either a static value or a path.
value Here you determine what the minimum value of the brake is.
color Here you determine the color of the meter brake.
show Label The show label check box makes it possible to show the minimum value of a brake.
BREAK 4
input For the input you can determine if it is either a static value or a path.
value Here you determine what the minimum value of the brake is.
color Here you determine the color of the meter brake.
show Label The show label check box makes it possible to show the minimum value of a brake.
BREAK 5
input For the input you can determine if it is either a static value or a path.
value Here you determine what the minimum value of the brake is.
color Here you determine the color of the meter brake.
show Label The show label check box makes it possible to show the minimum value of a brake.
Max
input For the input you can determine if it is either a static value or a path.
value Here you determine what the minimum value of the brake is.
color Here you determine the color of the meter brake.
show Label The show label check box makes it possible to show the minimum value of a brake.
x The X position of a element is defined here.
y The Y position of a element is defined here.
x The Z position of a element is defined here.

Miniplot

Button
Button Settings

Bar Description
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
frequency divider With the frequency divider you can reduce the rate at which the server publishes its data. The server update rate is divided by this value; e.g. if the server has an update rate of 1000 Hz, a frequency divider of 100 will make the publisher send only every 100th sample, resulting in an update rate of the received data of 10 Hz.
time range The Time Range of the mini plot can be defined here.
y min The minimum Y value is determined here.
y max The maximum Y value is determined here.
PATH 1
color Here you determine the color of your plot line.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here.
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
PATH 2
color Here you determine the color of your plot line.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here.
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
PATH 3
color Here you determine the color of your plot line.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here.
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
PATH 4
color Here you determine the color of your plot line.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here.
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
PATH 5
color Here you determine the color of your plot line.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here.
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
width The Width of the Mini plot can be defined here.
height The Height of the Mini plot can be defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

Dataplot

Button
Button Settings

Bar Description
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
title The title of the Plot can be defined here.
data Here you can choose your .csv or .json file containing the data for the plot.
xcol In the xcol you determine the column-index from the .csv or .json file to be shown as the x-axis of the plot. E.g. 0
ycol In the ycol you determine the column-indices from the .csv or .json file to be used for the values on the y-axis of the plot. E.g. [1,2,3]
xlabel The text inside the button can be changed by changing the label text.
ylabel The min value is the minimum value that can be selected within the range.
autoscale Y The Auto scale check box makes it possible to automatically scale the Y axis of the plot.
rangeslider X The step size determines the size of steps within the range.
y min The minimum Y axis value for the plot is determined here.
y max The maximum Y axis value for the plot is determined here.
plotstyle See the documentation of Plotly https://plotly.com/javascript/reference/layout/
plotlayout See the documentation of Plotly https://plotly.com/javascript/reference/layout/
refresh every Here you select how many times the plot gets refreshed per seconds.
show legend The Show legend check box makes it possible to turn on or off the legend of the plot.
color Here you determine the color of your plot line.
width The Width of a element is defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

Output

Button
Button Settings

Bar Description
PATH This is where you configure the linkage of the parameter you want to manipulate.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here.
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
map Here you can select the .json file that provides a mapping between the parameter value and a string.
unit Here you can define the output unit string.
decimals
color
font size The text size inside the output can be changed by changing the font size.
font weight The font weight can be changed here to: bold.
allign Here you can select the alignment of the output text to the left/center or right.
line height Here you can determine the line height of the output element.
hexadecimal By checking the hexadecimal box you can have the output shown as a hexadecimal number.
width The Width of a element is defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

3D

Button
Button Settings

Bar Description
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
frequency divider With the frequency divider you can reduce the rate at which the server publishes its data. The server update rate is divided by this value; e.g. if the server has an update rate of 1000 Hz, a frequency divider of 100 will make the publisher send only every 100th sample, resulting in an update rate of the received data of 10 Hz.
time range The Time Range of the mini plot can be defined here.
model Here you select your 3D file inside From your project inside Motorcortex.io
PAIR GEOMETRY Pair this widget with the geometry widget to visualize geometry items in this 3D widget.
width The Width of a element is defined here.
height The Height of a element is defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

Image

Button
Button Settings

Bar Description
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
PATH This is where you configure the linkage of the parameter you want to manipulate.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here.
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
file Here you can choose the file you want to be shown in your user interface.
json index Here you can select the .json file that provides a mapping between the parameter value and a image.
width The Width of a element is defined here.
height The Height of a element is defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

Camera

Button
Button Settings

Bar Description
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
subsctiption group In the Path bar you select the path in the parameter tree to link with this element.
Camera size
Camera resolution
Camera image
frequency divider The text inside the button can be changed by changing the label text.
use webcam Checking the Use Web cam box will make automatically use of the users web cam (make sure you allow your computer to do this.)
show FPS Checking the Show FPS box will how how much Frames Per Second are shown inside the Camera element.
width The Width of a element is defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

Other Widgets

Divider

Button
Button Settings

Bar Description
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
horizontal In the Path bar you select the path in the parameter tree to link with this element.
color The color of the divider can be changed by clicking this box
size The Width of a element is defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

HTML

HTML
HTML Settings

Bar Description
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
html In the Path bar you select the path in the parameter tree to link with this element.
font size The text size inside the output can be changed by changing the font size.
font weight The font weight can be changed here to: bold.
line height Here you can determine the line height of the output element.
background Here you can define the background color of your HTML element.
color The text inside the button can be changed by changing the label text.
width The Width of a element is defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

File List

Button
Button Settings

Bar Description
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
folder Url The URL of the folder that contains the files to be shown in the list. The list must be provided by the web server in json format. In NGINX you specify this by adding the following attributed to the location section of your folder: location /log { autoindex on; autoindex_format json; }
show date If enabled, shows the creation date of the file
show size If enabled, shows the size of the file. If you specify the nginx attribute “autoindex_exact_size off;", the size will be shown in in compact form (e.g. “1.2 Mb”).
width The Width of a element is defined here.
height The Height of a element is defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

Geometry

Button
Button Settings

Bar Description
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
pair program Pair this widget with the program widget to be able to add geometry point) to your program.
cart path Path to the actual Cartesian tool coordinates. When the Teach button of the widget is used these coordinates are sowed into the geometry point (usually: root/Control/actualToolCoordinates)
joint path Path to the actual joint coordinates. When the Teach button of the widget is used these coordinates are stored into the geometry point (usually: root/Control/actualJointPositionsFiltered)
mode command path Path to the mode command (usually: root/Logic/modeCommand)
semiAuto path Path to the signal to activate Semi-auto mode: (usually: root/Control/activateSemiAuto)
semiAuto target path Path where the Semi-auto move will move to, when using the MovoTo button. (usually: root/Control/semiAutoMotionGenerator/target)
background color The background color
width The Width of a element is defined here.
height The Height of a element is defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

Program

Button
Button Settings

Bar Description
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
PAIR GEOMETRY Pair this widget with the geometry widget to be able to add geometry point) to your program.
current command ID path The path to the current Motion Interpreter Command (usually: root/MotionJSInterpreter/currentCommandId)
current program ID path The path to the current Motion Interpreted Program (usually: root/MotionJSInterpreter/currentProgramId)
storage folder This is the location where Programs are stored relative to the current project path. (usually: /programs)
width The Width of a element is defined here.
height The Height of a element is defined here.
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

ColorPick

Button
Button Settings

Bar Description
PATH This is where you configure the linkage of the parameter you want to manipulate.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path In the Path bar you select the path in the parameter tree to link with this element.
channel If a selected parameter is a array you can select the desired channel of the array here
VISIBILITY This is where you configure the visibility of the this element.
visibility In the Visibility bar you can select the Parameter in the Parameter tree that will make this your element show up. Per default no path will always make a element show up.
prefix In the prefix you fill in the path of a parameter. A prefix is mainly useful for editing multiple paths of parameters.
path This Path manipulates the visibility of the element and can be selected from the parameter tree.
channel If a selected parameter is a array you can select the desired channel of the array here
expression With the expression you can manipulate the presentation of the output For example convert Meters to Inches (The raw parameter is called x).
x The X position of a element is defined here.
y The Y position of a element is defined here.
z The Z position of a element is defined here.

4.5 - Special Files

Introduction

It is possible to create complete custom GUI using motorcortex grids. To do this some special files are needed in the project folder to deploy to the Motorcortex controller. This section will show how to make and customize these special files.

4.5.1 - 3D-Models

Adding a 3D Model (Digital Twin) to GRID

Video Tutorial

See how easy it is to create and link a 3D model to a MOTORCORTEX application:

Introduction

The GRID 3D widget supports 3D models in GLTF format. GLTF is an open 3D format maintained by the Khronos Group. More information on the format can be found here: https://www.khronos.org/gltf/.

A lot of 3D modeling and CAD tools support exporting a model in GLTF format natively and these models can be use in the 3D widget directly.

A couple of guidelines are important to make the 3D model work properly:

  1. Binary output format (.glb) is preferred because of more efficient storage and smaller file sizes.
  2. Model size should be below 10 MB for optimal performance on lower end devices like tablets.
  3. Enabling shadows are expensive (cost a lot of computing power), especially when using complex scenes.
  4. Make sure your model has the Z-axis pointing up, also make sure the exporter keeps the z-axis up (some exporters make the y-axis point up). The 3D widgets camera navigation relies on this “z is up” convention to function properly.

Creating 3D models with Blender

Blender is an extremely capable open-source 3D modeler that is ideal for creating 3D models for use in GRID. You can download Blender for your favorite platform from the Blender website: https://www.blender.org/. Here you can also find excellent modeling tutorials that help you get started.

When modeling a Digital Twin in Blender there are some important guidelines:

  1. The GLTF exporter currently silently renames objects that contain spaces or other special character (like period (".")). This is a problem for objects that you want to link later to motorcortex parameters. Especially avoid putting spaces in Object names, since this will have unexpected results in the 3D view. Periods are okay, but you need to know that they are removed in the GLTF export; “Cube.001” will become Cube001 in the GLTF file.
  2. In GRID all transforms are done in the object’s local axis frame.
  3. You can connect your objects together by “parenting” them, the child has then a local axis frame that moves together with its parent object.
  4. Make sure your object Origin is located at the desired rotation point. One way to change an objects origin in Blender is to first position the 3D Cursor at the desired location and then “Origin to 3D Cursor” from the Object menu.
  5. Also make sure to “Apply Rotation” and “Apply Scale” to all your moving objects to avoid some strange behavior later.
  6. When exporting to GLTF from Blender, make sure the “+Y Up” in the “Transform” section of the exporter settings is Off.
  7. If you are using Object Modifiers, make sure you select “Apply Modifiers” in the “Geometry” section of the GLTF Exporter.

Using a GLTF file in GRID

To use a GLTF file in the GRID 3D Widget the following steps are required:

  1. Upload your GLTF file(s) in either .gltf or .glb format to your project. You can place you models in a subfolder if that is preferred.
  2. Create a new JSON configuration file, specifying some additional properties of the objects and linking object properties to MOTORCORTEX parameters. See below for an example. You can download the JSON schema here v-3d-schema.json. In the JSON you can add references to your model files that should be loaded by the 3D widget.
  3. In GRID, add a 3D widget to your canvas and in the “model” property select the JSON file.

Here is an example of a minimalistic JSON file:

{
  "files": [
    {
      "file": "cube.glb"
    }
  ],
  "objects": [
    {
      "name": "Cube",
      "links": [
        {
          "link": "root/Control/dummyDouble",
          "axis": "rz"
        }
      ]
    }
  ]
}

An example of a more complex JSON file:

{
  "files": [
    {
      "file": "scenery.glb",
      "name": "scenery"
    },
    {
      "file": "robot.glb",
      "name": "robot"
    }
  ],
  "camera": "Camera",
  "cameraLookAt": {
    "x": 0.0,
    "y": 0.0,
    "z": 0.5
  }
  "hemisphereLight": {
    "intensity": 0.8
  },
  "spotLight": {
    "x": 1,
    "y": 1,
    "z": 5.8,
    "castShadow": true,
    "angle": 0.5,
    "intensity": 0.2,
    "penumbra": 1.5
  },
  "traceLine": [
    {
      "link": "root/Control/actualToolCoordinates",
      "channel": 0,
      "axis": "x"
    },
    {
      "link": "root/Control/actualToolCoordinates",
      "channel": 1,
      "axis": "y"
    },
    {
      "link": "root/Control/actualToolCoordinates",
      "channel": 2,
      "axis": "z"
    }
  ],
  "objects": [
    {
      "name": "Floor",
      "receiveShadow": true,
      "castShadow": false
    },
    {
      "name": "Base",
      "receiveShadow": false,
      "castShadow": true
    },
    {
      "name": "Link1",
      "castShadow": true,
      "links": [
        {
          "link": "root/Control/dummyDoubleArray6",
          "channel": 0,
          "axis": "rz"
        },
        {
          "link": "root/Control/dummyDoubleArray6",
          "channel": 4,
          "axis": "opacity",
          "gain": 1,
          "value": 1
        },
        {
          "link": "root/Control/dummyBool",
          "axis": "visible"
        }
      ]
    },
    {
      "name": "Link2",
      "links": [
        {
          "link": "root/Control/dummyDoubleArray6",
          "channel": 1,
          "axis": "rz"
        }
      ],
      "castShadow": true
    }
  ]
}

4.5.2 - Output to Text Map

A file to map a value to text for an Output Widget

4.6 - GUI Example

A example for creating a Motorcortex GUI

A Motorcortex gui is loaded from a .grid file. you can create these files in Motorcortex Grids located in the Motorcortex.io portal.