...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
| Table of Contents | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Device specific functions
appl_ccmRpcInit
Purpose: Register irj45 System-on-Module API in GOAL (appl_init)
This function registers the irj45 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.
...
This function enables the possibility to update the firmware of the irj45 CC moduleSystem-on-Module. It returns a GOAL_STATUS_T status and has no parameters.
...
| 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).
...
This function disables the possibility to update the firmware of the irj45 CC moduleSystem-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.
...
This function reads information from the irj45System-on-Module:
MAC address (serial number)
Software version
device type
...
| Code Block | ||
|---|---|---|
| ||
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 /**< irj45System-on-Module device type */
); |
Example:
...
This function determines the behaviour of the irj45 System-on-Module regarding cyclic communication. By default, a cyclic communication is stopped when communication to the application controller (AC) is lost.
...
appl_ccmCommResetSet
Pupose: Set behaviour of irj45 module 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 irj45 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.
...
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.
...
appl_ccmLogToAcEnable
Minimal ccmmodule firmware version: 2.0.0.0
...
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.
...
appl_ccmFwUpdateStart
Minimal ccmmodule firmware 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.
...
appl_ccmFwUpdateExecute
Minimal ccmmodule firmware version: 2.0.0.0
...
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 module implicitly.
Function Prototype:
...
appl_ccmEcatSsiUpdate
Minimal ccmmodule firware version: 2.0.0.0
Purpose: Perform update oft he EtherCAT Ssi data in eeprom
...
appl_ccmFoeUpdateSettings
Minimal ccmmodule firmware version: 2.0.0.0
...
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 ccmmodule firmware version: 2.0.0.0
...
appl_ccmNetworkDefaultUp
Minimal ccmmodule firmware 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.
...
appl_ccmNetworkEoEUp
Minimal ccmmodule firmware 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.
...
| Code Block |
|---|
/* start EtherCAT networking */ res = appl_ccmNetworkEoEUp(); |
appl_ccmCfgVarGet
Minimal ccmmodule firmware version: 2.0.0.0
...
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 GOAL Programmer's Manual - chapter goal_cm.
Function Prototype:
| Code Block | ||
|---|---|---|
| ||
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 */
); |
...
| 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 ccmmodule firmware version: 2.0.0.0
...
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 GOAL Programmer's Manual - chapter goal_cm.
Function Prototype:
| Code Block | ||
|---|---|---|
| ||
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 */
); |
...
| Code Block | ||
|---|---|---|
| ||
/* 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 ccmmodule firmware version: 2.0.0.0
...
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 */
); |
...
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 | ||
|---|---|---|
| ||
GOAL_STATUS_T goal_ddCustomerIdSet(
GOAL_DD_T *pHdlDd, /*< dd handle */
uint32_t cid /*< customer ID */
); |
...
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:
| 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");
} |
...
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");
} |
...
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
| Note |
|---|
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. |
...
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
...
| Code Block | ||
|---|---|---|
| ||
/****************************************************************************/
/** 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.
...
| 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
...
| 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;
} |
...
| Code Block | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
/* 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;
} |
...
| Code Block | ||
|---|---|---|
| ||
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;
} |
...
| 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:
| Code Block | ||
|---|---|---|
| ||
/* 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;
} |
...
| 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
...
| Code Block | ||
|---|---|---|
| ||
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);
} |
...
| Code Block | ||
|---|---|---|
| ||
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 | ||
|---|---|---|
| ||
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);
} |
...
| 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 | ||
|---|---|---|
| ||
res = goal_maChanUdpSetNonBlocking(pMaChanUdp, pChan2, GOAL_TRUE);
if (GOAL_OK != res) {
goal_logErr("error while setting UDP channel to non-blocking");
return res;
} |
...
| 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:
| 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;
} |
...
| 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:
| Code Block | ||
|---|---|---|
| ||
res = goal_maChanUdpActivate(pMaChanUdp, pChan2);
if (GOAL_RES_ERR(res)) {
goal_logErr("error while enabling UDP channel");
return res;
} |
...
| Code Block | ||
|---|---|---|
| ||
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); |