...
Writing an Application for the Master SDK
Overview
An 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 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 All functions return a status code indicating whether the operation succeeded or not.
...
Creating a new instance of the CC-Link IE TSN protocol stack
After 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.
...
| Code Block | ||
|---|---|---|
| ||
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.
Tabelle fehlt
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_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_cclIeSlaveTimeSlotMacAddrAdd | Assign a Destination MAC address to a timeslot for this Remote Station. |
goal_cclIeSlaveTimeSlotVlanAdd | Assign a VLAN to a timeslot for this Remote Station. |
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. |
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.
...
cclIeTsnStart.
| Code Block | ||
|---|---|---|
| ||
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
...
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.
...
During initialization, the application can register a callback handler with the function goal_cclIeTsnNew. The callback handler uses the following arguments:
...
Table 1‑7: Handling of Application Callback IDs
| Code Block | ||
|---|---|---|
| ||
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;
...
break; /* ... */ |
...
}
return res;
} return res; } |
Figure 1.3: Sample implementation of the application callback
Configuration of CANopen Remote Stations
CANopen 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.
| Code Block | ||
|---|---|---|
| ||
static uint16_t slave2RpdoMapObj = 0x1601; |
...
/**< Slave2: RPDO Mapping object */ |
...
static uint16_t slave2TpdoMapObj = 0x1A01; |
...
/**< Slave2: TPDO Mapping object */ |
...
static GOAL_CCL_CO_STARTUP_T slave2StartUpCmds[] = |
...
{ {GOAL_TRUE, 0x1C00, 1, sizeof(uint16_t), (uint8_t *) &slave2RpdoMapObj}, |
...
{GOAL_TRUE, 0x1C01, 1, sizeof(uint16_t), (uint8_t *) &slave2TpdoMapObj}, |
...
}; |
...
static uint16_t slave2TpdoCfgTbl[] = |
...
{ 0x1C01, |
...
}; |
...
static uint16_t slave2RpdoCfgTbl[] = |
...
{ 0x1C00, |
...
}; |
...
res = goal_cclIeTsnSlaveCanOpenConfigSet(pCcl, |
...
slaveId, slave2StartUpCmds, ARRAY_ELEMENTS(slave2StartUpCmds), slave2TpdoCfgTbl, ARRAY_ELEMENTS(slave2TpdoCfgTbl), |
...
slave2RpdoCfgTbl, ARRAY_ELEMENTS(slave2RpdoCfgTbl)); |
...
if (GOAL_RES_ERR(res)) |
...
{ goal_logErr("Failed to configure CANopen properties of slave %u", slaveId); |
...
} |
Figure 1.4: Configuration of a CANopen remote station
...
An entry in the startup command table has the following fields::
| Code Block | ||
|---|---|---|
| ||
typedef struct |
...
{ GOAL_BOOL_T wrFlag; |
...
/**< write or read access */ |
...
uint16_t index; |
...
/**< object index |
...
*/ uint16_t subIndex; |
...
/**< object subindex */ |
...
uint16_t dataLen; |
...
/**< size of data to be written or read */ |
...
uint8_t *pData; |
...
/**< write data buffer */ |
...
} GOAL_CCL_CO_STARTUP_T; |
Figure 1.5: CANopen startup command table entry
...
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.
...
| Code Block | ||
|---|---|---|
| ||
res = goal_cclIeTsnCanOpenCallbackSet(pCcl, appl_goalCclCanOpenCb); |
...
if (GOAL_RES_ERR(res)) |
...
{ goal_logErr("Failed to register CANopen callback"); |
...
}
}
|
Figure 1.6: Register a CANopen callback handler
...
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.
...
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
NXP LS1028A
The The NXP LS1028A is a SoC that fullfills the hardware requirements for a Class B device.
...
The LS1028ARDB uses OpenIL, a Linux distribution for industrial automation with Realtime support. The distribution can be built with Buildroot.
...
git clone https://github.com/openil/openil.git
...
cd openil
...
git checkout OpenIL-v1.9-202009
...
| Code Block | ||
|---|---|---|
| ||
git clone cd openil git checkout OpenIL-v1.9-202009 #alternatively you can choose a newer release make nxp_ls1028ardb-64b_defconfig |
...
make 2>&1 | tee build.log |
...
Flashing the firmware
Once the firmware has been built it must be copied to the SD-Card of the LS1028ARDB.
insert SD-Card into Linux PPC
card is listed as /dev/sdX [e.g. /dev/sdc]
see log via dmesg
in directory openil:
sudo dd if=output/images/sdcard.img of=/dev/sdc bs=1024ATTENTION: choosing the wrong output device will overwrite sections of the PC’s HDD/SDD
...
causing data loss
insert SD-Card into LS1028ARD and start device
Debug Interface
A serial console is available on UART1.
Use the following parameters: 115,200 baud/s, 8 data bits, no parity, 1 stop bit.
Configuration of the LS1028ARDB
It is possible to configure the number of ports used for CC-Link IE TSN. By default each port of the integrated TSN Switch is independent, i.e. there is no forwarding between these ports.
The interfaces representing these ports are called swp0 to swp3. In order to enable forwarding between two or more ports the following script could be executed:
| Code Block | ||
|---|---|---|
| ||
#!/bin/sh |
...
# create a bridge device |
...
ip link add name switch type bridge |
...
ip link set switch up |
...
# add 1st port |
...
ip link set swp0 master switch |
...
ip link set swp0 up |
...
# add 2nd port |
...
ip link set swp1 master switch |
...
ip link set swp1 up |
...
# uncomment to add 3rd port |
...
#ip link set swp2 master switch |
...
#ip link set swp2 up |
...
# uncomment to add 4th port |
...
#ip link set swp3 master switch |
...
#ip link set swp3 up |
...
# add a route for this interface (subnet address might need to adjusted) |
...
ip route add 192.168.3.0/24 dev switch |
...
This will create a new interface called “switch”.
By default, the OpenIL image runs netopeer2, a NETCONF server. This server interfers with the Realtime behaviour of the GOAL process. Therefore, the server must be removed from the initialization scripts:
| Code Block | ||
|---|---|---|
| ||
rm /etc/init.d/S91netopeer2-server |
Building the CC-Link IE TSN Master Application
...
Navigate to the project folder of a sample application, e.g. “projects/goal_ccl_ie_tsn/03_master_ct/gcc”.
Select Select the target platform (only required once)
make selectenter the number of “linux_nxp_ls1028a”
build sample application
make
The The binary is located at
““projects/goal_ccl_ie_tsn/03_master_ct/gcc/linux_nxp_ls1028a/goal_ linux_nxp_ls1028a.bin”.
The file must be copied to the LS1028ARDB, e.g. via scp.
On the LS1028ARDB:
reduce kernel log messages to only critical ones
...
| Code Block | ||
|---|---|---|
| ||
#reduce kernel log messages to only critical ones echo 1 > /proc/sys/kernel/printk |
...
#disable memory overcommitting |
...
echo 2 > /proc/sys/vm/overcommit_memory |
...
make application ecutable
...
#make application executable chmod +x goal_ linux_nxp_ls1028a.bin |
...
#start application (adjust Ethernet port if necessary) |
...
./goal_ linux_nxp_ls1028a.bin -i <IFACE> |
Note:
<IFACE> is the ethernet interface that GOAL should use. This is either the bridge device “switch” or a standalone port, e.g. “swp0”.
...
Start CC-Link IE TSN Master application automatically
...
automatically
In order to start the Master SDK automatically after boot up, a script must be created in the directory /etc/init.d, e.g. S99GOAL.
The script should have the following content:
| Code Block |
|---|
#!/bin/sh |
...
# |
...
# CC-Link IE TSN Master SDK |
...
# |
...
GOAL=/root/goal_linux_nxp_ls1028a.bin |
...
start() { |
...
echo 1 > /proc/sys/kernel/printk |
...
echo 2 > /proc/sys/vm/overcommit_memory |
...
printf "Starting CC-Link IE TSN Master SDK: " |
...
${GOAL} -i swp0 & |
...
echo "OK" |
...
} |
...
stop() { |
...
printf "Stopping CC-Link IE TSN Master SDK: " |
...
killall $(basename ${GOAL}) |
...
echo "OK" |
...
} |
...
restart() { |
...
stop
start
}
...
stop start } case "$1" in |
...
start) |
...
start
;;
stop)
stop
;;
...
start ;; stop) stop ;; restart|reload) |
...
restart
;;
*)
...
restart ;; *) echo "Usage: $0 {start|stop|restart}" |
...
exit 1 |
...
esac |
Please make sure that the script is executable:
chmod +x /etc/init.d/S99GOAL
Conformance Test
In order to perform the conformance test, several configurations must be tested.
...
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 (see chapter 3.1.5) and copied to the LS1028ARDB (see chapter 3.1.6).
...