How it Works
BECKHOFF
Loading...
ET9300
User Manual
97 pgs2.76 Mb0
Table of contents
Loading...

BECKHOFF ET9300 User Manual

Download
Application Note ET9300 (EtherCAT Slave Stack Code)
Version 1.7 Date: 2015-01-13
LEGAL NOTICE
II Application Note ET9300
Version
Comment
1.0
Start document
1.1
Chapter 4 “Hardware access”. Define descriptions; prototypes changed
1.2
Add chapter 5 Application Add chapter 9 Tool Add chapter 9 TestApplication Enhance Hardware access (chapter 4) update name references Enhance EoE chapter
1.3
TestApplication; chapter9 :Update object/entry description (0x2020.1, 0x3003, 0x3004 and 0x3007) Update “HW_GetTimer()” description SSC Tool: Edit file information Update SSC Structure Add “Find Setting” dialog description Update naming in Object chapter
1.4
SSCTool:
- Remove Wizard
- Add Configuration handling
1.5
Editorial changes Add “Getting Started” chapter Add description for hardware adaption Test Application:
- Add new test description
- Enhance/update application description
- Describe mechanism to control the behaviors
Enhance Application chapter
- Add setting description
- Interface variables
- Guide to create an application Add “Synchronization” chapter Hardware chapter: Sync1_Isr() description added Update SSC configuration references Add “EEPROM Handling” chapter
- EEPORM Emulation
- EEPROM Programming
1.6
Editorial changes Update object list of test application Update SSC Tool description (chapter 12) according version 1.3.1
1.7
Chapter 6.5.2 : Add offline object dictionary enhancement Add new mailbox test behaviors Indicate obsolete hardware functions Editorial changes Update SSC Tool screenshots and GUI description Add further test object in the test application Add object design rules Update references if TwinCAT 3 is used Add SSC OD Tool description Add optional EEPROM interface functions. Add Bootloader information
DOCUMENT HISTORY
Stack Code. For annotations or comments to this document please send an email to
EthercatSSC@beckhoff.com.
Application Note ET9300 1
NOTE: This document makes no claim to be complete regarding to the containing topics or the Slave
CONTENTS 1 References 7 2 Terms, Definition, Abbreviation 8
2.1 Abbreviation 8
3 Getting Started 9
3.1 SSC Tool 9
3.2 Default SSC files 9 4 Code Structure 11 5 Hardware Access 12
5.1 Interrupt Handler 16
5.2 Interface Functions/Macros 16
5.2.1 Generic 17
5.2.2 Read Access 20
5.2.3 Write Access 23
6 Application 26
6.1 Application Settings 26
6.2 SSC Functions 26
6.3 Interface Functions 27
6.3.1 Generic 27
6.3.2 EtherCAT State Machine 28
6.3.3 Process data handling 30
6.4 Interface Variables 30
6.5 Create an Application 31
6.5.1 Adding a new Application 31
6.5.2 Examples 31
7 Objects 41
7.1 Design/Structure Rules 41
7.2 Define local memory 41
7.3 Entry descriptions 42
7.4 Object name 42
7.5 Object description 43
7.6 Index Ranges 44
7.7 Implementation examples 45
7.7.1 Usage of Object Deftype ENUM 45
8 Mailbox 47
8.1 FoE (File Transfer over EtherCAT) 47
8.1.1 Testing FoE 47
8.2 EoE (Ethernet over EtherCAT) 47
8.2.1 Implementation 47
8.2.2 EoE Examples 49
9 Synchronization 55 2 Application Note ET9300
9.1 Supported Sync Modes 55
9.1.1 FreeRun 57
9.1.2 SyncManager 57
9.1.3 SyncManager/Sync0 58
9.1.4 SyncManager/Sync0/Sync1 58
9.1.5 Sync0 59
9.1.6 Sync0/Sync1 59
9.1.7 Subordinated Cycles 59
10 CiA402 drive profile 61
10.1 Objects 61
10.2 State machine 62
10.3 Operation modes 64
10.4 TwinCAT setup 65
10.4.1 Automatic network setup 66
10.4.2 Manual network setup 67
10.4.3 NC parameter setup 69
11 TestApplication 71
11.1 Slave Behavior Control 71
11.1.1 Test Control Object 71
11.1.2 User RAM 0xF80:0xF83 72
11.2 ESM Tests (0x2000 – 0x200F) 72
11.3 Mailbox Tests (0x2010 – 0x201F) 73
11.4 CoE Tests (0x2020 – 0x202F) 73
11.5 FoE Tests (0x2030 – 0x203F) 73
11.6 Generic Objects 74 12 Tool 77
12.1 Default Startup Dialogs 77
12.2 Main User Interface Elements 78
12.2.1 Tool Bar 78
12.2.2 Windows 82
12.3 Create Files 83
12.4 Local SSC Update 84
12.5 Project Update 85
12.6 Import Configurations 85 13 OD Tool 87
13.1 Console application 87
13.2 SSC Tool Integration 87
13.3 PDO mapping and SM assign objects 88
13.4 Syntax 88
13.4.1 Comment 88
13.4.2 Object Index 88
Application Note ET9300 3
13.4.3 ObjectCode 88
13.4.4 SI (Subindex) 89
13.4.5 DataType 89
13.4.6 Default/Min/Max 90
13.4.7 M/O/C, B/S and rx/tx 90
13.4.8 Access 90
13.5 ENUM 90 14 EEPROM Handling 92
14.1 EEPROM Emulation 92
14.2 EEPROM Programming 92
14.2.1 EEPROM Programmer User Elements 92 15 Bootloader 94 Appendix 95
Support and Service 95 Beckhoff’s branch offices and representatives 95 Beckhoff Headquarters 95 Beckhoff Support 95 Beckhoff Service 95 EtherCAT Technology Group (ETG) Headquarters 95
4 Application Note ET9300
FIGURES
Figure 1: EtherCAT Slave Stack Code .................................................................................................. 11
Figure 2: File-Stack Association ............................................................................................................ 11
Figure 3: RxPdo data of an EtherCAT slave ......................................................................................... 36
Figure 4: EL9800 Application object ranges.......................................................................................... 45
Figure 5: Send EoE datagram ............................................................................................................... 48
Figure 6: Receive EoE datagram .......................................................................................................... 49
Figure 7: EoE Example 1 (Schema) ...................................................................................................... 50
Figure 8: Network card settings ............................................................................................................. 51
Figure 9: Access EtherCAT Slave Settings ........................................................................................... 51
Figure 10: EoE EtherCAT Slave Settings .............................................................................................. 52
Figure 11: Ping Command Window ....................................................................................................... 52
Figure 12: EoE Example 2 (Schema) .................................................................................................... 53
Figure 13: Enable IP Routing WinXP .................................................................................................... 53
Figure 14: Enable IP Routing WinCE .................................................................................................... 54
Figure 15: ESC Interrupt Signals ........................................................................................................... 55
Figure 16: Free Run .............................................................................................................................. 57
Figure 17: SyncManager Synchronization ............................................................................................ 57
Figure 18: SM/Sync0 Synchronization .................................................................................................. 58
Figure 19: SM/Sync0/Sync1 Synchronization ....................................................................................... 58
Figure 20: Sync0 Synchronization ......................................................................................................... 59
Figure 21: Sync0/Sync1 Synchronization .............................................................................................. 59
Figure 22: Subordinated Cycles ............................................................................................................ 60
Figure 23: CiA402 state transitions and option codes ........................................................................... 63
Figure 24: Axis configuration ................................................................................................................. 65
Figure 25: Set device variable without PLC link .................................................................................... 66
Figure 26: Scan for new EtherCAT devices with TwinCAT 2 ................................................................ 66
Figure 27: Scan for new EtherCAT devices with TwinCAT 3 ................................................................ 67
Figure 28: TwinCAT 2 CiA402 axis setup ............................................................................................. 67
Figure 29: TwinCAT 3 CiA402 axis setup ............................................................................................. 68
Figure 30: Add CiA402 device ............................................................................................................... 68
Figure 31: Link multiple variables .......................................................................................................... 69
Figure 32: Encoder scaling .................................................................................................................... 70
Figure 33: Velocity scaling..................................................................................................................... 70
Figure 34: Configurator Main User Interface ......................................................................................... 77
Figure 35: Configurator File Menu ......................................................................................................... 78
Figure 36: Create New Project .............................................................................................................. 78
Figure 37: Configurator Project Menu ................................................................................................... 78
Figure 38: Find Setting Dialog ............................................................................................................... 79
Figure 39: Tool Menu ............................................................................................................................ 79
Figure 40: Tool Options ......................................................................................................................... 80
Figure 41: Configurator Locked Setting ................................................................................................. 80
Figure 42: Configurations List................................................................................................................ 81
Figure 43: Configurator Help Menu ....................................................................................................... 81
Figure 44: Configurator Project Information .......................................................................................... 82
Figure 45: Configurator File Context Menu ........................................................................................... 82
Figure 46: Configurator Slave Settings ................................................................................................. 83
Figure 47: Configurator Create Files ..................................................................................................... 84
Figure 48: Configurator Slave Stack Code Update ............................................................................... 84
Figure 49: Configurator Project Update Dialog ..................................................................................... 85
Figure 50: New Project | Import Configuration ...................................................................................... 86
Figure 51: Options | Import Configuration ............................................................................................. 86
Figure 52: SSC OD Tool workflow ........................................................................................................ 87
Figure 53: Excel application definition example .................................................................................... 87
Figure 54: Application file comment ...................................................................................................... 88
Figure 55: EEPROM Programming Tool ............................................................................................... 92
Figure 56: EEPROM Programmer | File ................................................................................................ 93
Figure 57: EEPROM Programmer | Slaves ........................................................................................... 93
Figure 58: EEPROM Programmer | List Elements ................................................................................ 93
Application Note ET9300 5
TABLES
Table 1: Hardware Related Settings ..................................................................................................... 12
Table 2: Recommended Hardware Configurations ............................................................................... 14
Table 3: Application Related Settings ................................................................................................... 26
Table 4: TSDOINFOENTRYDESC member variables .......................................................................... 42
Table 5: "TOBJECT" member variables ................................................................................................ 43
Table 6: Basic object index ranges ....................................................................................................... 44
Table 7: Supported Sync Modes ........................................................................................................... 56
Table 8: Object definitions in file cia402appl.h ................................................................................ 61
Table 9: State machine .......................................................................................................................... 64
Table 10: Linking of device and NC variables ....................................................................................... 68
Table 11: Test Object ............................................................................................................................ 71
Table 12: Test Object Entry ................................................................................................................... 71
Table 13: Test Control Object................................................................................................................ 71
Table 14: Test Control Object Entries ................................................................................................... 72
Table 15: Test Application | ESC Register 0xF80:0xF83 ...................................................................... 72
Table 16: Test Object 0x2000 (ESM Group 1) ...................................................................................... 72
Table 17: Test Object 0x2010 (Mailbox Group 1) ................................................................................. 73
Table 18: Test Object 0x2020 (CoE Group 1) ....................................................................................... 73
Table 19: Test Object 0x2030 (FoE Group 1) ....................................................................................... 73
Table 20: Generic Objects ..................................................................................................................... 74
Table 21: PDO mapping and SM assign object generation .................................................................. 88
Table 22: Base Data Types ................................................................................................................... 89
Table 23: Entry access rights ................................................................................................................ 90
Table 24: Enum definition ...................................................................................................................... 91
Table 25: Enum usage .......................................................................................................................... 91
Table 26: EEPROM Emulation Settings ................................................................................................ 92
6 Application Note ET9300

1 References

[1] ETG.6010 Implementation Guideline for the CiA402 Drive Profile
(www.ethercat.org/ETG6010) [2] ETG.1000 part 6 Application Layer protocol specification (www.ethercat.org/ETG1000) [3] Application Note EL9800 [4] ETG.2000 Slave Information Specification (www.ethercat.org/ETG2000) [5] ETG 5001 Modular Device Profile Specification (www.ethercat.org/ETG5001) [6] ET1100 Datasheet [7] ETG.1020 Protocol Enhancements (www.ethercat.org/ETG1020) [8] EtherCAT Slave Quick Design Guide
(http://download.beckhoff.com/download/Document/EtherCAT/Development_products/EtherC
AT_Slave_Design_Quick_Guide.pdf)
Application Note ET9300 7
Abbreviation
Description
AL
Application Layer
CoE
CANopen application profile over EtherCAT CANopen™ is a registered trademark of CAN in Automation e.V., Nuremberg, Germany
CiA402
CANopen™ Drive Profile specified in IEC 61800-7-201;
CANopen™ and CiA™ are registered trademarks of CAN
in Automation e.V., Nuremberg, Germany
csp
cycle synchronous position
csv
cycle synchronous velocity
DC
Distributed Clocks
EoE
Ethernet over EtherCAT
ESC
EtherCAT Slave Controller
FoE
File Transfer over EtherCAT
GPO
General Purpose Output
NC
Numeric Control
PDI
Process data interface
PDO
Process Data Object
PLC
Programmable Logic Controller
SI
SubIndex
SII
Slave Information Interface
SM
Sync Manager
SPI
Serial Peripheral Interface
SSC
Slave Stack Code

2 Terms, Definition, Abbreviation

Base Datatypes -- CoE Datatypes defined in ETG.1000.6 Entry – in conclusion with object single element,
in conclusion with object dictionary the objects
Subindex -- describes a single element (entry) of an object Object dictionary – the object dictionary is a list of objects. Within this list each object is uniquely
identified by an (object) index.

2.1 Abbreviation

8 Application Note ET9300

3 Getting Started

This is a step by step instruction how to start the EtherCAT slave development with the Slave Stack Code (SSC). There is also an EtherCAT Slave Design Quick Guide available in the downloaded SSC archive. In general two possibilities are available either using the SSC Tool (3.1 SSC Tool) or the default SSC files (3.2 Default SSC files).

3.1 SSC Tool

1. Download the Slave Stack Code here.
NOTE: To download the SSC the ETG member login and an EtherCAT Vendor ID is required.
If you are not an ETG member click here or if you do not have an EtherCAT Vendor ID click
here.
2. Unzip the downloaded archive.
3. Install "EtherCAT Slave Stack Code Tool.msi".
4. Start the SSC Tool (Start -> Program Files -> EtherCAT Slave Stack Code Tool -> SSC Tool).
5. Acknowledge the usage agreement.
6. Enter your Vendor ID and company name.
7. Create a new project (File -> New)
8. Select ...
a. the default SSC configuration. b. a custom platform/application configuration. If a configuration file is available it can
also be added via the "Import" button.
NOTE: If the SSC shall be executed on a third party platform, e.g. Texas Instruments AM335x
or Renesas R-IN32M3, it is recommended to use the corresponding configuration.
9. If the default SSC configuration was selected the hardware settings should be adapted
according to the target platform (Project Navigation -> "Hardware").
10. Select the slave application (Project Navigation -> "Application").
11. Save the project (File -> Save).
12. If Doxygen is installed a source code documentation can be created automatically (Tool ->
Options -> Create Files -> Create Documentation).
13. Create the slave files (Project -> Create new Slave Files).
14. Click "Start".
15. Create a slave project with the target platform specific IDE, import the generated source files
and run the slave binary. For further details see the IDE/SDK documentation of the platform
vendor.
16. Make the ESI file available in the ESI cache of the EtherCAT configuration tool/master.
17. Connect the slave platform and the EtherCAT configuration tool and create a network.
18. Run the network configuration.

3.2 Default SSC files

1. Download the Slave Stack Code here.
NOTE: To download the SSC the ETG member login and an EtherCAT Vendor ID is required.
If you are not an ETG member click here or if you do not have an EtherCAT Vendor ID click
here.
2. Unzip the downloaded archive.
3. Create a slave project with the target platform specific IDE, import the SSC files and run the
slave binary. For further details see the IDE/SDK documentation of the platform vendor.
4. Adapt the settings in ecat_def.h to the target platform and application.
Application Note ET9300 9
5. Create an ESI file according to the settings in step 4.
6. Make the ESI file available in the ESI cache of the EtherCAT configuration tool/master.
7. Connect the slave platform and the EtherCAT configuration tool and create a network.
8. Run the network configuration.
10 Application Note ET9300
PDI and hardware abstraction
EtherCAT
State
Machine
Mailbox
Process
data
AoE
CoE
FoE
SoE
VoE
EoE
Application
e.g. CiA402 Drive Profile
Mailbox Process data
Register ESC address space (DPRAM)
0x0000 0x1000
User
Application
Generic
EtherCAT stack
Hardware
access
EtherCAT Slave
Controller (extract)
Application function set
Hardware function set
User application files (el9800appl.*,cia402appl.*,... )
PDI and hardware access functions (el9800hw.*; mcihw.*;fc1100hw.*)
Sate machine (ecatslv.*)
Slave configuration header (ecat_def.h)
Mailbox handling (mailbox.*)Process data handling (ecatappl.*)
Emergency (emcy.*)
AoE (ecataoe.*)
CoE (ecatcoe.*)
FoE (ecatfoe.*)
SoE (ecatsoe.*)
VoE
sdoserv.* objdef.*
aoeappl.*
coeappl.*
foeappl.*
EoE (ecateoe.*)
eoeappl.*

4 Code Structure

