EtherCAT Master

Introduction

In the context of the I-MECH project, funded by the European Commission under the ECSEL programme, we have ported the SOEM EtherCAT library on ERIKA.
Such experimental support will be soon released in the next stable version of the RTOS. This page explains how to setup and run the provided demo.

Requirements

For running the demo, an x86-64 platform with the following characteristics is needed:

• Supporting hardware-assisted virtualization (i.e. VT-x, VT-D, EPT) and capable of running the Xen hypervisor in HVM mode.
• With an Intel i210 network interface.

Demo

The provided demo assumes the Intel i210 network interface to be connected to a Beckhoff EL2004 EtherCAT slave. The demo has been tested on Advantech ARK-3520P-U7A1E.

To run the provided EtherCAT master demo, follow the next steps:

1. Download the EtherCAT SOEM library for ERIKA3
2. Download the bare-metal x86 toolchain available at this link http://erika-enterprise.com/download/erika3_x86_64_xtools.tar.gz and extract the downloaded archive on a local directory
3. (optional) Put the directory containing the toolchain binaries in the PATH environment variable before running RT-Druid.
4. Run the RT-Druid tool
5. Create a new project by clicking on New → RT-Druid v3 Oil and C/C++ Project as shown in the next Figure:
   

   Figure 1: Create a new RT-Druid project.
6. Name the new project (e.g., mytest) and select the Cross-GCC as shown in the next Figure:
   

   Figure 2: Naming the new RT-Druid project.
7. Check the box for using an existing template and select x86-64 → Xen → EtherCAT SOEM demoas shown in the next Figure:
   

   Figure 3: Selecting the EtherCAT template.
8. Right click the project and select Properties as shown in the following Figure:
   

   Figure 4: Eclipse project properties.
9. Click Oil → Generator properties, enable project specific settings and specify the directory containing the SOEM library for ERIKA3:
   

   Figure 5: Setting the path of the SOEM library.
10. If you didn't put the toolchain in the PATHdirectory, also set the GNU Compiler prefix property to /full/path/x-tools/x86_64-unknown-elf/bin/x86_64-unknown-elf-.
11. Edit the main.c file and set the SLAVE_NB variable for the Bechkhoff EL2004 slave (note that the SOEM library numbers slaves starting from 1).
12. Follow the instructions at this page for building and running the Xen iso image.

Motion control of CiA 402 compliant devices

CiA® 402 refers to CAN in Automation (CiA) CANopen® Drives and Motion Control Profile 402, which standardizes the functional behavior of controllers for servo drives, frequency inverters, and stepper motors.

The profile describes the Finite State Automation (FSA) of the device, where each state specifies the internal/external behavior and the accepted commands:

Figure 6:FSA of CiA402.

The generic CanOpen specification for the automation provides an Object Dictionary, a grouping of objects accessible via the network in an ordered pre-defined fashion. Each object within the dictionary is addressed using a 16-bit index.

The CiA 402 extends the basic dictionary with specific objects and among these we can find Controlword and Statusword.

The Controlword is used to set the required states in the state machine. Object ID is 0x6040 and bits are defined as follows:

Bit	Name	Abbreviation
0	Switch On	SO
1	Enable Voltage	EV
2	Quick Stop	QS
3	Enable Operation	EO
4-6	Operation mode specific	OMS
7	Fault Reset	<F/td>
8	Halt	H
9	Operation Mode Specific	OMS
10	Reserved	R
11-15	Manufacturer specific	MS

The following bits are required when transitioning between states:

Transition		Value (h)	BITS
			0 (SO)	1 (EV)	2 (QS)	3 (EO)	4-6 (OMS)	7 (F)	8-15
15	Fault → Ready to switch on	0x86	0	1	1	0	xxx	1	xxxxxxxx
8/9/0	Non fault → Ready to switch on	0x06	0	1	1	0	xxx	0	xxxxxxxx
3/5	→ Switched on(1)	0x07	1	1	1	0	xxx	0	xxxxxxxx
4/4a	→ Operation enabled	0x0F/0x1F	1	1	1	1	xxx	0	xxxxxxxx

⁽¹⁾ The switched on state is often bypassed by the master

