1 Device specific functions
2 Device Detection
3 PROFINET stack
4 EtherNet/IP stack
5 EtherCAT stack
6 Web server
7 Networking
8 TCP channel
9 UDP channel

Device specific functions

appl_ccmRpcInit

Purpose: Register System-on-Module API in GOAL (appl_init)

This function registers the System-on-Module specific API in GOAL and must be called in appl_init. It returns a GOAL_STATUS_T status and has no parameters.

Function Prototype:

GOAL_STATUS_T appl_ccmRpcInit(  
    void  
);

Example:

/****************************************************************************/  
/** Application Init 
 * 
 * Build up the device structure and initialize the Profinet stack. 
 */  
GOAL_STATUS_T appl_init(  
    void  
)  
{  
    GOAL_STATUS_T res = GOAL_OK;                /* result */  
  
    /* initialize ccm RPC interface */  
    res = appl_ccmRpcInit();  
    if (GOAL_RES_ERR(res)) {  
        goal_logErr("Initialization of ccm RPC failed");  
    }  
  
    return res;  
}

appl_ccmUpdateAllow

Purpose: Enable firmware update in the Communication Controller

This function enables the possibility to update the firmware of the System-on-Module. It returns a GOAL_STATUS_T status and has no parameters.

Function Prototype

GOAL_STATUS_T appl_ccmUpdateAllow(  
    void  
);

Example:
For an example, where firmware update capability can be enabled and disabled using the web server please check example project 01_pnio_io_mirror (chapter 7.1).

appl_ccmUpdateDeny

Purpose: Disable firmware update in the Communication Controller

This function disables the possibility to update the firmware of the System-on-Module. Possibly use of this function is to disable firmware update possibilities during a cyclic communication relation. It returns a GOAL_STATUS_T status and has no parameters.

Function Prototype:

GOAL_STATUS_T appl_ccmUpdateDeny(  
    void  
);

Example:
For an example, where firmware update capability can be enabled and disabled using the web server please check example project 01_pnio_io_mirror (chapter 7.1).

appl_ccmInfo

Purpose: Get version and device information

This function reads information from the System-on-Module:

MAC address (serial number)
Software version
device type

Function Prototype:

GOAL_STATUS_T appl_ccmInfo(  
    char *strVersion,                           /*< target string for version */  
    uint8_t lenStrVersion,                      /*< length of str buffer */  
    GOAL_ETH_MAC_ADDR_T *macAddress,            /*< mac address buffer */  
    uint16_t *pDevType                          /**< System-on-Module device type */  
);

Example:

/* get version and information of ccm */  
if (GOAL_RES_OK(res)) {  
    res = appl_ccmInfo(strVersion, APPL_VERSION_LEN, &mac, &devType);  
}  
  
if (GOAL_RES_OK(res)) {  
    goal_logInfo("ccm version : %s", strVersion);  
    goal_logInfo("ccm device : %u", devType);  
    goal_logInfo("ccm Serial : %02x:%02x:%02x:%02x:%02x:%02x",  
        mac[0], mac[1], mac[2], mac[3], mac[4], mac[5]);  
}

appl_ccmFaultStateSet

Pupose: Set behaviour of fieldbus communication on fault

This function determines the behaviour of the System-on-Module regarding cyclic communication. By default, a cyclic communication is stopped when communication to the application controller (AC) is lost.

Function Prototype:

GOAL_STATUS_T appl_ccmFaultStateSet(  
    APPL_CCM_FAULT_STATE_T faultState         /*< fault state to enter */  
);

Example:

/* set fault state behaviour */  
if (GOAL_RES_OK(res)) {  
    res = appl_ccmFaultStateSet(APPL_CCM_FAULT_STATE_ENTER);  
}

appl_ccmCommResetSet

Pupose: Set behaviour of System-on-Module on SPI sync reset request

A sync reset request is requested by the AC upon restart, while the CC was previously setup with a running AC application. This function determines the behaviour of the System-on-Module regardinging this reset request. By default, no reset is done. If this option is enabled, reset is done. The state of this setting is stored in non volatile memory on the CC. A value of 0 disables the reset. A value of 1 enables the reset.

Function Prototype:

GOAL_STATUS_T appl_ccmCommResetSet(  
    uint8_t value                               /*< option value */  
);

Example:

/* set sync reset behaviour */  
if (GOAL_RES_OK(res)) {  
    /* enable reset on sync reset request from AC */  
    res = appl_ccmCommResetSet(1);  
}

appl_ccmLogEnable

Pupose: Enable transport of AC log messages to the CC

Once this function is executed, log messages from the AC's logging buffer are continuously transferred to the module. Those are then accessible as the CC's own log messages through the management interface.

Function Prototype:

GOAL_STATUS_T appl_ccmLogEnable(  
    void  
);

Example:

/* enable logging to CC */  
if (GOAL_RES_OK(res)) {  
    res = appl_ccmLogEnable();  
}

appl_ccmLogToAcEnable

Minimal module firmware version: 2.0.0.0

Pupose: Enable transport of CC log messages to the AC

Once this function is executed, log messages from the CC's logging buffer are continuously transferred to the AC. Those are then accessible as the AC's own log messages through the local log mechanism, e.g. serial console or terminal.

Function Prototype:

GOAL_STATUS_T appl_ccmLogToAcEnable(  
    void  
);

Example:

/* enable logging from CC  to AC */  
if (GOAL_RES_OK(res)) {  
    res = appl_ccmLogToAcEnable();  
}

appl_ccmFwUpdateStart