The EtherCAT slave stack as seen in Figure 1 consists of three parts:
- PDI/Hardware abstraction
- Generic EtherCAT stack
- User application The functions and macros which shall be provided by the hardware access layer (Hardware function set) are defined in chapter 5 Hardware Access. The behavior of the generic EtherCAT stack is described in ETG.1000 Specification [2] . The functions which shall be provided by the application (Application function set) are defined in chapter 6 Application.
Figure 1: EtherCAT Slave Stack Code
Figure 2 shows the association between the Slave Stack Code layers and the source files.
The structure of the code can be adapted to the application specific requirements by using the Slave Stack Code Tool (chapter 12).
Figure 2: File-Stack Association
Application Note ET9300 11
Define
Description
EL9800_HW
Hardware access if the slave code is executed on the PIC mounted on EL9800 EtherCAT Evaluation Kit from Beckhoff Automation GmbH. It includes PIC initialization and ESC access via SPI. This configuration could also be used if the SSC needs to be adapted to any other 8 or 16Bit µC which accesses the ESC via SPI.
PIC24
Activates the configuration for the Microchip PCI24HJ128GP306 µC which is mounted on the EL9800 EtherCAT Evaluation board since
Revision 4A. This setting shall only active if define “EL9800_HW” is
also set.
PIC18
Activates the configuration for the Microchip PIC18F452 µC which is mounted on the EL9800 EtherCAT Evaluation board, Revision 2. This setting shall only active if define “EL9800_HW” is also set.
MCI_HW
Generic MCI implementation. Can be used if any kind of memory interface face is used to access the ESC.
FC1100_HW
Specific hardware implementation for the FC1100 PCI EtherCAT slave card from Beckhoff. Used on Win32 operating system.
CONTROLLER_16BIT This setting shall be used if the slave code is built for a 16Bit µC.
CONTROLLER_32BIT
This setting shall be used if the slave code is built for a 32Bit µC.
ESC_16BIT_ACCESS
If this setting is set, then only 16Bit aligned accesses will be performed on the ESC.
ESC_32BIT_ACCESS
If this setting is set, then only 32Bit aligned accesses will be performed on the ESC.
MBX_16BIT_ACCESS
If this setting is set, then the slave code will only access mailbox data 16Bit aligned. If the mailbox data is copied to the local µC memory and
the define “CONTROLLER_16BIT” is set, then this define should also
be set.
BIG_ENDIAN_16BIT
These define needs to be set if the µC always accesses external memory 16Bit wise. It works in big endian format and the switching of Low Byte and High Byte is done in hardware.
BIG_ENDIAN_FORMAT
This setting shall be set if the µC works in big endian format.

5 Hardware Access

The Slave Stack Code is executable on multiple platforms and controller architectures. This chapter describes the available hardware implementations/settings and how to implement a new user specific hardware access. To support multiple hardware architectures the SSC includes multiple settings to fulfill the specific hardware requirements. Table 1: Hardware Related Settings includes a list of the defined hardware settings (located in ecat_def.h or in the SSC Tool).
Table 1: Hardware Related Settings
The settings “EL9800_HW”, “PIC24”, “PIC18”, MCI_HW”, “FC1100_HW” are used to activate a predefined hardware access implementation. An extract of platforms/ µC is listed in Table 2: Recommended Hardware Configurations including the recommended settings. Some of the configurations can also be selected if a new project is created with the SSC Tool (see comment). If none of these settings are used, then user specific hardware access files need to be added to the
12 Application Note ET9300
slave project. In general the hardware access implementation needs to support the following features:
- ESC read/write access
- Timer supply (at least 1ms base tick)
- Calling of timer handler every 1ms (only required if timer interrupt handling is supported
,“ECAT_TIMER_INT” set to 1)
- Calling the interrupt specific functions (only required if synchronization is supported)
o PDI ISR (required if “AL_EVENT_SUPPORTED” set to 1) o SYNC0 ISR (required if “DC_SUPPORTED” set to 1)
Application Note ET9300 13
Platform
EL9800
_HW
PIC24 PIC18 MCI_HW FC1100_HW CONTROLLER_16BIT CONTROLLER_32BIT ESC_16BIT_ACCESS ESC_32BIT_ACCESS MBX_16BIT_ACCESS BIG_ENDIAN_16BIT BIG_ENDIAN_FORMAT
Comment
Microchip PIC18F452 Generic : 8Bit µC ; SPI ESC access
1 0 1 0 0 0 0 0 0 0 0 0 The stack is ready to use if the PIC 18 on the EL9800 EtherCAT Evaluation board is used. Otherwise there might be requirements to adapt the hardware access
Microchip PIC24HJ128GP306 Generic: 16Bit µC; SPI ESC access
1 1 0 0 0 1 0 1 0 1 0 0 The stack is ready to use if the PIC 24 on the EL9800 EtherCAT Evaluation board is used. Otherwise there might be requirements to adapt the hardware access.
x86 (OS Windows)
0 0 0 0 1 0 1 0 1 0 0 0 The stack is ready to use if the stack shall run on a Win32 OS in user mode. Otherwise changes in hardware access might be required. The setting “FC1100_HW” is a adapted implementation based on “MCI_HW
Texas Instruments Sitara AM335x
0 0 0 0 0 0 0 0 0 0 0 0 To use the SSC on TI AM335x chips the hardware access files from the TI SDK need to be added to the project. The files can be added to the slave project via the patch file (delivered with the SDK), by selecting the TI configuration in the SSC Tool or by adding the files manually.
Altera® NIOS®II (ESC connected via Avalon bus)
0 0 0 1 0 x x x x x 0 0 x: depends on the NIOS® configuration in the SOPC builder. In general the following points need to be adapted:
- define “MAKE_PTR_TO_ESC”
- ISRs for Timer/PDI interrupt and Sync0 (depends on the supported features)
- Implement timer access functions and macros Depending on the platform configuration further changes may be required.
Table 2: Recommended Hardware Configurations
14 Application Note ET9300
Platform
EL9800
_HW
PIC24 PIC18 MCI_HW FC1100_HW CONTROLLER_16BIT CONTROLLER_32BIT ESC_16BIT_ACCESS ESC_32BIT_ACCESS MBX_16BIT_ACCESS BIG_ENDIAN_16BIT BIG_ENDIAN_FORMAT
Comment
Xilinx Microblaze™ (ESC connected via PLB)
0 0 0 1 0 x x x x x x 0 x: depends on the Microblaze™ configuration. In general the following points need to be adapted:
- define “MAKE_PTR_TO_ESC”
- ISRs for Timer/PDI interrupt and Sync0 (depends on the supported features)
- Implement timer access functions and macros Depending on the platform configuration further changes may be required.
Renesas - RIN32M3
0 0 0 0 0 0 0 0 0 0 0 0 To use the SSC on Renesas RIN32M3 chip the chip specific hardware access files need to be added to the project. The files are added automatically if the Renesas PIN32M3 configuration is selected in the SSC Tool.
Application Note ET9300 15
Prototype:
void ECAT_CheckTimer (void)
Parameter
void
Return
void
Description
This function needs to be called every 1ms from a timer ISR (ECAT_TIMER_INT = 1). If no timer interrupt is supported this function is called automatically when 1ms is elapsed (based on the provided timer).
Prototype:
void PDI_Isr (void)
Parameter
void
Return
void
Description
This function need to be called from the PDI ISR. For the PDI specific pin naming and the interrupt generation logic please refer to [6] . To support PDI interrupt handling it is also required to set “AL_EVENT_ENABLED” to 1.
Prototype:
void Sync0_Isr (void)
Parameter
void
Return
void
Description
This function needs to be called from the Sync0 ISR. The Sync0 interrupt is generated by the DC Unit of the ESC. It is currently not supported by default to map the Sync0 signal to the PDI interrupt. To support Dc synchronization “DC_SUPPORTED” need to be set.
Prototype:
void Sync1_Isr (void)
Parameter
void
Return
void
Description
This function needs to be called from the Sync1 ISR. The Sync1 interrupt is generated by the DC Unit of the ESC. It is currently not supported by default to map the Sync1 signal to the PDI interrupt. To support Dc synchronization “DC_SUPPORTED” need to be set.

5.1 Interrupt Handler

The following functions are provided by the generic Slave Stack Code (defined in ecatappl.h) and need to be called from the hardware access layer.

5.2 Interface Functions/Macros

The functions and macros listed in this chapter need to be implemented by the hardware access layer.
16 Application Note ET9300

5.2.1 Generic

Prototype:
UINT16 HW_Init(void)
Parameter
void
Return
0 if initialization was successful > 0 if error has occurred while initialization
Description
Initializes the host controller, process data interface (PDI) and allocates resources which are required for hardware access.
Prototype:
void HW_Release(void)
Parameter
void
Return
void
Description
Release allocated resources.
Prototype:
UINT16 HW_GetALEventRegister(void)
Parameter
void
Return
Content of register 0x220-0x221
Description
Get the first two bytes of the AL Event register (0x220-0x221).
Prototype:
UINT16 HW_GetALEventRegister_Isr(void)
Parameter
void
Return
Content of register 0x220-0x221
Description
This function should be implemented if a special function for ESC access from interrupt service routines is required; otherwise this function is defined as HW_GetALEventRegister. Get the first two bytes of the AL Event register (0x220-0x221).
Prototype:
void HW_ResetALEventMask(UINT16 intMask)
Parameter
“intMask” Interrupt mask (disabled interrupt shall be zero)
Return
void
Description
Performs a logical AND with the AL Event Mask register (0x0204 : 0x0205). This function is only required if “AL_EVENT_ENABLED” is set.
NOTE: This function is only required for SSC 5.10 or older.
Application Note ET9300 17
Prototype:
void HW_SetALEventMask(UINT16 intMask)
Parameter
“intMask” Interrupt mask (enabled interrupt shall be one)
Return
void
Description
Performs a logical OR with the AL Event Mask register (0x0204 : 0x0205). This function is only required if “AL_EVENT_ENABLED” is set.
NOTE: This function is only required for SSC 5.10 or older.
Prototype:
void HW_SetLed(UINT8 RunLed,UINT8 ErrLed)
Parameter
“RunLed” EtherCAT Run LED state “ErrLed” EtherCAT Error LED state
Return
void
Description
Updates the EtherCAT Run and Error LEDs (or EtherCAT Status LED).
Prototype:
void HW_RestartTarget(void)
Parameter
void
Return
void
Description
Resets the hardware. This function is only required if “BOOTSTRAPMODE_SUPPORTED” is set.
Prototype:
void HW_DisableSyncManChannel(UINT8 channel)
Parameter
“channel” SyncManager channel
Return
void
Description
Disables selected SyncManager channel. Sets bit 0 of the corresponding 0x807 register.
NOTE: This function is only required for SSC 5.10 or older.
Prototype:
void HW_EnableSyncManChannel (UINT8 channel)
Parameter
“channel” SyncManager channel
Return
void
Description
Enables selected SyncManager channel. Resets bit 0 of the corresponding 0x807 register.
NOTE: This function is only required for SSC 5.10 or older.
18 Application Note ET9300
Prototype:
TSYNCMAN * HW_GetSyncMan(UINT8 channel)
Parameter
“channel” SyncManager channel
Return
Pointer to the SyncManager channel description. The SyncManager description structure size is always 8 Byte, the content of “TSYNCMAN” differs depending on the supported ESC access.
Description
Gets the content of the SyncManager register from the stated channel. Reads 8 Bytes starting at 0x800 + 8*channel.
NOTE: This function is only required for SSC 5.10 or older.
Prototype:
UINT32 HW_GetTimer(void)
Parameter
void
Return
Current timer value
Description
Reads the current register value of the hardware timer. If no hardware timer is available the function shall return the counter value of a multimedia timer. The timer ticks value (increments / ms) is defined in “ECAT_TIMER_INC_P_MS”. This function is required if no timer interrupt is supported (“ECAT_TIMER_INT” = 0) and to calculate the bus cycle time.
Prototype:
void HW_ClearTimer(void)
Parameter
void
Return
void
Description
Clears the hardware timer value.
Prototype:
UINT16 HW_EepromReload (void)
Parameter
void
Return
0 <> Error during EEPORM reload 0 = EEPROM load correct
Description
This function is called if an EEPROM reload request is triggered by the master. Only required if EEPROM Emulation is supported and the function pointer “pAPPL_EEPROM_Reload” is not set.
Application Note ET9300 19
Prototype:
void HW_EscRead(MEM_ADDR *pData, UINT16 Address, UINT16 Len )
Parameter
“pData”
Pointer to local destination buffer. Type of the pointer depends on the host controller architecture (specified in ecat_def.h or the SSC Tool).
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes. Only valid addresses are used depending on 8Bit/16Bit or 32 Bit ESC access (specified in ecat_def.h or the SSC Tool).
“Len”
Access size in Bytes
Return
void
Description
Reads from the EtherCAT Slave Controller. This function is used to access ESC registers and the DPRAM area.
Prototype:
void HW_EscReadIsr(MEM_ADDR *pData, UINT16 Address, UINT16 Len )
Parameter
“pData”
Pointer to local destination buffer. Type of the pointer depends on the host controller architecture (specified in ecat_def.h or the SSC Tool).
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes. Only valid addresses are used depending on 8Bit/16Bit or 32 Bit ESC access (specified in ecat_def.h or the SSC Tool).
“Len”
Access size in Bytes
Return
void
Description
This function should be implemented if a special function for ESC access from interrupt service routines is required; otherwise this function is defined as “HW_EscRead”. Reads from the EtherCAT Slave Controller. This function is used to access ESC registers and the DPRAM area.
Prototype:
void HW_EscReadDWord(UINT32 DWordValue, UINT16 Address)
Parameter
“DWordValue”
Local 32Bit variable where the register value shall be stored.
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes. Only valid 32Bit addresses are used..
Return
void
Description
Reads two words from the specified address of the EtherCAT Slave Controller.

5.2.2 Read Access

20 Application Note ET9300
Prototype:
void HW_EscReadDWordIsr(UINT32 DWordValue, UINT16 Address)
Parameter
“DWordValue”
Local 32Bit variable where the register value shall be stored.
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes. Only valid 32Bit addresses are used.
Return
void
Description
This function should be implemented if a special function for ESC access from interrupt service routines is required; otherwise this function is defined as “HW_EscReadWord”. Reads two words from the specified address of the EtherCAT Slave Controller.
Prototype:
void HW_EscReadWord(UINT16 WordValue, UINT16 Address)
Parameter
“WordValue”
Local 16Bit variable where the register value shall be stored.
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes. Only valid 16Bit addresses are used.
Return
void
Description
Reads one word from the specified address of the EtherCAT Slave Controller. Only required if “ESC_32BIT_ACCESS” is not set.
Prototype:
void HW_EscReadWordIsr(UINT16 WordValue, UINT16 Address)
Parameter
“WordValue”
Local 16Bit variable where the register value shall be stored.
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes. Only valid 16Bit addresses are used.
Return
void
Description
This function should be implemented if a special function for ESC access from interrupt service routines is required; otherwise this function is defined as “HW_EscReadWord”. Reads one word from the specified address of the EtherCAT Slave Controller. Only required if “ESC_32_BIT_ACCESS” is not set.
Application Note ET9300 21
Prototype:
void HW_EscReadByte(UINT8 ByteValue, UINT16 Address)
Parameter
“ByteValue”
Local 8Bit variable where the register value shall be stored.
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes.
Return
void
Description
Reads one byte from the EtherCAT Slave Controller. Only required if “ESC_16BIT_ACCESS” and “ESC_32BIT_ACCESS” are not set.
Prototype:
void HW_EscReadByteIsr(UINT8 ByteValue, UINT16 Address)
Parameter
“ByteValue”
Local 8Bit variable where the register value shall be stored.
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes.
Return
void
Description
This function should be implemented if a special function for ESC access from interrupt service routines is required; otherwise this function is defined as “HW_EscReadByte”. Reads one byte from the EtherCAT Slave Controller. Only required if “ESC_16BIT_ACCESS” and “ESC_32BIT_ACCESS” are not set.
Prototype:
void HW_EscReadMbxMem(MEM_ADDR *pData, UINT16 Address, UINT16 Len )
Parameter
“pData”
Pointer to local destination mailbox buffer. Type of the pointer depends on the host controller architecture (specified in ecat_def.h or the SSC Tool).
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes. Only valid addresses are used depending on 8Bit/16Bit or 32 Bit ESC access (specified in ecat_def.h or the SSC Tool).
“Len”
Access size in Bytes
Return
void
Description
Reads data from the ESC and copies to slave mailbox memory. If the local mailbox memory is also located in the application memory this function is equal to “HW_EscRead”.
22 Application Note ET9300

5.2.3 Write Access

