1 - Determining software versions and Hardware Key

Motorcortex consists of a number of software components that each have a version associated with them. Sometimes it is necessary to determine the version of the components in a running system to check if updates are available or if dependencies are met.

The hardware key is required when validating licenses. Each host system generates its own unique hardware id. For some motorcortex components a license is required for each hardware id that the system should run on.

To get the Operating System version information and hardware id type this command in a terminal when logged-in to the control system:

cat /etc/issue

Information similar to the following will be shown.

Motorcortex 2021.01[g17f4d5d+1] \n \l

The active license does NOT match the active application

Active license information:
  File: /etc/motorcortex/config/license.pem
  Hardware key: 2651256591846471365
  Modules: mcx-core2, mcx-io2, mcx-math2, mcx-control2, mcx-generic-app2

Active application information:
  File: /usr/local/bin/mcx-generic-app
  Hardware key: 6591555251580943153 mcx-core2 mcx-io2 mcx-math2 mcx-control2 mcx-generic-app2

  Hardware key as QR Code:
  ##################################################################################
  ##################################################################################
  ##################################################################################
  ##################################################################################
  ########              ##  ########  ######          ########              ########
  ########  ##########  ##  ####      ##    ############    ##  ##########  ########
  ########  ##      ##  ##    ####          ##  ##  ##      ##  ##      ##  ########
  ########  ##      ##  ##      ##  ##  ##########      ##  ##  ##      ##  ########
  ########  ##      ##  ####    ##  ##    ##  ####  ####    ##  ##      ##  ########
  ########  ##########  ##      ####        ######  ####  ####  ##########  ########
  ########              ##  ##  ##  ##  ##  ##  ##  ##  ##  ##              ########
  ############################    ##      ####  ########    ########################
  ########    ####      ######  ##  ##  ##            ####  ####  ##        ########
  ########  ####    ################    ####  ########          ##        ##########
  ########    ##    ##  ##      ######  ####  ##      ####      ##  ##  ############
  ########  ########  ##      ####        ####  ##  ####      ####        ##########
  ############  ######  ########  ##        ######  ########  ##    ##  ############
  ############        ##    ##  ##  ##  ########      ##    ######          ########
  ########      ##  ##    ##        ##  ####  ##      ######        ################
  ########  ##      ######  ##    ##  ##  ####  ##  ####  ##  ##    ##  ##  ########
  ########  ##  ######  ##########  ##  ##  ####  ##    ##  ######  ################
  ########        ##  ####      ####  ##  ##    ##  ####  ##              ##########
  ########      ##      ##############  ##    ##        ##  ##  ##    ##  ##########
  ##############  ##  ##  ##    ##          ##  ######        ########  ##  ########
  ##########  ####        ##  ##  ##    ####          ##      ##########    ########
  ########  ####  ##  ########  ##            ##    ##  ##  ##  ##    ##############
  ############            ####      ##  ####      ##  ####    ####    ##############
  ############      ######  ##    ##      ####  ########    ######  ##    ##########
  ########      ####    ##    ####    ##  ##    ##    ####                ##########
  ########################  ##  ####    ########  ####      ######  ##    ##########
  ########              ####    ############  ##  ##  ####  ##  ##    ##    ########
  ########  ##########  ##  ######        ##############    ######  ##  ############
  ########  ##      ##  ##  ##        ####  ####    ####            ######  ########
  ########  ##      ##  ####  ####        ##    ##  ####    ####    ####    ########
  ########  ##      ##  ######    ##########  ##      ##  ######  ##  ##############
  ########  ##########  ##  ##    ##  ##    ############  ####  ##        ##########
  ########              ##  ##        ########    ####  ####    ######      ########
  ##################################################################################
  ##################################################################################
  ##################################################################################
  ##################################################################################

The first line shows the OS version, in this case Motorcortex 2021.01[g17f4d5d+1] \n \l.

Under Active license information you can find the hardware id and where the license file is located.

2 - Ethernet/EtherCAT Bridge-mode

