%% Generate ENI Files for EtherCAT(R) Devices
% This example shows how to generate EtherCAT network information (ENI) 
% files to use in Simulink(R) Real-Time(TM) with EtherCAT devices.
%
% The example shows the generation process steps in EtherCAT Configurator 
% and the process steps in the TwinCAT XAE plugin for Microsoft Visual
% Studio(R).
%  
% The hardware connections are:
% 
% * EK1100 -- EtherCAT coupler
% * EL3062 -- EtherCAT terminal
% * EL4002 -- EtherCAT terminal
% * EL9011 -- Bus End terminal
% 
% The EK1100 coupler connects EtherCAT with the EtherCAT terminals (ELxxxx). 
% One station consists of an EK1100 coupler, any number of EtherCAT terminals, 
% and a bus end terminal.
% 
% To provide power connections, connect the 24 V and 0 V terminals of the EK1100 
% to a 24 V regulated power supply (RPS) +Ve and -Ve terminals.
% 
% The EL3062 analog input terminal processes signals in the range of [-10, 10] V. 
% 
% The EL4002 analog output terminal generates signals in the range of [0, 10] V.
%
% To configure the EtherCAT network, connect the EtherCAT devices to the development computer 
% on which the EtherCAT configurator is running. This connection permits scanning 
% and discovery of the EtherCAT devices. After the configurator generates the XML 
% file, you can reconnect the EtherCAT devices to the target computer. This diagram 
% shows the suggested connections.
%
% <<../ethercat_connections_eni.png>>
%

