Creating an Application with GOAL

This chapter describes all necessary steps for creating an application for EtherCAT with GOAL.

Files created by the Industrial Communication Creator

The Industrial Communication Creator (ICC) must be used to specify the options for the library and to define the layout of the object dictionary. Please refer to the manual of the ICC for details.

The following source files are created:

File	Description

File	Description
ecat_conf.h	contains all configuration macros
ec_od.c	contains the object dictionary tables
ec_objects.{c\|h}	contains all application variables of the object dictionary

Table: Source code files generated by the ICC

These files are considered to be part of the application. Other files generated by the ICCare ignored for this chapter.

The object dictionary either has managed variables or application variables. Managed variables are only accessible via the OD API of the library. Application variables are declared in ec_objects.{c|h} and can be used directly.

Application modules

The examples delivered with the EtherCAT library provide a good starting point for developing your own application.

Always include the header files goal_includes.h and goal_ecat.h.

The file goal_appl.c demonstrates how to initialize and use the EtherCAT library in a GOAL application.

Callback mechanism

When creating an instance of the EtherCAT Library, a callback function can be assigned.
The function requires the following signature:

/****************************************************************************/
/** EtherCAT Callback Handler
 *
 * This function collects all callbacks from the stack and decides if the
 * callback must be handled.
 *
 * @retval GOAL_OK successful
 * @retval other failed
 */
GOAL_STATUS_T appl_ecatCallback(
    GOAL_ECAT_T *pHdlEcat,                      /**< GOAL EtherCAT handle */
    GOAL_ECAT_CB_ID_T id,                       /**< callback id */
    GOAL_ECAT_CB_DATA_T *pCb                    /**< callback parameters */
)
{
    GOAL_STATUS_T res = GOAL_OK;                /* result */

    switch (id) {
        case GOAL_ECAT_CB_ID....
            break;
    }

    return res;
}

The id specifies the function being called within the callback function. The following list contains all possible callback IDs:

Symbol	Description

Symbol	Description
GOAL_ECAT_CB_ID_SDO_DOWNLOAD	SDO Write Access
GOAL_ECAT_CB_ID_SDO_UPLOAD	SDO Read Access
GOAL_ECAT_CB_ID_RxPDO_RECEIVED	Updated output data
GOAL_ECAT_CB_ID_TxPDO_PREPARE	Provide new input data
GOAL_ECAT_CB_ID_SYNC_FAIL	Synchronisation operation failed
GOAL_ECAT_CB_ID_NEW_DL_STATE	New datalink layer status
GOAL_ECAT_CB_ID_NEW_DC_CONFIG	New DC configuration
GOAL_ECAT_CB_ID_DC_FAIL	DC Synchronisation failed
GOAL_ECAT_CB_ID_SM_WATCHDOG_EXPIRED	Sync manager watchdog failed
GOAL_ECAT_CB_ID_EXPLICIT_DEV_ID	Request for explicit device id
GOAL_ECAT_CB_ID_NEW_ESM_STATE_ENTERED	New ESM state entered
GOAL_ECAT_CB_ID_NEW_ESM_STATE_REQUESTED	New ESM state requested
GOAL_ECAT_CB_ID_FOE_READ_REQ	FoE read request
GOAL_ECAT_CB_ID_FOE_READ_DATA	FoE read data
GOAL_ECAT_CB_ID_FOE_WRITE_REQ	FoE write request
GOAL_ECAT_CB_ID_FOE_WRITE_DATA	FoE write data
GOAL_ECAT_CB_ID_FOE_ERROR	FoE error
GOAL_ECAT_CB_ID_RUN_LED_STATE	RUN LED state change
GOAL_ECAT_CB_ID_EROR_LED_STATE	ERROR LED state change

Table: Callback Ids

Parameters are propagated to the callback function as a array of the datastructure GOAL_ECAT_CB_DATA_T.

Callback Data Content Structure

