Motorcortex-DESK

A explanation of how to work with Motorcortex Desk

10 minute read

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.

Last modified March 23, 2021: Restructured GRID (44d0658)