Application Programming Interface
- Marcus Züche
This chapter lists the API functions that are provided by GOAL POWERLINK. For further details please refer to the Reference Manual.
goal_eplPortsSet - Setting Ethernet ports for POWERLINK/HUB usage
This function sets the masked GOAL ports for POWERLINK/HUB. By default, all Ethernet ports are selected. Setting the ports has to be performed before initializing the POWERLINK stack.
Returns a GOAL_STATUS_T as result.
goal_eplPortsSet parameters | |
|---|---|
Parameter | Description |
uint32_t maskPorts | EPL port mask |
Code: goal_eplPortsSet example
GOAL_STATUS_T appl_init(
void
)
{
GOAL_STATUS_T res; /* result */
/* setting Ethernet POWERLINK on GOAL port 0 and 1 */
res = goal__eplPortsSet(GOAL_ETH_PORT_BIT(0) | GOAL_ETH_PORT_BIT(1));
if (GOAL_RES_ERR(res)) {
goal_logErr("Unable to set ports 0 and 1 for POWERLINK");
} else {
/* initialize Ethernet POWERLINK */
res = goal_eplInit();
if (GOAL_RES_ERR(res)) {
goal_logErr("Initialization of POWERLINK failed");
}
}
return res;
}goal_eplInit - Initialize GOAL POWERLINK
Initialize GOAL POWERLINK.
Returns a GOAL_STATUS_T as result.
See example 01_cn1 for a demonstration.
Code: goal_eplInit example
GOAL_STATUS_T appl_init(
void
)
{
GOAL_STATUS_T res; /* result */
/* initialize POWERLINK */
res = goal_eplInit();
if (GOAL_RES_ERR(res)) {
goal_logErr("Initialization of POWERLINK failed");
}
return res;
}goal_eplNew - Setup Ethernet POWERLINK
Setup a new Ethernet POWERLINK instance.
Returns a GOAL_STATUS_T as result.
goal_eplNew parameters | |
|---|---|
Parameter | Description |
GOAL_EPL_T **ppHdlEpl | [out] GOAL POWERLINK handle |
See example 01_cn1 for a demonstration.
Code: goal_eplNew example
static GOAL_EPL_T *pHdlEpl; /**< GOAL POWERLINK handle */
GOAL_STATUS_T appl_setup(
void
)
{
GOAL_STATUS_T res; /* result */
/* setup Ethernet POWERLINK */
res = goal_eplNew(&pHdlEpl);
if (GOAL_RES_ERR(res)) {
goal_logErr("failed to create a new POWERLINK instance");
}
return res;
}goal_eplSetCommPar - Set communication parameter
If a new communication parameter is set by user application this function has to be called e.g. after definition of a communication object a new parameter will be loaded from a nonvolatile memory. It is responsible for passing the communication parameter through to the internal variables.
goal_eplSetCommpar parameters | |
|---|---|
Parameter | Description |
GOAL_EPL_T *pHdlEpl | GOAL POWERLINK handle |
uint16_t index | index of communication object |
uint8_t subIndex | subindex of communication object |
Returns a GOAL_STATUS_T as result. Typical values are listed in the following table.
goal_eplSetCommPar return values | |
|---|---|
Parameter | Description |
GOAL_OK | success |
GOAL_EPL_E_NOT_EXIST | internal communication object doesn't exist |
GOAL_EPL_E_STATE | node is in state OPERATIONAL |
GOAL_EPL_E_MAP | dynamic mapping is not available |
GOAL_EPL_E_NO_INITIATE | service not available (not defined/compiled) |
GOAL_EPL_E_NONEXIST_SUBINDEX | subindex doesn't exist |
GOAL_EPL_E_TRANS_TYPE | bad transmission type |
GOAL_EPL_E_PARA_INCOMP | parameter incompatible |
goal_eplPutObj - Put an object to the local object dictionary
The function copies the data into the object referenced by index and subIndex. The indices are bounds checked and the write permission for remote access to the object is proofed as well. If the subindex equals zero, then the first element or the whole structure/array will be put into the dictionary. The parameter size specifies the size of the data in bytes.
The user is responsible for correct coding of this function. The user is responsible for a correct data size information.
Returns a GOAL_STATUS_T as result.
goal_eplPutObj parameters | |
|---|---|
Parameter | Description |
GOAL_EPL_T *pHdlEpl | GOAL POWERLINK handle |
uint16_t index | main-index |
uint8_t subIndex | sub-index |
uint8_t *pData | data address |
uint32_t size | data size |
goal_eplGetNumOfElem - gets the number of elements of an array or struct
The number of elements of the object referenced by index of an array or record is returned. Returns a GOAL_STATUS_T as result.
goal_eplGetNumOfElem parameters | |
|---|---|
Parameter | Description |
GOAL_EPL_T *pHdlEpl | GOAL POWERLINK handle |
uint16_t index | index |
uint8_t *pNumber | pointer to return the number of elements |
goal_eplGetObjEntry - get an object entry from the local object dictionary
The function gets the value and the data size of an object referenced by index and subIndex. Size is the object size of a single element in bytes in cases of arrays or records as an object. It tests the limits of indices and the read permission. If the entry is of type domain, then the function returns the address of this entry.
goal_eplGetObjEntry parameters | |
|---|---|
Parameter | Description |
GOAL_EPL_T *pHdlEpl | GOAL POWERLINK handle |
uint16_t index | main-index |
uint8_t subIndex | sub-index |
uint8_t *pData | destination for data |
uint32_t *pSize | destination for data size |
Returns a GOAL_STATUS_T as result. Typical values are listed in the following table.
goal_eplGetObjEntry return values | |
|---|---|
Parameter | Description |
GOAL_OK | success |
GOAL_EPL_E_NONEXIST_OBJECT | object doesn't exist |
GOAL_EPL_E_NO_READ_PERM | no read permission |
GOAL_EPL_E_NONEXIST_SUBINDEX | subindex doesn't exist |
goal_eplWriteSdoReq - write a data object to the server's object dictionary
The function writes data objects, which are referenced by the index and subindex to the server's object dictionary. After a successful confirmation by goal_eplSdoWrCon() the value is valid on the remote device. Errors on transmission have to be checked within goal_eplSdoWrCon(). Numeric values should be transmited using sdo e.g. sdo = sdo | 0x80. It is recommended to use the constant GOAL_EPL_NUM_SDO in order to ensure the portability of the application.
goal_eplWriteSdoReq parameters | |
|---|---|
Parameter | Description |
GOAL_EPL_T *pHdlEpl | GOAL POWERLINK handle |
uint16_t node | Node-ID |
uint16_t index | index of object dictionary |
uint8_t subIndex | subindex of object dictionary |
uint8_t *pData | sdo data address |
uint32_t length | length of sdo data |
uint32_t timeOut | timeout in 0.1 msec |
Returns a GOAL_STATUS_T as result. Typical values are listed in the following table.
goal_eplWriteSdoReq return values |
|
|---|---|
Parameter | Description |
GOAL_OK | success |
GOAL_EPL_E_NOT_EXIST | SDO with current code num doesn't exist |
GOAL_EPL_E_STATE | node isn't in correct state |
GOAL_EPL_E_TYPE | SDO usertype isn't CLIENT |
GOAL_EPL_E_BUSY | an autom. domain transfer is still operating for this SDO |
GOAL_EPL_E_DISABLED | selected SDO is disabled |
GOAL_EPL_E_TIMEOUT | start timeout failed |
goal_eplReadSdoReq - read a data object from the server's object dictionary
The function reads data objects, which are referenced by the index and subindex from the server's object dictionary. After a successful confirmation by goal_eplSdoRdCon() the value was received from the remote device. Errors on transmission have to be checked within goal_eplSdoRdCon().
goal_eplReadSdoReq parameters | |
|---|---|
Parameter | Description |
GOAL_EPL_T *pHdlEpl | GOAL POWERLINK handle |
uint16_t node | Node-ID |
uint16_t index | index of object dictionary |
uint8_t subIndex | subindex of object dictionary |
uint8_t *pObj | pointer to destination address for object |
uint32_t size | size of object |
uint32_t timeOut | timeout in 0.1 msec |
Returns a GOAL_STATUS_T as result. Typical values are listed in the following table.
goal_eplReadSdoReq return values | |
|---|---|
Parameter | Description |
GOAL_OK | success |
GOAL_EPL_E_NOT_EXIST | SDO with current code num doesn't exist |
GOAL_EPL_E_STATE | node isn't in state |
GOAL_EPL_E_TYPE | SDO usertype isn't CLIENT |
GOAL_EPL_E_BUSY | an autom. domain transfer is still operating for this SDO |
GOAL_EPL_E_DISABLED | selected SDO is disable |