Ethercat SoE: Read and write ctrlX DRIVE and/or Indradrive parameters via PLC

Overview Requirements Preparing ctrlX PLC Engineering software IL_ECATSoeRead Read string value Read unit as string value Read real value IL_ECATSoeWrite Write string parameter Write list parameter Notes Realted links

Overview

The goal is to read/write SoE parameters using standard function blocks from CXA_EtherCATMaster library. All the examples in the following are suited for single axis drives, for double axis drives some slight modifications should be done. In using EtherCAT all REAL parameters are managed as scaled INT/DINT parameters. These function blocks are working also with list parameters.

Requirements

ctrlX OS device
Indradrive or ctrlX DRIVE correctly connected via EtherCAT
PLC and EtherCAT app

If you don't know how to setup the EtherCAT bus just follow SoE drive setup

Preparing ctrlX PLC Engineering software

The first operation you need to do is to import the right library: the CXA_ETHERCATMASTER. Inside there are the SoE function blocks together with the examples, this guide is based on the use of them. Every of the following function blocks needs:

The address to a string variable containing the EtherCATmaster master name, usually "ethercatmaster"
The drive EtherCAT address: usually 1001, 1002, ...
The DriveNo: drive number if the drive is multi axis (0, 1, ...)
The Parameter Idn obtained using IL_ECATSoeIdnCoding Function

ctrlX PLC Engineering - CXA_EthercatMaster library - SoE access function blocks

IL_ECATSoeCommand

Here an example of how you can use the IL_ECATSoeCommand FB to clear and set the encoder absolute position is shown. The two parameters are both S parameters then the function IL_ECATSoeCommand takes SOE_S_PARAM as first entry. One executed the function remains active until it goes to "Command Executed" or "Error".

IL_ECATSoeRead

Here an example of how you can use the IL_ECATSoeRead function block to read a P parameter is shown. Differently from the previous, this needs as input also the address and the size of the destination variable.

Read string value

Exemplarily parameter S-0-0095 "Diagnostic message: Text" value is read.

ctrlX PLC Engineering - read S-0-0095 via SoE

Declaration:

// Example B : read a STRING Parameter (S-0-0095)
fbECATSoeRead2  : IL_ECATSoeRead;
rDiagnosis      : IL_ST_SOE_STRING;

Implementation:

// Example B : read a STRING Parameter (S-0-0095)
fbECATSoeRead2.Execute      := NOT (fbECATSoeRead2.Done OR fbECATSoeRead2.Error);
fbECATSoeRead2.MasterName   := ADR(strMasterName);
fbECATSoeRead2.SlaveAddress := uiEtherCatAdress;
fbECATSoeRead2.Idn          := IL_ECATSoeIdnCoding(SOE_S_PARAM,0,95); // = S-0-0095
fbECATSoeRead2.ValueAdr     := ADR(rDiagnosis);
fbECATSoeRead2.SizeOfValue  := SIZEOF(rDiagnosis);
fbECATSoeRead2();
IF TRUE = fbECATSoeRead2.Done THEN
  rDiagnosis.Text[rDiagnosis.ActLength]:=0;    // FB finished. We make zero termination of string.
END_IF
IF TRUE = fbECATSoeRead2.Error THEN
  ; // Error handling
END_IF

Read unit as string value

Exemplarily parameter S-0-0380 "Inverter DC bus: Voltage, actual value" unit is read.

ctrlX PLC Engineering - read S-0-0380 unit via SoE

Declaration:

//Example S-0-0380 "Inverter DC bus: Voltage"
fbECATSoeRead4  : IL_ECATSoeRead;
sS380: IL_ST_SOE_STRING;

Implementation:

//Example S-0-0380: Read Unit
fbECATSoeRead4.Execute      := TRUE;
fbECATSoeRead4.MasterName   := ADR(strMasterName);
fbECATSoeRead4.SlaveAddress := uiEtherCatAdress;
fbECATSoeRead4.Element      := IL_ECAT_SOE_ELEMENT.SOE_ELEMENT_UNIT;
fbECATSoeRead4.Idn          := IL_ECATSoeIdnCoding(SOE_S_PARAM,0,380);
fbECATSoeRead4.ValueAdr     := ADR(sS380);
fbECATSoeRead4.SizeOfValue  := SIZEOF(sS380);
fbECATSoeRead4();
IF TRUE = fbECATSoeRead4.Done THEN
	sS380.Text[sS380.ActLength]:=0; // FB finished value is unit of parameter.
END_IF
IF TRUE = fbECATSoeRead4.Error THEN
  ; // Error handling
END_IF

Read real value

Exemplarily parameter S-0-0380 "Inverter DC bus: Voltage, actual value" value is read.

ctrlX PLC Engineering - read S-0-0380 value via SoE

Declaration:

//Example S-0-0380 "Inverter DC bus: Voltage"
fbECATSoeRead5  : IL_ECATSoeRead;
  iS380: INT;
  rS380: REAL;

Implementation:

//Example S-0-0380: Read value
fbECATSoeRead5.Execute      := NOT (fbECATSoeRead5.Done OR fbECATSoeRead5.Error);
fbECATSoeRead5.MasterName   := ADR(strMasterName);
fbECATSoeRead5.SlaveAddress := uiEtherCatAdress;
fbECATSoeRead5.Element      := IL_ECAT_SOE_ELEMENT.SOE_ELEMENT_OPDATA;
fbECATSoeRead5.Idn          := IL_ECATSoeIdnCoding(SOE_S_PARAM,0,380);
fbECATSoeRead5.ValueAdr     := ADR(iS380);
fbECATSoeRead5.SizeOfValue  := SIZEOF(iS380);
fbECATSoeRead5();
IF TRUE = fbECATSoeRead4.Done THEN
  rS380 := to_REAL(iS380) /10; // FB finished value is "Inverter DC bus: Voltage".
END_IF
IF TRUE = fbECATSoeRead4.Error THEN
  ; // Error handling
END_IF

IL_ECATSoeWrite

Same as the previous function block but in the other direction. This example can be used to write the homing quota value.

Write string parameter

Exemplarily parameter S-0-0141 "Motor identification: Type" value is written.

ctrlX PLC Engineering - write S-0-0141 value via SoE

Declaration:

PROGRAM Write_StringParameter
VAR
	fbECATSoeWrite : IL_ECATSoeWrite ;
	WriteText: IL_ST_SOE_STRING;
	strText: STRING(255):='AKM24D';	
	MaxLength: UINT := 0;
	ActLength: UINT := 6;
	bExecute: BOOL;
	strMasterName  : STRING := 'ethercatmaster';
END_VAR

Implementation:

WriteText.Text := strText;
WriteText.MaxLength := MaxLength; //not relevant for writing
WriteText.ActLength := LEN(strText); //number of bytes/letters of string

fbECATSoeWrite.Execute      := bExecute;
fbECATSoeWrite.MasterName   := ADR(strMasterName);
fbECATSoeWrite.SlaveAddress := 1001;
fbECATSoeWrite.Idn          := IL_ECATSOEIdnCoding(SOE_S_PARAM,0,141);
fbECATSoeWrite.ValueAdr     := ADR(WriteText);
fbECATSoeWrite.SizeOfValue  := WriteText.ActLength + SIZEOF(WriteText.MaxLength) + SIZEOF(WriteText.ActLength);
fbECATSoeWrite();
IF TRUE = fbECATSoeWrite.Done THEN
  ; // FB finished .
END_IF
IF TRUE = fbECATSoeWrite.Error THEN
	fbECATSoeWrite.ErrorID;
	fbECATSoeWrite.ErrorIdent.Table;
	fbECATSoeWrite.ErrorIdent.Additional1;
	fbECATSoeWrite.ErrorIdent.Additional2;
  ; // Error handling
END_IF

Write list parameter

Exemplarily parameter P-0-0397 "Average value filter for display: Time constant" value is written.

Struct:

TYPE MyTableStruct :
STRUCT
	ActLength : UINT;
	MaxLength : UINT;
	ArrayOfElements : ARRAY[0..3] OF UDINT;
END_STRUCT
END_TYPE

Declaration:

PROGRAM Read_Write_StringParameter
VAR
	fbECATSoeWrite: IL_ECATSoeWrite;
	WriteList: MyTableStruct := (
                ActLength:= 16(*number of bytes*), 
                MaxLength := 16(*number of bytes*), 
                ArrayOfElements := [1000,2000,3000,4000](*number multiplied with digits after decimal point*));
	bExecute: BOOL;
	strMasterName: STRING := 'ethercatmaster';
	fbECATSoeRead2: IL_ECATSoeRead;
	bExecuteRead: BOOL;
	rDiagnosis: IL_ST_SOE_STRING;
END_VAR

Implementation:

fbECATSoeWrite.Execute      := bExecute;
fbECATSoeWrite.MasterName   := ADR(strMasterName);
fbECATSoeWrite.SlaveAddress := 1001;
fbECATSoeWrite.Idn          := IL_ECATSOEIdnCoding(SOE_P_PARAM,0,397);
fbECATSoeWrite.ValueAdr     := ADR(WriteList);
fbECATSoeWrite.SizeOfValue  := WriteList.ActLength(*number of bytes that should be written*) + SIZEOF(WriteList.MaxLength) + SIZEOF(WriteList.ActLength);
fbECATSoeWrite();
IF TRUE = fbECATSoeWrite.Done THEN
  ; // FB finished .
END_IF
IF TRUE = fbECATSoeWrite.Error THEN
	fbECATSoeWrite.ErrorID;
	fbECATSoeWrite.ErrorIdent.Table;
	fbECATSoeWrite.ErrorIdent.Additional1;
	fbECATSoeWrite.ErrorIdent.Additional2;
  ; // Error handling
END_IF

Notes

The EtherCat SoE specification is based on the SERCOS II. The structured parameter including the indexes (instance.element e.g. S-0-602.1.1) were first introduced in SERCOS III. Even IDN size changed from 2 Byte to 4 Byte and so access to this parameter "alias parameter" needs to be used.