Minimal module firmware version: 2.0.0.0

Pupose: Start firmware update of module using rpc

This function transfers the given data buffer, which contains firmware update data, to the communication controller.

Function Prototype:

GOAL_STATUS_T appl_ccmFwUpdateStart(
    uint8_t *pFwData,                           /*< firmware data */
    uint32_t fwSize                             /*< size of firmware data */
);

Example:

if (GOAL_RES_OK(res)) {
    res = appl_ccmFwUpdateStart(pBufFw, fsize);
}

appl_ccmFwUpdateExecute

Minimal module firmware version: 2.0.0.0

Purpose: Perform actual update of the firmware update

This function performs the actual update of the module. It must be called after transfer of the firmware data. This requires registration for firmware update events using appl_ccmFwUpdateCbReg(). If the application does not register for the events, the function appl_ccmFwUpdateExecute is called by the module implicitly.

Function Prototype:

GOAL_STATUS_T appl_ccmFwUpdateExecute(
     void
);

Example:

/* perform actual update */
appl_ccmFwUpdateExecute();

appl_ccmEcatSsiUpdate

Minimal module firware version: 2.0.0.0

Purpose: Perform update oft he EtherCAT Ssi data in eeprom

This function allows optionally an initialization of the EtherCAT ssi data in EEPROM. This should only be called once, since some EtherCAT masters rely on settings in the eeprom that should not be overwritten (Configured Station Alias).

Function Prototype:

GOAL_STATUS_T appl_ccmEcatSsiUpdate(
     unsigned char *pData,                       /*< SSI data */
     uint32_t dataLen,                           /*< SSI data length */
     GOAL_BOOL_T flgEmptyCheck                   /*< empty check before writing */
);

Example:

/* configure SII in EEPROM before creating the EtherCAT instance */
res = appl_ccmEcatSsiUpdate(
    &__09_ecat_slave_eeprom_bin[0],         /* data buffer */
    __09_ecat_slave_eeprom_bin_len,         /* data buffer length */
    GOAL_FALSE);                            /* always overwrite ssi data */
if (GOAL_RES_ERR(res)) {
    goal_logErr("failed to configure EEPROM ssi data");
}

Note:
There are some functions available for manipulating the provided example sii data. Usage can be found in the example 09_ecat_slave, file goal_appl.c. Usage must be enabled using the define ECAT_SSI_INIT.

appl_ccmFoeUpdateSettings

Minimal module firmware version: 2.0.0.0

Purpose: Configure requirements on FoE firmware update

This function allows changing required settings for FoE firmware update.

Function Prototype:

GOAL_STATUS_T appl_ccmFoeUpdateSettings(
     char *strName,                              /**< foe firmware filename */
     uint8_t matchLength,                        /**< string match length */
     uint32_t password,                          /**< foe password */
     GOAL_BOOL_T flgBootstrapReq                 /**< bootstrap required */
);

Example:

/* enable FoE */$
res = goal_ecatCfgFoeOn(GOAL_TRUE);$
if (GOAL_RES_ERR(res)) {$
    goal_logErr("failed to enable FoE support");$
}

/* enable BOOTSTRAP state */
res = goal_ecatCfgBootstrapOn(GOAL_TRUE);
if (GOAL_RES_ERR(res)) {
    goal_logErr("failed to enable BOOTSTRAP support");
}

/* set settings for ccm firmware update via FoE */
res = appl_ccmFoeUpdateSettings(
    "ccm.efw",                              /* filename beginning */
    0,                                      /* 0 -> match all characters */
    0,                                      /* password */
    GOAL_TRUE);                             /* only update in ESM state bootstrap */
if (GOAL_RES_ERR(res)) {
    goal_logErr("failed to configure FoE firmware update of CC");
    return res;
}

Remarks: For firmware update over FoE to work FoE needs to be enabled using the function goal_ecatCfgFoeOn(GOAL_TRUE). If firmware update is configured to take place on bootstrap esm state, support for this state needs to be enabled using goal_ecatCfgBootstrapOn(GOAL_TRUE). Beside that the parameters to appl_ccmFoeUpdateSettings define what required to perform the firmware update:

Parameter	Type	Function

Parameter	Type	Function
strName	String	filename expected for firmware update
matchLength	uint8	number of characters required to match between the configured foe file name and the foe file name of the update process. If matchLength is zero, all bytes of strName need to match. If strName is a string of length 0, the default file name "ccm.efw”is expected.
password	uint32	FoE password expected to accept the firmware update
flgBootstrapReq	bool	if enabled, firmware update will only be accepted in esm state bootstrap.

appl_ccmEthMacAddressSet

Minimal module firmware version: 2.0.0.0

Purpose: Configure a custom mac address for the device

This function allows changing of the mac address of the device. It needs to be called before any network related function (communication stack start, network initialization).

Function Prototype:

GOAL_STATUS_T appl_ccmEthMacAddressSet(
     uint8_t *pMacAddr
);

Example:

/* configure MAC address */ 
uint8_t devMacId[8] = {0x02, 0x01, 0x00, 0x00, 0x00, 0x01};
res = appl_ccmEthMacAddressSet(&devMacId[0]);

appl_ccmNetworkDefaultUp

Minimal module firmware version: 2.0.0.0

Purpose: Start default networking

This function starts the module in standard ethernet mode. It usually is not required to call this function, since protocol stacks automatically start the network in the proper mode.

Function Prototype:

GOAL_STATUS_T appl_ccmNetworkDefaultUp(
     void
);

Example:

/* start default networking */ 
res = appl_ccmNetworkDefaultUp();

appl_ccmNetworkEoEUp

Minimal module firmware version: 2.0.0.0

Purpose: Start EtherCAT eoe networking

This function starts the module in EtherCAT mode. It usually is not required to call this function, since the EtherCAT protocol stacks automatically start the network in the proper mode.

Function Prototype:

GOAL_STATUS_T appl_ccmNetworkEoEUp(
     void
);

Example:

/* start EtherCAT networking */ 
res = appl_ccmNetworkEoEUp();

appl_ccmCfgVarGet

Minimal module firmware version: 2.0.0.0

Purpose: Read any config variable

This function provides a mechanism to read any configuration variable of the module. It required a module id and a variable id, which is documented in GOAL Programmer's Manual - chapter goal_cm.

Function Prototype:

GOAL_STATUS_T appl_ccmCfgVarGet(
    uint32_t modId,                              /*< module id */
    uint32_t varId,                              /*< variable id */
    void *pBuf,                                  /*< [out] output buffer */
    uint32_t bufLength,                          /*< buffer length */
    uint32_t *pVarLength,                        /*< [out] variable length */
    uint32_t *pVarType                           /*< [out] variable type */
);

Example:

/* get signature of firmware */
if (GOAL_RES_OK(res)) {
    res = appl_ccmCfgVarGet(
        37, /* module id */
        0,  /* variable id */
        &fwSignature[0],
        sizeof(fwSignature),
        NULL, NULL);
}

appl_ccmCfgVarSet

Minimal module firmware version: 2.0.0.0

Purpose: Wrote any config variable

This function provides a mechanism to write any configuration variable of the module. It required a module id and a variable id, which is documented in GOAL Programmer's Manual - chapter goal_cm.

Function Prototype:

GOAL_STATUS_T appl_ccmCfgVarSet(
    uint32_t modId,                             /*< module id */
    uint32_t varId,                             /*< variable id */
    void *pBuf,                                 /*< [out] output buffer */
    uint32_t bufLength                          /*< buffer length */
);

Example:

/* demonstaration for writing of config variables */
valObj = 0x12345678;
if (GOAL_RES_OK(res)) {
    res = appl_ccmCfgVarSet(
        34, /* module id dd */
        1, /* variable id customer id */
        &valObj,
        sizeof(valObj));
}

appl_ccmCfgSave

Minimal module firmware version: 2.0.0.0

Purpose: Store config variable changes permanently

This function provides a mechanism to update the non volatile storage containing the config variables. The current values of the config variables will be stored.

Function Prototype:

GOAL_STATUS_T appl_ccmCfgSave(
     void
);

Example:

/* store current config variable values */
if (GOAL_RES_OK(res)) {
    res = appl_ccmCfgSave();
}

Device Detection

goal_ddInit - Register GOAL dd API in GOAL (appl_init)

Purpose: Initialize usage of dd component

This function registers the GOAL dd specific API in GOAL and must be called in appl_init. It returns a GOAL_STATUS_T status and has no parameters.

Function Prototype:

GOAL_STATUS_T goal_ddInit (  
    void  
);

Example:

GOAL_STATUS_T appl_init( 
    void  
)  
{  
    GOAL_STATUS_T res;  /*< GOAL result */   
    
    /* initialize GOAL dd API */  
    res = goal_ddInit();  
    if (GOAL_RES_ERR(res)) {  
        goal_logErr("failed to initialize GOAL dd API");  
    }  
    return res;  
}

goal_ddNew - Register GOAL dd API in GOAL (appl_setup)

Purpose: Create a new goal dd instance

This function creates an instance of GOAL dd in GOAL and must be called in appl_setup. A valid instance is requirement for using the GOAL dd API. It returns a GOAL_STATUS_T status and has the following parameters.

Parameter	Description
GOAL_DD_T **ppHdl	returned GOAL dd instance handle
uint32_t bitmaskFeatures	initial instance features to be enabled

Table 29 goal_ddNew parameters

The parameter bitmaskFeatures is a bitmask which disables single features of GOAL dd if set:

Bit	Feature
0	disable HELLO request (used for device scan detection)
1	disable WINK command
2	disable GETLIST command (read list of available CM variables)
3	disable GETCONFIG command (read cm variables value)
4	disable SETCONFIG command (write cm variables value)
5	disable SETIP command (configure IP through GOAL dd

Table 30 feature bitmask parameter
Function Prototype:

GOAL_STATUS_T goal_ddNew(  
    GOAL_DD_T **ppHdlDd,                        /*< DD handle */  
    uint32_t bitmaskFeatures                    /*< initial features */  
);

Example:

static GOAL_DD_T *pHdlDd;   /*< GOAL dd handle */  
  
GOAL_STATUS_T appl_setup(   
    void  
)  
{  
    GOAL_STATUS_T res;  /*< GOAL result */  
        / create GOAL dd instance */  
        res = goal_ddNew(&pHdlDd, GOAL_DD_FEAT_ALL);  
        if (GOAL_RES_ERR(res)) {  
            goal_logErr("failed to create GOAL dd instance");  
        }  
    return res;  
}

goal_ddCustomerIdSet

Purpose: Configure the customer id of GOAL dd instance

This function configures the customer Id of the given GOAL dd instance. The customer Id is a property of the underlying protocol which is contained in each request using GOAL dd. There is a special customer Id whith value of zero, which causes every request to be processed. If the customer Id is not equal to zero, a request will only be processed if the customer Id of the request equals the customer Id of the GOAL dd instance.

The customer Id is stored in non-volatile memory.

Parameter	Description
GOAL_DD_T *pHdl	GOAL dd instance handle
uint32_t customerId	instance customer Id

Table 31 goal_ddCustomerIdSet parameters
Function Prototype:

GOAL_STATUS_T goal_ddCustomerIdSet(  
    GOAL_DD_T *pHdlDd,                          /*< dd handle */  
    uint32_t cid                                /*< customer ID */  
);

Example:

/* configure DD properties */  
res = goal_ddCustomerIdSet(pHdlDd, APPL_DD_CUSTOMER_ID);  
if (GOAL_RES_ERR(res)) {  
    goal_logErr("failed to configure DD customer id");  
}

goal_ddModuleNameSet

Purpose: Configure the name of GOAL dd instance

This function configures the module name of the given GOAL dd instance. The module Id is a property of the device stored in non-volatile memory. It is used by the Industrial Communication Explorer for device naming. The module name length is limited to 20 bytes.

Parameter	Description
GOAL_DD_T *pHdl	GOAL dd instance handle
uint8_t *str	instance module name

Table 32 goal_ddModuleNameSet parameters
Function Prototype:

GOAL_STATUS_T goal_ddModuleNameSet(  
    GOAL_DD_T *pHdlDd,                          /*< dd handle */  
    uint8_t *str                                /*< module name */  
);

Example:

res = goal_ddModuleNameSet(pHdlDd, APPL_DD_MODULE_NAME);  
if (GOAL_RES_ERR(res)) {  
    goal_logErr("failed to configure DD module name");  
}

goal_ddFeaturesSet

Purpose: Configure the features of the GOAL dd instance

This function configures the features to be disabled for the given GOAL dd instance. This property is stored in the device stored in non volatile memory.

Parameter	Description
GOAL_DD_T *pHdl	GOAL dd instance handle
uint32_t bitmaskFeatures	instance features bitmask

Table 33 goal_ddFeaturesSet parameters
For parameter description see function "goal_ddNew".
Function Prototype:

GOAL_STATUS_T goal_ddFeaturesSet(  
    GOAL_DD_T *pHdlDd,                          /*< dd handle */  
    uint32_t bitmaskFeatures                    /*< bitmask with feature disable bits set */  
);

Example:

res = goal_ddFeaturesSet(pHdlDd, APPL_DD_FEATURES);  
if (GOAL_RES_ERR(res)) {  
    goal_logErr("failed to configure DD features");  
}

goal_ddCallbackReg

Purpose: Configure callback for GOAL dd instance

This function registers a callback to the given GOAL dd instance. Type of the callback:

typedef GOAL_STATUS_T (* GOAL_DD_FUNC_CB_T)(  
    struct GOAL_DD_T *pHdlDd,                   /*< dd handle */  
    GOAL_DD_CB_ID_T cbId,                       /*< callback id */  
    GOAL_DD_CB_DATA_T *pCbData                  /*< callback data */  
);

Function Prototype:

static GOAL_STATUS_T ddCallback(  
    GOAL_DD_T *pHdlDd,                          /*< dd handle */  
    GOAL_DD_CB_ID_T cbId,                       /*< callback ID */  
    GOAL_DD_CB_DATA_T *pCbData                  /*< callback data */  
);

Example:

/****************************************************************************/  
/** Application Setup 
 * 
 * This function must setup all used protocol stacks. 
 * 
 */  
GOAL_STATUS_T appl_setup(  
    void  
)  
{  
    GOAL_STATUS_T res;                          /* result */  
  
    res = goal_ddCallbackReg(pHdlDd, (GOAL_DD_FUNC_CB_T) ddCallback);  
  
    return res;  
}  
  
  
/****************************************************************************/  
/** goal dd callback 
 * 
 */  
 static GOAL_STATUS_T ddCallback(  
    GOAL_DD_T pHdlDd,                          /< dd handle */  
    GOAL_DD_CB_ID_T cbId,                       /*< callback ID */  
    GOAL_DD_CB_DATA_T pCbData                  /< callback data */  
)  
{  
    UNUSEDARG(pHdlDd);  
    UNUSEDARG(pCbData);  
  
    switch (cbId) {  
        case GOAL_DD_CB_ID_WINK:  
            goal_logInfo("Blink command received");  
            break;  
        default:  
            break;  
    }  
  
    return GOAL_OK;  
}

goal_ddSessionFeatureActivate

Purpose: Temporalily activation of features of GOAL dd instance

This function termporarily enabled features for the given GOAL dd instance. This property is _NOT stored in non volatile memory.

Parameter	Description
GOAL_DD_T *pHdl	GOAL dd instance handle
uint32_t bitmaskFeatures	instance features bitmask

Table 34 goal_ddSessionFeatureActivation parameters

The parameter bitmaskFeatures here is used inverted to the function for permanent configuration of the features, thus a bit set here, enabled the given feature.

Function Prototype:

GOAL_STATUS_T goal_ddSessionFeatureActivate(  
    GOAL_DD_T *pHdlDd,                          /*< dd handle */  
    uint32_t bitmaskFeatures                    /*< bitmask with feature enable bits set */  
);

Example:

/* temporarily enable capability to respond to hello requests (device detection) */
res = goal_ddSessionFeatureActipHdlDd, GOAL_DD_FEAT_HELLO);

goal_ddFilterAdd

Purpose: Limit access to cm variables