Prototype:
void HW_EscWrite(MEM_ADDR *pData, UINT16 Address, UINT16 Len )
Parameter
“pData”
Pointer to local source buffer. Type of the pointer depends on the host controller architecture (specified in ecat_def.h or the SSC Tool).
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes. Only valid addresses are used depending on 8Bit/16Bit or 32 Bit ESC access (specified in ecat_def.h or the SSC Tool).
“Len”
Access size in Bytes
Return
void
Description
Writes from the EtherCAT Slave Controller. This function is used to access ESC registers and the DPRAM area.
Prototype:
void HW_EscWriteIsr(MEM_ADDR *pData, UINT16 Address, UINT16 Len )
Parameter
“pData”
Pointer to local source buffer. Type of the pointer depends on the host controller architecture (specified in ecat_def.h or the SSC Tool).
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes. Only valid addresses are used depending on 8Bit/16Bit or 32 Bit ESC access (specified in ecat_def.h or the SSC Tool).
“Len”
Access size in Bytes
Return
void
Description
This function should be implemented if a special function for ESC access from interrupt service routines is required; otherwise this function is defined as “HW_EscWrite”. Writes from the EtherCAT Slave Controller. This function is used to access ESC registers and the DPRAM area.
Prototype:
void HW_EscWriteDWord(UINT32 DWordValue, UINT16 Address)
Parameter
“DWordValue”
Local 32Bit variable which contains the data to be written to the ESC memory area.
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes. Only valid 32Bit addresses are used.
Return
void
Description
Writes one word to the EtherCAT Slave Controller.
Application Note ET9300 23
Prototype:
void HW_EscWriteDWordIsr(UINT32 DWordValue, UINT16 Address)
Parameter
“DWordValue”
Local 32Bit variable which contains the data to be written to the ESC memory area.
“Address”
EtherCAT Slave Controller address . Specifies the offset within the ESC memory area in Bytes. Only valid 32Bit addresses are used.
Return
void
Description
This function should be implemented if a special function for ESC access from interrupt service routines is required; otherwise this function is defined as “HW_EscWriteWord”. Writes two words to the EtherCAT Slave Controller.
Prototype:
void HW_EscWriteWordIsr(UINT16 WordValue, UINT16 Address)
Parameter
“WordValue”
Local 16Bit variable which contains the data to be written to the ESC memory area.
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes. Only valid 16Bit addresses are used.
Return
void
Description
This function should be implemented if a special function for ESC access from interrupt service routines is required; otherwise this function is defined as “HW_EscWriteWord”. Writes one word to the EtherCAT Slave Controller. Only required if “ESC_32BIT_ACCESS” is not set.
Prototype:
void HW_EscWriteWord(UINT16 WordValue, UINT16 Address)
Parameter
“WordValue”
Local 16Bit variable which contains the data to be written to the ESC memory area.
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes. Only valid 16Bit addresses are used.
Return
void
Description
Writes one word to the EtherCAT Slave Controller. Only required if “ESC_32BIT_ACCESS” is not set.
Prototype:
void HW_EscWriteByte (UINT8 ByteValue, UINT16 Address)
Parameter
“ByteValue”
Local 8Bit variable which contains the data to be written to the ESC memory area.
24 Application Note ET9300
Prototype:
void HW_EscWriteByteIsr(UINT8 ByteValue, UINT16 Address)
Parameter
“ByteValue”
Local 8Bit variable which contains the data to be written to the ESC memory area
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes.
Return
void
Description
This function should be implemented if a special function for ESC access from interrupt service routines is required; otherwise this function is defined as “HW_EscWriteByte”. Writes one byte to the EtherCAT Slave Controller. Only defined if “ESC_16BIT_ACCESS” and “ESC_32BIT_ACCESS” are disabled.
Prototype:
void HW_EscWriteMbxMem(MEM_ADDR *pData, UINT16 Address, UINT16 Len )
Parameter
“pData”
Pointer to local source mailbox buffer. Type of the pointer depends on the host controller architecture (specified in ecat_def.h or the SSC Tool).
“Address”
EtherCAT Slave Controller address. Specifies the offset within the ESC memory area in Bytes. Only valid addresses are used depending on 8Bit/16Bit or 32 Bit ESC access (specified in ecat_def.h or the SSC Tool).
“Len”
Access size in Bytes.
Return
void
Description
Writes data from the slave mailbox memory to ESC memory. If the local mailbox memory is also located in the application memory this function is equal
to “HW_EscWrite”.
“Address”
EtherCAT Slave Controller address.Specifies the offset within the ESC memory area in Bytes.
Return
void
Description
Writes one byte to the EtherCAT Slave Controller. Only defined if “ESC_16BIT_ACCESS” and “ESC_32BIT_ACCESS” are disabled.
Application Note ET9300 25
Define
Description
TEST_APPLICATION
This application supports almost all SSC features. Furthermore it is possible to force specific application behavior (see chapter 9). NOTE: this application shall not be used as basis for the application development.
EL9800_APPLICATION
Application based on the EL9800 EtherCAT Evaluation Board. 8(4) LEDs: 8(4) switches; 16Bit analog input
CiA402_DEVICE
Sample Implementation for the CiA402 Drive Profile. This application supports 2 modular Axis. See chapter 8 for further information.
SAMPLE_APPLICATION
Hardware independent application. Recommend application is if no SSC Tool configuration is available for the target platform.
SAMPLE_APPLICATION_INTERFACE
Sample application for Win32 to create a dynamic link library.
Prototype:
UINT16 MainInit(void)
Parameter
Void
Return
0 if initialization was successful > 0 if error has occurred while initialization
Description
Initialize the generic slave stack. This function should be called after the platform including operating system and ESC is ready to use.
Prototype:
void MainLoop(void)
Parameter
Void
Return
Void
Description
This function handles the low priority function like EtherCAT state machine handling, mailbox protocols and if no synchronization is enabled also the application. This function shall be called cyclically from the application.

6 Application

This chapter includes an overview over the default (sample) applications, the application interface and a guideline how to start the own application development.

6.1 Application Settings

The SSC contains a list of (sample) applications which can be used for master/slave testing or as basis for the application development. The corresponding settings are listed in Table 3: Application Related Settings (located in ecat_def.h or in the SSC Tool).
Table 3: Application Related Settings

6.2 SSC Functions

These functions are provided by the generic stack and shall be called from the application layer. The functions are declared in the header “applInterface.h”.
26 Application Note ET9300
Prototype:
void ECAT_StateChange(UINT8 alStatus, UINT16 alStatusCode)
Parameter
alStatus
Requested Al Status
alStatusCode
AL Status Code. (if != 0 the error flag indication will be set)
Return
Void
Description
This function shall be called by the application to trigger state transition in case of an application error or to complete a pending transition. If the function was called due to an error it shall be again if the error is gone. NOTE: state requests to a higher state than the current state are not allowed.

6.3 Interface Functions

Prototype:
void APPL_Application(void)
Parameter
Void
Return
void
Description
This function is called by the synchronization ISR or from the mainloop if not synchronization is activated.
Prototype:
UINT16 APPL_GetDeviceID (void)
Parameter
Void
Return
Explicit Device ID which is written to the AL Status Code register.
Description
This function is called if the master requests the Explicit Device ID. Only required if the slave supports Explicit Device ID handling (EXPLICIT_DEVICE_ID).
Prototype:
UINT16 (* pAPPL_EEPROM_Read)(UINT32 wordaddr)
Parameter
Wordaddr start word address within the EEPROM memory
Return
0 if the operation was successful. greater 0 an error has occurred
Description
This is an optional function and only required if EEPROM_EMULATION is enabled and no EEPROM content is created (CREATE_EEPROM_CONTENT == 0) This function shall copy EEPROM data to the ESC EEPROM data register (0x508:0x50F/0x50B). The EEPROM data starting at the specified word address and the length specified with "EEPROM_READ_SIZE". The data shall be copied to the ESC EEPROM buffer (ESC offset 0x508)

6.3.1 Generic

Application Note ET9300 27
Prototype:
UINT16 (* pAPPL_EEPROM_Write)(UINT32 wordaddr)
Parameter
Wordaddr start word address within the EEPROM memory
Return
0 if the operation was successful. greater 0 an error has occurred
Description
This is an optional function and only required if EEPROM_EMULATION is enabled and no EEPROM content is created (CREATE_EEPROM_CONTENT == 0) This function shall copy data from the ESC EEPROM data register (0x508:0x50F/0x50B) to the EEPROM memory. The EEPROM data starting at the specified word address and the length specified with "EEPROM_WRITE_SIZE".
Prototype:
UINT16 (* pAPPL_EEPROM_Reload)(void)
Parameter
Void
Return
0 if the operation was successful. greater 0 an error has occurred
Description
This is an optional function and only required if EEPROM_EMULATION is enabled and no EEPROM content is created (CREATE_EEPROM_CONTENT == 0). In case that this function is implemented the function “HW_EepromReload()” is not used. This function shall copy the EEPROM reload information to the ESC EEPROM data register (0x508:0x50F/0x50B). Read the ESC data sheet for the reload information (e.g. Beckhoff IPCore ESC Datasheet section II, clause 3.45.1)
Prototype:
UINT16 APPL_StartMailboxHandler(void)
Parameter
Void
Return
See generic ESM return code description
Description
This function is called during the state transition from INIT to PREOP or INIT to BOOT.

6.3.2 EtherCAT State Machine

Each ESM function returns a 16Bit Value which reflects the result of the state transition. Return value:
0 Indicates a successful transition. Define : ALSTATUSCODE_NOERRO 0xFF Indicates a pending state transition (the application need to complete the transition by
calling ECAT_StateChange). Define : NOERROR_INWORK
Other Indicates the reason for the failed transition. See [2] for a list of valid return codes.
28 Application Note ET9300
Prototype:
UINT16 APPL_StopMailboxHandler(void)
Parameter
Void
Return
See generic ESM return code description
Description
This function is called during the state transition from PREOP to INIT or BOOT to INIT.
Prototype:
UINT16 APPL_StartInputHandler (UINT16 *pIntMask)
Parameter
pIntMask Value for register 0x204 (AL Event Mask).
Return
See generic ESM return code description
Description
This function is called during the state transition from PREOP to SAFEOP (even if no input process data is available).
Prototype:
UINT16 APPL_StopInputHandler (void)
Parameter
Void
Return
See generic ESM return code description
Description
This function is called during the state transition from SAFEOP to PREOP(even if no input process data is available).
Prototype:
UINT16 APPL_StartOutputHandler (void)
Parameter
Void
Return
See generic ESM return code description
Description
This function is called during the state transition from SAFEOP to OP (even if no output process data is available).
Prototype:
UINT16 APPL_StopOutputHandler (void)
Parameter
Void
Return
See generic ESM return code description
Description
This function is called during the state transition from OP to SAFEOP(even if no output process data is available).
Application Note ET9300 29
Prototype:
UINT16 APPL_GenerateMapping (UINT16 *pInputSize, UINT16 *pOutputSize)
Parameter
Pointer to two 16bit variables to store the process data size. pInputSize : Input process data (Slave -> Master). pOutputSize : Output process data (Master - > Slave).
Return
See generic ESM return code description
Description
This function is called when the transition from PREOP to SAFEOP is requested by the EtherCAT master. This function shall calculate the process data size in bytes The values are required to check the SyncManager settings and for the generic process data handling.
Prototype:
Void APPL_AckErrorInd(UINT16 stateTrans)
Parameter
stateTrans : Indicates the current state transition .
Return
Void
Description
This function is called when the master acknowledge and Error.
Prototype:
void APPL_InputMapping(UINT16 *pData)
Parameter
pData Pointer to the input process data.
Return
Void
Description
This function is called after the application call to map the input process data to the generic stack (The generic stack will copy the data to the SM buffer).
Prototype:
void APPL_OutputMapping(UINT16 *pData)
Parameter
pData Pointer to the output process data.
Return
Void
Description
This function is called before the application call to get the output process data.
Name
ApplicationObjDic
Type
Array of structure TOBJECT (see 7.5 for structure definition)
Description
Only required if the slave supports CoE. The variable shall be defined in the application header file. This array contains the application specific objects. The last element of this array shall have the index 0xFFFF.

6.3.3 Process data handling

6.4 Interface Variables

30 Application Note ET9300
Name
pEEPROM
Type
UINT8 *
Description
Pointer to the EEPROM buffer, it is only required if EEPROM emulation is enabled (ESC_EEPROM_EMULATION = 1). It is defined in ecatappl.h and shall be set by the application during power up (before MainInit() is called). The size of the EEPROM buffer is defined by the setting ESC_EEPROM_SIZE (default 2048)

6.5 Create an Application

A user specific application can either be created from the scratch, by adapting an existing sample application or import/create an application definition file (see chapter 13). The default SSC sample applications are listed at the beginning of this chapter. Other (sample) applications might be available by other vendors and can be added to the slave project manually, by patch file of the application vendor or the SSC Tool. See chapter 6.5.1 for details.
How to configure…
no mailbox support:
It is recommended that each complex EtherCAT slave supports at least the CoE mailbox protocol. To disable the mailbox handling all protocol settings shall be set to 0 ( “AOE_SUPPORTED”,
“COE_SUPPORTED”, “EOE_SUPPORTED”, “FOE_SUPPORTED”, “SOE_SUPPRTED” and
“VOE_SUPPORTED”).
NOTE: Even if no mailbox is supported the SyncManager0 and SyncManager1 shall just be disabled and reserved for mailbox communication. If the SM are removed the SSC need to be adapted.
input/output only device:
To create a input/output only EtherCAT slave set either “MAX_PD_INPUT_SIZE” or “MAX_PD_OUTPUT_SIZE” to 0. Otherwise these settings shall be set to the maximum
process data size. NOTE: The not used process data Sync Manager shall just be disabled. If the SM is removed
the SSC need to be adapted.

6.5.1 Adding a new Application The most comfortable way to add a new application to the SSC is using the SSC Tool. Just create a

new project and define an application by selecting “Tool->Application->Create new”. The syntax for the opened table is described in chapter 13. A step-by-step instruction is available in the EtherCAT Slave Quick Design Guide ([8] ).
To add a new application manually to the slave project all default sample applications need to be disabled (see 6.1). Afterwards the header file including the function definitions need to be included in the files “coeappl.c”, “ecatappl.c” and “ecatslv.c” (see “APPLICATION_FILE” comment). The corresponding ESI file needs to be created from the scratch or by adapting an existing one.
Adding an application via a patch file please refer to the instructions of the application vendor. The ESI file should be provided with the application source files.

6.5.2 Examples

6.5.2.1 Sample Application process data enhancement
This example base on the SSC version 5.01 and describes how to add new process data to the default sample application (SAMPLE_APPLICATION).
The default sample application provides the following process data:
- 32Bit Input Counter (0x6000)
Application Note ET9300 31
- 32Bit Output Counter (0x7010) If the Output Counter is 0 the Input Counter is incremented with every application cycle by 1,
otherwise the Input Counter is the Output Counter +1.
Process data of the new application:
- 32Bit Input Counter (0x6000)
- 32Bit Result (0x6010)
- Output Values (0x7010)
SI1: Value1 (32Bit) SI2: Value2 (32Bit)
0x6010 is the sum of 0x7010.1 and 0x7010.2. 0x6000 is incremented with every application cycle.
Initial Steps:
The initial steps describe how to create the basic sample application for the Beckhoff EL9800 EtherCAT evaluation board. Proceed with the “Adaption steps” if the basic sample application already exists (even if it was created for another platform).
1. Follow the steps 1-7 in chapter 3.1SSC Tool.
2. Select the custom configuration “EL9800 | 8Bit Digital I/O, 16Bit Analog Input”
3. Select group “Application” a. Set “EL9800_APPLICATION” to 0 b. Set “SAMPLE_APPLICATION” to 1
4. Save the project and create new slave files (Project -> “Create new Slave Files”)
5. Program the slave EEPROM based on the created ESI file (see “APPLICATION NOTE EL9800”
for further details)
6. Create an MPLAB project with the create source files (see “APPLICATION NOTE EL9800” for
further details)
Adaption steps:
1. File: sampleappl.h
Create the entry description, the object name and the variable for the “32Bit Result” process data.
/************************************************************************** * Object 0x6010: result object **************************************************************************/
#ifdef _OBJD_
/* Entry description */
OBJCONST TSDOINFOENTRYDESC OBJMEM EntryDesc0x6010 = {DEFTYPE_UNSIGNED32, 0x10, ACCESS_READ | OBJACCESS_TXPDOMAPPING};
/* Object name */
OBJCONST UCHAR OBJMEM aName0x6010[] = "Result"; #endif //#ifdef _OBJD_
/* Variable to handle the object data */
PROTO UINT32 ResultObj6010;
2. File: sampleappl.h
Change the existing definition of object 0x7010 (32Bit Output Counter) to a record object which handles more than one process data (the new object shall include two variables (entries)). The variable for the entry description is changed to an array and the description for SubIndex0 and for the second variable is added.
The name variable is enhanced by the names for the entries (each “subname” is terminated by
“\000” and the whole string is terminated by “\377”).
For the object data itself a structure including a variable for the subindex0 and the two process data variables is defined. See chapter 11 for detailed information regarding the definitions.
32 Application Note ET9300
/************************************************************************** * Object 0x7010: output values object **************************************************************************/
#ifdef _OBJD_ OBJCONST TSDOINFOENTRYDESC OBJMEM asEntryDesc0x7010[] = {
/* Entry description of Subindex0 */
{DEFTYPE_UNSIGNED8, 0x08, ACCESS_READ},
/* Entry description of the first entry “Value1” */
{DEFTYPE_UNSIGNED32, 0x20, ACCESS_READ | OBJACCESS_RXPDOMAPPING},
/* Entry description of the second entry “Value2” */
{DEFTYPE_UNSIGNED32, 0x20, ACCESS_READ | OBJACCESS_RXPDOMAPPING}};
/* Name of the object and the entries */
OBJCONST UCHAR OBJMEM aName0x7010[] = "Output values\000Value1\000Value2\000\377"; #endif //#ifdef _OBJD_
/* Structure to handle the object data*/
typedef struct OBJ_STRUCT_PACKED_START { UINT16 u16SubIndex0; UINT32 Value1; UINT32 Value2; } OBJ_STRUCT_PACKED_END TOBJ7010;
PROTO TOBJ7010 OutputData #ifdef _SAMPLE_APPLICATION_ = {0x02, 0x00, 0x00} #endif ;
3. File: sampleappl.h
Add information about the new process data to the PDO mapping objects. The changed code is marked bold red. NOTE: This step is required to have consistent process data information.
Definition for RxPDO (0x1601) (handling the output process data)
/************************************************************************** * Object 0x1601: RxPDO **************************************************************************/
#ifdef _OBJD_ OBJCONST TSDOINFOENTRYDESC OBJMEM asEntryDesc0x1601[] = { {DEFTYPE_UNSIGNED8, 0x8, ACCESS_READ }, {DEFTYPE_UNSIGNED32, 0x20, ACCESS_READ},
/* reference to the new process data. The information does NOT describe the process data itself, that means if the process data is an UNSIGNED8 value the deftype in this description is still UNSIGNED32*/
{DEFTYPE_UNSIGNED32, 0x20, ACCESS_READ}};
/* Only the object name is described all entries are automatically names as “SubIndex 000” (000 is incremented for each entry) */
OBJCONST UCHAR OBJMEM aName0x1601[] = "RxPDO-Map\000\377"; #endif //#ifdef _OBJD_
typedef struct OBJ_STRUCT_PACKED_START { UINT16 u16SubIndex0;
/* Add one additional array element for the reference to the new process data */
UINT32 aEntries[2]; } OBJ_STRUCT_PACKED_END TOBJ1601;
PROTO TOBJ1601 RxPDOMap
Application Note ET9300 33
#ifdef _SAMPLE_APPLICATION_ = {2/*the object has now two entries*/, {0x70100120,0x70100220/* Reference
to object 0x07010 Subindex2 and 32Bit length */}}
#endif ;
Definition for TxPDO (0x1A00) (handling the input process data)
/************************************************************************** * Object 0x1A00: TxPDO **************************************************************************/
#ifdef _OBJD_ OBJCONST TSDOINFOENTRYDESC OBJMEM asEntryDesc0x1A00[] = { {DEFTYPE_UNSIGNED8, 0x8, ACCESS_READ }, {DEFTYPE_UNSIGNED32, 0x20, ACCESS_READ},
/* reference to the new process data. The information does NOT describe the process data itself, that means if the process data is an UNSIGNED8 value the deftype in this description is still UNSIGNED32*/
{DEFTYPE_UNSIGNED32, 0x20, ACCESS_READ}};
/* Only the object name is described all entries are automatically names as “SubIndex 000” (000 is incremented for each entry) */
OBJCONST UCHAR OBJMEM aName0x1A00[] = "TxPDO-Map\000\377"; #endif //#ifdef _OBJD_
typedef struct OBJ_STRUCT_PACKED_START { UINT16 u16SubIndex0;
/* Add one additional array element for the reference to the new process data */
UINT32 aEntries[2]; } OBJ_STRUCT_PACKED_END TOBJ1A00;
PROTO TOBJ1A00 TxPDOMap #ifdef _SAMPLE_APPLICATION_ = {2/*the object has now two entries*/, {0x60000020,0x60100020/* Reference
to object 0x06010 Subindex0 and 32Bit length */}}
#endif ;
4. File: sampleappl.h
Add/Update the references in the object dictionary
TOBJECT OBJMEM ApplicationObjDic[] = { /* Object 0x1601 */ {NULL,NULL, 0x1601, {DEFTYPE_PDOMAPPING, 2 | (OBJCODE_REC << 8)}, asEntryDesc0x1601, aName0x1601, &RxPDOMap, NULL, NULL, 0x0000 }, /* Object 0x1A00 */ {NULL,NULL, 0x1A00, {DEFTYPE_PDOMAPPING, 2 | (OBJCODE_REC << 8)}, asEntryDesc0x1A00, aName0x1A00, &TxPDOMap, NULL, NULL, 0x0000 },
…
/* Object 0x6010 */ {NULL,NULL, 0x6010, {DEFTYPE_UNSIGNED32, 0 | (OBJCODE_VAR << 8)}, &EntryDesc0x6010, aName0x6010, &ResultObj6010, NULL, NULL, 0x0000 },
/* Object 0x7010 */ {NULL,NULL, 0x7010, {DEFTYPE_RECORD, 2 | (OBJCODE_REC << 8)},
asEntryDesc0x7010, aName0x7010, &OutputData, NULL, NULL, 0x0000 },
{NULL,NULL, 0xFFFF, {0, 0}, NULL, NULL, NULL, NULL}};
5. File: sampleappl.c
Update the expected process data size (which is similar to the size of the corresponding
34 Application Note ET9300
SyncManager). NOTE: if one of the values mismatch with the information in the ESI file the slave will abort the state transition from PreOP to SafeOP with the Error code 0x1E or 0x1D (depending on the wrong value)
UINT16 APPL_GenerateMapping(UINT16 *pInputSize,UINT16 *pOutputSize) {
/* 32Bit cyclic counter (0x6000) and 32Bit Result (*0x6010)/
*pInputSize = 8;
/*32Bit Value1 (0x7010.1) and 32Bit Value2 (0x7010.2)*/
*pOutputSize = 8;
return ALSTATUSCODE_NOERROR; }
6. File: sampleappl.c
Update the input process data mapping function to copy also the new process data.
void APPL_InputMapping(UINT16* pData) { MEMCPY(pData,&InputCounter,SIZEOF(InputCounter));
/* Increment the data pointer to write the next process data (pData refers to the buffer which is copied to the ESC memory controlled by SyncManager 3 (input process data) */
pData +=2;
/* Copy the value the result */
MEMCPY(pData,&ResultObj6010,SIZEOF(ResultObj6010));
}
7. File: sampleappl.c
Update the output process data mapping function to update the variables handling the output process data.
void APPL_OutputMapping(UINT16* pData) {
/* Update the variable “Value1” */
MEMCPY(&OutputData.Value1,pData,SIZEOF(OutputData.Value1));
/* Increment the data pointer to write the next process data (pData refers to the buffer which is copied to the ESC memory controlled by SyncManager 3 (input process data) */
pData += 2;
/* Update the variable “Value2” */
MEMCPY(&OutputData.Value2,pData,SIZEOF(OutputData.Value2));
}
8. File: sampleappl.c
Update the Application.
void APPL_Application(void) { /*Hardware independent sample application*/
ResultObj6010 = OutputData.Value1 + OutputData.Value2;
InputCounter++;
}
9. File: ESI file (in xml format)
Update the entries of the RxPdo and TxPdo elements according to step 3.
<RxPdo Mandatory="true" Fixed="true" Sm="2">
Application Note ET9300 35
<Index>#x1601</Index> <Name>RxPDO</Name> <Entry> <Index>#x7010</Index> <SubIndex>1</SubIndex> <BitLen>32</BitLen> <Name>Value1</Name> <DataType>UDINT</DataType>
</Entry>
<Entry> <Index>#x7010</Index> <SubIndex>2</SubIndex> <BitLen>32</BitLen> <Name>Value2</Name> <DataType>UDINT</DataType> </Entry>
</RxPdo>
<TxPdo Mandatory="true" Fixed="true" Sm="3"> <Index>#x1a00</Index> <Name>TXPDO</Name> <Entry> <Index>#x6000</Index> <SubIndex>0</SubIndex> <BitLen>32</BitLen> <Name>32Bit Input</Name> <DataType>UDINT</DataType> </Entry>
<Entry> <Index>#x6010</Index> <SubIndex>0</SubIndex> <BitLen>32</BitLen> <Name>Result</Name> <DataType>UDINT</DataType> </Entry>
</TxPdo>
The information is used by the master to calculate the size of the SyncManager (it shall be equal to the size specified in step 5) and to display the process data to the user (Figure 3: RxPdo data of an EtherCAT slave).
Figure 3: RxPdo data of an EtherCAT slave
10. File: ESI file
Update the default size of SyncManager according the total bit size of the RxPdo/TxPdo entries
<Sm MinSize="34" MaxSize="192" DefaultSize="128" StartAddress="#x1000" ControlByte="#x26" Enable="1">MBoxOut</Sm>
<Sm MinSize="34" MaxSize="192" DefaultSize="128" StartAddress="#x1400" ControlByte="#x22" Enable="1">MBoxIn</Sm>
36 Application Note ET9300
<Sm DefaultSize="8" StartAddress="#x1800" ControlByte="#x64" Enable="1">Outputs</Sm>
<Sm DefaultSize="8" StartAddress="#x1c00" ControlByte="#x20" Enable="1">Inputs</Sm>
11. File: ESI file
Update the offline object dictionary (element: “Profile/Dictionary”).
a. Add object 0x6010 (no structure definition is required for this object because it contains
only a single base data type value).
<Object> <Index>#x6010</Index> <Name>Result</Name> <Type>UDINT</Type> <BitSize>32</BitSize> <Info> <DefaultData>00000000</DefaultData> </Info> <Flags> <Access>ro</Access> <Category>o</Category> <PdoMapping>T</PdoMapping> </Flags> </Object>
b. Add the new structure of object 0x7010 to the DataType definitions.
<DataType> <Name>DT7010</Name> <BitSize>80</BitSize> <SubItem> <SubIdx>0</SubIdx> <Name>SubIndex 000</Name> <Type>USINT</Type> <BitSize>8</BitSize> <BitOffs>0</BitOffs> <Flags> <Access>ro</Access> <Category>o</Category> </Flags> </SubItem> <SubItem> <SubIdx>1</SubIdx> <Name>Value1</Name> <Type>UDINT</Type> <BitSize>32</BitSize> <BitOffs>16</BitOffs> <Flags> <Access>ro</Access> <Category>o</Category> </Flags> </SubItem> <SubItem> <SubIdx>2</SubIdx> <Name>Value2</Name> <Type>UDINT</Type> <BitSize>32</BitSize> <BitOffs>48</BitOffs> <Flags> <Access>ro</Access> <Category>o</Category> </Flags>
Application Note ET9300 37
</SubItem> </DataType>
c. Update the object 0x7010.
<Object> <Index>#x7010</Index> <Name>OutputCounter</Name> <Type>DT7010</Type> <BitSize>80</BitSize> <Info> <SubItem>
<Name>SubIndex 000</Name> <Info>
<DefaultData>02</DefaultData>
</Info> </SubItem> <SubItem> <Name>Value1</Name> <Info> <DefaultData>00000000</DefaultData> </Info> </SubItem> <SubItem> <Name>Value2</Name> <Info> <DefaultData>00000000</DefaultData> </Info> </SubItem>
</Info> <Flags> <Access>rw</Access> <Category>o</Category> <PdoMapping>R</PdoMapping> </Flags> </Object>
d. Update the PDO mapping object structure.
NOTE: the definition “DT1601” can be used for object 0x1601 and object 0x1A00 because
the object structures are equal.
<DataType> <Name>DT1601</Name> <BitSize>80</BitSize> <SubItem> <SubIdx>0</SubIdx> <Name>SubIndex 000</Name> <Type>USINT</Type> <BitSize>8</BitSize> <BitOffs>0</BitOffs> <Flags> <Access>ro</Access> <Category>o</Category> </Flags> </SubItem> <SubItem> <SubIdx>1</SubIdx> <Name>SubIndex 001</Name> <Type>UDINT</Type> <BitSize>32</BitSize> <BitOffs>16</BitOffs> <Flags> <Access>ro</Access> <Category>o</Category>
38 Application Note ET9300
</Flags> </SubItem>
<SubItem> <SubIdx>2</SubIdx> <Name>SubIndex 002</Name> <Type>UDINT</Type> <BitSize>32</BitSize> <BitOffs>48</BitOffs> <Flags> <Access>ro</Access> <Category>o</Category> </Flags> </SubItem>
</DataType>
e. Update PDO mapping object.
<Object> <Index>#x1601</Index> <Name>RxPDO-Map</Name> <Type>DT1601</Type> <BitSize>80</BitSize> <Info> <SubItem> <Name>SubIndex 000</Name> <Info> <DefaultData>02</DefaultData> </Info> </SubItem> <SubItem> <Name>SubIndex 001</Name> <Info> <DefaultData>20011070</DefaultData> </Info> </SubItem>
<SubItem> <Name>SubIndex 002</Name> <Info> <DefaultData>20021070</DefaultData> </Info> </SubItem>
</Info> <Flags> <Access>ro</Access> <Category>o</Category> </Flags> </Object>
<Object> <Index>#x1a00</Index> <Name>TxPDO-Map</Name> <Type>DT1601</Type> <BitSize>80</BitSize> <Info> <SubItem> <Name>SubIndex 000</Name> <Info> <DefaultData>02</DefaultData> </Info> </SubItem> <SubItem> <Name>SubIndex 001</Name>
Application Note ET9300 39
<Info> <DefaultData>20000060</DefaultData> </Info> </SubItem>
<SubItem> <Name>SubIndex 002</Name> <Info> <DefaultData>20101060</DefaultData> </Info> </SubItem>
</Info> <Flags> <Access>ro</Access> <Category>o</Category> </Flags> </Object>
40 Application Note ET9300

7 Objects

Objects are slave application data (e.g. variables) which can be accessed by the EtherCAT master via CoE or process data communication. An object is uniquely defined by the following characteristics:
- Local memory (7.2 Define local memory)
- Entry Description (7.3 Entry description)
- Object Name (7.4 Object name)
- OBJECT DESCRIPTION (7.5OBJECT DESCRIPTION)
The characteristics for all objects are collected in one panel, the Object Dictionary. This dictionary represents the interface for the EtherCAT master access the application data via CoE. In this paragraph we classify the objects into three different Object Codes: VARIABLE, ARRAY and RECORD. The VARIABLE includes just one base data type as one object. The ARRAY is a collection of identical base data types as one object. The RECORD includes a collection of different base data types as one object.

7.1 Design/Structure Rules

- Entries less or equal one 8Bit shall not overlap byte borders.
- Entries greater 8Bit shall always start at an exact word border. To get the required alignment the defines “ALIGNyy(x)” (yy : 1..15) can be used (see ecatappl.h). NOTE: If these rules cannot be matched a read/write callback function need to be registered in the
object dictionary.

7.2 Define local memory

The allocation of the local memory depends on the Object Code (VARIABLE, ARRAY or RECORD) which will be used.
In most cases for the Object Code VARIABLE it is sufficient to allocate memory by definition of a variable - if the desired object size is equal to a platform defined data type.
Example: Define local memory (Object Code VARIABLE)
UINT32 u32VarObject;
The other two Object Codes (ARRAY and RECORD) will be defined by structure. This contains an 8Bit variable as first member (Subindex0), which contains the highest subindex (last Object Entry). Note: in The Slave Stack Code the Subindex0 will always be defined as 16Bit variable due to alignment reasons!
Example: Define local memory (Object Code ARRAY)
typedef struct { UINT16 u16SubIndex0 ; UINT32 aEntries[4]; } _ARR_OBJ_DEF;
_ARR_OBJ_DEF ArrObj;
Example: Define local memory (Object Code RECORD)
typedef struct { UINT16 u16SubIndex0; UINT8 u8FirstEntry; UINT32 u32SecondEntry; INT16 i16ThirdEntry; } _REC_OBJ_DEF;
Application Note ET9300 41
Member
Data type
Description
DataType
unsigned 16 bit
Index of the base data type defined in [REF2].
BitLength
unsigned 16 bit
bit length of the object (entry)
ObjAccess
unsigned 16 bit
Bit 0: Read Access in Pre-Op Bit 1: Read Access in Safe-Op Bit 2: Read Access in Op Bit 3: Write Access in Pre-Op Bit 4: Write Access in Safe-Op Bit 5: Write Access in Op Bit 6: map able in RxPDO Bit 7: map able in TxPDO Bit 8: entry will be included in backup Bit 9: entry will be included in settings Bit 10: safe inputs Bit11: safe outputs Bit12: safe parameter
_REC_OBJ_DEF RecObj;

7.3 Entry descriptions

A single entry description is defined in TSDOINFOENTRYDESC. All entry descriptions of an object are referenced in one array. In case on the object code ARRAY only the first entry need to be described.
Table 4: TSDOINFOENTRYDESC member variables
Example: Object description (Object Code VARIABLE)
TSDOINFOENTRYDESC VarObjectEntryDesc = {DEFTYPE_UNSIGNED32,0x20,(ACCESS_READ|OBJACCESS_TXPDOMAPPING)};
Example: Object description (Object Code ARRAY)
TSDOINFOENTRYDESC ArrObjEntryDesc[] = { {DEFTYPE_UNSIGNED8, 0x08, ACCESS_READ}, {DEFTYPE_UNSIGNED32, 0x20, ACCESS_READ}};
Note: The object entry only describes the Subindex0 and one entry because all entries are equal.
Example: Object description (Object Code RECORD)
TSDOINFOENTRYDESC RecObjEntryDesc[] = { {DEFTYPE_UNSIGNED8, 0x08, ACCESS_READ}, {DEFTYPE_UNSIGNED8, 0x08, ACCESS_WRITE_PREOP}, {DEFTYPE_UNSIGNED32, 0x20, (ACCESS_WRITE|OBJACCESS_RXPDOMAPPING)}, {DEFTYPE_INTEGER16, 0x10, ACCESS_WRITE}};

7.4 Object name

The Object Name is an ASCII coded name. The Object Codes VARIABLE and ARRAY are described only by one name including the escape sequence "\0".
If the Object Code is RECORD each Entry (except Subindex0) is described. Between two names the sequence "\000" is added. The escape sequence string "\000\377" is added.
Example: Object name (Object Code VARIABLE)
UCHAR VarObjName[] = "Test var obj";
42 Application Note ET9300
Member
Data type
Description
Prev Entry
struct OBJECT
Pointer to previous dictionary entry. Only available if the object dictionary entries
are dynamic linked (STATIC_OBJECT_DIC = 0).
Next Entry
struct OBJECT
Pointer to next dictionary entry. Only available if the object dictionary entries
are dynamic linked (STATIC_OBJECT_DIC = 0).
Index
unsigned 16 bit
Object index of the described object. The object value depends on the type of EtherCAT slave and object usage (7.6Index Ranges)
ObjDesc
TSDOINFOOBJDESC (32 bit)
Data Type
unsigned 16 bit
Includes the data type index of the object. (defined in [2] )
ObjFlags
unsigned 16 bit
Bit 0-7: Max Subindex (value of subindex 0) Bit 8-15: Object Code (defined in [2] )
pEntryDesc
TSDOINFOENTRYDESC *
Pointer to object description. Defined in “7.3Entry description”
pName
unsigned char *
Pointer to object name. Defined in “7.4Object name”
pVarPtr
void *
Pointer to local memory. Defined in “7.2Define local memory”
Read
Pointer to Read Function. The prototype is listed below. This function will be called when an SDO upload is received. If this pointer is NULL the standard SDO upload function is executed.
Prototype: UINT8 ReadFunction ( UINT16 Index, UINT8 Subindex, UINT32 Size, UINT16 MBXMEM * pData, UINT8 bCompleteAccess )
Example: Object name (Object Code ARRAY)
UCHAR ArrObjName[] = "Array Obj";
Example: Object name (Object Code RECORD)
UCHAR RecObjName[] = "Record Obj\000First Entry\000Second Entry\000Third Entry\000\377";

