The CC-Link IE TSN Remote Station SDK is used to implement a Remote Station in a device. The SDK uses GOAL, port’s Industrial Communication Framework.
The SDK has the following directory structure.
Path | Description |
appl/goal_ccl_ie_tsn/02_slave | Sample application for communication with a Master Station |
goal* | GOAL core, platform independent |
plat | Platform specific files: architecture, board configuration, drivers |
projects/goal_ccl_ie_tsn/02_slave | Sample project |
protos/ccl_ie_tsn | CC-Link IE TSN protocol stack |
protos/goal_ts | (g)PTP protocol stack |
protos/slmp | SLMP protocol stack |
protos/acd | ACD protocol stack |
protos/802_1Qbv | Goal Qbv connector for software Qbv |
ext/802_1Qbv | software Qbv implementation |
Table 2‑1: Directory structure of the Remote Station SDK
Writing an Application for the Remote Station SDK
Overview
An application for the Remote Station SDK is a GOAL application. It consists of three functions that are called by GOAL: appl_init, appl_setup, appl_loop.
Additionally, the application can register a callback that is called by the CC-Link IE TSN Remote Station stack to inform the application about events.
The function appl_init is used to register components in GOAL, e.g. the CC-Link IE TSN protocol stack. The actual initialization of the application happens in appl_setup.
The application must include goal_includes.h and goal_ccl_ie_tsn.h.
Configuration of the CC-Link IE TSN protocol stack
The function appl_setup is called by GOAL during initialization. Within this function all functions listed in this chapter can be used to configure the behavior of the Remote Station. All Functions must be called before calling goal_cclIeTsnNew.
All functions return a status code indicating whether the operation succeeded or not.
Function | Description |
goal_cclIeTsnCfgNodeTypeSet | Set the node Type of this station (Remote Station) |
goal_cclIeTsnCfgCertificationClassSet | Set the Certification Class of this station |
goal_cclIeTsnCfgDeviceVersionSet | Set the Device Version of this station |
goal_cclIeTsnCfgDeviceVendorCodeSet | Set the Device Vendor Code of this station |
goal_cclIeTsnCfgDeviceProductIdSet | Set the Product Id of this station |
goal_cclIeTsnCfgDeviceExModelCodeSet | Set the Device Expansion Model Code of this station |
goal_cclIeTsnCfgDeviceTypeIdSet | Set the Device Type Id of this station |
goal_cclIeTsnCfglogSyncIntSet | Set the default logarithmic Sync Tx interval |
goal_cclIeTsnCfglogAnnounceIntSet | Set the default logarithmic Announce Tx interval |
goal_cclIeTsnCfglogPDelayIntSet | Set the default logarithmic PDelay Tx interval |
goal_cclIeTsnCfgPdelayResTimeSet | Set the time between Pdelay_Req and Pdelay_Resp_Follow_Up |
goal_cclIeTsnCfgDelaySetTimeSet | Set the time between Peer delay calculation and port role adjustment |
goal_cclIeTsnCfgAnounceRelayTimeSet | Set the time for relaying Announce frames from Remote Station port to Remote Station ports |
goal_cclIeTsnCfgNumTxSubpayloadEntriesSet | Set the number of allowed Tx Subpayload information entries. The number defines how many Transmit Subpayloads can be handled by this station. |
goal_cclIeTsnCfgNumRxSubpayloadEntriesSet | Set the number of allowed Rx Subpayload information entries. The number defines how many Receive Subpayloads can be handled by this station. |
goal_cclIeTsnCfgNumCycTxHandlersSet | Set the number of cyclic transmission handlers. The number defines how many cyclic connections can be established at the same time. |
goal_cclIeTsnCfgNumCycRxHandlersSet | Set the number of cyclic reception handlers. The number defines how many cyclic connections can be established at the same time. |
goal_cclIeTsnCfgNumSlmpServerHandlesSet | Define how many received SLMP requests can be processed in parallel |
goal_cclIeTsnCfgNumSlmpClientHandlesSet | Defines how many SLMP requests can be sent in parallel. |
goal_cclIeTsnCfgNumSlmpDivDataHandlesSet | Define how many fragmented SLMP messages can be received in parallel. |
goal_cclIeTsnCfgClearOnHoldEnable | Defines whether imported cyclic data is cleared or held if the the sender's application is stopped. |
goal_cclIeTsnCfgPtpPrio1Set | Overwrite the PTP prio1 value for this station. |
goal_cclIeTsnCfgLinkSpeedEnforce | Enforce a link speed for all ports |
Table 2‑2: Configuration Functions of the Remote Station protocol stack
Creating a new instance of the CC-Link IE TSN protocol stack
After the stack has been configured the function goal_cclIeTsnNew must be invoked to create a new instance of the protocol stack. It is also used to register a callback handler for processing events from the stack. The callback handler will be explained in detail in a later chapter.
GOAL_STATUS_T res; /* result */ static GOAL_CCL_HANDLE_T *pCcl = NULL; /**< GOAL CCL handle */
/* create instance of CC-Link IE TSN stack */ res = goal_cclIeTsnNew(&pCcl, GOAL_CCL_INSTANCE_DEFAULT, appl_goalCclCb); if (GOAL_RES_ERR(res)) { goal_logErr("Failed to instantiate CC-Link IE TSN stack"); return res; }
|
Figure 2.1: Creating a new instance of the Remote Station stack
This function creates a handle (in this example it is called pCcl) that must be used for all other function calls to reference the stack instance.
Runtime behavior of the CC-Link IE TSN Remote Station stack
The functions in this chapter influence the runtime behaviour of the CC-Link IE TSN Remote Station. The functions must be called after goal_cclIeTsnNew returned successfully and before goal_cclIeTsnStart is called. These functions can be directly called within appl_setup or at a later point in time.
Function | Description |
goal_cclIeTsnCanOpenCallbackSet | Register a CANopen callback handler |
goal_cclIeTsnStationNumSet | Set the station number of the device. |
goal_cclIeTsnStationModeAdd | Register a Station mode for this device |
goal_cclIeTsnLinkDevAdd | Add a Link device to a Station Mode |
Table 2‑3: Runtime behavior functions of the Remote Station stack
Starting the CC-Link IE TSN Remote Station Stack
After finishing all settings of the runtime behavior and the expected Remote Station configuration the stack must be started by calling goal_cclIeTsnStart.
res = goal_cclIeTsnStart(pCcl); if (GOAL_RES_ERR(res)) { goal_logErr("Failed to start stack"); }
|
Figure 2.2: Start an instance of the Remote Station stack
If this function succeeds the stack CC-Link IE TSN Remote Station stack has been started and will now wait for a configuration by a master device. All functions described in previous chapters cannot be used anymore.
Functions used during Run phase
After sucessfulling starting the stack. The application can use the following functions to access cyclic data and to influence the stack’s behaviour.
Function | Description |
goal_cclIeTsnCyclicStopSet | Enable or Disable Cyclic Stop for the Remote Station. |
goal_cclIeTsnInputGet | Read Input data from the Cyclic Memory Map. |
goal_cclIeTsnOutputSet | Write Output data to the Cyclic Memory Map |
goal_cclIeTsnAppStopSet | Enable or Disable Application Stop mode for this station. |
goal_cclIeTsnAppErrorStopSet | Enable or Disable Application Error Stop mode for this station. |
goal_cclIeTsnEmergencyStopExec | Issue an Emergency Stop due to internal error. |
goal_cclIeTsnPowerSupplyErrorStopExec | Issue an Emergency Stop due to Power supply error. |
goal_cclIeTsnOutputDevGet | Get data from an Output Link Device (data received via Master-to-Master communication). |
goal_cclIeTsnInputDevSet | Set data of an Input Link Device (data transmitted for Master-to-Master communication). |
goal_cclIeTsnNmtUpload | Get the NMT state of a CANopen Remote Station. |
goal_cclIeTsnSlaveProcTypeRead | Request processor Type information from a Remote Station |
Table 2‑4: Functions used during Run phase in the Remote Station SDK
Application Callback
During initialization, the application can register a callback handler with the function goal_cclIeTsnNew.
The callback handler uses the following arguments:
Argument data type | Description |
GOAL_CCL_HANDLE_T * | CC-Link IE TSN stack instance reference |
GOAL_CCL_CB_ID_T | callback ID indicating callback type |
GOAL_CCL_CD_DATA_T * | callback data, actual meaning depends on callback ID |
Table 2‑5: Arguments of the Application Callback Handler in the Remote Station SDK
Some callback ID also evaluate the return value of the handler to decide how to proceed.
Callback ID | Description | Callback data | Return value |
GOAL_CCL_CB_ERROR_STATE | device entered Error state | NULL | don't care |
GOAL_CCL_CB_RSV_TRANSIENT_DONE | reserved transient transmission done | NULL | don't care |
GOAL_CCL_CB_RESERVED_STATION_ON | device entered Reserved Station mode | NULL | don't care |
GOAL_CCL_CB_RESERVED_STATION_OFF | device left Reserved Station mode | NULL | don't care |
GOAL_CCL_CB_CYCLIC_STOP_ON | cyclic communication stopped | NULL | don't care |
GOAL_CCL_CB_CYCLIC_STOP_OFF | cyclic communication restarted | NULL | don't care |
GOAL_CCL_CB_OWN_STATION_EMG_STOP | device received Emergency Stop request | pEmgGroup | don't care |
GOAL_CCL_CB_CYCLIC_ERROR_ON | other station causes cyclic error | pCyclicErrIpAddr | don't care |
GOAL_CCL_CB_CYCLIC_ERROR_OFF | other station fixed cyclic error | pCyclicErrIpAddr | don't care |
GOAL_CCL_CB_CYC_COM_ENABLED | station started to send and receive process data | NULL | don't care |
GOAL_CCL_CB_CYC_COM_DISABLED | station stopped to send and receive process data | NULL | don't care |
GOAL_CCL_CB_IP_ADDR_DUPL | station’s IP address is also used by another station | NULL | don’t care |
GOAL_CCL_CB_STATION_MODE_CHANGE | local station changed station mode | NULL | don’t care |
Table 2‑6: Handling of Application Callback IDs in the Remote Station SDK
static GOAL_STATUS_T appl_goalCclCb( GOAL_CCL_HANDLE_T *pCclm, /**< GOAL CCL handle */ GOAL_CCL_CB_ID_T cbId, /**< callback ID */ GOAL_CCL_CD_DATA_T *pCbData /**< callback data */ ) { GOAL_STATUS_T res = GOAL_OK; /* result */
switch (cbId) { /* ... */
case GOAL_CCL_CB_SLAVE_WRONG_IP_ADDR: goal_logInfo("slave 0x%04x has unexpected IP address", /* abort initialization */ res = GOAL_ERROR; break;
/* ... */ }
return res; } |
Figure 2.3: Sample implementation of the application callback
Data Access with CANopen
The Remote Station SDK can be extended with a CANopen package which provides an additional approach to configure the data transfer, using methods known originally adapted from the CANopen specification. Specifically, this uses the concepts of RPDO and TPDO configuration and PDO or SDO data transfer.
To set up this operation mode, the station mode needs to be marked as CANopen. Instead of Word link devices, CANopen link devices must be initialized. Additionally, this mode requires an object dictionary and a CANopen configuration file. It is recommended to use the port ICC tool to interactively create them. (See chapter 3 in this document.)
When accessing the CANopen link devices, the general access function will not work. Instead, the following functions will address CANopen objects by index and subindex directly:
Function | Description |
goal_cclIeTsnInputDevSetCANopen | Write to object in object dictionary |
goal_cclIeTsnInputDevGetCANopen | Read from object in object dictionary |
|
|
|
|
Table 2‑7: CANopen Data Access Functions
Tabelle fehlt
Supported Platforms
Since the CC-Link IE TSN Protocol stack runs on GOAL, it can run on any platform supported by GOAL.
In the less strict Conformance Class A, the time sensitive sending of ethernet frames can be supported by the included SoftwareQbv package. The hardware only has to support timestamping of the frames.
To fullfill the requirements of a Conformance Class B device, special hardware support is needed. The hardware must support timestamping of Ethernet frames as defined by IEEE 1588v2 or IEEE 802.1AS. Additionally, it must support time aware queuing of Ethernet frames as defined by IEEE 802.1Qbv.
As development is constantly ongoing, the following table should not be seen as complete.
Confirmed Supported Hardware | Features
|
STM32F429ZI Nucleo Discovery Board | Conformance Class A Software Qbv IEEE1588v2 and IEEE802.1AS 100Mbit |
|
|
|
|
Table 2‑8: Confirmed Supported Hardware of the Remote Station SDK
Conformance Test
To perform the conformance test, several configurations must be tested. All of them where tested with the example application appl/goal_ccl_ie_tsn/02_slave. The respective master device or PLC is responsible for setting up the remote station for a specific test.