By default an external application as the Industrial Communication Explorer has total access to all CM variables of the device. This is a handy feature for development, but for production purpose one wants to limit access to only the variables that are required for minimal functionality using the Industrial Communication Explorer. Therefore filters were introduced, which do this task. Following filters are predefined:

Filter ID	Filter Name
0	GOAL_DD_ACCESS_FILTER_SET_ALL
1	GOAL_DD_ACCESS_FILTER_SET_BASIC
2	GOAL_DD_ACCESS_FILTER_SET_HIDDEN

Table 35 goal_ddFilterAdd filter sets

Filter ID	Filter Actions	Purpose
0	Full access granted to all variables	Development
1	Read Access to all variables of the NET module (IP settings), Read Access to all variables of the ETH module (MAC, status), Full access to all variables of the LM module (logging)	Production Code with minimal support of the Industrial Communication Explorer
2	Disables read access to the web server authentication strings	Production Code

Table 36 goal_ddFilterAdd predefined filters

definition of filter GOAL_DD_ACCESS_FILTER_SET_ALL

/*< complete access */  
static GOAL_DD_VAR_T ddAccessAll[] = {  
    {  
        .pNext = NULL,  
        .modId = GOAL_DD_VAR_ALL,  
        .varId = GOAL_DD_VAR_ALL,  
        .access = (1 << GOAL_DD_ACCESS_READ) | (1 << GOAL_DD_ACCESS_WRITE)  
    }  
};

definition of filter GOAL_DD_ACCESS_FILTER_SET_BASIC

/*< list of variables that are required for basic functionality */  
static GOAL_DD_VAR_T ddAccessListBasic[] = {  
    {   /* read access to network settings */  
        .pNext = (struct GOAL_DD_VAR_T *) &ddAccessListBasic[1],  
        .modId = GOAL_ID_NET,  
        .varId = GOAL_DD_VAR_ALL,  
        .access = (1 << GOAL_DD_ACCESS_READ)  
    },  
    {   /* read access to ethernet properties */  
        .pNext = (struct GOAL_DD_VAR_T *) &ddAccessListBasic[2],  
        .modId = GOAL_ID_ETH,  
        .varId = GOAL_DD_VAR_ALL,  
        .access = (1 << GOAL_DD_ACCESS_READ)  
    },  
    {   /* access to logs */  
        .pNext = NULL,  
        .modId = GOAL_ID_LM,  
        .varId = GOAL_DD_VAR_ALL,  
        .access = (1 << GOAL_DD_ACCESS_READ) | (1 << GOAL_DD_ACCESS_WRITE)  
    }  
};

definition of filter GOAL_DD_ACCESS_FILTER_SET_HIDDEN

static GOAL_DD_VAR_T ddAccessListHidden[] = {  
    {   /* disable read access to HTTP user level 0 */  
        .pNext = (struct GOAL_DD_VAR_T *) &ddAccessListHidden[1],  
        .modId = GOAL_ID_HTTP,  
        .varId = 2, / USERLEVEL0 /  
        .access = (1 << GOAL_DD_ACCESS_WRITE)  
    },  
    {   /* disable read access to HTTP user level 1 */  
        .pNext = (struct GOAL_DD_VAR_T *) &ddAccessListHidden[2],  
        .modId = GOAL_ID_HTTP,  
        .varId = 3, / USERLEVEL1 /  
        .access = (1 << GOAL_DD_ACCESS_WRITE)  
    },  
    {   /* disable read access to HTTP user level 2 */  
        .pNext = (struct GOAL_DD_VAR_T *) &ddAccessListHidden[3],  
        .modId = GOAL_ID_HTTP,  
        .varId = 4, / USERLEVEL2 /  
        .access = (1 << GOAL_DD_ACCESS_WRITE)  
    },  
    {   /* disable read access to HTTP user level 3 */  
        .pNext = NULL,  
        .modId = GOAL_ID_HTTP,  
        .varId = 5, / USERLEVEL3 /  
        .access = (1 << GOAL_DD_ACCESS_WRITE)  
    },  
};

Function Prototype:

GOAL_STATUS_T goal_ddFilterAdd(  
    GOAL_DD_T *pHdlDd,                          /*< dd handle */  
    GOAL_DD_ACCESS_FILTER_SET_T setId           /*< set id */  
);

Example:

#if 0  
    /* enable for full access */  
    res = goal_ddFilterAdd(pHdlDd, GOAL_DD_ACCESS_FILTER_SET_ALL);  
    if (GOAL_RES_ERR(res)) {  
        goal_logErr("failed to set dd access filter");  
    }  
#endif  
  
    res = goal_ddFilterAdd(pHdlDd, GOAL_DD_ACCESS_FILTER_SET_HIDDEN);  
    if (GOAL_RES_ERR(res)) {  
        goal_logErr("failed to set dd access filter");  
    }

PROFINET stack

Please see the PROFINET documentation.

EtherNet/IP stack

Please see the EtherNet/IP documentation.

EtherCAT stack

Please see the EtherCAT documentation.

Web server

Please see the GOAL programmer's manual.

Networking

goal_netRpcInit

Purpose: Initialize RPC functionality for networking.

If networking functionality (IP settings, UDP channel, TCP channel) is required, this function needs to be called during application initialization.

Function Prototype:

GOAL_STATUS_T goal_netRpcInit(  
    uint32_t id                                 /*< id for MA instance */  
)

Example:

/****************************************************************************/  
/** Application Init 
 * 
 * Initialize the net stack 
 */  
