%% EtherCAT(R) Communication - Sequenced Writing Slave CoE Configuration Variables 
% This example shows how to use CoE blocks and a simple state machine to
% write configuration values to variables that can only be written before
% going to EtherCAT Op state.  For code needed to use the SoE blocks for 
% slaves that understand SoE protocol, see 
% <docid:slrealtime_ug#example-slrtethercatasyncsoesscinorder>.
%
% For slaves that understand CoE addressing, limited ability to read or
% write specific objects is somewhat rare.  For slaves that understand SoE
% addressing, this restriction is much more common.
% 
% This example also shows distributed clocks synchronization using the bus
% shift DC mode where the slaves are shifted in time to match the execution
% time of the master.
%
%% Requirements
% To run this example, you need an EtherCAT network that consists of the
% target computer as EtherCAT master device and at least one slave that
% has CoE addressed objects.  The supplied ENI file is for a 5 element
% slave stack: EK1100+EL1202+EL2202+EL3102+EL4032.
% 
% EtherCAT in Simulink Real-Time requires a dedicated network port on the
% target computer that is reserved for EtherCAT by using the Ethernet
% configuration tool. Configure the dedicated port for EtherCAT
% communication, not with an IP address. The dedicated port must be
% distinct from the port used for the Ethernet link between the development
% and target computers.
% 
% To test this model:
%
% # Connect the port that is reserved for EtherCAT in the target computer 
% to the EtherCAT IN port of the EL1100 interface.
% # Make sure the EK1100 is supplied with a 24-volt power
% source.
% # 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 illustrates how you can read or write to CoE/SDO objects if 
% they are only writable in EtherCAT PreOp state. You can move the CoE/SDO 
% transfers to EtherCAT SafeOp state by changing the *Initialization end state* 
% in the EtherCAT Init block and by also changing the constant in the 
% *Wait for this state* constant block. These settings direct the state 
% machine to start sending CoE messages when it reaches the initialization 
% end state.
%
% # Init = 1
% # PreOp = 2
% # SafeOp = 4
% # Op = 8
% 
% The EtherCAT initialization block requires that the configuration ENI
% file is present in the current folder.
%
% If you want to modify this model to experiment with it, then 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_asyncCoE_cycle'))
%%
%
% *Figure 1:* EtherCAT model for sequencing through CoE commands after
% pausing initialization at PreOp state
%% Configure the Model
% Open the parameter dialog 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 a Different Set of Slaves
% 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 |Stack4_BS_1ms.xml|.
% 
% Each ENI file is specific to the exact
% network setup from which it was 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 an EK1100+EL1202+EL2202+EL3102+EL4032. If you
% have a different set of EtherCAT slave devices this example works, but
% you need to create a new ENI file that uses your devices.
% 
% For overview of the process for creating an ENI file, see  
% <docid:slrealtime_io_ref#btrgepa>.
%
% If you use different slave devices, you need to consult the manual
% for your devices and find the CoE mapping.  Using that mapping, you need
% to change the SDO commands in the *SDO commands in order* subsystem to
% use objects on your devices.
%
%% 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 two host side scopes by double clicking each, data is 
% relayed from the target computer to the development computer and is
% displayed.
%
% Included in the model is the ability to control the amplitude of the
% cycling motion.  With the *Run on Target* button, the slider is active and
% connected to the |Amplitude| constant block.
%
% The model is preconfigured to run for 15 seconds.  If you want to run the
% model longer, pull down the *Run on Target* menu and change the number on
% the bottom line.  Press the green arrow to configure, build, and run.
%% Display the Target Computer Data
% If you run the model using the *Run on Target* button, external mode
% is connected and you can double click the scope blocks and see the data
% on the development computer.  The |Display| blocks also work.
%
% When using *Run on Target*, the *Scope* block shows the DC timing error between the
% master code on the target computer and the first DC enabled slave.  Because the
% error is returned as nanoseconds, this graph shows that the timing
% difference settles down to the order of 3-5 microseconds (3000 to 5000
% nanoseconds) difference between the DC enabled slaves and the target
% machine running the code.  The residual scatter reflects task
% scheduling variability in the target computer RTOS.
%
% <<../ecat_coe_dctiming.png>>
%
% *Scope1* shows the progression of EtherCAT states, from idle to Init to
% PreOp, SafeOp and finally Op state.  SafeOp is only entered briefly and
% only shows up as the value 4 for a few time steps before the switch to Op
% state.  Since this model uses the distributed clocks mechanism, the
% switch to Op state only occurs once the timing error settles down.
%
% <<../ecat_coe_state.png>>
%
% *Scope2* shows the status outputs of the 5 async SDO blocks inside the
% subsystem.  Each SDO block is enabled to write for one time step, then
% switches to status = 1 (busy) for a few time steps, then on successful
% completion status = 2 (done) for one time step.  If a block encounters
% an error, status = 3 (error) for one time step.  On an error, the *Cycle
% control* embedded Matlab code block stops the sequence and sets the error
% output which stops the model.  In that case, the failing block has
% output an error code that is displayed on Display1.  This display is
% zoomed into the interval just after state went to PreOp (=2) state.
%
% <<../Ecat_coe_status.png>>
%
% *Scope3* shows several of the outputs from the *Cycle control* block.
% The first 5 are the enable signals, made true one at a time by *Cycle
% control*.  Then the *oprequest* output is true for one time step to
% trigger the request to proceed to Op state.  This display is zoomed in to
% the same interval as in *Scope2*.
%
% <<../ecat_coe_triggers.png>>
%
% When the requested SDO commands are complete and the state has 
% progressed to Op state, the *done* signal is
% set to *true* for the remainder of execution.  The rest of your model
% goes into the *Op State Model* subsystem.
%
% If you need a different number of SDO commands to execute before Op
% state, you need to edit the *Cycle control* embedded MATLAB
% code block and modify the persistent array that is currently sized to
% have length 5, the same as the number of SDO commands being requesting.
%
% If you run the model from the command line, you can 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.
%
%% See Also
%
% * <docid:slrealtime_ug#example-slrtethercatasyncsoesscinorder>
% * <docid:slrealtime_ug#example-slrtethercatnotifyreset>
% * <docid:slrealtime_io_ref#btrh2rf>
% * <docid:slrealtime_io_ref#btrgepa>
% 
% Copyright 2012-2020 The MathWorks, Inc.