Versions Compared

Old Version 4

changes.mady.by.user Torsten Bitterlich

Saved on

compared with

New Version 5

changes.mady.by.user Torsten Bitterlich

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


This chapter lists the API functions that are provided by irj45.

...

Purpose: Anchor_Toc534961860_Toc534961860
This chapter lists the API functions that are provided by irj45.

device specific functions

appl_ccmRpcInit

Purpose: Register irj45 API in GOAL (appl_init)

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

Function Prototype:

Code Block
languagec
GOAL_STATUS_

...

T goal_ddRpcInit(

...

  
    void  
);

Example:

Code Block
languagec
/****************************************************************************/

...

  
/**

...

 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: Anchor_Toc534961861_Toc534961861 Enable firmware update in the Communication Controller
This function enables the possibility to update the firmware of the irj45 CC module. It returns a GOAL_STATUS_T status and has no parameters.

Function Prototype

Code Block
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: Anchor_Toc534961862_Toc534961862 Disable firmware update in the Communication Controller
This function disables the possibility to update the firmware of the irj45 CC 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:

Code Block
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).
...
01_pnio_io_mirror (chapter 7.1).
appl_ccmInfo

Purpose: Anchor_Toc534961863_Toc534961863 Get version and device information 
This function reads information from the irj45:
  • MAC address (serial number)
  • Software version
  • device type

Function Prototype: 
 Code Block
languagec
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                          /**< irj45 device type */  
);

Example: 
 Code Block
languagec
/* 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:  Anchor_Toc534961864_Toc534961864 Set behaviour of fieldbus communication on fault 
This function determines the behaviour of the irj45 regarding cyclic communication. By default, a cyclic communication is stopped when communication to the application controller (AC) is lost. 
Function Prototype: 
 Code Block
GOAL_STATUS_
...
T appl_ccmFaultStateSet(
...
  
    APPL_CCM_FAULT_STATE_
...
T faultState         /*< fault state to enter */  
);   

Example: 
 Code Block
/* set fault state behaviour */  
if (GOAL_RES_OK(res))
...
 {  
    res = appl_ccmFaultStateSet(APPL_CCM_FAULT_STATE_ENTER);
...
  
}  
appl_ccmCommResetSet

Pupose:  Anchor_Toc534961865_Toc534961865 Set behaviour of irj45 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 irj45 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: 
 Code Block
GOAL_STATUS_
...
T appl_ccmCommResetSet(
...
  
    uint8_t value                               /*< option value */  
); 

Example: 
 Code Block
/* 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 CC module. Those are then accessible as the CC's own log messages through the management interface. 
Function Prototype: 
 Code Block
GOAL_STATUS
...
_T appl_ccmLogEnable(
...
  
    void  
);
...

Example: 
 Code Block
languagec
/
...
* enable logging to
...
 CC */  
if (GOAL_RES_OK(res))
...
 {  
    res = appl_ccmLogEnable();
...
  
}  
appl_ccmLogToAcEnable

Minimal ccm firware 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 module. Those are then accessible as the AC's own log messages through the local log mechanism, e.g. serial console or terminal. 
Function Prototype: 
 Code Block
languagec
GOAL_STATUS_
...
T appl_ccmLogToAcEnable(
...
  
    void  
);
...

Example: 
 Code Block
/
...
* enable logging from
...
 CC  to AC */  
if (GOAL_RES_OK(res))
...
 {  
    res = appl_ccmLogToAcEnable();
...
  
}
appl_ccmFwUpdateStart

Minimal ccm firware version: 2.0.0.0 
Pupose: Start firmware update of ccm module using rpc 
This function transfers the given data buffer, which contains firmware update data, to the communication controller. 
Function Prototype: 
 Code Block
GOAL_STATUS_
...
T appl_ccmFwUpdateStart(
    uint8_t *pFwData,                           /*< firmware data */
    uint32_t fwSize                             /*< size of firmware data */
); 

Example: 
 Code Block
