# Example application The example application EcMasterDemo handles the following tasks: - Showing basic EtherCAT® communication - EC-Master stack initialization - Start (set all SubDevices into OPERATIONAL state) - “Out of the box” solution for different operating systems, see [Platform and Operating Systems (OS)](os.html.md#platform-and-operating-systems-os) - Thread with periodic tasks and application thread already implemented - The output messages of the demo application will be printed on the console as well as in some files. The following log files will be created: : - `ecmaster0.log` all messages - `error0.log` application error messages (logged via LogError function) \\newpage ## File reference The EC-Master Demo application consists of the following files: ![Overview of the EC-Master demo application source file structure showing the main files and their functional relationships](../Media/EcMasterDemoFileOverview.png) [`EcDemoMain.cpp`](_downloads/fc875d17cbef52a4c4879f7ba411fe69/EcDemoMain.cpp) : Entrypoint for the different operating systems [`EcDemoPlatform.h`](_downloads/8a98bd88751f8738d3ec7f509d67f6e7/EcDemoPlatform.h) : Operating system specific settings (taskpriorities, timer settings) EcDemoTimingTask[[`.h`](_downloads/743e13d5dad7cdbcc0bf1977191f46ce/EcDemoTimingTask.h)/[`.cpp`](_downloads/bec5300f8660116569772b28390fa6d1/EcDemoTimingTask.cpp)] : Operating system independent default timing task implementation (base class) EcDemoTimingTaskPlatform[[`.h`](_downloads/a1d055d5452e80c1ab3935a65fc65181/EcDemoTimingTaskPlatform.h)/[`.cpp`](_downloads/50d93bb5e26ea06e29ba3aaaae5b9cfb/EcDemoTimingTaskPlatform.cpp)] : Operating system dependent performance increasing overrides of EcDemoTimingTask [`EcDemoApp.cpp`](_downloads/76bfae586096876679f8829df50b527a/EcDemoApp.cpp) : Initialize, start and terminate the EtherCAT® MainDevice [`EcDemoApp.h`](_downloads/04255e5e3200415c8d12a8ffdff511c2/EcDemoApp.h) : Application specific settings for EcDemoApp [`EcDemoParms.cpp`](_downloads/cc5a320ac29f8e16f99cb4d2be8320fa/EcDemoParms.cpp) : Parsing of command line parameters [`EcDemoParms.h`](_downloads/7da4d0b851574416d0292c150711af29/EcDemoParms.h) : Basic configuration structs and EC-Master parameters [`EcSelectLinkLayer.cpp`](_downloads/bf62c71a4a7e317930818b9da4a9815c/EcSelectLinkLayer.cpp) : Common Functions which abstract the command line parsing into Real-time Ethernet Driver parameters `EcNotification.cpp` : SubDevice monitoring and error detection (function `emNotify()` ) `EcSdoServices.cpp` : CoE object dictionary example `EcSlaveInfo.cpp` : SubDevice information services (bus scan, SubDevice properties, getting information of SubDevices connected to the EtherCAT® bus) `EcLogging.cpp` : Message logging functions `EcTimer.cpp` : Start and monitor timeouts \\newpage ## EC-Master lifecycle This chapter provides a brief overview of starting and stopping the EC-Master. Basically the operation of the EC-Master is wrapped between the functions: - [`emInitMaster()`](api_general_functions.html.md#_CPPv412emInitMaster10EC_T_DWORDPK22EC_T_INIT_MASTER_PARMS) - [`emSetMasterState()`](api_general_functions.html.md#_CPPv416emSetMasterState10EC_T_DWORD10EC_T_DWORD10EC_T_STATE) and - [`emDeinitMaster()`](api_general_functions.html.md#_CPPv414emDeinitMaster10EC_T_DWORD) The EC-Master is made ready for operation and started with the first two functions mentioned. During this preparation, a thread is set up and started that handles all the cyclic tasks of the EC-Master. The last function stops the EC-Master and clears the memory. The following sequence diagram gives an overview of the complete life cycle. \\newpage A more detailed description of the functions: EcDemoMain() : A wrapper to start the demo from the respective operating system. In addition to initializing the operating system, parsing command line parameters, and initializing logging, it also starts the timing task. EcDemoApp() : Demo application. The function takes care of starting and stopping the MainDevice and all related tasks. In between, the function runs idle, while all relevant work is done by the EcMasterJobTask(). EcMasterJobTask() : Thread that does the necessary periodic work. Very important here is `myAppWorkpd()` between [`EC_T_USER_JOB::eUsrJob_ProcessAllRxFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB26eUsrJob_ProcessAllRxFramesE) and [`EC_T_USER_JOB::eUsrJob_SendAllCycFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB24eUsrJob_SendAllCycFramesE). Application-specific working on process data, which must be synchronous with the bus cycle, can be carried out here. EcDemoTimingTask() : Timing Thread. This thread sets the timing event that triggers the EcMasterJobTask for the next cycle. emInitMaster() : EC-Master API function: Prepare the EC-Master for operation and set operational parameters, e.g. used Real-time Ethernet Driver, buffer sizes, maximum number of SubDevices, … . emConfigureNetwork() : EC-Master API function: Loads the configuration from the ENI (XML file). emRegisterClient() : EC-Master API function: Register the application as a client at the EC-Master to receive event notifications. emSetMasterState() : EC-Master API function: Start the EC-Master and switch the bus to the different states from INIT to OPERATIONAL. emDeinitMaster() : EC-Master API function: Clean up. \\newpage ## Synchronization This chapter relates the tasks or functions that run in the `EcMasterJobTask()` to the timing and communication on the EtherCAT® bus. App : Shown are the tasks/jobs `P`, `Task`, `S`, `MT` and `AS` which must be done by the application every single cycle. The details of the individual tasks are described below. Once all tasks are finished, the application is idle for the next cycle. In buffer : Shown are the contents of the input section of the process image. The contents are not valid while the EtherCAT® MainDevice updates the data `P`. Out buffer : Shown are the contents of the output section of the process image. The contents are not valid while the application updates the data `Task`. EtherCAT® bus : Shown are the timing positions, when the EtherCAT® MainDevice does cyclic and acyclic communication on the EtherCAT® bus. Besides the timing position of the start for the cyclic frames, the shown positions may vary, depending on the number of frames. In `EcDemoApp.cpp` the tasks/jobs shown in the timing-diagram are managed and scheduled by `EcMasterJobTask()`. Job `P` : The job [`EC_T_USER_JOB::eUsrJob_ProcessAllRxFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB26eUsrJob_ProcessAllRxFramesE) handles the frames and data received from previous bus activity, including both cyclic and acyclic frames. These received frames are analyzed for new input data, and the local process image is updated accordingly. During this update, the input data section of the process image is invalid. `Task` : The function `myAppWorkpd()` allows application-specific working on process data. In this function, the application can use updated input information from Job `P`, perform calculations and manipulations, and write new data to the output section of the process image. Job `S` : The job [`EC_T_USER_JOB::eUsrJob_SendAllCycFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB24eUsrJob_SendAllCycFramesE) initiates the transmission of all cyclic frames on the EtherCAT® bus. Job `MT` : The job [`EC_T_USER_JOB::eUsrJob_MasterTimer`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB19eUsrJob_MasterTimerE) serves as an administrative role, primarily managing the timeout timers. During these calls, there is no interaction with the process image, nor do they trigger any bus traffic. It is not essential to run this function with every bus cycle, particularly in systems with cycle times shorter than 1 ms. However, it is recommended to run this function at a 1 ms interval. Job `AS` : The job [`EC_T_USER_JOB::eUsrJob_SendAcycFrames`](api_general_functions.html.md#_CPPv4N13EC_T_USER_JOB22eUsrJob_SendAcycFramesE) schedules the transmission of acyclic frames. `Idle` : Currently implemented to wait for the next cycle, which is triggered by the timing event. ## Event notification The EC-Master provides event notification for a great number of events. These events are for example: - Bus state change - Link state change - Working counter errors - … Any thread can register for these events to be notified. This is achieved by calling the API function ### [EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) [emRegisterClient](api_general_functions.html.md#_CPPv416emRegisterClient10EC_T_DWORD12EC_PF_NOTIFYP9EC_T_VOIDP20EC_T_REGISTERRESULTS)([EC_T_DWORD](toc_api.html.md#_CPPv410EC_T_DWORD) dwInstanceID, [EC_PF_NOTIFY](api_general_functions.html.md#_CPPv412EC_PF_NOTIFY) pfnNotify, EC_T_VOID \*pCallerData, [EC_T_REGISTERRESULTS](api_general_functions.html.md#_CPPv420EC_T_REGISTERRESULTS) \*pRegResults) In case of the EcMasterDemo the class `CEmNotification` is provided. It implements the complete framework to catch and handle the EC-Master notifications. The class is instantiated once and registered at the EC-Master with the call [`emRegisterClient()`](api_general_functions.html.md#_CPPv416emRegisterClient10EC_T_DWORD12EC_PF_NOTIFYP9EC_T_VOIDP20EC_T_REGISTERRESULTS) shown above. The class implements the method `ecatNotify()` as major entry point (or callback function) for events. There are two different ways events can be handled. The method of handling an event is primarily determined by the time required to handle the event and the processing context in which the event is to be handled. The methods are described below. ### Direct notification handling Smaller events can be handled directly in the context in which they are detected. A possible example of such an event is the detection of a false work counter (WKC). The procedure is as follows: The event handling is reduced to simply issuing a log message, which is not time critical. The event is handled directly within the context of the [`emExecJob()`](api_general_functions.html.md#_CPPv49emExecJob10EC_T_DWORD13EC_T_USER_JOBP19EC_T_USER_JOB_PARMS) ( `eUsrJob_ProcessAllRxFrames`) function. ### Postponed notification handling Events that require more time-consuming processing cannot be handled directly in the context in which they are detected. The handling or processing of the event must be postponed. This is accomplished through a queue, which is also readily implemented using the `CEmNotification` class. The procedure is as follows: By calling periodically `CEmNotification::ProcessNotificationJobs()`, the application checks and handles all queued notifications. #### IMPORTANT The call of `CEmNotification::ProcessNotificationJobs()` shall NOT be executed in the `EcMasterJobTask()`. As the CPU time consumption may be high, this would have a high impact to the real-time behavior of the cyclic operation. \\newpage ## Logging The `EcMasterDemo` examples demonstrate how log messages can be processed by the application, see `Examples/Common/EcLogging.cpp`. The messages processed by `EcLogging.cpp` are of different types, e.g. EC-Master log messages, application messages, DCM messages and are logged to the console and/or files. Identical messages are skipped automatically by default. #### NOTE With some operating systems, logging in files is deactivated, e.g. because a file system is not available. ### Parameters The verbosity of the `EcMasterDemo` is specified as a `-v` command line parameter. It is used to determine the log level of the application, see `EcDemoMain.cpp`. For performance reasons the EC-Master automatically filters log messages according to [`EC_T_LOG_PARMS::dwLogLevel`](api_general_functions.html.md#_CPPv4N14EC_T_LOG_PARMS10dwLogLevelE). `EcLogging.cpp` has various parameters beside the log level, like Roll Over setting, log task prio and affinity, log buffer size, etc. See `EcMasterDemo` for reference. ### Configure EC-Master logging The EC-Master logging is configured on initialization, see [`EC_T_INIT_MASTER_PARMS::LogParms`](api_general_functions.html.md#_CPPv4N22EC_T_INIT_MASTER_PARMS8LogParmsE) in [`emInitMaster()`](api_general_functions.html.md#_CPPv412emInitMaster10EC_T_DWORDPK22EC_T_INIT_MASTER_PARMS). The application can provide customized log message handlers of type [`EC_PF_LOGMSGHK`](api_general_functions.html.md#_CPPv414EC_PF_LOGMSGHK) if the default handler in `EcLogging.cpp` does not fulfill the needs of the application. #### NOTE The callback is typically called from the context of the EcMasterJobTask and should return as fast as possible.