7.5 Object description

The object description connects all object characteristics in one type “TOBJECT” (structure “OBJECT”). The member variables of OBJECT are listed in
Table 5.
Table 5: "TOBJECT" member variables
Application Note ET9300 43
Member
Data type
Description
Write
Pointer to Write Function. The prototype is listed below. This function will be called when an SDO download is received. If this pointer is NULL the standard SDO download function is executed.
Prototype: UINT8 WriteFunction( UINT16 index, UINT8 subindex, UINT32 dataSize, UINT16 MBXMEM * pData, UINT8 bCompleteAccess )
NonVolatileOffset
unsigned 16 bit
determine offset within nonvolatile memory. This value is evaluated if the object should be stored(load) as backup parameter.
Index Range
Description
0x0000 – 0x0FFF
Data Type Area
0x1000 – 0x1FFF
Communication Area
0x1600 – 0x19FF
RxPDO Mapping
0x1A00 – 0x1BFF
TxPDO Mapping
0x1C10 – 0x1C2F
Sync Manager PDO Assignment
0x1C30 – 0x1C4F
Sync Manager Parameters
0x2000 – 0x5FFF
Manufacturer specific Area
0x6000 – 0x6FFF
Input Area
0x7000 – 0x7FFF
Output Area
0x8000 – 0x8FFF
Configuration Area
0x9000 – 0x9FFF
Information Area
Example: Object dictionary entry description (Object Code VARIABLE)
TOBJECT VarObj_ODEntryDesc = {0x6000, {DEFTYPE_UNSIGNED32, 0 | (OBJCODE_VAR << 8)}, &VarObjectEntryDesc, VarObjName, &u32VarObject, NULL, NULL, 0x0000 };
Example: Object dictionary entry description (Object Code ARRAY)
TOBJECT ArrObj_ODEntryDesc = {0x9000, {DEFTYPE_UNSIGNED32, 5 | (OBJCODE_ARR << 8)}, ArrObjEntryDesc, ArrObjName, &ArrObj, NULL, NULL, 0x0000 };
Example: Object dictionary entry description (Object Code RECORD)
TOBJECT RecObj_ODEntryDesc = {0x7000, {DEFTYPE_RECORD, 4 | (OBJCODE_REC <<
8)}, RecObjEntryDesc, RecObjName, &RecObj, NULL, NULL, 0x0000 };

7.6 Index Ranges

The index ranges depends on the used EtherCAT profile. See Ref.[5] for further information. The Basic index ranges used in the SSC are listed in Table 6: Basic object index ranges.
Table 6: Basic object index ranges
44 Application Note ET9300
Index Range
Description
0xA000 – 0xAFFF
Diagnosis Area
0xB000 – 0xBFFF
Service Transfer Area
0xC000 – 0xEFFF
Reserved Area
0xF000h – 0xFFFF
Device Area
RxPDO (Outputs) 0x16xx 0x1601
Output Entries 0x7xxx 0x7010
TxPDO (Inputs) 0x1Axx 0x1A00 0x1A02
Input Entries 0x6xxx 0x6000 0x6020
Configuration Parameter 0x8xxx 0x8020
Configuration Area 0x1000 – 0x1FFF
Device Parameter 0xF000 – 0xFFFF
El9800 Base Objects Digital Inputs Digital Outputs Analog Inputs
If the EtherCAT slave supports CiA402 drive profile the object range 0x6000 – 0xDFFF is subdivided according to [1] . The CiA402 objects used in the CiA402 sample listed in 10.1Objects.
The object indices used in the EL9800 Application are used according to the Modular device Profile (Figure 4: EL9800 Application object ranges).
Figure 4: EL9800 Application object ranges

7.7 Implementation examples

7.7.1 Usage of Object Deftype ENUM

Each Enum Object definition shall be within the index range 0x800 – 0x0FFF. The content of an Enum definition is described in [2] . For each enum Value a 4Byte unsigned integer Value and a Name is defined. The 4Byte unsigned integer is Byte wise Octed coded . e.g: "\058\000\000\000EnumValueName"
“\058” = 5*8 + 8 = 48 = 0x30 => “EnumValueName” = 0x00000030 = 48
Example: Define Object Deftype ENUM
CHAR sEnum0801_Value00[] = "\000\000\000\000Startup"; /* Value = 0x00, Text = Startup*/ CHAR sEnum0801_Value01[] = "\001\000\000\000Runnig"; /* Value = 0x01, Text = Runnig*/ CHAR sEnum0801_Value02[] = "\012\000\000\000End"; /* Value = 0xA, Text = End*/ CHAR *apEnum0801[] = { sEnum0801_Value00, sEnum0801_Value01, sEnum0801_Value02};
OBJCONST TSDOINFOENTRYDESC OBJMEM asEntryDesc0x0801[] = {{DEFTYPE_UNSIGNED8, 8, ACCESS_READ | OBJACCESS_NOPDOMAPPING},
Application Note ET9300 45
{DEFTYPE_OCTETSTRING, 8*SIZEOF(sEnum0801_Value00), ACCESS_READ | OBJACCESS_NOPDOMAPPING}, {DEFTYPE_OCTETSTRING, 8*SIZEOF(sEnum0801_Value01), ACCESS_READ | OBJACCESS_NOPDOMAPPING}, {DEFTYPE_OCTETSTRING, 8*SIZEOF(sEnum0801_Value02), ACCESS_READ | OBJACCESS_NOPDOMAPPING}};
Example: Define Object dictionary entry: ENUM Object
{NULL,NULL, 0x0801, {DEFTYPE_ENUM, 0x03 | (OBJCODE_REC << 8)}, asEntryDesc0x0801, 0, apEnum0801 },
Example: Define New Object (using ENUM)
OBJCONST TSDOINFOENTRYDESC OBJMEM sEntryDesc0x2001 = {0x801, 0x20, ACCESS_READ }; OBJCONST UCHAR OBJMEM aName0x2001[] = "MySampleObject"; UINT32 u32MyObject = 0xA;
Example: Object dictionary entry description New Object (using ENUM)
TOBJECT MyObject_ODEntryDesc = { 0x2001, {0x801, 0 | (OBJCODE_VAR << 8)}, &sEntryDesc0x2001, aName0x2001, & u32MyObject, NULL, NULL, 0x0000 },
46 Application Note ET9300

8 Mailbox

8.1 FoE (File Transfer over EtherCAT)

FoE can be used to download and upload a file to an EtherCAT device. The protocol is similar to TFTP service.

8.1.1 Testing FoE

The Slave Stack Code supports FoE not by default but it can be activated and tested:
1.) Set the defines in “ecat_def.h”
a. FOE_SUPPORTED 1 b. FOE_SAVE_FILES 1
(FoE is also available if this define is not set but the downloaded file will not be saved)
2.) Build a binary file (*.hex) (see [3] )
3.) Write binary to the PIC controller of the Evaluation Kit (see Application Note EL9800 [3] ).
4.) Check if FoE flag in ESI file
a. Open ESI file (..\SlaveStackCode\VXiXX\esi\SlaveStackCode.xml) b. Open corresponding entry
i. Board 4a (new board): EL9800-SPI-PIC24
ii. Board 2 (former board): EL9800-SPI-PIC18
iii. If CiA 402 example is used: EL9800-CiA402
c. Check if the element EtherCATInfo : Descriptions : Devices : Device : Mailbox : FoE is
available. It has only to be present. No content is necessary.
5.) If the ESI file was edited replace the original ESI file from TwinCAT
(../Io/Ethercat/SlaveStackCode.xml) with the edited one.
6.) Rewrite SII if ESI file was edited (see[3] )
7.) Restart device and restart TwinCAT
8.) Scan Network
9.) Select device (Evaluation Kit with FoE activated)
10.) Select Tab-“Online” and read or write a file to the slave device be pressing the corresponding
buttons in the File Access over EtherCAT – group box.

8.2 EoE (Ethernet over EtherCAT)

EoE is used to send Ethernet telegrams to EtherCAT devices (supporting a Ethernet stack). EoE is used for Ethernet communication i.e. a device supports a web server that can be accessed via browser.

8.2.1 Implementation

The EoE stack is Implemented in the files ecateoe.* (basic EoE handling) and eoeappl.* (EoE application handling).To support EoE the switch “EOE_SUPPORTED” need to be set to 1 and the EoE flag need to be set in the ESI (REF.[4] ). Depending on the switch “STATIC_ETHERNET_BUFFER” dynamic memory is allocated for Ethernet frame handling or a fixed memory is used (1514 Bytes). By default the stack only handles ICMP and ARP frames.
8.2.1.1 Sending EoE datagrams
To send EoE datagram from the EtherCAT slave to the EtherCAT master the function “EOE_SendFrameReq()” shall be called.
Application Note ET9300 47
EOE_SendFrameReq()
SendFragment()
MBX_MailboxSendReq()
Pending frame?
Yes
Full Mbx buffer?
Yes
Frame complete?
No
Store datagram in
„pEoESendStored“
No
No
Clear
„bSendFramePending“ flag
This function is called to send an ethernet frame. (Slave -> Master)
If no ethernet frame is currently pending („bSendFramePending“ is FALSE).
Split the ethernet frame into EoE datagrams
Generic send mailbox handling (write mailbox data to Input Mbx SyncManger (default: SM1))
If MBX_MailboxSendReq() returns a value unequal 0 the mailbox buffer is full
If the complete ethernet frame was splitted into EoE datagrams and at least enqued for sending
The function „EOE_SendFrameReq()“ need to be called once again by the application
If frame was not complete sended the flag
„bSendFramePending“ is
still set and „SendFragment()“ is called by „EOE_ContinueInd()“
Yes
8.2.1.2 Receiving EoE datagrams
Received EoE datagrams are handled by the function “EOE_ServiceInd()” which is called from the
generic mailbox stack. The program flow is shown in Figure 6.
48 Application Note ET9300
Figure 5: Send EoE datagram
EOE_ServiceInd()
Init Request
Yes
Yes
No
No
Copy frame fragment to
local buffer
This function is called from the generic mailbox stack if a EoE datagram was received
Checks if an EoE Init Request was received
EOEAPPL_SettingsInd()
Frame Fragment
EOEAPPL_ReceiveFrameInd()
Checks if ethernet fragment was received via EoE. All other EoE services are not supprted by the SSC
Received MAC („aMacAdd“) and IP („aIpAdd“) address are stored.
Complete frame
Depending on the switch
„STATIC_ETHERNET_BUFFER“
dynamic memory is allocated or the frame is stored in
„aEthernetReceiveBuffer“
If the complete ethernet frame was received the EoE application shall be triggered
No
Yes
By default only ICMP and ARP frames are handled by this function

8.2.2 EoE Examples

The Sample code has a simple ping service integrated that answers to a ping request.
1.) Set the define EOE_SUPPORTED 1 (in ecat_def.h)
2.) Build a binary file (*.hex) (see [3] ).
Figure 6: Receive EoE datagram
Application Note ET9300 49
3.) Write binary to the PIC controller of the Evaluation Kit (see Application Note EL9800 [3] ).
4.) Change EoE flag in ESI file
a. Open ESI file (..\SlaveStackCode\VXiXX\esi\SlaveStackCode.xml) b. Open corresponding entry
i. Board 4a (new board): EL9800-SPI-PIC24
ii. Board 2 (former board): EL9800-SPI-PIC18
iii. If CiA 402 example is used: EL9800-CiA402
c. Enter the element EtherCATInfo : Descriptions : Devices : Device : Mailbox : EoE
Only the element has to be present.
5.) Replace the original ESI file from TwinCAT (../Io/Ethercat/SlaveStackCode.xml) with the
edited one.
6.) Rewrite SII (see [3] ).
8.2.2.1 EoE Example 1
The prerequisite for this example are the steps described in the introduction of chapter 8.2.2 EoE Examples. The example describes how to ping an EtherCAT slave device from a master platform (Figure 7: EoE Example 1 (Schema)).
Figure 7: EoE Example 1 (Schema)
1.) Restart device and restart TwinCAT
2.) Configure Network Card NIC
a. Open network adapter setting b. Open the settings of the Network-Card that is used for EtherCAT (!)
i. Set IP-Address of the card to the value you want to use, e.g.:
ii. IP-Address: 192.168.1.10
iii. Subnet Mask: 255.255.255.0
c. Leave all other fields blank (DNS, WINS, Gateway)
50 Application Note ET9300
3.) Save settings
a. Configure device b. Open TwinCAT c. Scan Network d. Select device (Evaluation Kit with EoE activated) e. Select EtherCAT tab and [Advanced Settings]
Figure 8: Network card settings
Figure 9: Access EtherCAT Slave Settings
f. Configure a IP address in the same subnet g. Set the IP address of the NIC as gateway
Application Note ET9300 51
Figure 10: EoE EtherCAT Slave Settings
4.) Set network at least to PRE-OP (mailbox communication needed)
5.) Open a program supporting PING service
6.) Ping device
Figure 11: Ping Command Window
8.2.2.2 EoE Example 2
The prerequisite for this example are the steps described in the introduction of chapter 8.2.2 EoE Examples.The example describes how to ping an EtherCAT slave device from a remote PC (Figure 12: EoE Example 2 (Schema)).
52 Application Note ET9300
Figure 12: EoE Example 2 (Schema)
Steps 1 to 3 are equal to EoE Example 1 (chapter 8.2.2.1).
4.) Enable IP Routing on the EtherCAT Master platform. The following steps depend on the
operating system.
a. Windows XP
i. Open the Advanced EtherCAT settings of the Master interface and select “IP
Enable Router”().
Figure 13: Enable IP Routing WinXP
b. Windows CE (CX platform)
i. Open CX Configuration Tool and enable “IP Routing”.
Application Note ET9300 53
Figure 14: Enable IP Routing WinCE
5.) Restart the PC
6.) Add Route on the external PC
a. Command: route ADD 192.168.1.0 MASK 255.255.255.0 10.35.16.52
7.) Ping slave device
54 Application Note ET9300

9 Synchronization

The Slave Stack Code supports different modes of synchronisation which are based on three physical signals: (PDI_)IRQ, Sync0 and Sync1 (Figure 15: ESC Interrupt Signals).
Figure 15: ESC Interrupt Signals
Which of these signals are supported by the stack are based on the following settings. AL_EVENT_ENABLED: Enable/Disable the (PDI_)IRQ support. The interrupt can be triggered by
different event which are controlled by the AL event register (0x220:0x223) and the AL event mask register (0x204:0x207). For further details see the ESC datasheet. By default only the process data event (process data was written to SyncManager2 or process data was read from SyncManger3) triggers the interrupt.
DC_SUPPORTED: Enable/Disable the handling of the Sync0/Sync1 signals generated by the DC UNIT.

9.1 Supported Sync Modes

If AL_EVENT_ENABLED and DC_SUPPORTED are disabled, then the SSC is operating in Free Run (slave application is not synchronized with EtherCAT cycle) mode. Otherwise the synchronisation mode is configured by the SyncTypes 0x1C32.1 and 0x1C33.1 (see [7] ). If no CoE is supported or no SyncType is written (during the state transition from PreOP to SafeOP) , then the synchronisation mode is set based on the DC activation register (0x981, ESI element: “Dc/OpMode/AssignActivate”). In Table 7 the supported Sync Modes are listed including the corresponding settings, if no SyncType was set before (writing 0x1C32:1 and 0x1C33:1).
Application Note ET9300 55
Sync Type
AL_EVENT_ENABLED
DC_SUPPORTED
Sync0/1 Activation (Reg. 0x981)
Sync0 Cycle time (Reg. 0x9A0:0x9A3)
Sync1 Cycle time (Reg. 0x9A4:0x9A7)
Free Run*
0
--
Bit0:7: 0
--
SyncManager(SM) *
1
--
Bit0:7: 0
--
SM/Sync0*
1 1 Bit0: 1 Bit1: 1 Bit2:7: --
--
SM/Sync0/Sync1
1 1 Bit0: 1 Bit1: 1 Bit2: 1 Bit3:7: --
Sync0Cycle >= Sync1Cycle Sync0*
0 1 Bit0: 1 Bit1: 1 Bit2:7: --
--
Sync0/Sync1
0 1 Bit0: 1 Bit1: 1 Bit2: 1 Bit3:7: --
--
Subordinated cycles
1 1 Bit0: 1 Bit1: 1 Bit2: 1 Bit3:7: --
Sync0Cycle < Sync1Cycle
Table 7: Supported Sync Modes
*: Default sync type if no CoE is supported.
In the following chapters the supported synchronization modes are described. The terms and values in the figures are:
- PDO_OutputMapping(): Copies the output process data from the SM2 buffer to the local
memory and calls APPL_OutputMapping(). See chapter 6 for further details.
- ECAT_Application(): Calls the function APPL_Application(). See chapter 6 for further details.
- PDO_InputMapping(): Calls the function APPL_InputMapping(). See chapter 6 for further
details. Copy the input process data from the local memory to the SM3 buffer.
- 0x1C32.6 / 0x1C33.6 (Calc and Copy Time): Required time to copy the process data from the
ESC to the local memory and calculate the output value. This can be defined by “PD_OUTPUT_CALC_AND_COPY_TIME and “PD_INPUT_CALC_AND_COPY_TIME”.
- 0x1C32.9 / 0x1C33.9 (Delay Time): Delay from receiving the trigger to set the output or latch
the input. This can be defined by “PD_OUTPUT_DELAY_TIME” and “PD_INPUT_DELAY_TIME”.
- 0x1C32.2 / 0x1C33.2 (Cycle Time): When using DC synchronization the value is read from
register 0x9A0:0x9A3.
- 0x1C32.5 / 0x1C33.5 (Min Cycle Time): Minimum cycle time for the application. This can be
specified by “MIN_PD_CYCLE_TIME”. It is the total execution time of all slave application related operations. In the SSC it is the PDO_OutputMapping(), ECAT_Application() and PDO_InputMapping().
56 Application Note ET9300
Main Loop Start
Main Loop Start
Outputs valid
Inputs latch
PDO_OutputMapping() PDO_InputMapping()ECAT_Application()
Calc and Copy
Time
(0x1C32.6)
Delay Time (0x1C32.9)
Calc and Copy
Time
(0x1C33.6)
Delay Time
(0x1C33.9)
Start Input Latch
SM2/3 Event SM2/3 Event
Outputs valid
Inputs latch
PDO_OutputMapping() PDO_InputMapping()ECAT_Application()
Calc and Copy
Time
(0x1C32.6)
Delay Time (0x1C32.9)
Calc and Copy
Time
(0x1C33.6)
Delay Time (0x1C33.9)
Min Cycle Time (0x1C32.5/0x1C33.5)
Cycle Time (0x1C32.2/0x1C33.2)
Start Input Latch

