%% EtherCAT(R) Communication with Beckhoff(R) Analog IO Slave Devices EL3062 and EL4002
% This example shows how to communicate with EtherCAT devices using the Beckhoff(R) 
% analog I/O terminals EL3062 and EL4002. 
%
%% Requirements
% To run this example, you need an EtherCAT network that consists of the target computer as
% EtherCAT Master device and two analog input/output terminals EL3062 
% and EL4002 as EtherCAT Slave devices. This example requires 
% a dedicated network port that is reserved for EtherCAT using the Ethernet Configuration
% tool on the target 
% computer. Use the reserved port for EtherCAT communication. This
% port is in addition to the port used for the Ethernet link between 
% the development and target computers.
% 
% <<../ethercat_aioconnections.png>>
%
% To test this model:
%
% # Connect the reserved network port in the target computer 
% to the network IN port of the Beckoff(R) EK1100 coupler.
% # Assemble Terminals EL3062 and EL4002 with Coupler EK1100.
% # Loop back the I/O ports: Connect each output port of Terminal EL4002 
% to a corresponding input port of Terminal EL3062.
% # Make sure that the terminals are supplied with the required
% 24-volt power supply.
% # Build and download the model onto the target.
% 
% For a complete example that configures the EtherCAT network, configures 
% the EtherCAT master node model, and builds then runs the real-time 
% application, see <docid:slrealtime_io_ref#btrh2rf>.
%
%% Open the Model
% This model creates two sine wave signals and sends the signals to the 
% EL4002 terminal.  The model receives input signal values from the 
% EL3062 terminal.
%
% The EtherCAT initialization block requires that the configuration ENI
% file is present in the current folder. Copy the example configuration
% file from the example folder to the current folder. To open the model, 
% in the MATLAB Command Window, type:
%
open_system(fullfile(matlabroot,'toolbox','slrealtime','examples','slrt_ex_ethercat_beckhoff_aio'));  
%%
%
% *Figure 1:* EtherCAT model using Beckhoff(R) analog I/O slave 
% devices EL3062 and EL4002.
%
%% Configure the Model
% Open the mask for the *EtherCAT Init* block and observe the 
% pre-configured values.  The EtherCAT slave devices that are
% daisy chained together with Ethernet cable is a Device, also referred to 
% as an EtherCAT network.  The Device Index selects one such
% chained EtherCAT network.  The Ethernet Port Number identifies which
% Ethernet port to use to access that Device.  The EtherCAT Init block
% connects these two so that other EtherCAT blocks use the Device
% Index to communicate with the slave devices on that EtherCAT network.
%
% If you only have one connected network of EtherCAT slaves, and you have
% only reserved one Ethernet port with the Ethernet configuration tool,
% use Device Index = 0 and Ethernet Port Number = 1.
%% Create an ENI file for different A/D D/A slave devices, if needed
% If you need to create a new ENI file you need to use a third-party
% EtherCAT configurator such as TwinCAT 3 from Beckhoff that you install on
% a development computer. The EtherCAT configuration (ENI) file 
% preconfigured for this model is *BeckhoffAIOconfig.xml*.
%
% The ENI (EtherCAT Network Information) file that is provided with this
% example has an EK1100 with EL3062 and EL4002 slaves attached, in that
% order.  If you have different analog IO modules, you need to create
% a new ENI file for that collection.
%
% For an overview of the process for creating an ENI file, see 
% <docid:slrealtime_io_ref#btrgepa>.
%
% Each EtherCAT configuration file (ENI file) is specific to the exact
% network setup for which it has been created (for example, the network
% discovered in step 1 of the configuration file creation process). The
% configuration file provided for this example is valid if and only if the
% EtherCAT network consists of terminals EK1100, EL3062, and EL4002.
%
% The ENI file defines a set of transmit and receive variables. 
% For this example, a set of receive variables are defined 
% for each input channel of terminal EL3062. Make sure the 
% variables for channel 1 and channel 2 of terminal EL3102 are selected 
% respectively in the two *EtherCAT PDO Receive* blocks. These two variables are 
% |Term 2 (EL3062).AI Standard Channel 1.Value| and 
% |Term 2 (EL3062).AI Standard Channel 2.Value|.
%
% A set of transmit variables are defined for the two output channels of 
% terminal EL4002. Make sure the variables for 
% channel 1 and channel 2 of terminal EL4002 are selected  
% in the two *EtherCAT PDO Transmit* blocks. These 
% two variables are 
% |Term 3 (EL4002).AO Outputs Channel 1.Analog Output| and
% |Term 3 (EL4002).AO Outputs Channel 2.Analog Output|.
%
%% Build, Download, and Run the Model
% To build, download, and run the model:
% 
% # In the *Simulink Editor*, from the targets list on the *Real-Time* tab, 
% select the target computer on which to run the real-time application.
% # Click *Run on Target*. 
% 
% If you open the three host side scopes by double clicking each, data is 
% relayed from the target back to the development computer and displayed there.
%
% Zooming into the first quarter second of execution for this model, on all
% three of the scopes shows:
% 
% <<../aioScope.png>>
%
% Scope shows the notifications in yellow and the state in blue.  The only
% notificatons have the value of 1 which has meaning that the state has
% changed.  Each of those is aligned with a step in the state output.
% Because this ENI file does not use distributed clock synchronization, the
% progression to Op state is very fast, just over 0.1 second.  Also,
% because this ENI file does not use distributed clocks, the last 4
% elements of the vector out of the init block are all 0.
% 
% <<../aioScope1.png>>
%
% Scope1 shows the 1Hz sinewave output in yellow and the value read back by
% the A/D in blue.  Notice that there is no input until the EtherCAT state
% has progressed to Op state just after .1 seconds.  If you zoom in
% tighter, you notice that the A/D signal is delayed by several clock
% cycles from the D/A output.  This is because the A/D is read before the
% D/A is commanded to a new value and the A/D value is not available until
% the next sample time.  This D/A slave takes a signed int as input, but
% can only output in the range of [0,+10] volts so the input values only
% show positive values, even though this A/D can read inputs from [-10,+10].
%
% <<../aioScope2.png>>
%
% Scope2 shows the 2Hz sinewave sent to the second D/A channel, with the
% same delayed start on input and delayed response to a change.
%
% The second way is to build the model (rtwbuild() or ^B), download from
% the MATLAB command line and run from the command line.  In that case, the
% scope blocks do not display data, but the Simulation Data Inspector can be used.
% 
% The model is preconfigured to run for 10 seconds.  If you want to run the
% model longer, use the MODELING tab on the model editor toolstrip to
% change the Stop Time and rebuild.
%% Display the Target Computer data
% After running the model, you can also use the Simulation Data
% Inspector to view any signal that has been marked for signal logging.  
% Signals marked for signal logging have a dot with two arcs above it in the 
% model editor.
%
%% Stop and Close the Model
% When the example completes its run, stop and close the model.
% 
close_system('slrt_ex_ethercat_beckhoff_aio');
%% See Also
% 
% * <docid:slrealtime_ug#example-xpcethercatdio>
% * <docid:slrealtime_io_ref#btrh2rf>
% * <docid:slrealtime_io_ref#btrgepa>
% 
%%
% Copyright 2012-2020 The MathWorks, Inc.
