The GOAL Application Programming Interface
- Torsten Bitterlich (Unlicensed)
- Tino Biehle
- Marcus Tangermann
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:
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:
Example:
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:
Example:
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:
Example:
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:
Example:
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:
Example:
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:
Example:
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:
Example:
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:
Example:
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:
Example:
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 |
|---|---|---|
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:
Example:
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:
Example:
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:
Example:
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:
Example:
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:
Example:
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:
Example:
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:
Example:
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:
Example:
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:
Example:
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:
Example:
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:
Example:
goal_ddCallbackReg
Purpose: Configure callback for GOAL dd instance
This function registers a callback to the given GOAL dd instance. Type of the callback:
Function Prototype:
Example:
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:
Example:
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 | Filter Actions | Purpose |
0 | Full access granted to all variables | Development |
1 | Read Access to all variables of the NET module | Production Code with minimal support of the Industrial Communication Explorer |
2 | Disables read access to the web server | Production Code |
Table 36 goal_ddFilterAdd predefined filters
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
Function Prototype:
Example:
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:
Example:
goal_maNetOpen - open network channel
Purpose: Open the network media adapter for usage.
Function Prototype:
Example:
goal_maNetClose - close network
Purpose: Close the network MA
Function Prototype:
goal_maNetGetById - get network MA handle
Purpose: Get the network MA handle which was previously open for usage.
Function Prototype:
Example:
goal_maNetIpSet – set ip address
Purpose: Set the network interface IP address.
Function Prototype:
Example:
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:
Example:
goal_maChanTcpNew - create a new tcp channel
Purpose: This function creates a new tcp channel.
Function Prototype:
Example:
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:
Example:
goal_maChanTcpSetNonBlocking - set channel to non blocking
Purpose: Set socket to non blocking mode for reading.
Function Prototype:
Example:
goal_maChanTcpGetRemoteAddr - get remote address of tcp channel
Purpose: Get the ip address of the remote end point of the tcp channel.
Function Prototype:
Example:
goal_maChanTcpSend - send data through tcp channel
Purpose: Send data to a previously opened TCP channel.
Function Prototype:
Example:
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:
Example:
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_maChanUdpNew - create a new udp channel
Purpose: Create a new udp channel.
Function Prototype:
Example:
goal_maChanUdpClose - close the udp channel MA
Purpose: Close an existing channel.
Function Prototype:
goal_maChanUdpSetNonBlocking - set the opened channel to non blocking access
Purpose: Set a channel to non blocking operation.
Function Prototype:
Example:
goal_maChanUdpSetBroadcast - set the opened udp channel to broadcast operation
Purpose: Set a channel to broadcast.
Function Prototype:
Example:
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_maChanUdpActivate - acticate a udp channel
Purpose: Activate a channel.
Function Prototype:
Example:
goal_maChanUdpSend - send data to the udp channel
Purpose: Send data to an open udp channel.
Function Prototype:
Example: