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

goal_eipReset

Locally execute the Reset service of the Identity object.

Parameter	Description

Parameter

Description

GOAL_EIP_T *pHdlEip

GOAL Ethernet/IP handle

uint32_t resetService

kind of Reset service

GOAL_EIP_RESET_POWER
- simulate power cycle
GOAL_EIP_RESET_FACTORY
- factory reset (clear all NVM data)
GOAL_EIP_RESET_FACTORY_OTHER
- clear all NVM data except communication settings
GOAL_EIP_RESET_FACTORY_COMM
- restart state machine to apply new IP addres

Table: goal_eipReset parameters