9.1.1 FreeRun

In this mode there is no slave application synchronisation (see Figure 16: Free Run). The function “PDO_OutputMapping()” is called only if new output process data is available.
Figure 16: Free Run
Free Run synchronization parameter: 0x1C32.1 = 0 0x1C33.1 = 0

9.1.2 SyncManager

In this mode the slave application is executed SyncManager synchronous (Figure 17: SyncManager Synchronization). On every write event to the output process data SyncManager (SM2) the slave application is started. If the device supports only inputs, then the application is started on reading the input process data (SM3).
SyncManager synchronization parameter: 0x1C32.1 = 0x1 0x1C33.1 = 0x22
Application Note ET9300 57
Figure 17: SyncManager Synchronization
SM2 Event SM2 Event
Outputs valid
Inputs latch
PDO_OutputMapping()
PDO_InputMapping()ECAT_Application()
Calc and Copy
Time
(0x1C32.6)
Delay Time (0x1C32.9)
Calc and Copy
Time
(0x1C33.6)
Delay Time (0x1C33.9)
Cycle Time (0x1C32.2/0x1C33.2)
Sync0 Sync0
Start Input Latch
SM2 Event SM2 Event
Outputs valid Inputs latch
PDO_OutputMapping()
PDO_InputMapping()ECAT_Application()
Calc and Copy
Time
(0x1C32.6)
Delay Time (0x1C32.9)
Calc and Copy
Time
(0x1C33.6)
Delay Time (0x1C33.9)
Cycle Time (0x1C32.2/0x1C33.2)
Sync0 Sync0
Sync1

9.1.3 SyncManager/Sync0

This mode is recommended for most applications when the Sync0-event is used for synchronization. The output process data mapping is triggered by the SM2 event and the ECAT_Application to set the output values and start the input latch is started on Sync0 (see Figure 18: SM/Sync0 Synchronization). With monitoring the SM2-event (before the Sync0-event occurs), the application ensures that there are new target values available for each local cycle. If the SM2-event is too late to complete the CalcAndCopy before the Sync0-Event occurs, the “SmEventMissed-Counter” is incremented and if the SmEventMissedLimit is exceeded the slave goes to SafeOpErr.
Figure 18: SM/Sync0 Synchronization
SyncManager/Sync0 synchronization parameter: Sync Activation Register (0x981): Bit0, Bit1 = 1 0x1C32.1 = 2 0x1C33.1 = 2 AL_EVENT_ENABLED = 1 (if 0 see 9.1.5)

9.1.4 SyncManager/Sync0/Sync1

In this mode the output process data mapping is triggered by the SM2 event, the ECAT_Application is started on Sync0 and the input latch is started with Sync1 (see Figure 19: SM/Sync0/Sync1 Synchronization). NOTE: The input latch shall be added to APPL_InputMapping(); by default it is done in APPL_Application()
SyncManager/Sync0/Sync1 synchronization parameter:
Figure 19: SM/Sync0/Sync1 Synchronization
Sync Activation Register (0x981): Bit0, Bit1, Bit2 = 1 0x1C32.1 = 2 0x1C33.1 = 3 AL_EVENT_ENABLED = 1 (if 0 see 9.1.6)
58 Application Note ET9300
Outputs valid
Inputs latch
PDO_OutputMapping()
PDO_InputMapping()ECAT_Application()
Calc and Copy
Time
(0x1C32.6)
Delay Time (0x1C32.9)
Calc and Copy
Time
(0x1C33.6)
Delay Time (0x1C33.9)
Min Cycle Time (0x1C32.5/0x1C33.5)
Cycle Time (0x1C32.2/0x1C33.2)
Sync0 Sync0
Frame
Frame
Start Input Latch
Outputs valid Inputs latch
ECAT_Application()
PDO_OutputMapping()
PDO_InputMapping()
Calc and Copy
Time
(0x1C32.6)
Delay Time (0x1C32.9)
Calc and Copy
Time
(0x1C33.6)
Delay Time
(0x1C33.9)
Cycle Time (0x1C32.2/0x1C33.2)
Sync0 Sync0
Sync1
Frame
Frame

9.1.5 Sync0

In this mode the slave application is started on Sync0 (see Figure 20: Sync0 Synchronization). To reduce the jitter delay between Sync0 and Outputs valid, the preferred synchronization is SyncManager/Sync0 (see chapter 9.1.3).
Figure 20: Sync0 Synchronization
Sync0 synchronization parameter: Sync Activation Register (0x981): Bit0, Bit1 = 1 0x1C32.1 = 2 0x1C33.1 = 2 AL_EVENT_ENABLED = 0 (if 1 see 9.1.3)

9.1.6 Sync0/Sync1

The output process data mapping and the ECAT_Application is started on Sync0 and the input latch is started with Sync1 (Figure 21: Sync0/Sync1 Synchronization). NOTE: The input latch shall be added to APPL_InputMapping(); by default it is done in APPL_Application().
Figure 21: Sync0/Sync1 Synchronization
Sync0/Sync1 synchronization parameter: Sync Activation Register (0x981): Bit0, Bit1, Bit2 = 1 0x1C32.1 = 2 0x1C33.1 = 3 AL_EVENT_ENABLED = 0 (if 1 see 9.1.4)

9.1.7 Subordinated Cycles

In this mode the output process data mapping is triggered on the SM 2 event, the ECAT_Application is started on Sync1 and each subordinated cycle is triggered with Sync0 (Figure 22: Subordinated
Application Note ET9300 59
Possible Outputs valid
Possible Inputs latch
Calc and Copy
Time
(0x1C32.6)
Delay Time (0x1C32.9)
Calc and Copy
Time
(0x1C33.6)
Delay Time
(0x1C33.9)
Sync0
Sync1
PDO_OutputMapping()
SM2 Event
PDO_InputMapping()
Sync0 Cycle Time
(0x1C32.10/0x1C33.10)
Cycle Time (0x1C32.02/0x1C33.02)
Sync0
Sync1
Start Input Latch
ECAT_Application()
Sync0
ECAT_Application()
Sync0
ECAT_Application()
Sync0
ECAT_Application()
SM2 Event
Cycles). The relation between Sync0 and the bus cycle is configured by the ESI element:CycleTimeSync0@Factor.
Figure 22: Subordinated Cycles
Subordinated Cycles synchronization parameter: Sync Activation Register (0x981): Bit0, Bit1, Bit2 = 1 Sync0Cycle Time (0x9A0:0x9A3) < Sync1Cycle Time (0x9A4:0x9A7) 0x1C32.1 = 3 0x1C33.1 = 3 AL_EVENT_ENABLED = 1
60 Application Note ET9300
Index
Object name
Variable in source code
Comment/Description
0x1600
Rx PDOs
sRxPDOMap0
includes all objects required for dynamic change between csv/csp
0x1601
Rx PDOs
sRxPDOMap1
includes objects required for csp mode of operation
0x1602
Rx PDOs
sRxPDOMap2
includes objects required for csv mode of operation
0x1A00
Tx PDOs
sTxPDOMap0
includes all objects required for dynamic change between csv/csp
0x1A01
Tx PDOs
sTxPDOMap1
includes objects required for csp mode of operation
0x1A02
Tx PDOs
sTxPDOMap2
includes objects required for csv mode of operation
0x1C12
SyncManger 2 PDO assign (Rx PDOs)
sRxPDOassign
this object is written in change state from PREOP to SAFEOP; the configuration depends on the number of axes (not include in CiA402Objects)
0x1C13
SyncManger 3 PDO assign (Tx PDOs)
sTxPDOassign
equal to 0x1C12 (not include in CiA402Objects)
0x603F
Error Code
objErrorCode
this value shall be set if an error in the PDS occurs

10 CiA402 drive profile

Since version 4.30 the Slave Stack Code contains a sample implementation of the CiA402 drive profile as described in [1] . This implementation provides the interface between the motion controller application and communication layer.
Following features are supported:
- CiA402 objects (see chapter 10.1 Objects)
- CiA402 state machine (see chapter 10.2 State machine)
- This implementation supports cyclic synchronous position (csp) and cyclic synchronous
velocity (csv) operation modes.
CiA402 specific files:
cia402appl.c : CiA402 drive profile implementation cia402appl.h : Drive profile specific objects, definitions and axes structures All motion controller related values are encapsulated in structure TCiA402Axis (file:
cia402appl.h). The configuration parameters and error codes are directly mapped to the
corresponding objects. The process data objects are updated in the input/output mapping functions (file: ecatappl.c). Currently the sample supports maximum of two axes. The axes are initialized in the EtherCAT state change from PREOP to SAFEOP.
The motion controller is a simple integration, which just copies the target values to the actual values (see chapter 10.3 Operation modes).

10.1 Objects