Sometimes it is needed to configure a EtherCAT device via the manufacturers software, while keeping the EtherCAT topology intact (e.g. configuring a drive with integrated safety with the FSoE master located in the GCC). Normally this would mean unplugging the EtherCAT cable from the EtherCAT master and plugging it into a laptop, however in the case of a GCC this would mean opening the cabinet. Since this is laborious action involving opening the GCC, an alternative is made available by switching the MotorCortex Controller into bridge-mode, passing all data from front port “EN” directly to the EtherCAT network.

Switching on Bridge mode

  1. Log into the system from the console (or through ssh):

  1. Login to the system login using the default credentials or the credentials of the system:
  • login: admin
  • password: vectioneer
  1. Now the command line will change to
sudo mcx-bridge on
  1. After this you will be able to scan the EtherCAT network with your manufacturers software (directly via your PC or with an other EtherCAT master device) via the ENET port on the GCC.

⚠ It might be needed to change the network adapter IP settings if you use your PC with the manufacturers software

Switching off Bridge mode

There are two methods to switch off bridge mode and return the control to the MotorCortex Controller:

  1. Restarting the Motion Controller: Push the power button of the GCC to switch off the Motion Controller. Wait for all lights to switch off, before switching it on again.

  2. Directly in the controller (requires keyboard and screen) The controller is not available via SSH, since the system is now in bridge mode. However it is possible to access the console of the controller directly via a keyboard and screen.

sudo mcx-bridge off
  • password: vectioneer

TBD:

⚠ It might be needed to restore the network adapter IP settings to use your PC with MotorCortex again

MCX-bridge options

For more options type

sudo mcx-bridge --help

The current version of mcx-bridge has the following options:

  usage: sudo mcx-bridge on [-s SOURCE] [-t TARGET] [-b BRIDGE] [-i IP/MSK]
    SOURCE: Source device, e.g. eth0 (eth0 = default)
    TARGET: Target device, e.g. eth1 (eth1 = default)
    BRIDGE: Bridge device, e.g. br0  (br0 = default)
    IP/MSK: IP and Mask, e.g. 192.168.2.100/24 (192.168.2.100/24 = default)

  usage: sudo mcx-bridge off [-b BRIDGE] [-s SOURCE] [-i IP/MSK]
    BRIDGE: Bridge device, e.g. br0  (br0 = default)
    SOURCE: Source device, e.g. eth0 (eth0 = default)
    IP/MSK: IP and Mask, e.g. 192.168.2.100/24 (192.168.2.100/24 = default)

3 - Starting/Stopping/Restarting

Normally a Motorcortex application is configured to automatically boot when the machine is powered on. However it may be required for the software to be stopped or restarted in a different mode. This chapter shows how Motorcortex applications can be started, stopped and restarted.

  1. Log into the system from the console (or through ssh):

  1. Login to the system login using the default credentials or the credentials of the system:
  • login: admin
  • password: vectioneer
  1. Now the command line will change to

     mcx-intel:$~
    

You can use standard Linux commands to go trough files and perform Software Maintainance.

⚠ If a Virtual Machine is used it is convenient to put Motorcortex into Simulation Mode to prevent errors because there is no hardware connected.

Running of Motorcortex applications is handled through a system daemon. The daemon can be managed by calling

sudo /etc/init.d/motorcortex start|stop|restart|startsim|restartsim

For instance to switch an already running system to simulation mode execute:

sudo /etc/init.d/motorcortex restartsim

To return back to normal operation run:

sudo /etc/init.d/motorcortex restart

4 - Backup and Restore

The MOTORCORTEX-Imager USB Stick is a bootable USB drive that can be used to create backups and restore images of MOTORCORTEX Systems.

Downloading and flashing the MOTORCORTEX-Imager image to a USB stick

  1. You will need an USB Stick of at least 6Gb and at least 7Gb of free space on your PC.
  2. Download the latest MOTORCORTEX-Imager release: MOTORCORTEX-Imager
  3. Extract the image, so you should have a 6Gb .img file.
  4. On Windows systems, you will need an external tool to write disk images to an USB device. There are several options, one of them is http://unetbootin.github.io. On most Linux distribution s you can just doubleclick on the img file and this will open the Disk Image Writer tool.
  5. Write the image to your USB Drive.
  6. When done, you can mount the stick on your system and copy an existing image file onto the ImageData partition of the stick.

