Remote Station SDK

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.

SDK directory structure

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. Only Input Link devices can be used. Each Link Device has ist own memory map.
goal_cclIeTsnOutputSet	Write Output data to the Cyclic Memory Map Only Output Link devices can be used. Each Link Device has its own 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. Calling this function will cause all controlled devices in the network to shutdown. After calling this function the application is expected to halt the device and stop processing cyclic data.
goal_cclIeTsnPowerSupplyErrorStopExec	Issue an Emergency Stop due to Power supply error. Calling this function will cause all controlled devices in the network to shutdown. After calling this function the application is expected to halt the device and stop processing cyclic data.
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
goal_cclIeTsnStationModeSetActive	Set an existing station mode for this station to active
goal_cclIeTsnStationModeGet	Get the current Station Mode that was set by the Master Station
goal_cclIeTsnCycleNumberGet	Get the current cycle number used in CyclicS frames
goal_cclIeTsnStationModeSetCANopen	Mark a station mode as CANopen compatible

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 (EMG group causing stop)	don't care
GOAL_CCL_CB_CYCLIC_ERROR_ON	other station causes cyclic error	pCyclicErrIpAddr (IP address of Remote Station)	don't care
GOAL_CCL_CB_CYCLIC_ERROR_OFF	other station fixed cyclic error	pCyclicErrIpAddr (IP address of Remote Station)	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", 
                         *(pCbData->pWrongIpAddrSlaveId));
            /* 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 ICC Support 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

/* set the station mode */
res = goal_cclIeTsnStationModeAdd(pCcl, GOAL_APPL_STATION_MODE_CANOPEN);
if (GOAL_RES_ERR(res)) {
    goal_logErr("Failed to set station mode");
    return res;
}

/* this is a CANopen station mode */
res = goal_cclIeTsnStationModeSetCANopen(pCcl, GOAL_APPL_STATION_MODE_CANOPEN);
if (GOAL_RES_ERR(res)) {
    goal_logErr("Failed to set station mode to CANopen mode");
    return res;
}

/* Statusword communication linkdevice */
res = goal_cclIeTsnLinkDevAdd(pCcl, GOAL_APPL_STATION_MODE_CANOPEN, GOAL_CCL_LINK_DEV_STSW, 0x60, 8);
if (GOAL_RES_ERR(res)) {
    goal_logErr("Failed to set local linkDev");
    return res;
}

/* CANopen In -- CANopen uses a virtual address */
res = goal_cclIeTsnLinkDevAdd(pCcl, GOAL_APPL_STATION_MODE_CANOPEN, GOAL_CCL_LINK_DEV_CANOPEN_IN, 0x00004000, 1000);
if (GOAL_RES_ERR(res)) {
    goal_logErr("Failed to set local linkDev");
    return res;
}

/* CANopen Out -- CANopen uses a virtual address */
res = goal_cclIeTsnLinkDevAdd(pCcl, GOAL_APPL_STATION_MODE_CANOPEN, GOAL_CCL_LINK_DEV_CANOPEN_OUT, 0x00008000, 1000);
if (GOAL_RES_ERR(res)) {
    goal_logErr("Failed to set local linkDev");
    return res;
}

Figure 2.4: Sample of CANopen Remote Station Setup

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.