All CiA402 specific objects are defined in file cia402appl.h. All mandatory and some optional object are defined in this sample implementation. Table 8 contains a
list of all defined objects. The object variables are located in the structure CiA402Objects.
Table 8: Object definitions in file cia402appl.h
Application Note ET9300 61
Index
Object name
Variable in source code
Comment/Description
0x6040
Controlword
objControlWord
object for the output commands from the master
0x6041
Status word
objStatusWord
current axis status
0x605A
Quick stop option code
objQuickStopOptionCode
predefined ramp if an quick stop shall be performed
0x605B
Shutdown option code
objShutdownOptionCode
predefined action in state transition 8
0x605C
Disable operation option code
objDisableOperationOptionCode
predefined action in state transition 5
0x605E
Fault reaction option code
objFaultReactionCode
predefined action in state “Fault
reaction active”
0x6060
Modes of operation
objModesOfOperation
requested operation mode
0x6061
Modes of operation display
objModesOfOperationDisplay
current operation mode 0x6064
Position actual value
objPositionActualValue
current position value (delivered by encoder)
0x606C
Velocity actual value
objVelocityActualValue
velocity feedback
0x6077
Torque actual value
objTorqueActualValue
currently not used (only for completion)
0x607A
Target position
objTargetPosition
requested Postion value (set in csp mode)
0x607D
Software position limit
objSoftwarePositionLimit
includes the minimum and maximum actual position limit
0x6085
Quick stop declaration
objQuickStopDeclaration
predefined action in state “Quick
stop active”
0x60C2
Interpolation time period
objInterpolationTimePeriod
0x60FF
Target velocity
objTargetVelocity
target velocity requested by the master
0x6502
Supported drive modes
objSupportedDriveModes
list of all supported operation modes
The objects from 0x6000 to 0x67FF are incremented with 0x800 for each axis (Index + #Axis*0x800).

10.2 State machine

Figure 23 shows the state machine described in [1] . State changes are requested by setting 0x6040 (Controlword) or by a local event (if an error occurs). If the device is in state OP the transitions 0, 1 and 2 are skipped. The option codes next to the transition lines indicate that a specific action which shall be performed in of one of these state changes. All handled state transitions including the required Controlword, resulting state and corresponding functions are listed in Table 9: State machine. The bits 0,1,2,3 and 7 of the control word are taken into consideration in this sample implementation. Drive functions e.g.”Break applied” or “Axis function enabled” need to be activated or deactivated corresponding to the current state. In this sample these functions are handled by Boolean variables.
62 Application Note ET9300
Figure 23: CiA402 state transitions and option codes
Application Note ET9300 63
Transition
Control word bits
Resulting state
Variable (Function)
Bit 7 (fault
reset)
Bit 3 (enable operation)
Bit 2 (quick stop)
Bit 1 (enable voltage)
Bit 0 (switch on)
bBrakeApplied
bLowLevelPower
Applied
bHighLevelPower
Applied
bAxisFunction
Enabled
bConfiguration
Allowed
3 0 x 1 1 1 Switched on
true
true
true
false
true
4 0 1 1 1 1 Operation enabled
false
true
true
true
false 5 0 0 1 1 1 Switch on
true
true
true
false
true
6 0 x 1 1 0 Ready to switch on
true
true
false
false
true
7 0 x x 0 x
Switch on disabled
true
true
false
false
true 0 x 0 1 x
8 0 x 1 1 0 Ready to switch on
true
true
false
false
true
9 0 x x 0 x Switch on disabled
true
true
false
false
true
10 0 x x 0 x
Switch on disabled
true
true
false
false
true
0 x 0 1 x
11 0 x 0 1 x Quick stop active
false
true
true
true
false
12 0 x x 0 x Switch on disbaled
true
true
false
false
true
13
Triggered by application
Fault reaction active
false
true
true
true
false
14
Transition if option code 0x605E is finished
Fault
true
true
false
false
true
15 1 x x x x Switch on disabled
true
true
false
false
true
16
After quick stop always goto “Switch on disabled”
(Operation enabled)
false
true
true
true
false
Table 9: State machine
The transition number in Table 8 referring to the transition number in Figure 23.[1]

10.3 Operation modes

In general this sample supports the csv and csp mode of operation. Each axis can be configured as csv, csp or combined controller via modules (Figure 24). In last case the mode of operation can be switch dynamically. For this reason all objects required for motion control are mapped to PDOs. In the current TwinCAT Version (2.11 build 1539) the NC task doesn’t provide a variable for the objects 0x6060 (Mode of operation) and 0x6061 (Mode of operation display), so these objects values need to be directly provided by the PLC. The motion controller function (CiA402_DummyMotionControl()) just copies the target velocity values to the actual velocity. The actual position is calculated by the actual velocity and the motion controller cycle time. If the device is in SM Sync mode the cycle time is calculated by an internal timer within the first application cycle. In DC Sync mode the cycle time is set to Sync0 cycle value.
64 Application Note ET9300
Figure 24: Axis configuration
NOTE: This sample doesn’t provide a target value overflow control!

10.4 TwinCAT setup

This chapter describes the setup of motion control loop over EtherCAT. It is based on TwinCAT Version V2.11 build 1539 (major differences to TwinCAT 3 are marked in the description). At least the TwinCAT level NC is required. The position control is located on the EtherCAT master so in this case only the “target velocity” and “actual position” need to be linked to the NC task. The mode of operation shall be set to cyclic synchronous velocity mode (csv). For the corresponding objects 0x6061 (Mode of operation display) and 0x6060 (Mode of operation) is no NC axis variable reserved. So these drive variables should be mapped direct to the PLC application. The ModeOfOperation process data is only available if an axis module with dynamic mode switching is configured (as shown in Figure 24: Axis configuration). Otherwise it has to accessed via CoE.
For testing purposes 0x6060 (Mode of operation) could be set manually at each EtherCAT master restart.
Application Note ET9300 65
Figure 25: Set device variable without PLC link

10.4.1 Automatic network setup

The TwinCAT System Manger provides a comfortable master setup.
a. TwinCAT 2: Open a new System Manager configuration and scan the network for new
devices (Figure 26).
Figure 26: Scan for new EtherCAT devices with TwinCAT 2
b. TwinCAT 3: Open the Visual Studio shell, create a new TwinCAT project and scan the
network for new devices (Figure 27).
66 Application Note ET9300
Figure 27: Scan for new EtherCAT devices with TwinCAT 3
After the network scan is complete a message box appears with a notification that an EtherCAT drive was found. If the this message is acknowledged with “Yes” the System Manager will automatically create an NC task with the correct process data mapping.

10.4.2 Manual network setup

First add a NC task including a CiA402 Axis to the NC configuration.
a. TwinCAT 2 : Add NC task ->Add continuous Axis -> set Axis type to “CANopen DS402” (see
Figure 28).
Figure 28: TwinCAT 2 CiA402 axis setup
a. TwinCAT 3 : Open the context menu of the MOTION TreeItem -> “Add New Item” -> Type
“NC/PTP NCI Configuration” -> Open the context menu of the new created “Axes” TreeItem -> “Add New Item” -> Type “Continuous Axis” -> set Axis type to “CANopen DS402” (see Figure
29: TwinCAT 3 CiA402 axis setup).
Application Note ET9300 67
object index
Type variable name
device
NC axis
0x6040
output
Controlword
“Drive_Out” -> “nCtrl1” + “nCtrl2”
0x60FF
output
Target velocity
“Drive_Out” -> “nOutData2”
0x6041
input
Statusword
“Drive_In” -> ”nStatus1” + “nStatus2”
Figure 29: TwinCAT 3 CiA402 axis setup
Add a new EtherCAT device and append the CiA402 description (Figure 30).
Now the device variables (objects) need to be linked to the axis variables as shown in Table 10.
68 Application Note ET9300
Figure 30: Add CiA402 device
Table 10: Linking of device and NC variables
object index
Type variable name
device
NC axis
0x6064
input
Actual position
“Enc_In” -> “nInData1”
For the Stausword and Controlword continues process data mapping is required. This can be performed in the linking window (eg. Statusword link window Figure 31). Enable “All Types”,
“Continuous” and select the desired variables. TwinCAT will map “nStatus1” to the low byte and
“nStatus2” to the high byte of the Statusword.
Figure 31: Link multiple variables

10.4.3 NC parameter setup

It is required to setup the encoder and velocity output scaling in the NC-task of the EtherCAT master according to the drive parameters. The sample implementation not supports user defined factor group objects so the default units are used.
- Position unit: inc
- velocity unit: inc/s
- Encoder resolution: 2^16 inc/rev If a non-predefined drive is used two basic information are required, the target velocity value for
1rev/min (=> target velocity resolution) and the encoder resolution. The encoder resolution defined as 2^16 inc/rev and if 1 rev is equal to 1mm the encoder scaling factor
[mm/inc] is 0.0000152588 (Figure 32). Note: In TwinCAT 3 the parameter is called “Scaling Factor Numerator”. Encoder scaling factor formula: enc.scaling = (mm/rev)/encoder resolution
Application Note ET9300 69
Figure 32: Encoder scaling
The velocity output scaling is calculated with the following formula: velo.scaling = (2^20 / encoder resolution) * (velo resolution / 139,81)
The velocity resolution [inc/(1rev/min)] is the numerical increment if 1 rev/min is desired. In this case the ratio is 1 so the velocity scaling factor is 0.114441027(Figure 33).
Figure 33: Velocity scaling
70 Application Note ET9300
Attribute
Value
Index
0x2000 to 0x2FFD
Name
Test object
Object Code
RECORD
Max SubIndex
1-255
Sub­Index
Description
Data Type
Acces s
PDO Mappin g
Description / Default value
n (equal for every test)
Control/Cou nter
UNSIGNE D16
RW/R
No
Control the test behavior
Bit0
enable/disable the test 0: Test disabled 1: Test enabled
Bit1 -7
Reserved for future use
Bit8-15
Counter (indicates the number of test executions)
Attribute
Value
Index
0x2FFF
Name
Test control object

11 TestApplication

The test application is a specific slave stack which provides most of the specified EtherCAT slave features and also a mechanism to generate a slave behavior (also behavior which is not conform to the standard). This may be used to check master behavior with incorrect slave behavior.
This chapter is dealing with the possible configurations. The possible (mis)behaviors are organized within CoE objects in the index range from 0x2000 to 0x2FFD (Table 11 and Table 12).
In object 0x8000 the stack configuration is listed (SDO info need to be supported by EtherCAT master).
A release build of the test application for the EL9800 EtherCAT Evaluation board is located in “SSC_Vxixx/hex”. To create new test application slave files select the test application configuration in the SSC Tool.
Table 11: Test Object
Table 12: Test Object Entry

11.1 Slave Behavior Control

Three possibilities are available to control the slave behavior either updating the enable/disable bit of the test object directly (Table 12: Test Object Entry), or via the Test Control object (Chapter 11.1.1) or by updating the ESC register 0xF80:0xF83 (Chapter 11.1.2).

11.1.1 Test Control Object

The Test Control object structure (Table 13 and Table 14) is similar to the PDO mapping objects. Every Subindex (entry) of the test control object maps an enable/disable function (Bit 0) to a physical digital input of the slave device.
If the application is compiled for the EL9800_4 EtherCAT Evaluation Kit the control object contains 7 entries (SI1-7) which are mapped to the switches 2 to 8 (switch 1 is a global test function enable switch). If the stack is not compiled for the EL9800 the control element contains 16 Entries which are mapped to the GPO register (0xF10:0xF11).
Application Note ET9300 71
Table 13: Test Control Object
Attribute
Value
Object Code
ARRAY
Max SubIndex
16 (7if build for EL9800)
Sub­Index
Descripti on
Data Type
Acces s
PDO Mappin g
Description / Default value
1 – Max SubIndex (see Table 13)
Linked test object entry
UNSIGNE D32
RW
No
Linked test object entry
Bit0 – 7
Reserved for future use
Bit8 ­15
Subindex of the test object entry
Bit16­32
Index of the test object
Bit
Description
Purpose
0:15
Object Index
Updated by the master
16:23
Subindex
Updated by the master
24
1 : behavior active
Shall be set to 0 by the master if a new index/subindex was written. Is set to 1 by the slave application
32:31
Reserved for future use
Sub­Index
Description
Purpose
1
Invalid state transition from INIT to PreOP AL status Code 0x16 (Invalid Mailbox)
2
Invalid state transition from PreOP to SafeOP AL status Code 0x1D (Invalid Output SyncManager config)
3
Invalid state transition from PreOP to SafeOP AL status Code 0x1E (Invalid Input SyncManager config)
4
Do not unlock the SM3 (process data input SyncManager) buffer during the transition from PreOP to SafeOP.
Check if the Master starts the process data communication without initial input process data.
Table 14: Test Control Object Entries

11.1.2 User RAM 0xF80:0xF83

The master can write the object index and subindex of the behavior to be activated to the register (Table 15: Test Application | ESC Register 0xF80:0xF83). The value is read by the application on a state trigger from INIT to any (also INIT to INIT), if the behavior is accepted the first bit in 0xF83 is set.
Table 15: Test Application | ESC Register 0xF80:0xF83

11.2 ESM Tests (0x2000 – 0x200F)

Table 16: Test Object 0x2000 (ESM Group 1)
72 Application Note ET9300
Sub­Index
Description
Purpose
1
Check if the master mailbox counter is always incremented by 1. If not a mailbox error will be returned.
Check if the EtherCAT master sends the correct mailbox counter sequence.
2
Change the slave mailbox counter in alternating order. The mailbox counter may also have the value 0 after it was incremented.
An EtherCAT master should also handle a mailbox counter sequence unequal an increment by one.
Sub­Index
Description
Purpose
1
On SDO upload and SDO Info List request a maximum mailbox size of 16Bytes is used.
Decouple physical mailbox size from mailbox data length.
2
Create diagnosis message on every state change.
3 Create diagnosis message with every application cycle.
4
“simulate” huge object dictionary. The
number of objects is specified by “DUMMY_OD_LENGTH” (default 1000). All objects have the index 0x1000
This behavior is used to test the List segmentation handling of the master and SSC.
5
Return on SDO upload with complete access always the full object data based on MAX Subindex ( Value of SI0 is ignored)
6
Send an emergency on any SDO request in SafeOP
7
Pending SDO response on a SDO upload or download on 0x3006.0.
The request will be answered when a FoE read request for file “UnlockSdoResp” is received or in case that the mailbox queue is not supported on the next received mbx request.
Check correct pending SDO request handling.
Sub­Index
Description
Purpose
1
Return an FoE Busy on a FoE Read request

11.3 Mailbox Tests (0x2010 – 0x201F)

Table 17: Test Object 0x2010 (Mailbox Group 1)

11.4 CoE Tests (0x2020 – 0x202F)

Table 18: Test Object 0x2020 (CoE Group 1)

11.5 FoE Tests (0x2030 – 0x203F)

Application Note ET9300 73
Table 19: Test Object 0x2030 (FoE Group 1)
Index / Subindex
Daftype / Code
Access
Description
Purpose
0x3001
REAL32 / VAR
RW
Default value: 0xBABABABA
Use to test the value view by the master.
0x3002
UINT32 / VAR
RW
Default value: 0xBABABABA
0x3003
RECORD / REC
Includes base dataypes less or equal 1Byte.
SI1
BOOLEA N
RW
Default value: TRUE
SI2
BIT1
RW
Default value:0x0
SI3
BIT2
RW
Default value:0x3
SI4
BIT3
RW
Default value:0x5
SI5
1BIT Align
Next entry shall start at an Byte border
SI6
BIT4
RW
Default value:0xA
SI7
4BIT Align
Next entry shall start at an Byte border
SI8
BIT5
RW
Default value:0x1A
SI9
3BIT Align
Next entry shall start at an Byte border
SI10
BIT6
RW
Default value:0x2A
SI11
2BIT Align
Next entry shall start at an Byte border
SI12
BIT7
RW
Default value:0x6A
SI13
1BIT Align
Next entry shall start at an Byte border
SI14
BIT8
RW
Default value:0xFF
SI15
UINT8
RW
Default value:0xAA
SI16
INT8
RW
Default value:0xBB
0x3004
RECORD / REC
Object to test alignment, empty entries and several access rights
SI1
UINT16
RO
Default value:0x1122
SI2
UINT16
RW
Default value:0x3344
SI3
UINT16
WO
Default value:0x5566
SI4
BIT8
RW
Default value:0x77
Datatype BIT8 is used because to
“group” them into one 16Bit block
(in case of an 16 or 32 Bit Controller the Alignment entry and
SI5
8Bit Align
SI6
Empty
SI7
8Bit Align

11.6 Generic Objects

The objects described in this chapter are used to test the correct SDO handling by the slave and the master. Table 20: Generic Objects includes all defined objects.
Table 20: Generic Objects
74 Application Note ET9300
SI8
UINT8
RO
Default value:0x88
Bit types are based on unsigned short)
SI9
BIT2
WO
Default value:0x1
SI10
BIT2
RW
Default value:0x2
SI11
2BIT Align
SI12
BIT2
RO
Default value:0x3
SI13
BOOLEA N
RW
Default value TRUE
SI14
BIT7
RW
Default value: 0
A single access to this entry will always return the SDO Abort Code 0x08000021 (Data cannot be read or stored because of local control)
0x3005
RECORD / REC
Uses two enum definitions:
0x800: Signed/unsigned presentation
0x801: Boolean
Generic enum test and test access to byte aligned enum definitions
SI1
0x800
RW
Default value : “signed presentation”
SI2
0x801
RW
Default Value: “True”
0x3006
OCTET_S TRING / VAR
RW
The object size is 349 Byte. If a 128 Bytes mailbox is used the object is transmitted with one complete and two segmented services minus one Byte. Default value: Each Byte is incremented by one (starts with 0x00)
This object is used to test the mailbox unlock mechanism within the slave stack and the correct segmented handling by the master.
0x3007
BIT3/ARR AY
RW
BIT3 array with 5 elements
0x3008
RECORD / REC
Includes set of Array base data types (e.g. BITARR32)
SI1
UNICODE _STRING
RW
UINT16 Array with two elements
SI2
OCTET_S TRING
RW
UINT8 Array with two elements
SI3
BITARR32
RW
32Bit Array SI4
BITARR16
RW
16BitArray SI5
BITARR8
RW
8BitArray
0x3009
OCTET_S TRING / ARRAY
Huge Array Object.
This object is used to test huge object handling in the master
Application Note ET9300 75
SI1
–
254
OCTET_S TRING
RW
The first WORD of SI1 contains the Bitlength of each entry. The value can also be updated by single WORD access to SI1 all other write access will be ignored (no SDO Abort returned). The uploaded data will always be 0xBA.
0x300A
RECORD / REC
Huge Record Object Within the SSC it is handled equal to 0x3009 only the object code is changed.
This object is used to test huge object handling in the master
SI1
–
254
OCTET_S TRING
RW
The first WORD of SI1 contains the Bitlength of each entry. The value can also be updated by single WORD access to SI1 all other write access will be ignored (no SDO Abort returned). The uploaded data will always be 0xBA.
0x300B
RECORD / REC
Byte Arrays with odd word length
Test correct complete access handling of byte array entries with odd word length.
SI1
OCTET_S TRING
RW
Default value : “12345”
SI2
UINT8
RO
Default value : 0x66
SI3
OCTED_S TRING
RW
Default value : 0x77 – 0xBB SI4
UINT8
RW
Default value : 0xCC
0x300C
VAR
Max entry size object
Test behavior if the entry size is > 65535
0x300D
RECORD / REC
Slave-to-Slave test object
Test the Slave - to- Slave communication by sending an SDO upload on 0x1018.2 to a specific slave
SI1
UINT16
RW
Destination slave address
EtherCAT address of the destination slave.
SI2
UINT8
RW
Command
If 1 is written an SDO upload on 0x1018.2 is generated.
SI3
UINT8
RO
Status
1 : The SDO upload is generated 2 : The SDO upload response was
received and written to SI4
SI4
UINT32
RO
IdentValue
Value of 0x1018.2 from the slave addressed in SI1.
76 Application Note ET9300

12 Tool

The Slave Stack Code Tool allows creating new slave files depending on user specific requirements and settings. List of slave files:
- C source code files
- Source code documentation (optional)
- Device Description (ESI) (optional) Supported OS: Windows XP, Vista, 7 (32bit)
Required Framework: .NET (4.0) Two new file extensions are registered: SSC Configuration File (*.escfg) and Slave Project File (*.esp).
The configuration file is provided with each SSC version and includes all settings and information about the code. The Slave Project File is created by the configurator to save a slave project. The main user interface (Figure 34: Configurator Main User Interface) is structured in the tool bar (File,
Project, Tool and Help) above and 3 separated windows (Slave Project Navigation, Slave Settings and Conflicts).
Figure 34: Configurator Main User Interface
The following chapters describe the elements in more detail.

12.1 Default Startup Dialogs

[Usage Information] SSC tool usage information which need to be acknowledged before start working.
[Vendor Information] Dialog to enter your Vendor Information including Vendor ID and Vendor name. These Information will be added automatically to a new slave project. This information can also be added via the Options dialog.
[Run Wizard] Start the project wizard to create a new slave project.
Application Note ET9300 77

12.2 Main User Interface Elements

12.2.1 Tool Bar

12.2.1.1 File
The file menu (Figure 35: Configurator File Menu) contains the project file operations.
Figure 35: Configurator File Menu
[New] Create a new slave project based on the local SSC files. The project can either be created on the default configuration or a custom configuration (Figure 36: Create New Project). To import third party configurations see 12.6.
[Open] Open an existing project file.
[Save] Save the actual settings to the current project file (if no project file was created before a file browser dialog appears to create a new file).
[Save As] Save the actual settings to a new project file.
[Exit] Close current session.
12.2.1.2 Project
Figure 36: Create New Project
Figure 37: Configurator Project Menu
78 Application Note ET9300
[Project Update] Check for new Slave Stack Code version and update the current project. For further information see chapter 12.5.
[Find Setting] Open a dialog to find settings.
[Create new Slave Files] Open a dialog to create new slave files depending on the actual settings.
12.2.1.3 Tool
[Show Conflict Window] Hide or show the conflict window.
[Options] Open the options dialog (see Figure 40: Tool Options).
Figure 38: Find Setting Dialog
Figure 39: Tool Menu
[EEPROM Programmer] Open the EEPROM Programmer tool. This tool can be used to create an EEPROM header or binary file or to program the EEPROM of EtherCAT slaves. For further details see
14.2EEPROM Programming. [Application->Create new]
Creates a new Excel based application definition file. After Excel (or the corresponding *.xlsx Editor is closed) the application will be applied to the slave project.
[Application->Import] Imports a new slave application. The supported file types are described in chapter 13.
Application Note ET9300 79
Figure 40: Tool Options
- Generic
o [Open last project on startup]
o [Update SSC before creating a new project]
o [Update local SSC]
o [Vendor Name]
o [Vendor ID]
- Editor
o [Show advanced settings]
o [Show read only settings]
The last slave project is reloaded on the next startup of the tool.
If this flag is set the Slave Stack Code Tool checks if a new SSC version is available before creating a new project. NOTE: Before each project update ([Project] -> [Project Update]) an update of the local SSC file will be triggered. The local SSC files are stored in the application data folder.
Update local SSC files.
Add your Vendor name here. This information will be added to slave project.
Add your Vendor ID here. This information will be added to the slave project.
If you don’t have a Vendor ID yet please contact info@ethercat.org.
Show also settings which are marked as advanced (e.g. compiler settings)
Settings which are marked as read-only are shown (but remain read only). Read only settings are marked with a lock symbol (see Figure 41: Configurator Locked Setting).
Figure 41: Configurator Locked Setting
o [Block type mismatching setting values]
If enabled the new values with an invalid type format will be blocked.
o [Update dependent settings]
Ignore: dependent settings will not be updated ApplyAll: all dependent settings will be updated AskUser: a dialog will be displayed if a dependent setting has changed.
- Create Files 80 Application Note ET9300
o [Add comment if obsolete code was skipped]
Specify if a source code comment shall be added when code was deleted in comparison with the default Slave Stack Code.
o [Create documentation]
Create a code documentation based on the previously created source files. This feature requires external tools which are NOT covered by the SSC Beckhoff license agreement! Note the tool specific usage license. Basically Doxygen is required. It is possible to use an specific Doxygen configuration file otherwise the default configuration is used which additionally requires GraphViz and HTML Help Workshop.
o [Use configuration file]
Use a user specific doxygen configuration file.
o [Required Software]
Select location of the required software.
o [Create device description (ESI)]
If this option is checked an application specific device description will be cereated.
- Configurations
In this Options tab the list of custom configurations can be changed. A Configuration contains a setting list, files and ESI fragments which are required to run the SSC on a specific platform or to add a new application. A Configuration is described in xml format. Contact
EtherCATSSC@beckhoff.com to get the corresponding schema.
o [+]
Import new configurations.
o [-]
Remove a configuration from the list.
Figure 42: Configurations List
12.2.1.4 Help
Application Note ET9300 81
Figure 43: Configurator Help Menu
[About] Show information about the SSC Tool.
[Contact] Create a new email to EtherCATSSC@beckhoff.com with your standard email client.
[Documentation] List of SSC related documents

12.2.2 Windows

I. [Slave Project Navigation]
The Slave Project Navigation window lists all kinds of settings which can be configured. Selecting one of the nodes, the corresponding settings are displayed in the Slave Settings window. If the project was saved at least once the root node name is equal to the project name. This window also supports Drag & Drop.
[Slave Settings] The information shown in this window depends on the selected node in the Slave Project Navigation window. If the root project node is selected the SSC Version, Config File Version, a list of all Slave Stack Code files and user files are shown (see Figure 44: Configurator Project Information). The file list within provides a right-click context menu (see Figure 45: Configurator File Context Menu).
.
Figure 44: Configurator Project Information
Figure 45: Configurator File Context Menu
[Reload File] Cached file will be reloaded (only possible for user files).
[Remove File] Remove file from project (only possible for user files).
82 Application Note ET9300
[Add File(s)] Add one or more files to the project. These files will not evaluated and just copied to the output folder. If a new hardware access file is add it can be included to the generic files by define
“HW_ACCESS_FILE” in the hardware settings (e.g. “#include “myhw.h””).
If a new application file is add also add the reference to “APPLICATION_FILE” (e.g. “#include
“myappl.h””). NOTE: “Advanced Editor settings need to be activated to edit the file reference settings.
Edit File (double click on file)
To Edit a user specific source file double click on the file. The default editor for this file type will be open.
If one of the setting nodes are selected within the Slave Project Navigation, the corresponding settings are displayed within the Slave Settings window (Figure 46: Configurator Slave Settings).
Figure 46: Configurator Slave Settings
II. Conflict Window
This window displays conflicts of settings. Conflicts are distinguished between errors, warnings and information. Conflicting settings are denoted by the corresponding conflict symbol. NOTE: Not every combination of settings is checked. So it is up to the user to create a logical configuration.
[Error] Indicate that the configurator cannot create a valid slave stack with the actual configuration. [Warning] The settings marked with the warning symbol should be checked before creating new slave files. [Info] Additional information about the current configuration.

12.3 Create Files

Creating new files is the last step to create a new slave stack. The dialog is opened by selecting [Project] -> [Create new Slave Files].
a) Select output folder. b) [Start] Start creating new files. c) Output window dumps progress information.
Application Note ET9300 83
Figure 47: Configurator Create Files
[Cancel] Close dialog without creating new files
[Close] Close dialog when new files were created.
[Start] Create new slave files in the specified folder.
After new slave files are created a dialog appears to open the specified output folder or to return to the configurator.