typedef union {
    uint16_t index;              /**< object index */
    uint8_t subIndex;            /**< object sub-index */
    uint8_t *pData;              /**< object data */
    uint32_t size;               /**< object size */
    GOAL_BOOL_T completeAccess;  /**< complete object is accessed */
    uint16_t dlState;            /**< new Data Link layer state */
    uint32_t dcCycleTime;        /**< current DC cycle time */
    uint32_t dcCycleTimeMin;     /**< minimum supported DC cycle time */
    uint16_t explDevId;          /**< Explicit device ID */
    uint16_t esmState;           /**< new ESM state */
    GOAL_BOOL_T esmError;        /**< device is in error state */
    uint16_t statusCode;         /**< status code explaining error */
    uint16_t appStatusCode;      /**< application specific error */
    uint32_t foePassword;        /**< password for file access */
    char *pFileName;             /**< file to be accessed via FoE */
    uint16_t foeError;           /**< FOE error code */
    uint32_t foeOffset;          /**< read/write offset in file */
    uint16_t foeMaxSize;         /**< maximum size of a FOE chunk */
    uint16_t foeActSize;         /**< actual size of a FOE chunk */
    GOAL_BOOL_T foeFinished;     /**< write access finished */
    GOAL_BOOL_T bLedEnable;      /**< led state */
} GOAL_ECAT_CB_DATA_ELEM_T;

Depending on the callback Id parameters and return values are provided and expected in id specific positions within the callback data array.

Public Functions

goal_ecatInit

Purpose: Initial registration of EtherCAT library

Function Prototype:

GOAL_STATUS_T goal_ecatInit(
    void
);

Example:

goal_ecatNew

Purpose: Create an instance of the EtherCAT Library

Function Prototype:

Example:

goal_ecatCfgEmergencyOn

Purpose: Enable Emergency Message support

Function Prototype:

Example:

Remarks:

This function is required to be called before goal_ecatNew.

goal_ecatCfgEmergencyQueueNum

Purpose: set number of queueable emergency messages

Function Prototype:

Example:

Remarks:

This function is required to be called before goal_ecatNew.

goal_ecatCfgFoeOn

Purpose: enable FoE support

Function Prototype:

Example:

Remarks:

This function is required to be called before goal_ecatNew.

goal_ecatCfgExplDevIdOn

Purpose: Enable support for Explicit Device Identification

Function Prototype:

Example:

Remarks:

This function is required to be called before goal_ecatNew.

goal_ecatCfgBootstrapOn

Purpose: Enable support for BOOTSTRAP esm state

Function prototype:

Example:

Remarks:

This function is required to be called before goal_ecatNew.

goal_ecatCfgDcRequiredOn

Purpose: Enable enforcement of DC mode

Function Prototype:

Example:

Remarks:

This function is required to be called before goal_ecatNew.

goal_ecatCfgSizePdoStreamBufSet

Purpose: Configure PDO data buffer

Function Prototype:

Example:

Remarks:

This function is required to be called before goal_ecatNew.

To utilize maximum process data length for CCM module the buffer should be configured to 2 * 68 = 136 bytes.

goal_ecatCfgLedStatusIndicator

Purpose: Configure behaviour of LED emulation

Function Prototype:

Example:

Remarks:

This function is required to be called before goal_ecatNew.

If set to FALSE, led emulation will support dedicated RUN and ERROR indicator.
If set to TRUE, led emulation will support combined STATUS indicator.

goal_ecatObjAddrGet

Purpose: get a pointer to the object value

Function Prototype:

Example:

Remarks:

goal_ecatObjValGet

Purpose: get the object value

Function Prototype:

Example:

Remarks:

goal_ecatObjValSet

Purpose: set the object value

Function Prototype:

Example:

Remarks:

goal_ecatdynOdObjAdd

Purpose: add object

Function Prototype:

Example:

Remarks:

goal_ecatdynOdSubIndexAdd

Purpose: add subindex to object

Function Prototype:

Example:

Remarks:

goal_ecatdynOdObjNameAdd

Purpose: assign name to object

Function Prototype:

Example:

Remarks:

goal_ecatdynOdSubIndexNameAdd

Purpose: assign name to subindex

Function Prototype:

Example:

Remarks:

goal_ecatdynOdFinish

Purpose: finish object creation

Function Prototype:

Example:

Remarks:

This function ends dynamic creation of objects. It must be called when the last object was created. After calling this function, no additional objects can be created.

goal_ecatEsmStateGet

Purpose: get current ESM state

Function Prototype:

Example:

Remarks:

goal_ecatEmcyReqWrite

Purpose: generate an Emergency Message for transmission

Function Prototype:

Example:

Remarks:

goal_ecatGetVersion

Purpose: Get version information about EtherCAT Library

Function Prototype:

Example:

Remarks:

goal_ecatEsmLocalErrorSet

Purpose: Set error from application

Function Prototype:

Example:

Remarks:

Definitions

Symbol	Description

Symbol	Description
GOAL_ERR_SDO_HARDWARE	hardware error
GOAL_ERR_SDO_TOO_LOW	value to low
GOAL_ERR_SDO_TOO_HIGH	value to high
GOAL_ERR_SDO_APPL	application specific reason
GOAL_ERR_SDO_DEV_STATE	current device state insufficient
GOAL_ERR_SDO_GENERAL	unspecified SDO error

Table: application specific SDO accesses errors

Symbol	Description

Symbol	Description
GOAL_ERR_OBJ_NOT_FOUND	object not found
GOAL_ERR_SIDX_NOT_FOUND	sub-index not found
GOAL_ERR_OBJ_VAL_TO_HIGH	new value exceeds object’s upper limit
GOAL_ERR_OBJ_VAL_TO_LOW	new value exceeds object’s lower limit
GOAL_ERR_OBJ_SIZE	invalid data size for object

Table: object dictionary access errors

Symbol	Description