The Statusword provides information that is sent from the drive device back to the controller about the operational status. Object ID is 0x6041 and defined bits are:

Bit	Name	Abbreviation
0	Ready to Switch On	RTSO
1	Switched On	SO
2	Operation Enable	OE
3	Fault	F
4	Voltage Enabled	VE
5	Quick Stop	QS
6	Switch On Disabled	SOD
7	Warning	W
8	Manufacturer Specific	MA
9	Remote	RM
10	Target Reached	TR
11	Internal Limit Active	ILA
12-13	Operation Mode Specific	OMS
14-15	Manifacturer Specific	MS

The following table outlines the Statusword bits and the represented state:

State	Statusword Bits	Functional Meaning
Not ready to switch on	xxxx xxxx x0xx 0000	No CiA mode of operation selected
Switch on disabled(1)	xxxx xxxx x100 0000	No motor torque - drive disabled
Ready to switch on	xxxx xxxx x01x 0001	No motor torque - drive disabled
Switched on	xxxx xxxx x01x 0011	No motor toque - drive disabled
Operation Enabled	xxxx xxxx x01x 0111	Motor has torque - drive enabled
Fault reaction active(1)	xxxx xxxx x0xx 1111	Motor is losing torque - drive disabling
Fault	xxxx xxxx x0xx 1000	No motor torque - drive disabled
Quick stop active(2)	xxxx xxxx x00x 0111	Not implemented

⁽¹⁾ these states are automatically transitioned through

⁽²⁾ quick stop active is not currently implemented

Controlling a CiA 402 drive with Erika + SOEM

Using the SOEM EtherCat library, Erika can control the position of a digital servo motor. Before executing Erika, it is useful to discover the mapping of the foundamentals SDOs (Controlword, Statusword, Current Position and Target Position) into the PDO in order to access them as simple memory in the IOmap provided by the SOEM stack. The latter provides the "slaveinfo" utility which prints the mapping of SDOs into the PDOs. The application must be executed on linux with the -map arguments

 sudo ./slaveinfo <eth_interface> -map

This will print the mapping of SDOs into PDOs. For example a possible mapping could be the following:

 PDO mapping according to CoE :
 SM2 outputs
    addr b   index: sub bitl data_type    name
 [0x0000.0] 0x607A:0x00 0x20 INTEGER32    Target position
 [0x0004.0] 0x60FE:0x01 0x20 UNSIGNED32   Physical outputs
 [0x0008.0] 0x6040:0x00 0x10 UNSIGNED16   Controlword
 SM3 inputs
    addr b   index: sub bitl data_type    name
 [0x000A.0] 0x6064:0x00 0x20 INTEGER32    Position actual value
 [0x000E.0] 0x60FD:0x00 0x20 UNSIGNED32   Digital inputs
 [0x0012.0] 0x6041:0x00 0x10 UNSIGNED16   Statusword

These fields can be easily accessed using the function set_output_int16 and get_input_int16 implemente in the file oshw/erika/oshw.c:

 void set_output_int16 (uint16_t slave_nb, uint8_t module_index, int16_t value)
 {
  	uint8_t *data_ptr;
 
  	data_ptr = ec_slave[slave_nb].outputs;
  	/* Move pointer to correct module index*/
  	data_ptr += module_index * 2;
  	/* Read value byte by byte since all targets can't handle misaligned
     	   addresses */
  	*data_ptr++ = (value >> 0) & 0xFF;
  	*data_ptr++ = (value >> 8) & 0xFF;
 }

 void get_input_int16(uint16_t slave_nb, uint8_t module_index, int16_t *value)
 {
       uint8_t *data_ptr;
        
       data_ptr = ec_slave[slave_nb].inputs;
  	/* Move pointer to correct module index*/
  	data_ptr += module_index * 2;
  	/* Read value byte by byte since all targets can't handle misaligned
     	   addresses */

*value |= ((*data_ptr++) & 0xFF); *value |= ((*data_ptr) << 8) & 0xff00;

 }

In details, the steps to follow are described here:

All the steps described above have been test on the ELMO's Gold duet servo drive:

Figure 6: ELMO Gold Duet 40