GOAL_STATUS_T appl_init(  
    void  
)  
{  
    GOAL_STATUS_T res;                          /* result */  
  
    /* initialize goal net */  
    res = goal_netRpcInit(GOAL_NET_ID_DEFAULT);  
    if (GOAL_RES_ERR(res)) {  
        goal_logErr("Initialization of goal net RPC failed");  
    }  
  
    return res;  
}

goal_maNetOpen - open network channel

Purpose: Open the network media adapter for usage.

Function Prototype:

GOAL_STATUS_T goal_maNetOpen(  
    uint32_t id,                                /*< id of NET handler to use */  
    GOAL_MA_NET_T **ppNetHdl                    /*< pointer to store NET handler */  
);

Example:

/****************************************************************************/  
/** Application Setup 
 * 
 * This function is called by the GOAL init-stage system to open UDP channels. 
 * 
 * API functions from earlier stages are allowed to be used here. 
 */  
GOAL_STATUS_T appl_setup(  
    void  
)  
{  
    GOAL_STATUS_T res;                          / result */  
    GOAL_MA_NET_T pMaNet;                      / net ma handle */  
  
    res = goal_maNetOpen(GOAL_NET_ID_DEFAULT, &pMaNet);  
    if (GOAL_RES_ERR(res)) {  
        goal_logErr("error opening network MA");  
    }  
  
    return res;  
}

goal_maNetClose - close network

Purpose: Close the network MA

Function Prototype:

GOAL_STATUS_T goal_maNetClose(  
    GOAL_MA_NET_T *pNetHdl                      /*< pointer to store NET handler */  
);

goal_maNetGetById - get network MA handle

Purpose: Get the network MA handle which was previously open for usage.

Function Prototype:

GOAL_STATUS_T goal_maNetGetById(  
    GOAL_MA_NET_T **ppHdlMaNet,                 /*< NET handle ref ptr */  
    uint32_t id                                 /*< MA id */  
);

Example:

res = goal_maNetGetById(&pMaNet, GOAL_NET_ID_DEFAULT);  
if (GOAL_RES_ERR(res)) {  
     goal_logErr("error getting network MA");  
}

goal_maNetIpSet – set ip address

Purpose: Set the network interface IP address.

Function Prototype:

GOAL_STATUS_T goal_maNetIpSet(  
    GOAL_MA_NET_T *pNetHdl,                     /*< pointer to store NET handler */  
    uint32_t addrIp,                            /*< IP address */  
    uint32_t addrMask,                          /*< subnet mask */  
    uint32_t addrGw,                            /*< gateway */  
    GOAL_BOOL_T flgTemp                         /*< temporary IP config flag */  
);

Example:

/* set IP address */  
ip = MAIN_APPL_IP;  
nm = MAIN_APPL_NM;  
gw = MAIN_APPL_GW;  
res = goal_maNetIpSet(pMaNet, ip, nm, gw, GOAL_FALSE);  
if (GOAL_RES_ERR(res)) {  
    goal_logErr("error while setting IP address");  
    return res;  
}

TCP channel

goal_maChanTcpOpen - open the tcp channel MA

Purpose: Opens the networking MA for further usage. This needs to be done once at application startup.

Function Prototype:

GOAL_STATUS_T goal_maChanTcpOpen(  
    uint32_t id,                                /*< MA id */  
    GOAL_MA_CHAN_TCP_T **ppHdlMaChanTcp         /*< CHAN_TCP handle ref ptr */  
);

Example:

res = goal_maChanTcpOpen(GOAL_NET_ID_DEFAULT, &pMaTcp);  
if (GOAL_RES_ERR(res)) {  
    goal_logErr("error getting tcp MA");  
    return res;  
}

goal_maChanTcpNew - create a new tcp channel

Purpose: This function creates a new tcp channel.

Function Prototype:

GOAL_STATUS_T goal_maChanTcpNew(  
    GOAL_MA_CHAN_TCP_T *pChanTcpHdl,            /*< pointer to store CHAN_TCP handler */  
    GOAL_NET_CHAN_T **ppChanHandle,             /*< pointer to channel handle */  
    GOAL_NET_CHAN_T *pChanOut,                  /*< pointer to channel handle for output */  
    GOAL_NET_ADDR_T *pAddr,                     /*< remote address */  
    GOAL_NET_TYPE_T type,                       /*< connection type */  
    GOAL_MA_CHAN_TCP_CB_T callback              /*< channel callback */  
);

Example:

/* register TCP server */  
GOAL_MEMSET(&addr, 0, sizeof(GOAL_NET_ADDR_T));  
addr.localPort = (uint16_t) (MAIN_APPL_TCP_PORT + cnt);  
res = goal_maChanTcpNew(pMaTcp, &pChan, NULL, &addr, GOAL_NET_TCP_LISTENER,
 tcpCallback);  
if (GOAL_OK != res) {  
    goal_logErr("error while opening TCP server channel on port %"FMT_u32,
        (uint32_t) MAIN_APPL_TCP_PORT + cnt);  
    return res;  
}

goal_maChanTcpActive - activate a created tcp channel

Purpose: Activate a previously created tcp channel. Once it is activated, it establish connections or accepts incoming connection requests.

Function Prototype:

GOAL_STATUS_T goal_maChanTcpActivate(  
    GOAL_MA_CHAN_TCP_T *pChanTcpHdl,            /*< pointer to store CHAN_TCP handler */  
    GOAL_NET_CHAN_T *pChanHandle                /*< channel handle */  
);

Example:

/* activate channel */  
res = goal_maChanTcpActivate(pMaTcp, pChanTcp);  
if (GOAL_OK != res) {  
    goal_logErr("error while enabling TCP channel");  
    return;  
}