Booting from the MOTORCORTEX-Imager USB stick

The Motorcortex-Imager can be used with a screen and keyboard attached to the controller or over an SSH connection, so no screen and keyboard is necessarily.

Using a Screen and Keyboard

  1. Make sure the controller is switched off.
  2. Insert the Motorcortex-Imager USB Stick into an available USB port of the controller.
  3. Attach a keyboard to one of the USB-ports and a display to the HDMI-port.
  4. Switch the controller on.
  5. If all is correct you will see the something like the picture below:

If above screen does not appear, check the screen and usb connection. If that does not help, check the bios settings of the Motorcortex Controller, it might be that USB stick is not first in the boot order.

Using SSH

  1. Make sure the controller is switched off.
  2. Insert the Motorcortex-Imager USB Stick into an available USB port of the controller.
  3. Switch the controller on.
  4. Give the controller some time to boot. Log in after 20 seconds using a SSH client like Putty, the Linux Terminal or Windows Command Line. Type

ssh tc@192.168.2.100

Log in with password vectioneer.

  1. If all is correct you will see the something like the picture below:

    If above screen does not appear, check network settings and network connection (tip: first try

ping 192.168.2.100

If that does not help, check the bios settings of the Motorcortex Controller, it might be that USB stick is not first in the boot order.

Making a back-up

  1. Type sudo mcx-backup to start the back-up procedure.

  2. Choose which disk you want to back-up. Hard disks and solid state disks usually start with SD.. SD cards and USB sticks with eMMC.

  3. Next choose where you want to store your image:

    1. This is the default option, it stores it on the USB stick (/mnt/usb/), followed by the date and time on the controller + mcx-image.img.xz.
    2. It is also possible to choose your own name and location. Type /mnt/usb/ to store it on the USB stick. Follow this by the name you want to give. End with .img or .img.xz. The .xz means that the file is zipped. It is recommended to use zip, since otherwise the image file will be the size of the disk (in case of the Motorcortex Fitlet2 this is 32GB). If you follow this you will get something like:

    /mnt/usb/2020-04-08_another-image_name.img.xz

  4. Creating a backup image will take some time. You can watch the progress in the console.

  5. When the backup is finished the number of bytes written will be shown. Please check if there are any errors being reported that may indicate that creating the image has failed.

  6. Now you can reboot or poweroff. In case you are done with the back-up and want to go back to the Motorcortex Operating System, type:

    sudo poweroff

  7. Wait for for the system to power off. During this time any cached data is still written to the disk, so no not switch off early.

  8. The system should reboot or power off automatically. At that time remove the USB stick.

  9. Switch on the power again to start the system from the internal storage again.

  10. It is good practice to restore an image to another system or boot the image in a virtual box, to see if the backup went well.

Restoring an image (Cold Start)

This method can be used to install a fresh MOTORCORTEX-OS image or a backup image to your controller.

  1. If the MCX boot stick does not already contain your source image, copy it into the ImageData partition of the USB stick. Supported image file formats are raw image (.img), compressed images (.img.xz) or WIC images (.wic).
  2. Boot from the USB stick and log into the system (see above)
  3. Type sudo mcx-restore -f to start the restore procedure. The -f option will expand the image to use the full disk size, this is useful if you are restoring a truncated image and you wish to use all available disk space on the target system.
  4. Choose which image you would like to restore.
  5. Choose the drive where you want to restore your image to.
  6. Be patient, restoring the image will take some time. When the process is done, check for any errors in the console

make sure that the image will fit on your disk. Otherwise your system may not function properly!

  1. You will get the message Done when the process is finished.
  2. Now you can reboot or poweroff. In case you are done with the back-up and want to go back to the Motorcortex Operating System, type:

sudo poweroff

  1. Wait for 20 seconds for the system to power off.
  2. Switch off the power of the controller.
  3. Remove the USB stick.
  4. Switch on the power again.
  5. Done.

5 - Bios Settings Fitlet2

This chapter tells the bios settings of the Fitlet2 Motorcortex Controller.

These settings make it easier to back-up the system and use other storage devices to boot from.

Setting Fitlet2 Bios settings

  1. Make sure the controller is switched off.
  2. Attach a keyboard to one of the USB-ports.
  3. Start tapping the delete key.
  4. Switch the controller on.
  5. Stop tapping the delete key when the bios menu appears.
  6. In the Main screen Load Optimized Defaults by pressing the F3 key. Select Yes.

  1. Use the arow keys to navigate trough the BIOS. Go to OS Selection hit enter and select Linux.

  1. Go to the Boot screen using the arow keys and go to Boot Options hit enter and set the correct boot options as below:

    1. Go to Boot Option #1 and select USB Key.
    2. Go to Boot Option #2 and select USB HDD.
    3. Go to Boot Option #3 and select USB CD/DVD.
    4. Go to Boot Option #4 and select SD.
    5. Go to Boot Option #5 and select HDD:....

  1. go to the Save & Exit screen.
  2. Press F4 or go to Save Changes and Exit. Select Yes.

6 - Date and time

Setting date and time is important for debugging problems and to correlate data from different sources.

First, set the timezone by replacing the link /etc/localtime with a link that points to the desired timezone:

sudo rm -f /etc/localtime 
sudo ln -sf /usr/share/zoneinfo/Universal /etc/localtime

Replace Universal with your desired region or timezone.

The date and time can be set by executing the following Linux command (as root):

sudo date -s "Mon Mar 15 18:49:40UTC 2019"
sudo hwclock -w

The last line is important because only then the time is set correctly in the hardware clock and is not lost on reboot.

7 - Default File Locations

This page describes where on the Motion Controller Motorcortex related (configuration) files can be found. These are default locations, actual location may vary depending on your setup.

Application Specific Configuration files

Application Specific Configuration files are located in:

/etc/motorcortex/config/

This folder may be a link to a certain application configuration, e.g.:

/etc/motorcortex/config --> /etc/motorcortex/config.myproject

Inside the /etc/motorcortex/config/ folder there are a number of files and folders that hold configuration options:

  • motorcortex.conf; specifies which executable is going to be used and sets some commend line options. This file is used by the init.d script that automatically starts and stops motorcortex applications.
  • config.json; specifies runtime options for the exectuable. This file sets task priorities and can set various options that are used when the application starts.
  • control/; folder that holds control system parameters
  • io/; folder that holds io configuration

License certificates

License certificates for MOTORCORTEX products have to be installed in:

/etc/motorcortex/licenses/

Communication certificates

Communication certificates are installed in:

/etc/motorcortex/config/certificates/

Log files

Log files are created in:

/var/www/motorcortex/log/

or

/var/log/motorcortex/

depending on the system configuration.

8 - Network settings

This chapter will explain how to change the IP address of your controller.

Network adapter configuration

First log in to the controller. Either by connecting a keyboard and screen to the controller or logging in through ssh:

ssh admin@192.168.2.100

Then if you want to reconfigure the controller’s network settings, like changing its IP address do the following.

sudo nano /etc/network/interfaces

Look for the following section in this file:

# Wired or wireless interfaces
auto eth0
iface eth0 inet static
    address 192.168.2.100
    netmask 255.255.255.0
    gateway 192.168.2.100

Change the address and the gateway to the desired values. Save the file and exit.

If you want to modify the system’s hostname you can change it by modyfying /etc/hostname and /etc/hosts.

Restart the network to apply the new settings.

sudo /etc/init.d/networking restart

If you changed IP address while connected to the terminal over the network, your connection will probably be lost after restarting the network.

It is possible that due to the network change the communication certificate has become invalid. For security reasons, the certificate is only valid for the ip address and hostname of the controller. MCX-Linux OS provides a certificate renewal service that checks the certificate and renews it if either it has expired or if the host name or ip address has changed. To renew the certificate, either reboot the controller or restart the cert-gen service:

sudo /etc/init.d/cert-gen restart

Optionally, you can modify the certificate settings by modifying the cert-gen config file:

sudo nano /usr/share/cert-gen/config.json

After your modification restart the service to generate the new certificate.

EtherCAT adapter config

The EtherCAT master needs to know which card it will use for EtherCAT. The EtherCAT network card should not be configured for normal networking.

To change the EtherCAT network settings do:

sudo nano /etc/ethercat.conf

The important settings in this file are which network adapter to use and which driver to use.

You can select your network adapter by modifying the following line:

MASTER0_DEVICE="eth1"

To select the driver type, change the line:

DEVICE_MODULES="generic"

Refer to the EtherLAB documentation for a description of all available configuration options.

9 - Advanced use of disk images

Filling empty space with zeros

To improve compression of image files, the remaining free space of a partision can be filled with zeros before the image is created. Run this on the system to be backed up:

dd if=/dev/zero of=file; rm file

This command uses the low-level dd copy command to write zeros to a file, and when the disk is full and the command exits, removes the file.

Check if the space is actually freed again (file is actually deleted).

df -h

Create an Image from removable media

If the Motorcortex system is installed on a removable drive an image can also be made by attaching the drive to your PC and creating an image directly. Many Linux distributions already have convenient graphical tools to create an image if a disk.

In Ubuntu you can use the Disks tool to create an image file.

Then from the menu select create Disk Image:

Mounting an image

If you need to inspect or modify a partition of an image after the image has been created you can mount it on a Linux System.

First check the partition table of the image file:

fdisk -l image.img

In this case we would like to mount the second partition, which starts at block 1026048. We first need a mount point; and empty folder that will then be the location where the image will be mounted. In this case we use /mnt/image. If that does not exist, create a folder somewhere. Then mount the image:

sudo mount -o loop,offset=$((512*1026048)) image.img /mnt/image

When you are finished inspecting the contents of the image, unmount it.

sudo umount /mnt/image

Compressing an image

This command compresses the image using all available cpus:

xz -v \--threads=0 image.img

The result will be an image.img.xz file, which in Ubuntu can be restored with the Disks tool. if you want to keep the original file:

xz -v -k \--threads=0 image.img

An typical 8 GB image file should compress to about 400 MB if the empty space was first zeroed out.

Uncompressing an image file

Some operations on image files, such as mounting an image to make modifications to it or converting the image to a VirtalBox image require the xz compressed image file to be uncompressed. In Linux this is accomplished by executing the shell command:

unxz -k image.img.xz

the -k option keeps the original compressed file; without this option the compressed file is removed after uncompression.

Restoring an image to a removable disk

You can restore an image to a removable disk (for instance a CFAST card that is attached to your laptop with a card-reader) in Ubuntu by right-clicking the image and choosing “Open With Disk Image Writer” from the context menu:

This also works with xz compressed images directly.

Truncating (resizing) an image

Orignal Article: https://softwarebakery.com/shrinking-images-on-linux

When creating images from existing ISOs you often need to allocate a number of MB for the image to at least fit the files that are in the ISO. Predicting the exact size of the image is hard, even for a program. In this case you will create an image that is larger than actually needed: the image is much larger than the files on the image are combined.

This post will show how to shrink an existing image to a more optimal size. We will do this on Linux, since all required tools are available there: GParted, fdisk, gdisk (for GPT), and truncate.

Requirements

  • A Linux PC
  • Some knowledge how the terminal works will helps
  • The unoptimal image (myimage.img in this example)

Creating loopback device

GParted is a great application that can handle partition tables and filesystems quite well. In this tutorial we will use GParted to shrink the filesystem (and its accompaning partition in the partition table).

GParted operates on devices, not simple files like images. This is why we first need to create a device for the image. We do this using the loopback-functionality of Linux.

First we will enable loopback if it wasn’t already enabled:

$ sudo modprobe loop

Now we can request a new (free) loopback device:

$ sudo losetup -f

This will return the path to a free loopback device. In this example this is /dev/loop0.

Next we create a device of the image:

$ sudo losetup /dev/loop0 myimage.img

Now we have a device /dev/loop0 that represents myimage.img. We want to access the partitions that are on the image, so we need to ask the kernel to load those too:

$ sudo partprobe /dev/loop0

This should give us the device /dev/loop0p1, which represents the first partition in myimage.img. We do not need this device directly, but GParted requires it.

Resize partition using GParted

Next we can load the device using GParted:

$ sudo gparted /dev/loop0

This should show a window similar to the following:

Now notice a few things:

  • In this example, there is only one partition. There may also be a boot partion preceding the main partition.
  • The partition allocates the entire disk/device/image.
  • The partition is filled only partly.

We want to resize this partition so that is fits it content, but not more than that.

Select the partition and click Resize/Move. A window similar to the following will popup:

gparted-02

Drag the right bar to the left as much as possible.

Note that sometimes GParted will need a few MB extra to place some filesystem-related data. You can press the up-arrow at the New size-box a few times to do so. For example, I pressed it 10 times (=10MiB) for FAT32 to work. For NTFS you might not need to at all.

Finally press Resize/Move. You will return to the GParted window. This time it will look similar to the following:

gparted-03

Notice that there is a part of the disk unallocated. This part of the disk will not be used by the partition, so we can shave this part off of the image later. GParted is a tool for disks, so it doesn’t shrink images, only partitions, we have to do the shrinking of the image ourselves.

Press Apply in GParted. It will now move files and finally shrink the partition, so it can take a minute or two, most of the time it finishes quickly. Afterwards close GParted.

Now we don’t need the loopback-device anymore, so unload it:

$ sudo losetup -d /dev/loop0

Shaving the image

Now that we have all the important data at the beginning of the image it is time to shave of that unallocated part. We will first need to know where our partition ends and where the unallocated part begins. We do this using fdisk:

$ fdisk -l myimage.img

Here we will see an output similar to the following:

Disk myimage.img: 6144 MB, 6144000000 bytes, 12000000 sectors
Units = sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disk identifier: 0x000ea37d

      Device Boot      Start         End      Blocks   Id  System
myimage.img1            2048     9181183     4589568    b  W95 FAT32

Note two things in the output:

  • The last partition (in this example there is only one partition) ends on block 9181183 (shown under End)
  • The block-size is 512 bytes (shown as sectors of 1 * 512)

We will use these numbers in the rest of the example. The block-size (512) is often the same, but the ending block (9181183) will differ for you. The numbers mean that the parition ends on byte 9181183512 of the file. After that byte comes the unallocated-part. Only the first 9181183512 bytes will be useful for our image.

Next we shrink the image-file to a size that can just contain the partition. For this we will use the truncate command (thanks uggla!). With the truncate command need to supply the size of the file in bytes. The last block was 9181183 and block-numbers start at 0. That means we need (9181183+1)*512 bytes. This is important, else the partition will not fit the image. So now we use truncate with the calculations:

Additionally (for a GPT) we will leave some free space (say 1Mb = 1048576 (= 1024**2) bytes) at the end of the image for the GPT backup header which we need to fix after truncation.

$ truncate --size=$(((9181183+1)*512+1024**2)) myimage.img

To fix the GPT backup header we use gdisk

(echo r; echo d; echo w; echo y) | gdisk ./myimage.img

Meaning of letters in gdisk:

r	recovery and transformation options (experts only)
d	use main GPT header (rebuilding backup)
w	write table to disk and exit
y	yes to confirm

Converting an image to VirtualBox

If you have a compressed image you first need to uncompress it:

unxz -k -v 2019-03-18-image.img.xz

Then convert it to a VDI image:

VBoxManage convertfromraw 2019-03-18-Vectioneer-v1.0.5-test.img
2019-03-18-Vectioneer-v1.0.5-test.vdi

For using the Virtual Machine see the Virtual Machine user guide.

10 - Installing a License Key

Motorcortex Libraries require a license key to run in a production environment. You can still run your Motorcortex application without a license key, but the program will exit after 30 minutes.

You can check if you have a valid license if you look at your Motorcortex application log:

...
2020-06-08 07:18:21.301 [INFO] Configuration:
Motorcortex-core version: 1.6.3-133-g2accb25_release
Motorcortex-control version: 1.0.8-12-g391134e_release
Motorcortex-math version: 1.0.1-5-g5258e76_release
License is valid
...

In the near future you can request a new license from the motorcortex.io portal. Until then the process involves some manual steps:

  1. Generate a hardware key: {path/to/application} -k This will return a License Key: License key: 12345678910
  2. email this key value to license@vectioneer.com
  3. if you have purchase a license for the required components you will receive a license.pem file.
  4. Copy the license.pem file to the controller into the folder /etc/motorcortex/license/
  5. Restart the application and check the log file again.

11 - Simulation Mode

Sometimes it is desirable to put Motorcortex into simulation mode. this makes it possible to use controlls and tools without the need to connect any physical hardware. this can be done directly on directly on the machine or done using by using SSH from a PC.

Setting Motorcortex into simulation mode

In the comandline of the Motorcortex controller (trough ssh connection or connected directly on the controller).

  1. Go to the /etc/motorcortex/config folder

     cd /etc/motorcortex/config/
    
  2. Open the motorcortex.conf file

     nano motorcortex.conf
    
  3. In the file change

     OPTIONS="-c=/etc/motorcortex/config -l=var/www/motorcortex/log"
    

    to

     OPTIONS="-c=/etc/motorcortex/config -l=var/www/motorcortex/log -s"
    
  4. Press Ctrl+s to save the file and exit editing the file with Ctrl+x

  5. Restart The system

     sudo reboot
    

(it might be needed to use the password to execute this command)

Motorcortex is now in simulation mode.

Exit Motorcortex simulation mode

In the comandline of the Motorcortex controller (trough ssh connection or connected directly on the controller).

  1. Go to the /etc/motorcortex/config folder

     cd /etc/motorcortex/config/
    
  2. Open the motorcortex.conf file

     nano motorcortex.conf
    
  3. In the file change

     OPTIONS="-c=/etc/motorcortex/config -l=var/www/motorcortex/log -s"
    

    to

     OPTIONS="-c=/etc/motorcortex/config -l=var/www/motorcortex/log"
    
  4. Press Ctrl+s to save the file and exit editing the file with Ctrl+x

  5. Restart The system

     sudo reboot
    

(it might be needed to use the password to execute this command)

Motorcortex is now out of simulation mode.

12 - Linking Ethercat Signals

Linking Ethercat hardware signals to Motorcortex.

After connecting and configuring your slave devices it is time to configure and link the slaves to Motorcortex. 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

Before linking and configuring the Ethercat slaves it is necessary to know some basics of how Ethercat works with motorcortex. In Motorcortex there are two files that have to be configured when adding new Ethercat devices:

  • topology.xml
  • master.xml

Creating the topology.xml

The topology.xml 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.

  1. Connect all Ethercat devices that you want to link and configure.

  2. Login to your controller using ssh (having trouble login in check out Remote access to the Motorcortex Computer).

     ssh admin@192.168.2.100
    

Note: the standard password on a motorcortex controller is vectioneer.

  1. Go to the location of the topology.xml file

     cd /etc/motorcortex/config/io
    
  2. Check if your Ethercat devices are connected using the following command.

     ethercat slaves
    

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

    0  0:0  OP     +  EK1914, 2 K. Safety Eingang/Ausgang 24V,  TwinSAFE
    1  0:1  OP     +  EL6910, TwinSAFE PLC
    2  0:2  PREOP  +  EK1110 EtherCAT-Verl�ngerung
    3  0:3  OP     +  EP2316-0003 8 K. Dig. Ein, 10�s, 8 K. Dig. Aus 24V, 0,5A, Diagn
  1. Next the topology.xml has to be updated. but before doing this it is wise to create a backup topology file in case things go wrong. Run the following command to create a copy of the topology file with a different name.

     cp topology.xml topology_backup.xml
    
  2. Now the topology.xml can be updated using the following command.

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.

    sudo ethercat xml > topology.xml

The topology file is now updated to the new configuration of all connected Ethercat devices.

Creating the master.xml basics

The master.xml is used by Motorcortex to generate the EtherCAT folder in the Parameter Tree (more on the parameter tree will follow later in this chapter). Creating the master.xml is a complicated procedure which needs knowlegde about ethercat and rules creating this master.xml. Motorcoterx Link makes this procces a lot easyer and quicker linking and configuring your Ethercat devices. For this example Motorcoterx Link won’t be used. Therefore this chapter will provide the basic knowlege needed to create the master.xml file.

Motorcortex Parameter Tree

In the master.xml the user can define which parameter types are shown in 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 of your Motorcortex application you can use Motorcoterx Desk.

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:

Creating the master.xml

The standard master.xml on a Generic control cabinet will look like this.

TBD

The master.xml has to start with

    <?xml version="1.0"?>
    <Master Type="EtherCAT" Device="0" Name="Ethercat">

and end with

    </Master>

In between these lines you will have to configure the folowing elements:

  • Domains
  • Devices
  • SDO/PDO/MAILBOX

EtherCAT Domains

It is possible to divide EtherCAT IOs in separate domains.

A Domain is an group of EtherCAT slaves (physical cluster of EtherCAT modules). 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.

to open a domain start with:

    <Domain File="topology.xml" Name="Domain Name">

and end with:

    </Domain>

EtherCAT Devices

Devices can be added inside the domains

To add a device start with:

    <Device Id="#" Name="Device name" MapAll="0">

The Id="#" is the position of the ethercat device in the bus and can be found running the following command (The slave Id’ number is in front of every device.).

    ethercat slaves

The Name="Device name" can be a custom name you give to the device.

The MapAll="0" is a function to automatically configure all mandatory SDO and PDO in the device. It can be turned on by setting the value to "1". It is not guaranteed that this function will provide a usable outcome in the Parameter Tree and is vendor dependant.

end a device with:

    </Device>

EtherCAT PDO/SDO/Mailbox

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

PDO (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 (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.

Mailbox.
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.

Configurating SDO/PDO is dificult and vendor documentation in form of a object dictionary or esi.xml is needed to determine what name connects to what PDO/SDO. Some PDO/SDO are mandatory, these must be configured.

To open a pdo start with:

    <Pdo Index="####" Entry="####:##" Group="Group Name" Name="PDO Name" DataType="Datatype">

The Index+"####" of a PDO can be found in vendor documentation or esi.xml.

The Entry="####:##" of a PDO can be found in vendor documentation or esi.xml.

The Group="Group Name" makes it possible to create a group within the device with a custom name.

The Name="PDO Name" makes it possible to create a custom name for your PDO.

The DataType="Datatype"of a PDO can be found in vendor documentation or esi.xml.

end a pdo with:

     </Pdo>

To open a sdo start with:

    <Sdo Index="####" Entry="####:##" Group="Group Name" Name="SDO Name" DataType="Datatype">

The Index+"####" of a SDO can be found in vendor documentation or esi.xml.

The Entry="####:##" of a SDO can be found in vendor documentation or esi.xml.

The Group="Group Name" makes it possible to create a group within the device with a custom name.

The Name="SDO Name" makes it possible to create a custom name for your SDO.

The DataType="Datatype"of a SDO can be found in vendor documentation or esi.xml.

end a SDO with:

     </Sdo>

Master.xml file example

Below is a example of a master.xml file of the generic control cabinet.

Parameter Tree

to check the result:

Save the file

/etc/Motorcortex/config/io/master.xml, 

restart Motorcortex

sudo/etc/init.d/Motorcortex restart 

log in on Motorcortex-Desk (http://192.168.2.100:8000) and check the result.

13 - Back-up and Restore Slave Configurations

Synapticon Somanet Drives

To upload the configuration from connected Somanet slaves first log in to the master controller through ssh.

At the command line, first list the connected slave devices:

ethercat slaves

Then use the correct slave id to upload the configuration file from the slave:

ethercat -p [ID] foe_read config.csv > config-backup-[ID].csv

where [ID] is the slave id. The ethercat command outputs the contents of the file on stdout so this is redirected to a file, in this case config-backup-[ID].csv.

To restore a backup type:

ethercat -p [ID] foe_write -o config.csv config-backup-[ID].csv

Once the file is copied to the drive the drive needs to be told to reload its configuration from the file:

ethercat download -p [ID] -t uint32 0x1011 0x1 0x64616f6c

The value 0x64616f6c hex is actually “load” in ASCII (note that the byte order of the drive is reversed so you are actually sending “daol”.

Ingenia Drives

TBD

Beckhoff Drives

TBD