%% Install TwinCAT 3.1 XAE and Run Microsoft Visual Studio(R) with TwinCAT
% The latest version of TwinCAT is the 3.x version and that is the preferred
% configuration tool.
%
% The XAE sub version does not contain the full run time engine that runs
% on Windows.  This is available free of charge from the Beckhoff web site.
% For use with Simulink Real-Time, you do not need the run time engine
% because you are using the run time implementation on the target.  The full
% version with run time engine requires the purchase of a license from
% Beckhoff.
%
% The TwinCAT 3.1 software requires a supported version of Microsoft Visual
% Studio to be installed.  TwinCAT 3.1 uses the MSVC GUI integration and
% does not have a GUI by itself. The versions of MSVC with which a given version
% of TwinCAT works are discussed in the TwinCAT documentation.
% Installation finds supported MSVC versions on your machine and installs
% to them.
%
% To install the TwinCAT 3.1 XAE:
% 
% # Go to <https://www.beckhoff.com/ www.beckhoff.com> and select *Download*.
% # Select TwinCAT 3 and download the setup.
% # Install TwinCAT 3.
% # Start Microsoft Visual Studio. 
% # From the *TwinCAT* menu, select *Show Realtime Ethernet Compatible Devices*.
% # Select the Ethernet adapter for your EtherCAT device, then select *Install*.
% 
% Because TwinCAT installs an Ethernet filter inline with the Ethernet port
% you have selected, it is good practice to add an extra Ethernet port to
% use exclusively with EtherCAT to avoid any possible problem the filter
% can cause when sharing the Simulink Real-Time host-target communication
% port with TwinCAT.
%
% All EtherCAT configuration programs use EtherCAT Slave Information (ESI) files
% to describe the slaves that are found on the network.  These Beckhoff
% configuration programs come prepopulated with mostly Beckhoff devices.
% To correctly configure an EtherCAT network with devices from other
% manufacturers, you may need to get the correct ESI file from the device
% manufacturer web site.  If you do not have an ESI file for a slave on your
% network, the scan process does not populate the Solution Explorer with
% the correct name of the device and the read and write variables are not
% correct.
%
% To create a new TwinCAT project in Visual Studio:
% 
% # Start Visual Studio. Go to *File > New > Project*.
% # Under *Installed*, select *TwinCAT Projects* and click *OK*.
% # Verify whether the project has been created successfully in the status
% bar of Microsoft Visual Studio.
% # Enter your license if this instance is the first time that you are
% using TwinCAT and you installed the full version. If you are using
% TwinCAT in evaluation mode, fill in the Captcha.
% # Observe the *Solution Explorer* pane the left side of Visual Studio.
% # Go to *TWINCAT* in the menu and select *Scan*. You can also right click
% *Solution Explorer > your TwinCAT project > I/O > Devices > Scan*.
% # A dialog box opens with the message *All devices may not automatically
% be found*. Click *OK* and wait for the scan to complete. You now see a
% dialog box saying *New I/O devices have been found*.
% # Ensure that the check box is selected, then click *OK*. A dialog box
% appears with a *Scan for boxes?* message. Click *Yes*. The EtherCAT
% devices in your network are scanned, and the devices appear.
% # You see a dialog box that asks whether to activate free run mode. Select *No*.
% # Observe the Solution Explorer and verify that the devices were scanned correctly. 
%
% When you first start TwinCAT the right information panel is not displayed.
% You need to double-click any item in the tree view the first time.  After
% that the information dialog for any item is displayed by a single click
% on that item in the *Solution Explorer* tree view.
% 
% <<../msvc_solutions_explorer_01.png>>
% 
%% Configure EtherCAT Master Node Data with TwinCAT
% To configure the EtherCAT master node, create and configure a task, then add the inputs and outputs to the task.
% 
% To create an EtherCAT Task:
% 
% # In the *Solution Explorer*, right-click the *Tasks* node and select
% *Add New Item*.
% # In the *Insert Task* dialog box, select *TwinCAT Task With Image*,
% provide a name for the task, and click *OK*.
% # Select the task that you created. The value *Cycle Ticks*
% determines the cycle time as a multiple of the *Base Time* determined on
% the *Real-Time* item. The default task time is set to 10 ms.  If you
% are using Distributed Clock synchronization, a task time of 1-2 ms is the
% slowest that works with Master Shift DC mode.
% # Create at least one cyclic input/output task. Link this task to at
% least one input variable and one output variable on each slave device.
% # If you want to run faster than 1ms time, you need to change the base
% time on the *Real-Time* item above *Tasks*.  On the *Settings* tab, you
% need to change the *Base Time* selection to a faster one.
% 
% By using distributed clocks (DC), the EtherCAT protocol can synchronize
% the time in all local bus devices within a narrow tolerance range. Only
% some EtherCAT devices support DC. It is important that if a device
% supports DC, you configure it accordingly. For example, in the example
% configuration, the EL4002 supports DC.  Most motion controllers (motor
% drives) support DC and some require it to get to Op state.
% 
% To configure EtherCAT DC:
% 
% Enable DC and choose *Bus shift* or *Master shift* DC mode.
%
% # Click on the *Device n (EtherCAT)* node
% # Select the *EtherCAT* tab in the information panel.
% # Click on *Advanced Settings* which opens a new dialog.
% # In the *Advanced Settings* dialog, select the *Distributed Clocks*
% page.
% # By default the *Automatic DC Mode Selection* box is checked, which 
% generally gets you Master Shift DC mode.  The first DC enabled slave is
% the reference clock and the Simulink Real-Time execution time is
% shifted slightly to align execution with the reference clock.
% # Deselect the *Automatic* mode and you have control over which DC mode to
% use or to turn it off.  Next items are with *Automatic* deselected.
% # With *DC in use* deselected, no Distributed clock synchronization 
% takes place.  This results in much quicker initialization time to get to
% Op state, but there is no synchronization between slaves.
% # With *DC in use* selected, you have two different synchronization
% methods between the Speedgoat target machine and the EtherCAT slaves.
% # *Independent DC Time* uses the first DC enabled slave as the reference
% clock and the target machine clock is adjusted slightly to phase lock
% model execution to the first DC enabled slave.
% # *DC Time controlled by TwinCAT Time* should be read as *controlled by
% target machine time* in Simulink Real-Time.  This is bus shift mode where
% the target machine is the reference clock and the slave execution times
% are shifted slightly to phase lock to the target machine.
% # Select both *Continuous Run-Time Measuring* and *Sync Window
% Monitoring*.
%
% Now that you have chosen the DC mode to use, you can visit all of the DC
% enabled slaves in your network and set them to the correct mode.  This
% example ENI file only supports one DC enabled slave, the EL4002.
%
% # Click the node *Term 3 (EL4002)* and select the *DC* tab. 
% # By default, the *Operation Mode* is set to *SM-Synchron* which does not
% synchronize output to DC time. Change the *Operation Mode* to *DC-Synchron*.
% Different slaves have different names for the operating mode.
% # Click *Advanced Settings* and set the *Distributed Clock* options as shown.
% 
% <<../msvc_io_device_dc_advanced_01.png>>
% 
% To export and save the EtherCAT configuration, generate the ENI file:
% 
% # Click the node for your EtherCAT device and click the *EtherCAT* tab. 
% # Click *Export Configuration File*.
% # In the *Save As* dialog box, enter an XML file name, such as
% |simple_adda_eni.xml|, then click *Save*. This XML file is the ENI file.
% The ENI file and the Simulink Real-Time model that uses the ENI
% file cannot have the same name. They must have different names.
% # When you close the TwinCAT project, the editable version of this
% configuration is saved in the project file.  You can modify the
% configuration by opening this project and by exporting to XML again.
%
%% Install and Run EtherCAT Configurator ET9000
% To install the EtherCAT configurator ET9000:
% 
% # Go to <https://www.beckhoff.com/ www.beckhoff.com> and select *Download*.
% # Select ET9000 and download the setup.
% # Install the ET9000 configurator and start the software. 
% # Run the configurator and select the correct license keys or select the evaluation option.
%
% The EtherCAT configurator creates an EtherCAT network information (ENI) file from the standardized 
% slave description files (ESI - EtherCAT slave information). To generate the ESI files for the slaves:
% 
% # Start the ET9000 software. 
% # Right-click *I/O Devices* and select *Scan Devices*. Click *OK*.
% # Select the correct network interface card (NIC) in your system and click *OK*.
% # When the dialog box asks whether to scan for boxes, select *Yes*. As the EtherCAT devices in your network are scanned, they appear in the *System Pane*.
% # When the dialog box asks whether to activate free run mode, select *No*.
% 
% When the scan is complete, expand the tree under *Devices* in the *I/O*. 
% The EL3062 and the EL4002 devices appear under the EK1100 device.
% 
% <<../et9000_io_device_hierarchy_01.png>>
% 
%% Configure EtherCAT Master Node Data with Configurator
% The configurator uses the ESI to configure the EtherCAT master node. This operation 
% includes creating a task, configuring the task, and adding the I/O to the task.
% 
% To create an EtherCAT task:
%
% # Under *SYSTEM - Configuration*, right-click *Additional Tasks > Append Task*.
% # Provide a name for the task and click *OK*. In this example, the name
% of the task is |slrt_task|.
% # Click the task. The value *Cycle Ticks* determines the cycle time. In
% the settings, it is set to |10ms|.
% 
% To configure an EtherCAT task outputs:
% 
% # Click and drag the node *Analog output* (under *AO Outputs Channel 1*)
% to *Outputs* (under |slrt_task|).
% # Select *Analog output* (under *Outputs*) and select the *Variable* tab. 
% # Click the *Linked to* button and select the corresponding entry
% (*Analog Output* under *AO Outputs Channel 1* under *Term 3*).
% 
% By using distributed clocks (DC), the EtherCAT real-time Ethernet
% protocol can synchronize the time in all local bus devices within a
% narrow tolerance range. Only some EtherCAT devices support DC. When the
% device supports DC, it is important to configure a device for DC. For
% example, in the example configuration, the EL4002 supports DC. To
% configure the EL4002 for DC:
%
% # Click *Term 3 (EL4002)* in the *System Pane* and select the *DC* tab. By default, the *Operation Mode* is set to *SM-Synchron*. Change Operation Mode to *DC-Synchron*.
% # Click the *Advanced Settings* button and set the *Distributed Clock* options as shown.
% 
% <<../et9000_io_device_dc_advanced_01.png>>
%
%% Import a Device with the Configurator
% Device import is often part of the workflow for third-party (different manufacturer) devices. 
% Use this process to configure a device that is not present in the Beckhoff system. 
% Numerous motors and their drives fall under this category. Sometimes, you must configure a 
% device that is not present in the Beckhoff system. The TwinCAT EtherCAT master or System Manager 
% uses the device description files for the devices to generate the configuration in online 
% or offline mode. 
% 
% The device descriptions are contained in ESI files (EtherCAT Slave Information) in XML format. 
% These files can be requested from the respective manufacturer and are made available for 
% download. An XML file can contain several device descriptions.
% 
% The ESI files for Beckhoff EtherCAT devices are available on the Beckhoff website and are 
% stored in the TwinCAT installation folder. The default for TwinCAT2 is |C:\TwinCAT\IO\EtherCAT|. 
% The files are read (once) when you open a new System Manager window and if they have changed 
% since the last time that you opened the System Manager window. 
% 
% If using a TwinCAT configurator, the TwinCAT installation includes the set of Beckhoff ESI files 
% which were current at the time when the TwinCAT build was created. For TwinCAT 2.11, TwinCAT 3, 
% and later, you can update the ESI folder from the System Manager if the programming PC is 
% connected to the Internet (*Option > Update EtherCAT Device Descriptions*).
% 
% To import a device from an ESI file:
% 
% # For the ET9000 Configurator, the ESI folder is |C:\Program Files (x86)\EtherCAT Configurator\EtherCAT|. Paste the file from the manufacturer into this location.
% # After adding the XML file, restart your configurator and select *Actions > Reload Devices*.
% # If the device is connected, you can scan again to add the devices. (See <#3 Install and Run EtherCAT Configurator ET9000>.)
% # If the device is not connected, you can also add the device in Offline
% mode. If you want to add the device to the same term, right-click your device in the hierarchy and select *Append Box*. A dialog box appears asking which device to add.
% # Click the square icon next to Beckhoff Automation GmbH to collapse the hierarchy. You now see the manufacturer whose devices you added.
% # Select the device that you want to add and click *OK*. Your device should now appear in the *System Pane* on the left.
% # Repeat the steps under *Configure EtherCAT Master Node Data* to add the Outputs to your task. In this example, drag the available outputs under your drive to *Outputs* under |slrt_task|. Remember to make the appropriate DC Configurations for your device.
% # DC configuration information is available from the manufacturer. In this case, enable DC.
% # Continue with configuration of the terminals.
% 
%% Export and Save the EtherCAT Configuration with the Configurator
% To generate the ENI file and save the configuration:
% 
% # Click the node for your EtherCAT device, then click the *EtherCAT* tab.
% # Click *Export Configuration File*.
% # In the file save dialog box, enter an XML file name, such as |BeckhoffAIOconfig.xml| for this example, and then click *Save*. This XML file is the ENI file. The ENI file and the Simulink(R) Real-Time(TM) model that uses the ENI file cannot have the same name. They must have different names.
% # Save the configuration as an ESM file. Click *File > Save*. If the ESM file corresponding to the ENI file is not present, the Beckhoff ET9000 program cannot open the ENI file. 
% # In the *File Save* dialog box, enter an ESM file name, such as |et9000config.esm|, and then click *Save*.
% 
%% See Also
%
% * <docid:slrealtime_io_ref#btrh2rf>
% * <docid:slrealtime_io_ref#btrgepa>
% * <docid:slrealtime_io_ref#btrjvz_>
%
% Copyright 2018-2020 The MathWorks, Inc.