Master Station SDK
The CC-Link IE TSN Master SDK is used to implement a Management Master station or a Control Master 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/01_master | Sample application for communication with port’s Remote Station SDK |
appl/goal_ccl_ie_tsn/03_master_ct | Sample application for Conformance Test |
goal* | GOAL core, platform independent |
plat | Platform specific files: architecture, board configuration, drivers |
projects/goal_ccl_ie_tsn/01_master | Sample project for communication with port’s Remote Station SDK |
projects/goal_ccl_ie_tsn/03_master_ct | Sample project for Conformance Test |
protos/ccl_ie_tsn | CC-Link IE TSN protocol stack |
protos/goal_ts | (g)PTP protocol stack |
protos/acd | ACD protocol stack |
protos/slmp | SLMP protocol stack |
Table 1‑1: Directory structure of the Master SDK
Writing an Application for the Master SDK
Overview
An application for the Master 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 Master 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_master.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 bahavior of the Management Master. 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_cclIeTsnCfgManagementPrioritySet | Set the Management Priority of this master station |
goal_cclIeTsnCfgNumGmRecordEntriesSet | Set the maximum number of Grandmaster Record entries |
goal_cclIeTsnCfgNumSlavesSet | Set the maximum number of Remote Stations handled by this station |
goal_cclIeTsnCfgNumS2sSubpayloads | Set the maximum number of Subpayloads for direct communication between remote stations |
goal_cclIeTsnCfgSlaveCheckIntervalSet | Set the check interval for pending Remote Stations during RUN phase |
goal_cclIeTsnCfgNodeTypeSet | Set the node Type of this station (Management Master or Control Master) |
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 Master ports |
goal_cclIeTsnCfgNumTxSubpayloadEntrieSet | Set the number of allowed Tx Subpayload information entries. The number defines how many Transmit Subpayloads can be handled by this station. |
goal_cclIeTsnCfgNumRxSubpayloadEntrieSet | 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 1‑2: Configuration Functions of the CC-Link IE TSN 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 1.1: Creating a new instance of the CC-Link IE TSN master 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 the stack instance.
Runtime behavior of the CC-Link IE TSN Master stack
The functions in this chapter influence the runtime behaviour of the CC-Link IE TSN Master 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. These functions represent settings that usually come from an Engineering Tool. Therefore, the settings can be applied after receiving the current configuration from the tool.
Function | Description |
---|---|
goal_cclIeTsnDetectionAckEnforce | Enforce DetecktionAck transmission with every Detection frame |
goal_cclIeTsnNetworkConfigSet | set Network properties:
|
goal_cclIeTimeSlotAdd | Add a time slot in ascending order from TSLT0 to TSLT7. |
goal_cclIeTimeSlotEtherTypeAdd | Assign an Ethertype to a timeslot in ascending order from TSLT1 to TSLT7. |
goal_cclIeTimeSlotMacAddrAdd | Assign a Destination MAC address to a specific timeslot. |
goal_cclIeTimeSlotVlanAdd | Assign a VLAN Tag to a specific timeslot. |
goal_cclIeTsnPortFilterSet | Set a port filter for each port. Use the GOAL_CCL_PORT_FILTER_* macros. |
goal_cclIeTsnMulticastGroupAdd | Register a Multicast Group for reception. |
goal_cclIeTsnRxAddrOverlapCheckEnable | Request Remote Stations to check their Rx Memory configurations for overlaps. |
goal_cclIeTsnCycleCounterIgnoreEnable | Instruct all Remote Stations to ignore the cycle counter in cyclic frames. |
goal_cclIeTsnTimeoutsGet | Get the timeout values of the Management Master state machine. |
goal_cclIeTsnTimeoutsSet | Set the timeout values of the Management Master state machine. |
goal_cclIeTsnTimeSyncSet | Set the time synchronization settings:
|
goal_cclIeTsnNetworkNumberSet | Set the SLMP network number |
goal_cclIeTsnMasterIdSet | Set the Id of the master station |
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 1‑3: Runtime behavior functions of the CC-Link IE TSN Master stack
Remote Station Configuration
For each Remote Station station in the network a Remote Station handle must be added. Each Remote Station is represented by an Id. 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, i.e. after the expected Remote Station configuration has been received from the Engineering Tool.
Function | Description |
goal_cclIeTsnSlaveAdd | Add a Remote Station station with an IPv4 address and the ID of the Control Master. |
goal_cclIeTsnControlMasterAdd | Add a Control Master station with an IPv4 address and ist Master ID. |
goal_cclIeTsnSlaveStationModeSet | Set the expected station mode of a Remote Station. |
goal_cclIeTsnSlaveTsltMagnificationSet | Set the timeslot magnification value for a Remote Station. |
goal_cclIeTsnSlavePortFilterSet | Set the port filter for a Remote Station. Each array entry represents a port. Use the GOAL_CCL_PORT_FILTER_* macros. |
goal_cclIeTsnSlaveCyclicConfigSet | Set the cyclic configuration for a Remote Station:
|
goal_cclIeTsnSlaveInputAdd | This function is used to register an Input Link device for a Remote Station, i.e. a Subpayload transmitted by the Remote Station to the master. |
goal_cclIeTsnSlaveOutputAdd | This function is used to register an Output Link device for a Remote Station, i.e. a Subpayload received by the Remote Station from the master. |
goal_cclIeTsnSlaveS2sTxSplAdd | Add a Tx Subpayload for direct communication to a Remote Station. The destination MAC address and IP address of the receiving Remote Station must be specified. Furthermore the Subcycle settings must be specified. |
goal_cclIeTsnSlaveS2sRxSplAdd | Add a Rx Subpayload for direct communication to a Remote Station. |
goal_cclIeTsnSlaveS2sRxSrcAdd | Add a Rx Source information item for direct communication to a Remote Station. This function sets the IP address of the sending Remote Station and the subcycle settings. |
goal_cclIeTsnSlaveRxMulticastGroupSet | Add a Remote Station to a Rx multicast group. The Remote Station's Output Subpayloads will be sent with other Subpayloads via Multicast frames. |
goal_cclIeTsnSlaveTxMulticastGroupSet | Add a Remote Station to a Tx multicast group. The Remote Station's Input Subpayloads will be received with other Subpayloads via Multicast frames. |
goal_cclIeTsnSlaveUncontrolledMulticastGroupAdd | Add a Remote Station to a Multicast Group that is not controlled by this station, i.e. multicast group for Remote Station-to-Remote Station communication |
goal_cclIeTsnSlaveAppNetSyncEnable | Request the Remote Station to synchronize its application to the network cycle. |
goal_cclIeTsnSlaveCyclicStopEnable | Enable or disable the Cyclic Stop request for a Remote Station station. |
goal_cclIeTsnSlaveCanOpenConfigSet | Configure a Remote Station for CANopen communication. |
goal_cclIeTsnSlaveVlanSettingSelectSet | Assign a VLAN setting that shall be used by the Slave. |
Table 1‑4: Functions for Remote Station configuration
Starting the CC-Link IE TSN Master 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 1.2: Start an instance of the CC-LINK IE TSN master stack
If this function succeeds the stack CC-Link IE TSN Master stack has been started and tries to detect all configured Remote Stations. 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 Master 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_cclIeTsnSdoWrite | Start a SDO Write operation for a Remote Station. |
goal_cclIeTsnSdoRead | Start a SDO Read operation for a Remote Station. |
goal_cclIeTsnNmtUpload | Get the NMT state of a CANopen Remote Station. |
goal_cclIeTsnNmtDownload | Set the NMT state of a CANopen Remote Station. |
goal_cclIeTsnSlaveProcTypeRead | Request processor Type information from a Remote Station |
Table 1‑5: Functions used during Run phase
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 1‑6: Arguments of the Application Callback Handler
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_DETECTION_MISMATCH | mismatch in detected Remote Stations and configuration from engineering tool | NULL | don't care |
GOAL_CCL_CB_NETCFG_MISMATCH | mismatch in network configuration | pNetConfigMismatchId | GOAL_OK: continue operation |
GOAL_CCL_CB_MASTERCFG_MISMATCH | mismatch in configuration of a Control Master | NULL | don't care |
GOAL_CCL_CB_ERROR_STATE | device entered Error state | NULL | don't care |
GOAL_CCL_CB_UNKNOWN_SLAVE | detected a Remote Station that was not set by the engineering tool | pUnknownSlaveIpAddr | don't care |
GOAL_CCL_CB_SLAVE_UNDETECTED | Remote Station was not detected in the network | pUndetectedSlaveId | GOAL_OK: continue operation |
GOAL_CCL_CB_SLAVE_WRONG_IP_ADDR | Remote Station has wrong IP address (not in the same subnet) | pWrongIpAddrSlaveId | GOAL_OK: continue operation |
GOAL_CCL_CB_SLAVE_IP_ADDR_DUPL | Remote Station has a duplicate IP address | pDuplicateIpAddrSlaveId | GOAL_OK: continue operation |
GOAL_CCL_CB_SLMP_ERROR | SLMP error received from station | pSlmpErrorInfo->slaveId | don't care |
GOAL_CCL_CB_CM_UNCONFIGURED | Control Master is not configured | pUnconfiguredMasterId | GOAL_OK: continue operation |
GOAL_CCL_CB_SLAVE_UNCONTROLLED | Remote Station not controlled by its Control Master | pUncontrolledSlaveId | GOAL_OK: continue operation |
GOAL_CCL_CB_WRONG_GRANDMASTER | Remote Station has a different Grandmaster | pWrongGrandmasterSlaveId | 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_OTHER_STATION_EMG_STOP | Emergency stop for an Emergency Group | pEmgGroup | don't care |
GOAL_CCL_CB_OTHER_STATION_GOF_STOP | Emergency stop for a GOF Group | pGofGroup | don't care |
GOAL_CCL_CB_SLAVE_INVALID_CFG | expected configuration of Remote Station is not valid | pInvalidCfgSlaveId | GOAL_OK: continue operation |
GOAL_CCL_CB_SLAVE_INVALID_DATA_ON | received invalid control data from Remote Station | pInvalidCycDataSlaveId | don't care |
GOAL_CCL_CB_SLAVE_INVALID_DATA_OFF | control data from Remote Station is valid again | pInvalidCycDataSlaveId | 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_READPROCTYPE_RES | received a ReadProcType response | pReadProcTypeRes | don’t care |
GOAL_CCL_CB_SLAVE_INCOMPATIBLE | the slave's protocol version and/or certification class cannot be handled | pInvalidCfgSlaveId | don’t care |
Table 1‑7: Handling of Application Callback IDs
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 1.3: Sample implementation of the application callback
Configuration of CANopen Remote Stations
CANopen Remote Stations are configured with the same functions as Link Device Remote Stations. Additionally, there is the function goal_cclIeTsnSlaveCanOpenConfigSet to set CANopen specific properties of the Remote Station.
Figure 1.4: Configuration of a CANopen remote station
An entry in the startup command table has the following fields:
Figure 1.5: CANopen startup command table entry
The other two tables contain lists of TPDO Config Objects and RPDO Config objects that must be enabled for cyclic communication.
In the RUN phase the application can use the functions goal_cclIeTsnSdoWrite and goal_cclIeTsnSdoRead to start SDO write or read operations.
CANopen Data Callback
The application can use the function goal_cclIeTsnCanOpenCallbackSet to register a callback handler for CANopen object access.
Figure 1.6: Register a CANopen callback handler
The handler is called by the protocol stack every time a SDO Read or Write response was received, including those of the startup commands.
The callback handler uses the callback IDs GOAL_CCL_CO_CB_SDO_READ_RES or GOAL_CCL_CO_CB_SDO_WRITE_RES to indicate if the callback data refers to a read response or a write response.
The callback IDs GOAL_CCL_CO_CB_NMT_UPL_RES and GOAL_CCL_CO_CB_NMT_DNL_RES are used to indicate results of an NMT Upload or Download request.
Member | Data type | Description |
slaveId | uint16_t | Remote Station id |
endCode | uint16_t | SLMP end code (status of operation) |
index | uint16_t | object index (only valid during startup or if endCode == 0x0000) |
subIndex | uint8_t | object subindex (only valid during startup or if endCode == 0x0000) |
dataLen | uint16_t | object data length (only valid for read access and if endCode == 0x0000) |
pData | uint8_t * | object data (only valid for read access and if endCode == 0x0000) or |
Table 1‑8: Members of callback data of CANopen data callback
Supported Platforms
Since the CC-Link IE TSN Protocol stack runs on GOAL, it can run on any platform supported by GOAL. However, to fullfill the requirements of a 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
|
NXP LS1028A | Conformance Class B Hardware Qbv Support IEEE1588v2 and IEEE802.1AS 100Mbit/1000Mbit |
Table 1‑9: Confirmed Supported Hardware for the Master SDK
Conformance Test
In order to perform the conformance test, several configurations must be tested.
Configuration of the Master Station the network and the expected Remote Stations is done by API functions as described in a previous chapter.
There is a sample application that contains the required configurations. In can be found in appl/goal_ccl_ie_tsn/03_master_ct.
There are configuration macros to enable or disable features. If a new configuration is required, the macros must be set to the appropriate values. The application must be recompiled and copied to the LS1028ARDB.
Configuration Macro | Description |
GOAL_APPL_SLAVE0_ENABLED | 1: enable Remote Station 0 0: disbale Remote Station 0 (NZ2GN2B1-32DTE, 192.168.3.1) |
GOAL_APPL_SLAVE1_ENABLED | 1: enable Remote Station 1 0: disbale Remote Station 1 (RJ71GN11-T2, 192.168.3.2) |
GOAL_APPL_SLAVE2_ENABLED | 1: enable Remote Station 0 0: disbale Remote Station 0 (MR-J5-10G, 192.168.3.10) |
GOAL_APPL_SLAVE2_ALT_MAPPING | 1: use an alternate PDO mapping for Remote Station 2 |
GOAL_APPL_CO_OBJ_TEST | 1: execute CANopen object test for Remote Station 2 |
GOAL_APPL_SLMP_TEST | 1: execute SLMP Client test 0: do not execute test |
GOAL_APPL_TIMESYNC_1588 | 1: use IEEE 1588v2 for time synchronization 0: use IEEE 802.1AS for time synchronization |
GOAL_APPL_MULTICAST | 1: use multicast frames for cyclic communication 0: use unicast frames for cyclic communication |
GOAL_APPL_TIME_SYNC_SLAVE | 1: device is not the Grandmaster 0: device is the Grandmaster |
GOAL_APPL_LINKSPEED_100 | 1: enforce a Link speed of 100 Mbit/s 0: enforce a Link speed of 1000 Mbit/s |
Table 1‑10: Configuration Macros of the Conformance Test sample application
- 1 SDK directory structure
- 2 Writing an Application for the Master SDK
- 2.1 Overview
- 2.2 Configuration of the CC-Link IE TSN protocol stack
- 2.3 Creating a new instance of the CC-Link IE TSN protocol stack
- 2.4 Runtime behavior of the CC-Link IE TSN Master stack
- 2.5 Remote Station Configuration
- 2.6 Starting the CC-Link IE TSN Master Stack
- 2.7 Functions used during Run phase
- 2.8 Application Callback
- 2.9 Configuration of CANopen Remote Stations
- 2.10 CANopen Data Callback
- 3 Supported Platforms
- 4 Conformance Test