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 |
|---|---|
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 |
|---|---|
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 |
|---|---|
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 |
|---|---|
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 |
|---|---|
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 |
|---|---|
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 |
|---|---|
goal_ecatEsmStateGet() | get current ESM state |
Table: ESM API
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 |
|---|---|
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 |
|---|---|
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