EtherCAT for GOAL

The EtherCAT Library can also be used with GOAL, port’s Industrial Communication Framework.

This chapter introduces the API that is provided to write an application for EtherCAT on GOAL. The application can also be created with port’s Industrial Communication Creator.

The EtherCAT library is able to run several instances. An instance is a variable of the type GOAL_ECAT_T. Every API function requires a reference to aninstance. An instance is created using the API function goal_ecatNew.

Public API of the EtherCAT library

This chapter gives an overview on all public functions of the EtherCAT library. There are functions that must be called by the application to trigger events and there are callbacks invoked by the library.

If the EtherCAT library is used in combination with GOAL, the application must use the API functions defined in this chapter. It must not use the legacy API functions of previous chapters.

Setting up and running the library

In order to initialize the library the following function must be called during
appl_init():

/****************************************************************************/
/** Application Init
 *
 * This function must initialize GOAL and all used protocol stacks.
 * Furthermore application specific resources must be initialized.
 */
GOAL_STATUS_T appl_init(
    void
)
{
    GOAL_STATUS_T res;                          /* result */

    /* initialize EtherCAT */
    res = goal_ecatInit();
    if (GOAL_RES_ERR(res)) {
       goal_logErr("Initialization of EtherCAT failed");
    }

    return res;
}

To create an instance of the EtherCAT library the following function must be called:

/****************************************************************************/
/** Application Setup
 *
 * Setup the application.
 */
GOAL_STATUS_T appl_setup(
    void
)
{
    GOAL_STATUS_T res;                          /* result */

    res = goal_ecatNew(&pHdlEcat, GOAL_ECAT_INSTANCE_DEFAULT, appl_ecatCallback);
    if (GOAL_RES_ERR(res)) {
        goal_logErr("failed to create a new EtherCAT instance");
        return res;
    }

    return res;
}

Debugging

The EtherCAT library used GOAL logging mechanism. By default error messages, warnings and informational messages are printed. To enable additional debugging messages, the GOAL API function goal_setDbgLevel function can be used.

Object Dictionary access

These functions enable the application to access managed variables of the object dictionary. Application variables can be accessed directly since their variable name is known to all modules.

Function	Description

Function	Description
goal_ecatObjAddrGet()	get a pointer to the object value
goal_ecatObjValGet()	get the object value
goal_ecatObjValSet()	set the object value

Table: OD Access API

Dynamic Object Dictionary

Beside static generation of the object dictionary using the design tool, a API is provided to create ojects dynamically.

Function	Description

Function	Description
goal_ecatdynOdObjAdd()	add object
goal_ecatdynOdSubIndexAdd()	add subindex to object
goal_ecatdynOdObjNameAdd()	assign name to object
goal_ecatdynOdSubIndexNameAdd()	assign name to subindex
goal_ecatdynOdFinish()	finish object creation

Table: OD Creation API

Dynamic Library Configuration

These functions allow the configuration of the EtherCAT library at runtime during initialization. In order to take effect they must be called before goal_ecatNew() is called.

Function	Description

Function	Description
goal_ecatCfgEmergencyOn()	enable CoE Emergency Service
goal_ecatCfgNumEmergencyQueueSlots()	set size of CoE Emergency message queue
goal_ecatCfgFoeOn()	enable FoE service
goal_ecatCfgExplDevIdOn()	enable Explicit Device Identification
goal_ecatCfgBootstrapOn()	enable ESM state BOOTSTRAP
goal_ecatCfgDcRequiredOn()	make DC synchronization mandatory
goal_ecatCfgSizePdoStreamBuf()	set size of PDO bytestream buffer
goal_ecatCfgLedStatusIndicator()	set LED emulation to combined RUN/ERROR led

Table: Dynamic Configuration API

CoE API

The CoE module provides indication events to connect the application to the objects and the process data. There are also some API functions that trigger the CoE and SDO module.

Callback ID	Description

Callback ID	Description
GOAL_ECAT_CB_ID_SDO_UPLOAD	indicate SDO Read access to an object
GOAL_ECAT_CB_ID_SDO_DOWNLOAD	check an object’s new data before it is written
GOAL_ECAT_CB_ID_RxPDO_RECEIVED	indicate reception of output process data (objects updated)
GOAL_ECAT_CB_ID_TxPDO_PREPARE	update input process data objects before they are mapped to Sync Manager

Table: CoE Indication events

Function	Description

Function	Description
goal_ecatEmyReqWrite()	send a CoE emergency message

Table: CoE API

EoE API

There is no EoE API since when enabled EoE will internally be connected to the GOAL framework.

FoE API

This module provides indication events that must be implemented by the application.

Event	Description

Event	Description
GOAL_ECAT_CB_ID_FOE_READ_REQ	open a file for reading
GOAL_ECAT_CB_ID_FOE_WRITE_REQ	open a file for writing
GOAL_ECAT_CB_ID_FOE_READ_DATA	get fragment of read file
GOAL_ECAT_CB_ID_FOE_WRITE_DATA	write fragment of write file
GOAL_ECAT_CB_ID_FOE_ERROR	error occurred, close file

Table: FOE indication events

EtherCAT State machine

These functions inform the application about a change in the EtherCAT state machine.

Function	Description

Function	Description
goal_ecatEsmStateGet()	get current ESM state

Table: ESM API

Event	Description

Event	Description
GOAL_ECAT_CB_ID_NEW_ESM_STATE_ENTERED	indicate new ESM state and possible error
GOAL_ECAT_CB_ID_NEW_ESM_STATE_REQUESTED	indicate an ESM state change request
GOAL_ECAT_CB_ID_EXPLICIT_DEV_ID	get the Explicit Device ID (during state change)

Table: ESM Events

Data Layer indication functions

These events are called by the EtherCAT library if a data layer event happened. The application programmer must implement these functions.

Function	Description

Function	Description
GOAL_ECAT_CB_ID_SM_WATCHDOG_EXPIRED	process data reception timeout (Hardware Watchdog)
GOAL_ECAT_CB_ID_NEW_DL_STATE	port state change

Table: Data Link Events

Distributed Clock API

If synchronization via Distributed Clocks is activated, the following events are called by the library and must be implemented by the application programmer.

Function	Description

Function	Description
GOAL_ECAT_CB_ID_NEW_DC_CONFIG	check the synchronization settings, e.g. cycle time
GOAL_ECAT_CB_ID_DC_FAIL	indicate loss of Sync0 interrupts

Table: DC Events