Symbol	Description
GOAL_ECAT_STATE_CODE_OK	No error
GOAL_ECAT_STATE_CODE_UNSPEC	Unspecified error
GOAL_ECAT_STATE_CODE_NO_MEM	No Memory
GOAL_ECAT_STATE_CODE_INVALID_SETUP	Invalid Device Setup
GOAL_ECAT_STATE_CODE_SII_MISMATCH	SII/EEPROM information does not match firmware
GOAL_ECAT_STATE_CODE_FW_UPDATE_FAIL	Firmware update not successful, old firmware still running
GOAL_ECAT_STATE_CODE_LICENSE_ERR	License error
GOAL_ECAT_STATE_CODE_INVALID_REQ	Invalid requested state change
GOAL_ECAT_STATE_CODE_UNKNOWN_REQ	Unknown requested state
GOAL_ECAT_STATE_CODE_NO_BOOTSTRAP	Bootstrap not supported
GOAL_ECAT_STATE_CODE_NO_FIRMWARE	No valid firmware
GOAL_ECAT_STATE_CODE_INVALID_MBX_CONF_B	Invalid mailbox configuration
GOAL_ECAT_STATE_CODE_INVALID_MBX_CONF	Invalid mailbox configuration
GOAL_ECAT_STATE_CODE_INVALID_SYNCM_CONFIG	Invalid sync manager configuration
GOAL_ECAT_STATE_CODE_NO_INPUTS	No valid inputs available
GOAL_ECAT_STATE_CODE_NO_OUTPUTS	No valid outputs
GOAL_ECAT_STATE_CODE_UNSPECIFIC_SYNC_ERROR	Synchronization error
GOAL_ECAT_STATE_CODE_SYNCM_WATCHDOG	Sync manager watchdog
GOAL_ECAT_STATE_CODE_INVALID_SYNCM_TYPE	Invalid Sync Manager Types
GOAL_ECAT_STATE_CODE_INVALID_OUTPUT_CONFIG	Invalid Output Configuration
GOAL_ECAT_STATE_CODE_INVALID_INPUT_CONFIG	Invalid Input Configuration
GOAL_ECAT_STATE_CODE_INVALID_WD_CONFIG	Invalid Watchdog Configuration
GOAL_ECAT_STATE_CODE_COLD_START	Slave needs cold start
GOAL_ECAT_STATE_CODE_NEED_INIT	Slave needs INIT
GOAL_ECAT_STATE_CODE_NEED_PREOP	Slave needs PREOP
GOAL_ECAT_STATE_CODE_NEED_SAFEOP	Slave needs SAFEOP
GOAL_ECAT_STATE_CODE_INVALID_INPUT_MAPPING	Invalid Input Mapping
GOAL_ECAT_STATE_CODE_INVALID_OUTPUT_MAPPING	Invalid Output Mapping
GOAL_ECAT_STATE_CODE_INVALID_SETTING	Inconsistent Settings
GOAL_ECAT_STATE_CODE_NO_FREERUN	FreeRun not supported
GOAL_ECAT_STATE_CODE_INVALID_SYNC_MODE	SyncMode not supported
GOAL_ECAT_STATE_CODE_FREERUN_3BUF	FreeRun needs 3Buffer Mode
GOAL_ECAT_STATE_CODE_BACKGROUND_WD	Background Watchdog
GOAL_ECAT_STATE_CODE_INVALID_INPUT_OUTPUT	No Valid Inputs and Outputs
GOAL_ECAT_STATE_CODE_FATAL_SYNC_ERROR	Fatal Sync Error
GOAL_ECAT_STATE_CODE_NO_SYNC_RECEIVED	No Sync Error
GOAL_ECAT_STATE_CODE_SMALL_CYCLE_TIME	Cycle time too small
GOAL_ECAT_STATE_CODE_INVALID_DC_SYNC	Invalid DC SYNC Configuration
GOAL_ECAT_STATE_CODE_INVALID_DC_LATCH	Invalid DC Latch Configuration
GOAL_ECAT_STATE_CODE_PLL_ERR	PLL Error
GOAL_ECAT_STATE_CODE_UNSYNCED_IO	DC Sync IO Error
GOAL_ECAT_STATE_CODE_UNSYNCED	DC Sync Timeout Error
GOAL_ECAT_STATE_CODE_INVALID_SYNC_CYCLE_TIME	DC Invalid Sync Cycle Time
GOAL_ECAT_STATE_CODE_DC_SYNC_0_CYCLE_TIME	Sync0 Cycle Time
GOAL_ECAT_STATE_CODE_DC_SYNC_1_CYCLE_TIME	DC Sync1 Cycle Time
GOAL_ECAT_STATE_CODE_MBX_AOE	MBX_AOE
GOAL_ECAT_STATE_CODE_MBX_EOE	MBX_EOE
GOAL_ECAT_STATE_CODE_MBX_COE	MBX_COE
GOAL_ECAT_STATE_CODE_MBX_FOE	MBX_FOE
GOAL_ECAT_STATE_CODE_MBX_SOE	MBX_SOE
GOAL_ECAT_STATE_CODE_MBX_VOE	MBX_VOE
GOAL_ECAT_STATE_CODE_EEPROM_NO_ACCESS	EEPROM no access
GOAL_ECAT_STATE_CODE_EEPROM_ERR	EEPROM Error
GOAL_ECAT_STATE_CODE_EXT_HW_ERR	External Hardware not ready
GOAL_ECAT_STATE_CODE_RESTARTED	Slave restarted locally
GOAL_ECAT_STATE_CODE_DEVICE_ID_UPDATE	Device Identification value updated
GOAL_ECAT_STATE_CODE_MODULE_IDENT_MISMATCH	Detected Module Ident List does not match
GOAL_ECAT_STATE_CODE_APP_AVAILABLE	Application controller available