if (GOAL_RES_OK(res))
...
 {
    res = appl_ccmFwUpdateStart(pBufFw,
...
 fsize);
...

}
...
appl_ccmFwUpdateExecute

Minimal ccm firware version: 2.0.0.0 
Pupose: Perform actual update of the firmware update 
This function performs the actual update of the ccm 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 ccm implicetily. 
Function Prototype: 
 Code Block
GOAL_STATUS_
...
T appl_ccmFwUpdateExecute(
...

     void
);

Example: 
 Code Block
...
/* perform actual update */
appl_ccmFwUpdateExecute();
...
...
appl_ccmEcatSsiUpdate

Minimal ccm firware version: 2.0.0.0 
Pupose: 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: 
 Code Block
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: 
 Code Block
...
/* 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_ccmEthMacAddressSet

Minimal ccm firware version: 2.0.0.0 
Pupose: 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: 
 Code Block
GOAL_STATUS_
...
T appl_ccmEthMacAddressSet(
...

     uint8_t
...
 *pMacAddr
...

);

Example: 
 Code Block
...
/* configure MAC address */ 
uint8_t devMacId[8] = {0x02, 0x01, 0x00, 0x00, 0x00, 0x01};
...

res = appl_ccmEthMacAddressSet(&devMacId[0]);
...
...
appl_ccmNetworkDefaultUp

Minimal ccm firware version: 2.0.0.0 
Purpose: Start default networking 
This function starts the ccm 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: 
 Code Block
GOAL_STATUS_
...
T appl_ccmNetworkDefaultUp(
...

     void
);

Example: 
 Code Block
...
/
...
* start default networking */ 
res = appl_ccmNetworkDefaultUp();
...
appl_ccmNetworkEoEUp

Minimal ccm firware version: 2.0.0.0 
Purpose: Start EtherCAT eoe networking 
This function starts the ccm 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: 
 Code Block
GOAL_STATUS_
...
T appl_ccmNetworkEoEUp(
...

     void
);

Example:
 Code Block
...
/
...
* start EtherCAT networking */ 
res = appl_ccmNetworkEoEUp();
...

appl_ccmCfgVarGet

Minimal ccm firware version: 2.0.0.0 
Purpose: Read any config variable 
This function provides a mechanism to read any configuration variable of the ccm module. It required a module id and a variable id, which is documented in chapter 4.9. 
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 
Purpose: Read any config variable 
This function provides a mechanism to read any configuration variable of the ccm module. It required a module id and a variable id, which is documented in chapter 4.9. 
Function Prototype: 
 Code Block
languagec
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: 
 Code Block
/* 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 ccm firware version: 2.0.0.0 
Purpose: Wrote any config variable 
This function provides a mechanism to write any configuration variable of the ccm module. It required a module id and a variable id, which is documented in chapter 4.9. 
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 
Function Prototype: 
 Code Block
languagec
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: 
 Code Block
languagec
/* 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 ccm firware 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: 
 Code Block
GOAL_STATUS_
...
T appl_ccmCfgSave(
...

     void
);

Example:     / store current config variable values /
    if 
 Code Block
/* 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: 
 Code Block
GOAL_STATUS_
...
T goal_ddInit
...
 (  
    void  
);

Example: 
 Code Block
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: 
 Code Block
GOAL_STATUS_
...
T goal_ddNew(
...
  
    GOAL_DD_
...
T **ppHdlDd,
...
                        /*< DD handle */  
    uint32_t bitmaskFeatures                    /*< initial features */  
);   

Example: 
 Code Block
languagec
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: 
 Code Block
languagec
GOAL_STATUS_
...
T goal_ddCustomerIdSet(
...
  
    GOAL_DD_
...
T *pHdlDd,
...
                          /*< dd handle */  
    uint32_t cid                                /*< customer ID */  
); 

Example: 
 Code Block
/* 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 my the management tool 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: 
 Code Block
GOAL_STATUS_
...
T goal_ddModuleNameSet(
...
  
    GOAL_DD_
...
T *pHdlDd,
...
                          /*< dd handle */  
    uint8_t *str                                /*< module name */  
);
  
