Application Programming Interface

This chapter lists the API functions that are provided by GOAL EtherNet/IP. See the applications on appl/goal_eip/* for a demonstration of the code examples. For further details please refer to the Reference Manual.

goal_eipInit

Initialize GOAL EtherNet/IP. Returns a GOAL_STATUS_T as result. This function must be called within the function appl_init().

No parameters required.

res = goal_eipInit();

goal_eipNew

Create a GOAL EtherNet/IP instance for the given ID and register a callback. This function must be called within the function appl_setup().

Parameter

Description

Parameter

Description

GOAL_EIP_T **ppEip

[out] EtherNet/IP instance ref

const uint32_t id

ID of EtherNet/IP instance

GOAL_EIP_FUNC_CB_T pFunc

GOAL Ethernet/ IP handle application callback

Table: goal_eipNew parameters

res = goal_eipNew(&pHdlEip, EIP_INSTANCE_DEFAULT, main_eipCallback);

goal_eipCipClassRegister

Register an application specific CIP class. When the EtherNet/IP stack receives a request for the the registered CIP class it is passed to the handler function.

Parameter

Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL Ethernet/IP handle

uint16_t classId

class ID to be registered

GOAL_EIP_REQ_HANDLER_T pFunc

request handler

Table: goal_eipCipClassRegister parameters

res = goal_eipCipClassRegister(pEip, APPL_CLASS_ID_PARAMETER, appl_parameterClassHandler);

goal_eipCreateAssemblyObject

Creates an Assembly onto the given Instance. Returns a GOAL_STATUS_T as result.

On MCTC platforms, the function equals goal_eipCreateAssemblyObjectDm and the Assembly will be added to the Data Mapper - thus the total size of Assemblies is limited to buffer length of MI DM instance.

Parameter

Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL EtherNet/IP handle

uint32_t instanceId

instance number of the assembly object to create

uint16_t len

length of the assembly object’s data

Table: goal_eipCreateAssemblyObject parameters

goal_eipCreateAssemblyObjectDm

Adds an CIP instance to the selected Class. Returns a GOAL_STATUS_T as result.

The assembly object data will be mapped to Data Mapper for exchanging the content with the peer core.

On MCTC platforms, the Assembly will be added to the Data Mapper - thus the total size of Assemblies is limited to buffer length of MI DM instance.

Parameter

Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL EtherNet/IP handle

uint32_t instanceId

instance number of the assembly object to create

uint16_t len

length of the assembly object’s data

Table: goal_eipCreateAssemblyObjectDm parameters

goal_eipCreateAssemblyObjectRpc

Creates an Assembly onto the given Instance on MCTC platforms, the Assembly won’t be added to the Data Mapper. Data are transported to the peer core by RPC instead. Returns a GOAL_STATUS_T as result.

Only on MCTC platforms. The Assembly won’t be added to the Data Mapper - therefore the size is restricted by RPC.

Parameter

Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL EtherNet/IP handle

uint32_t instanceId

instance number of the assembly object to create

uint16_t len

length of the assembly object’s data

Table: goal_eipCreateAssemblyObject parameters

goal_eipAssemblyObjectGet

Get the pointer to the data array of an assembly.

Parameter

Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL Ethernet/IP handle

uint32_t instanceId

instance number of the assembly object

uint8_t **ppData

[out] pointer to assembly data

uint16_t *pLen

[out] length of assembly data

Table: goal_eipAssemblyObjectGet parameters

goal_eipAddExclusiveOwnerConnection

Create one Exclusive Owner connection with producing and consuming endpoints.

Parameter

Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL EtherNet/IP handle

uint32_t outputAssembly

the O-to-T point to be used for this connection

uint32_t inputAssembly

the T-to-O point to be used for this connection

uint32_t configAssembly

the configuration point to be used for this connection

Table: goal_eipAddExclusiveOwnerConnection parameters

goal_eipAddInputOnlyConnection

Create multiple Input Only connections with the same producing and consuming endpoints.

goal_eipAddInputOnlyConnection parameters

Parameter

Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL EtherNet/IP handle

uint32_t connNum

the number of the input only connection

uint32_t outputAssembly

the O-to-T point to be used for this connection

uint32_t inputAssembly

the T-to-O point to be used for this connection

uint32_t configAssembly

the configuration point to be used for this connection

Table: goal_eipAddInputOnlyConnection parameters

goal_eipAddListenOnlyConnection

Create multiple Listen Only connections with the same producing and consuming endpoints.

Parameter

Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL EtherNet/IP handle

uint32_t connNum

the number of the input only connection.

uint32_t outputAssembly

the O-to-T point to be used for this connection

uint32_t inputAssembly

the T-to-O point to be used for this connection

uint32_t configAssembly

the configuration point to be used for this connection

Table: goal_eipAddListenOnlyConnection parameters

goal_eipGetVersion

Get the EtherNet/IP version. Returns a GOAL_STATUS_T as result.

Parameter

Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL EtherNet/IP handle

char **ppVersion

[out] Ethernet/IP version

Table: goal_eipGetVersion parameters

goal_eipDeviceStatusSet

Set device status bits. The parameter statusBits uses the GOAL_EIP_STATUS_ macros. They can be combined with binary OR.

Parameter

Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL Ethernet/IP handle

uint16_t statusBits

status bitmap

Table: goal_eipDeviceStatusSet parameters

goal_eipDeviceStatusClear

Clear device status bits. All bits of statusBits will be cleared. The parameter uses the GOAL_EIP_STATUS_ macros. They can be combined with binary OR.

Parameter

Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL Ethernet/IP handle

uint16_t statusBits

status bitmap

Table: goal_eipDeviceStatusClear parameters

goal_eipAssemblyObjectWrite

Write data to an Assembly Object.

Parameter

Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL Ethernet/IP handle

uint32_t instanceId

instance ID oft the Assembly object

uint8_t *pData

buffer with write data

uint16_t len

number of bytes to write

Table: goal_eipAssemblyObjectWrite parameters

goal_eipAssemblyObjectRead

Read data from an Assembly Object.

Parameter

Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL Ethernet/IP handle

uint32_t instanceId

instance ID oft the Assembly object

uint8_t *pData

buffer for read data

uint16_t len

number of bytes to read

Table: goal_eipAssemblyObjectRead parameters

goal_eipIdentitySerialNumberSet

Set the serial number of the device. Each device must have a unique serial number. This function updates the Identity instance attribute, i.e. it changes the Serial Number after the EtherNet/IP instance has been created.

Parameter

Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL Ethernet/IP handle

uint32_t serialNum

new Serial Number

Table: goal_eipIdentitySerialNumberSet parameters