Table: AL status codes

Symbol	Description

Symbol	Description
GOAL_ECAT_ESM_STATE_UNKNOWN	unknown ESM state
GOAL_ECAT_ESM_STATE_INIT	ESM state INIT
GOAL_ECAT_ESM_STATE_PREOP	ESM state PreOP
GOAL_ECAT_ESM_STATE_BOOTSTRAP	ESM state BOOTSTRAP
GOAL_ECAT_ESM_STATE_SAFEOP	ESM state SafeOP
GOAL_ECAT_ESM_STATE_OP	ESM state OP

Table: EtherCAT State Machine states

Symbol	Description

Symbol	Description
GOAL_ECAT_FOE_ERR_NOT_DEFINED	unefined error
GOAL_ECAT_FOE_ERR_NOT_FOUND	not found
GOAL_ECAT_FOE_ERR_ACCESS_DENIED	access denied
GOAL_ECAT_FOE_ERR_DISK_FULL	disk full
GOAL_ECAT_FOE_ERR_ILLEGAL	illegal
GOAL_ECAT_FOE_ERR_PACKET_NUMBER_WRONG	wrong packet number
GOAL_ECAT_FOE_ERR_ALREADY_EXISTS	already exists
GOAL_ECAT_FOE_ERR_NO_USER	no user
GOAL_ECAT_FOE_ERR_BOOTSTRAP_ONLY	Bootstrap only
GOAL_ECAT_FOE_ERR_NOT_BOOTSTRAP	not Bootstrap
GOAL_ECAT_FOE_ERR_NO_RIGHTS	no rights
GOAL_ECAT_FOE_ERR_PROGRAM_ERROR	programm error
GOAL_ECAT_FOE_ERR_CSUM_WRONG	checksum wrong
GOAL_ECAT_FOE_ERR_FIRMWARE	wrong firmware
GOAL_ECAT_FOE_ERR_NO_FILE_TO_READ	no file to read
GOAL_ECAT_FOE_ERR_NO_HEADER	file header does not exist
GOAL_ECAT_FOE_ERR_FLASH	error
GOAL_ECAT_FOE_ERR_FILE_INCOMPATIBLE	file incompatible
GOAL_ECAT_FOE_BUSY_STATE	Server is busy

Table: FoE Error Codes

Symbol	Description

Symbol	Description
GOAL_ECAT_OBJCODE_VAR	object is a variable object
GOAL_ECAT_OBJCODE_ARRAY	object is an array object
GOAL_ECAT_OBJCODE_RECORD	object is a record object

Table: object dictionary object types

Symbol	Description

Symbol	Description
GOAL_ECAT_DATATYPE_UNKNOWN	data type: UNKNOWN
GOAL_ECAT_DATATYPE_BOOL	data type: BOOL
GOAL_ECAT_DATATYPE_INTEGER8	data type: INTEGER8
GOAL_ECAT_DATATYPE_INTEGER16	data type: INTEGER16
GOAL_ECAT_DATATYPE_INTEGER32	data type: INTEGER32
GOAL_ECAT_DATATYPE_UNSIGNED8	data type: UNSIGNED8
GOAL_ECAT_DATATYPE_UNSIGNED16	data type: UNSIGNED16
GOAL_ECAT_DATATYPE_UNSIGNED32	data type: UNSIGNED32
GOAL_ECAT_DATATYPE_REAL32	data type: REAL32
GOAL_ECAT_DATATYPE_VISSTRING	data type: VISSTRING
GOAL_ECAT_DATATYPE_OCTETSTRING	data type: OCTETSTRING
GOAL_ECAT_DATATYPE_REAL64	data type: REAL64
GOAL_ECAT_DATATYPE_INTEGER64	data type: INTEGER64

Table: object dictionary data types