12.4 Local SSC Update

Each new project is based on the local Slave Stack Code files. These files will be updated before a project update is started or when a new project is created (if this option is set). The Slave Stack Code files are stored in application folder of the SSC Tool. The update dialog is shown in Figure 48: Configurator Slave Stack Code Update.
Figure 48: Configurator Slave Stack Code Update
[online] Load SSC files from the Beckhoff FTP server.
84 Application Note ET9300
[offline] Load SSC files from a local SSC zip archive.
Both options require an external archive tool (7-Zip, WinRAR® or WinZip®).

12.5 Project Update

The SSC Tool provides the possibility to update generic files within the current project to the latest version. If new files are available the update dialog is show (Figure 49: Configurator Project Update Dialog).
Figure 49: Configurator Project Update Dialog
[Current version] Slave Stack Code version of the current project
[New version] Latest Slave Stack Code version available
[Show only current project related changes] If checked only changes are show which are related to the current project settings. Otherwise all changes are displayed. NOTE: If checked only the latest changes are shown. Related changes which are older than one version are not displayed.
[OK] Update current project. If an exclamation mark is show important information need to be acknowledged before the project is updated.
[Cancel] Cancel project update

12.6 Import Configurations

A configuration offers the possibility to manipulate SSC settings, to reference source files and add new elements ESI. By default a series of application-related configurations are available, but it is also possible to import new e.g. a configuration for the Texas Instruments AM335x.
Application Note ET9300 85
Importing a Configuration can either be done via the new project dialog (Figure 50: New Project | Import Configuration) or the options menu (Figure 51: Options | Import Configuration).
Figure 50: New Project | Import Configuration
Figure 51: Options | Import Configuration
NOTE: a Configuration may reference files which are not covered by the Beckhoff Automation GmbH license agreement. Contact the configuration vendor for further information.
86 Application Note ET9300
SSC based application files
application definition
SSC OD Tool

13 OD Tool

The SSC OD Tool converts an application definition file to slave application files for the Beckhoff Slave Stack Code (Figure 52).
Figure 52: SSC OD Tool workflow
The supported definition file formats are:
- *xls ; *xlm ; *xlsx ; *xlsm
- *.xml
- *.eds The tool can be either used as a console application (chapter 13.1) or by the Integration in the SSC
Tool (chapter 13.2).

13.1 Console application

The console application (SSC OD Tool.exe) is located in the installation folder of the SSC Tool (e.g. “c:\Program Files (x86)\EtherCAT Slave Stack Code Tool\SSC OD Tool.exe”.
Command line:
SSC OD Tool.exe application_defintion_file Options:
/esi existing_esi_file_to_update
/src folder_to_save_the_source_code NOTE: In case that an ESI file is located next to the application_defintion_file with the same name this ESI file
will be update, the “/esi” option does not need to be set. In case that that a “src” folder is located next to the application_defintion_file the source files will be
generated in that folder, the “/src” option does not need to be set.

13.2 SSC Tool Integration

If an application definition file already exists it can be imported with the menu “Tool->Application­>Import”. If no application definition file exists a new *xlsx definition file is created by click “Tool->Application­>Create new”. After the *xlsx editor is closed the application will be included to the slave project.
This chapter is handling the *.xlsx based application definition. An Example for an application definition is shown in Figure 53.
Figure 53: Excel application definition example
Application Note ET9300 87
Index range
0x2000 – 0x5FFF
Objects are added to the online and offline OD, but they are not added to the mapping objects
0x6FFF – 0x9FFF
Mapping and Assign rules apply, e.g. 0x6000 0x1A00 0x1C12:01 0x6010 0x1A01 0x1C12:02 0x6011 0x1A01 0x6020 0x1A02 …
0x7000 0x1600 0x1C13:01 0x7010 0x1601 0x1C13:02 0x7020 0x1602 0x1C13:03 ….
The slave application data is organized in objects (see chapter 7). Only objects in the manufacturer specific range 0x2000 – 0x5FFF and the profile specific range 0x6000 – 0x9FFF shall be defined. The communication specific objects are generated automatically or they are configured via the SSC Tool.

13.3 PDO mapping and SM assign objects

The PDO mapping and SyncManager assign objects are generated automatically according the Modular Device Profile (MDP), as defined in ETG.5001-1 (Since ETG.5003 Semiconductor Device Profile uses the MDP structure, the tool also generated the objects for such object dictionaries). Mapping and Assign object generation is described in Table 21.
Table 21: PDO mapping and SM assign object generation
For profiles like CiA402 input objects and output objects are all mapped into one single input and output PDO.
When defining the application objects keep always the object design rules (clause 7.1) into account.

13.4 Syntax

The following chapter describes the syntax for the application definition file.

13.4.1 Comment

Single lines can be used as a comment line (ignored) by setting a leading “//” (Figure 54).
Figure 54: Application file comment

13.4.2 Object Index

The object index shall be of the format “0xZZZZ” (Z is a hexadecimal value) otherwise the complete line is skipped.

13.4.3 ObjectCode

Valid object codes are “VARIABLE”, “ARRAY” or “RECORD”. The code VARIABLE identifies an object a single entry, and ARRAY has multiple entries with the same base data type and a RECORD contains multiple entries with different base data types. If this value is not set the object code will automatically set (based on the defined entries).
88 Application Note ET9300
Index
Name
Base Data Type
Bit Size
0x0001
BOOLEAN
BOOL BIT
1 0x001E
BYTE
BYTE
8
0x001F
WORD
WORD
16
0x0020
DWORD
DWORD
32
0x0030
BIT1
BIT1
1
0x0031
BIT2
BIT2
2
0x0032
BIT3
BIT3
3
0x0033
BIT4
BIT4
4
0x0034
BIT5
BIT5
5
0x0035
BIT6
BIT6
6
0x0036
BIT7
BIT7
7
0x0037
BIT8
BIT8
8
0x002D
BITARR8
BITARR8
8
0x002E
BITARR16
BITARR16
16
0x002F
BITARR32
BITARR32
32
0x0002
INTEGER8
SINT
8
0x0003
INTEGER16
INT
16
0x0004
INTEGER32
DINT
32
0x0005
UNSIGNED8
USINT
8
0x0006
UNSIGNED16
UINT
16
0x0007
UNSIGNED32
UDINT
32
0x0008
REAL32
REAL
32
0x0009
VISIBLE_STRING
STRING(n)
8*n

13.4.4 SI (Subindex)

The Subindex can be either a decimal or hexadecimal value from 1 to 255. In case of an entry range
the syntax “n..m” shall be used (e.g. 1..15). If the object code is record the entries may have defined
names the placeholder “{_SI_:d}” can be used in the entry name, this placeholder will be replaced by the subindex (in the specified format).

13.4.5 DataType

To set the entry data type the specification name, ESI name or the SSC syntax is accepted. Table 22: Base Data Types describes the supported data types. See ETG.1020 for reference.
Table 22: Base Data Types
Application Note ET9300 89
Index
Name
Base Data Type
Bit Size
0x000A
OCTET_STRING
ARRAY [0..n] OF BYTE
8*(n+1)
0x000B
UNICODE_STRING
ARRAY [0..n] OF UINT
16*(n+1)
0x0260
ARRAY_OF_INT
ARRAY [0..n] OF INT
16*(n+1)
0x0261
ARRAY_OF_SINT
ARRAY [0..n] OF SINT
8*(n+1)
0x0262
ARRAY_OF_DINT
ARRAY [0..n] OF DINT
32*(n+1)
0x0263
ARRAY_OF_UDINT
ARRAY [0..n] OF UDINT
32*(n+1)
Syntax
Description
RO
Read-only in all states
WO
Write-only in all states
RW
Readable and writable in all states
rd_preop
Readonly in Preop
rd_preop_safeop
Read-only in PreOP and SafeOP
rd _safeop
Read-only in SafeOP
rd_ safeop_op
Read-only in SafeOP and OP
rd _op
Read-only in OP
wr_preop
Write only in PreOP
wr _preop_safeop
Write only in PreOP and SafeOP
wr _safeop
Write only in SafeOP
wr _Safeop_op
Write only in SafeOP and OP
wr _op
Write only in OP
A padding entry is described with the notation ”pad_x” where x defines the bit size from 1 to 15.

13.4.6 Default/Min/Max

Default/Min/Max values shall be hexadecimal values. They shall have a leading “0x” and be of big endian format.

13.4.7 M/O/C, B/S and rx/tx The column “M/O/C” defines if an entry is mandatory optional or conditional. This value is only set in

the ESI file and has no influence to the slave application.
The column “B/S” specifies if an entry is a backup or setting object. The column “rx/tx” specifies if an entry is rx or tx PDO map able.

13.4.8 Access

Defines the access rights via CoE. The access (read, write, readwrite) can be identical in PreOp, SafeOp, Op. Or they can be different in some states. Example: A configuration value may be readable and writeable in PreOp, but must not be changed any more in Op. the allowed values are listed in Table 23: Entry access rights.
Table 23: Entry access rights
The state-dependent access rights shall be separated by a comma (,).

13.5 ENUM

Enums shall be defined in the index range 0x800 to 0xFFF (see also ETG.1000-6). The used name and data type shall be “DTXXXXENYY”. XXXX is the index of the enumeration and YY the used bit size.
90 Application Note ET9300
//Index
ObjectCode
SI
DataType
M/O/C
Access
Default
Name
0x0800
DT0800EN03
1 1
Signed
2 2
Unsigned
//Index
ObjectCode
SI
DataType
M/O/C
Access
Default
Name
0x8nn0
RECORD
0x01
Pad_16
0x11
DT0800EN0 3
M
RO 4 Data Unit
Example
Table 24 shows an Enum definition example.
Table 24: Enum definition
Table 25 shows an example for an entry using the above defined Enum.
Table 25: Enum usage
Application Note ET9300 91
Setting
Description
ESC_EEPROM_EMULATION
If set to 1, then EEPROM emulation is enabled. The pointer “pEEPROM” is used to access the EEPROM data and is needed to be in initialized on startup. “pEEPROM” is a global pointer defined in ecatappl.h.
CREATE_EEPROM_CONTENT
Only available in the SSC Tool. If set to 1, then a header file including the EEPROM data according to the slave configuration will be created during the slave file generation process (see chapter 12.3 Create Files).
ESC_EEPROM_SIZE
Available EEPROM buffer size in Bytes.
EEPROM_READ_SIZE
Number of Bytes the ESC can handle on a single read access. See ESC datasheet for further details. ET1100/ET1200 : 8Byte
EEPROM_WRITE_SIZE
Number of Bytes the ESC can handle on a single write access. This value is always 2.

14 EEPROM Handling

To identify an EtherCAT slave and to provide parameter (e.g. process data, supported mailbox protocols) every EtherCAT slave has to have a SII (Slave Information Interface). Usually this information is stored in an EEPROM which is connected via an I2C to the ESC. Depending on the used ESC (see ESC datasheet) it is also possible to emulate the EEPROM, which means the data is stored in the application memory and is handled by the slave application.

14.1 EEPROM Emulation

Since SSC version 5.01 EEPROM Emulation is supported and can be controlled by the settings listed in Table 26: EEPROM Emulation Settings.
Table 26: EEPROM Emulation Settings
Generating EEPROM content is required if the slave application has changed after the slave file generation with the SSC Tool or if the basic SSC is used for the slave development. Therefore an additional “EEPROM Programming” tool is provided (see chapter 14.2).

14.2 EEPROM Programming

Where a physical EEPROM is available or the EEPROM is emulated the EEPROM content needs to be generated. This can be done in multiple ways, e.g. with TwinCAT (see [3] ) or by the EEPROM programming tool (Figure 55: EEPROM Programming Tool) which is described in this chapter.
Figure 55: EEPROM Programming Tool

14.2.1 EEPROM Programmer User Elements

File menu (Figure 56: EEPROM Programmer | File):
[Open]: Open an ESI file. [Save as]: Save the EEPROM data in a binary or a header file.
92 Application Note ET9300
Figure 56: EEPROM Programmer | File
Slaves menu (Figure 57: EEPROM Programmer | Slaves):
[Scan]: Scans for connected EtherCAT slaves on the available network cards. [Program Selected]: Program the EEPROM of the slave selected in the slave list. [Program All]: Program the EEPROM of all slaves found.
Figure 57: EEPROM Programmer | Slaves
List elements (Figure 58: EEPROM Programmer | List Elements):
[Device Description]: List of all device descriptions defined in the ESI file opened. [Slaves]: List of all slaves connected.
Figure 58: EEPROM Programmer | List Elements
Application Note ET9300 93

15 Bootloader

The SSC is prepared to be used as the base code for a Bootloader implementation. The basic bootloader features are the Bootstate and firmware download. Both features are already fully provided by the SSC and can be enabled by the following settings:
- BOOTSTRAPMODE_SUPPORTED
- FOE_SUPPORTED The following functions are intent to be used in the firmware download process:
BL_Start(): Called in the state transition from INIT to BOOT BL_StartDownload(): Called on a write request in case that the file name starts with "ECATFW__" (the
file name is specified in aFirmwareDownloadHeader (foeappl.c) BL_Data(): Called on every data fragment
The firmware update itself (e.g. writing the flash and reset the Controller) can either be done during the FoE file download or on the transition from BOOT to INIT. Which mechanism is implement is up to the slave vendor.
For further information about the recommend slave behaviour during a state transition see the ETG.5003.2.
94 Application Note ET9300

Appendix

Support and Service

Beckhoff and their partners around the world offer comprehensive support and service, making available fast and competent assistance with all questions related to Beckhoff products and system solutions.

Beckhoff’s branch offices and representatives

Please contact your Beckhoff branch office or representative for local support and service on Beckhoff products! The addresses of Beckhoff's branch offices and representatives round the world can be found on her internet pages: http://www.beckhoff.com You will also find further documentation for Beckhoff components there.

Beckhoff Headquarters

Beckhoff Automation GmbH Eiserstr. 5 33415 Verl Germany phone: + 49 (0) 5246/963-0 fax: + 49 (0) 5246/963-198 e-mail: info@beckhoff.com web: www.beckhoff.com

Beckhoff Support

Support offers you comprehensive technical assistance, helping you not only with the application of individual Beckhoff products, but also with other, wide-ranging services: world-wide support design, programming and commissioning of complex automation systems and extensive training program for Beckhoff system components hotline: + 49 (0) 5246/963-157 fax: + 49 (0) 5246/963-9157 e-mail: support@beckhoff.com

Beckhoff Service

The Beckhoff Service Center supports you in all matters of after-sales service: on-site service repair service spare parts service hotline service hotline: + 49 (0) 5246/963-460 fax: + 49 (0) 5246/963-479 e-mail: service@beckhoff.com

EtherCAT Technology Group (ETG) Headquarters

Phone: +49 (911) 540 5620 Fax: +49 (911) 540 5629 Email: info@ethercat.org Internet: www.ethercat.org
Application Note ET9300 95
Loading...
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use