Example: 
 Code Block
...
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: 
 Code Block
GOAL_STATUS_
...
T goal_ddFeaturesSet(
...
  
    GOAL_DD_
...
T *pHdlDd,
...
                          /*< dd handle */  
    uint32_t bitmaskFeatures                    /*< bitmask with feature disable bits set */  
);  
 
Example: 
 Code Block
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: 
 Code Block
languagec
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: 
 Code Block
languagec
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: 
 Code Block
/****************************************************************************/
...
  
/**
...
 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
ATTENTION: The parameter bitmaskFeatures here is used iverted to the function for permanent configuration of the features, thus a bit set here, enabled the given feature. 
Function Prototype: 
 Code Block
GOAL_STATUS_
...
T goal_ddSessionFeatureActivate(  
    GOAL_DD_T *pHdlDd,                          /*< dd handle */  
    uint32_t bitmaskFeatures                    /*< bitmask with feature enable bits set */  
);   

Example: 
 Code Block
/* 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 Management Tool 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 Management Tool. 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 Management Tool
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
 Code Block
/*< 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
 Code Block
languagec
/*
...
< 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
 Code Block
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:
 Code Block
GOAL_STATUS_
...
T goal_ddFilterAdd(
...
  
    GOAL_DD_
...
T *pHdlDd,
...
                          /*< dd handle */  
    GOAL_DD_ACCESS_FILTER_SET_
...
T setId           /*< set id */  
);  

Example:
 Code Block
#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

see profinet documentation
...
ethernet ip stack

see ethernet ip documentation
...
EtherCAT stack

See EtherCAT documentation
...
web server

see 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:Prototype: 
 Code Block
languagec
GOAL_STATUS_
...
T goal_netRpcInit(
...
  
    uint32_t id                                 /*< id for MA instance */  
)

Example: 
 Code Block
languagec
/****************************************************************************/
...
  
/**
...
 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: 
 Code Block
languagec
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: 
 Code Block
languagec
/****************************************************************************/
...
  
/**
...
 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: 
 Code Block
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: 
 Code Block
GOAL_STATUS_
...
T goal_maNetGetById(
...
  
    GOAL_MA_NET_
...
T **ppHdlMaNet,
...
                 /*< NET handle ref ptr */  
    uint32_t id                                 /*< MA id */  
);  

Example: 
 Code Block
languagec
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: 
 Code Block
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: 
 Code Block
/* 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: 
 Code Block
GOAL_STATUS_
...
T goal_maChanTcpOpen(
...
  
    uint32_t id,                                /*< MA id */  
    GOAL_MA_CHAN_TCP_T **ppHdlMaChanTcp         /*< CHAN_TCP handle ref ptr */  
);   
  
Example: 
 Code Block
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:
 Code Block
languagec
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: 
 Code Block
languagec
/
...
* 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 established connection or accepts incoming connection requests. 
Function Prototype: 
 Code Block
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: 
 Code Block
/* 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: 
 Code Block
languagec
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: 
 Code Block
/* 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: 
 Code Block
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
 Code Block
languagec
/* 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: 
 Code Block
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:
 Code Block
/* 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: 
 Code Block
languagec
GOAL_STATUS_
...
T goal_maChanUdpOpen(
...
  
    uint32_t id,                                /*< MA id */  
    GOAL_MA_CHAN_UDP_T **ppHdlMaChanUdp         /*< CHAN_UDP handle ref ptr */  
);
  
Example: 
 Code Block
/* 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: 
 Code Block
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: 
 Code Block
languagec
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: 
 Code Block
languagec
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: 
 Code Block
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: 
 Code Block
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: 
 Code Block
languagec
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: 
 Code Block
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
 Code Block
/* 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: 
 Code Block
languagec
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: 
 Code Block
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
 Code Block
languagec
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: 
 Code Block
languagec
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: 
 Code Block
/* echo message */  
goal_maChanUdpSend(pMaChanUdp,
...
 pChan,
...
 pBuf);
...