goal_maChanTcpSetNonBlocking - set channel to non blocking

Purpose: Set socket to non blocking mode for reading.

Function Prototype:

GOAL_STATUS_T goal_maChanTcpSetNonBlocking(  
    GOAL_MA_CHAN_TCP_T *pChanTcpHdl,            /*< pointer to store CHAN_TCP handler */  
    GOAL_NET_CHAN_T *pChanHandle,               /*< channel handle */  
    GOAL_BOOL_T flgOption                       /*< non blocking state */  
);

Example:

/* set TCP channel to non-blocking */  
res = goal_maChanTcpSetNonBlocking(pMaTcp, pChanTcp, GOAL_TRUE);  
if (GOAL_OK != res) {  
    goal_logErr("error while setting TCP channel to non-blocking");  
    return;  
}

goal_maChanTcpGetRemoteAddr - get remote address of tcp channel

Purpose: Get the ip address of the remote end point of the tcp channel.

Function Prototype:

GOAL_STATUS_T goal_maChanTcpGetRemoteAddr(  
    GOAL_MA_CHAN_TCP_T *pChanTcpHdl,            /*< pointer to store CHAN_TCP handler */  
    GOAL_NET_CHAN_T *pChanHandle,               /*< channel handle */  
    GOAL_NET_ADDR_T *pAddr                      /*< remote address */  
);

Example:

/* get IP Address of remote node */  
res = goal_maChanTcpGetRemoteAddr(pMaTcpHdl, pChan, &remote);  
if (GOAL_RES_ERR(res)) {  
    goal_logErr("Failed to get Remote Address for socket %p", (void *) pChan);  
    return;  
}

goal_maChanTcpSend - send data through tcp channel

Purpose: Send data to a previously opened TCP channel.

Function Prototype:

GOAL_STATUS_T goal_maChanTcpSend(  
    GOAL_MA_CHAN_TCP_T *pChanTcpHdl,            /*< pointer to store CHAN_TCP handler */  
    GOAL_NET_CHAN_T *pChanHandle,               /*< channel handle */  
    GOAL_BUFFER_T *pBuf                         /*< buffer with data to send */  
);

Example:

/* echo message */
goal_maChanTcpSend(pMaTcpHdl, pChan, pBuf);

UDP channel

goal_maChanUdpOpen - open the udp channel MA

Purpose: Open the udp channel ma. This needs to be done once at application startup.

Function Prototype:

GOAL_STATUS_T goal_maChanUdpOpen(  
    uint32_t id,                                /*< MA id */  
    GOAL_MA_CHAN_UDP_T **ppHdlMaChanUdp         /*< CHAN_UDP handle ref ptr */  
);

Example:

/* open udp channel MA and create new channel */  
res = goal_maChanUdpOpen(GOAL_NET_ID_DEFAULT, &pMaChanUdp);  
if (GOAL_RES_OK(res)) {  
    GOAL_MEMSET(&addr, 0, sizeof(GOAL_NET_ADDR_T));  
    addr.localPort = MAIN_APPL_UDP_PORT_1;  
    res = goal_maChanUdpNew(pMaChanUdp, &pChan1, NULL, &addr, GOAL_NET_UDP_SERVER, udpCallback);  
}

goal_maChanUdpGetById - get the udp channel MA handle

Purpose: This function gets the handle of the udp channel ma which was previously opened.

Function Prototype:

GOAL_STATUS_T goal_maChanUdpGetById(  
    GOAL_MA_CHAN_UDP_T **ppHdlMaChanUdp,        /*< CHAN_UDP handle ref ptr */  
    uint32_t id                                 /*< MA id */  
);

goal_maChanUdpNew - create a new udp channel

Purpose: Create a new udp channel.

Function Prototype:

GOAL_STATUS_T goal_maChanUdpNew(  
    GOAL_MA_CHAN_UDP_T *pChanUdpHdl,            /*< pointer to store CHAN_UDP handler */  
    GOAL_NET_CHAN_T **ppChanHandle,             /*< pointer to channel handle */  
    GOAL_NET_CHAN_T *pChanOut,                  /*< pointer to channel handle for output */  
    GOAL_NET_ADDR_T *pAddr,                     /*< remote address */  
    GOAL_NET_TYPE_T type,                       /*< connection type */  
    GOAL_MA_CHAN_UDP_CB_T callback              /*< channel callback */  
);

Example:

if (GOAL_RES_OK(res)) {  
     GOAL_MEMSET(&addr, 0, sizeof(GOAL_NET_ADDR_T));  
     addr.localPort = MAIN_APPL_UDP_PORT_1;  
     res = goal_maChanUdpNew(pMaChanUdp, &pChan1, NULL, &addr, GOAL_NET_UDP_SERVER,
 udpCallback);  
 }

goal_maChanUdpClose - close the udp channel MA

Purpose: Close an existing channel.

Function Prototype:

GOAL_STATUS_T goal_maChanUdpClose(  
    GOAL_MA_CHAN_UDP_T *pChanUdpHdl,            /*< pointer to store CHAN_UDP handler */  
    GOAL_NET_CHAN_T *pChanHandle                /*< pointer to channel handle */  
);

goal_maChanUdpSetNonBlocking - set the opened channel to non blocking access

Purpose: Set a channel to non blocking operation.

Function Prototype:

GOAL_STATUS_T goal_maChanUdpSetNonBlocking(  
    GOAL_MA_CHAN_UDP_T pChanUdpHdl,            /*< pointer to store CHAN_UDP handler */  
    GOAL_NET_CHAN_T pChanHandle,               /*< channel handle */  
    GOAL_BOOL_T flgOption                      /*< option value */  
);

Example:

res = goal_maChanUdpSetNonBlocking(pMaChanUdp, pChan2, GOAL_TRUE);  
if (GOAL_OK != res) {  
    goal_logErr("error while setting UDP channel to non-blocking");  
    return res;  
}

goal_maChanUdpSetBroadcast - set the opened udp channel to broadcast operation

Purpose: Set a channel to broadcast.

Function Prototype:

GOAL_STATUS_T goal_maChanUdpSetBroadcast(  
    GOAL_MA_CHAN_UDP_T *pChanUdpHdl,            /*< pointer to store CHAN_UDP handler */  
    GOAL_NET_CHAN_T *pChanHandle,               /*< channel handle */  
    GOAL_BOOL_T flgOption                       /*< option value */  
);

Example:

/* enable broadcast reception */  
res = goal_maChanUdpSetBroadcast(pMaChanUdp, pChan1, GOAL_TRUE);  
if (GOAL_RES_ERR(res)) {  
    goal_logErr("error while setting UDP channel to receive broadcasts");  
    return res;  
}

goal_maChanUdpGetRemoteAddr - get remote address of the udp channel

Purpose: Get the remote address of a udp channel, thus the address it received data from.

Function Prototype:

GOAL_STATUS_T goal_maChanUdpGetRemoteAddr(  
    GOAL_MA_CHAN_UDP_T *pChanUdpHdl,            /*< pointer to store CHAN_UDP handler */  
    GOAL_NET_CHAN_T *pChanHandle,               /*< channel handle */  
    GOAL_NET_ADDR_T *pAddr                      /*< remote address */  
);

goal_maChanUdpActivate - acticate a udp channel

Purpose: Activate a channel.

Function Prototype:

GOAL_STATUS_T goal_maChanUdpActivate(  
    GOAL_MA_CHAN_UDP_T *pChanUdpHdl,            /*< pointer to store CHAN_UDP handler */  
    GOAL_NET_CHAN_T *pChanHandle                /*< channel handle */  
);

Example:

res = goal_maChanUdpActivate(pMaChanUdp, pChan2);  
if (GOAL_RES_ERR(res)) {  
    goal_logErr("error while enabling UDP channel");  
    return res;  
}

goal_maChanUdpSend - send data to the udp channel

Purpose: Send data to an open udp channel.

Function Prototype:

GOAL_STATUS_T goal_maChanUdpSend(  
    GOAL_MA_CHAN_UDP_T *pChanUdpHdl,            /*< pointer to store CHAN_UDP handler */  
    GOAL_NET_CHAN_T *pChanHandle,               /*< channel handle */  
    GOAL_BUFFER_T *pBuf                         /*< buffer with data to send */  
);

Example:

/* echo message */  
goal_maChanUdpSend(pMaChanUdp, pChan, pBuf);

The GOAL Application Programming Interface

Device specific functions

appl_ccmRpcInit

appl_ccmUpdateAllow

appl_ccmUpdateDeny

appl_ccmInfo

appl_ccmFaultStateSet

appl_ccmCommResetSet

appl_ccmLogEnable

appl_ccmLogToAcEnable

appl_ccmFwUpdateStart

appl_ccmFwUpdateExecute

appl_ccmEcatSsiUpdate

appl_ccmFoeUpdateSettings

appl_ccmEthMacAddressSet

appl_ccmNetworkDefaultUp

appl_ccmNetworkEoEUp

appl_ccmCfgVarGet

appl_ccmCfgVarSet

appl_ccmCfgSave

Device Detection

goal_ddInit - Register GOAL dd API in GOAL (appl_init)

goal_ddNew - Register GOAL dd API in GOAL (appl_setup)

goal_ddCustomerIdSet

goal_ddModuleNameSet

goal_ddFeaturesSet

goal_ddCallbackReg

goal_ddSessionFeatureActivate

goal_ddFilterAdd

definition of filter GOAL_DD_ACCESS_FILTER_SET_ALL

definition of filter GOAL_DD_ACCESS_FILTER_SET_BASIC

definition of filter GOAL_DD_ACCESS_FILTER_SET_HIDDEN

PROFINET stack

EtherNet/IP stack

EtherCAT stack

Web server

Networking

goal_netRpcInit

goal_maNetOpen - open network channel

goal_maNetClose - close network

goal_maNetGetById - get network MA handle

goal_maNetIpSet – set ip address

TCP channel

goal_maChanTcpOpen - open the tcp channel MA

goal_maChanTcpNew - create a new tcp channel

goal_maChanTcpActive - activate a created tcp channel

goal_maChanTcpSetNonBlocking - set channel to non blocking

goal_maChanTcpGetRemoteAddr - get remote address of tcp channel

goal_maChanTcpSend - send data through tcp channel

UDP channel

goal_maChanUdpOpen - open the udp channel MA

goal_maChanUdpGetById - get the udp channel MA handle

goal_maChanUdpNew - create a new udp channel

goal_maChanUdpClose - close the udp channel MA

goal_maChanUdpSetNonBlocking - set the opened channel to non blocking access

goal_maChanUdpSetBroadcast - set the opened udp channel to broadcast operation

goal_maChanUdpGetRemoteAddr - get remote address of the udp channel

goal_maChanUdpActivate - acticate a udp channel

goal_maChanUdpSend - send data to the udp channel

Related content