BECKHOFF ET9300 User Manual

Application Note ET9300

(EtherCAT Slave Stack Code)

Version 1.7

Date: 2015-01-13

LEGAL NOTICE

Trademarks

Beckhoff®, TwinCAT®, EtherCAT®, Safety over EtherCAT®, TwinSAFE® and XFC® are registered trademarks of and licensed by Beckhoff Automation GmbH. Other designations used in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owners.

Patent Pending

The EtherCAT Technology is covered, including but not limited to the following German patent applications and patents: DE10304637, DE102004044764, DE102005009224, DE102007017835 with corresponding applications or registrations in various other countries.

Disclaimer

The documentation has been prepared with care. The products described are, however, constantly under development. For that reason the documentation is not in every case checked for consistency with performance data, standards or other characteristics. In the event that it contains technical or editorial errors, we retain the right to make alterations at any time and without warning. No claims for the modification of products that have already been supplied may be made on the basis of the data, diagrams and descriptions in this documentation.

Copyright

© Beckhoff Automation GmbH

The reproduction, distribution and utilization of this document as well as the communication of its contents to others without express authorization are prohibited. Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a patent, utility model or design.

II	Application Note ET9300

							DOCUMENT HISTORY
	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

NOTE: This document makes no claim to be complete regarding to the containing topics or the Slave Stack Code. For annotations or comments to this document please send an email to [e-mail].

Application Note ET9300

1

			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

1References

[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

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.1Abbreviation

Abbreviation	Description
AL	Application Layer
CoE	CANopen application profile over EtherCAT
	CANopen™ is a registered trademark of CAN in
	Automation e.V., Nuremberg, Germany
	CANopen™ Drive Profile specified in IEC 61800-7-201;
CiA402	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

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.1SSC 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.2Default 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

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.

EtherCAT

State

Machine

0x0000	Register

Application e.g. CiA402 Drive Profile

Application function set

AoE	FoE	EoE	SoE	VoE	CoE	Process
						data
		Mailbox
	Hardware function set
PDI and hardware abstraction
		Mailbox				Process data
	0x1000		ESC address space (DPRAM)

User

Application

Generic EtherCAT stack

Hardware

access

EtherCAT Slave

Controller (extract)

Figure 1: EtherCAT Slave Stack Code

Figure 2 shows the association between the Slave Stack Code layers and the source files.

User application files (el9800appl.*,cia402appl.*,... )

coeappl.*

	aoeappl.*	sdoserv.* objdef.*	foeappl.*	eoeappl.*			header (ecat_def.h)
Emergency (emcy.*)	AoE (ecataoe.*)	CoE (ecatcoe.*)	FoE (ecatfoe.*)	EoE (ecateoe.*)	SoE (ecatsoe.*)	VoE	Slave configuration

Sate machine (ecatslv.*)

Process data handling (ecatappl.*)

Mailbox handling (mailbox.*)

PDI and hardware access functions (el9800hw.*; mcihw.*;fc1100hw.*)

Figure 2: File-Stack Association

The structure of the code can be adapted to the application specific requirements by using the Slave Stack Code Tool (chapter 12).

Application Note ET9300

11

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).

Define

EL9800_HW

Table 1: Hardware Related Settings

Description

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

PIC18

MCI_HW

FC1100_HW

CONTROLLER_16BIT

CONTROLLER_32BIT

ESC_16BIT_ACCESS

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.

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.

Generic MCI implementation. Can be used if any kind of memory interface face is used to access the ESC.

Specific hardware implementation for the FC1100 PCI EtherCAT slave card from Beckhoff. Used on Win32 operating system.

This setting shall be used if the slave code is built for a 16Bit µC.

This setting shall be used if the slave code is built for a 32Bit µC.

If this setting is set, then only 16Bit aligned accesses will be performed on the ESC.

ESC_32BIT_ACCESS

MBX_16BIT_ACCESS

BIG_ENDIAN_16BIT

BIG_ENDIAN_FORMAT

If this setting is set, then only 32Bit aligned accesses will be performed on the ESC.

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.

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.

This setting shall be set if the µC works in big endian format.

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

Microchip PIC18F452 Generic : 8Bit µC ; SPI ESC access

Microchip PIC24HJ128GP306 Generic: 16Bit µC; SPI ESC access

x86

(OS Windows)

Texas Instruments Sitara

AM335x

Altera® NIOS®II

(ESC connected via Avalon bus)

Table 2: Recommended Hardware Configurations

BIG ENDIAN FORMAT

Comment

EL9800 HW

PIC24

PIC18

MCI HW

FC1100 HW

CONTROLLER 16BIT

CONTROLLER 32BIT

ESC 16BIT ACCESS

ESC 32BIT ACCESS

MBX 16BIT ACCESS

BIG ENDIAN 16BIT

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
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.
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
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.
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.

14	Application Note ET9300

Platform

Xilinx Microblaze™

(ESC connected via PLB)

Renesas - RIN32M3

CONTROLLER 16BIT

CONTROLLER 32BIT

MBX 16BIT ACCESS

BIG ENDIAN FORMAT

Comment

EL9800_HW

PIC24

PIC18

MCI_HW

FC1100_HW

ESC_16BIT_ACCESS

ESC_32BIT_ACCESS

BIG_ENDIAN_16BIT

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.

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

5.1Interrupt 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.

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.2Interface 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.1Generic

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

5.2.2Read Access

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.

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.3Write 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_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_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_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

	“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.
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”.

Application Note ET9300

25

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.1Application 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
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.

6.2SSC 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”.

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.
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.3Interface Functions

6.3.1Generic

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)

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)

6.3.2EtherCAT 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.
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.

28	Application Note ET9300