|On this page…|
Simulink® provides an application programming interface, called the block run-time interface, that enables programmatic access to block data, such as block inputs and outputs, parameters, states, and work vectors, while a simulation is running. You can use this interface to access block run-time data from the MATLAB® command line, the Simulink Debugger, and from Level-2 MATLAB S-functions (see Write Level-2 MATLAB S-Functions).
Note You can use this interface even when the model is paused or is running or paused in the debugger.
The block run-time interface consists of a set of Simulink data object classes (see Data Objects) whose instances provide data about the blocks in a running model. In particular, the interface associates an instance of Simulink.RunTimeBlock, called the block's run-time object, with each nonvirtual block in the running model. A run-time object's methods and properties provide access to run-time data about the block's I/O ports, parameters, sample times, and states.
Every nonvirtual block in a running model has a RuntimeObject parameter whose value, while the simulation is running, is a handle for the blocks' run-time object. This allows you to use get_param to obtain a block's run-time object. For example, the following statement
rto = get_param(gcb,'RuntimeObject');
returns the run-time object of the currently selected block. Run-time object data is read-only. You cannot use run-time objects to change a block's parameters, input, output, and state data.
Note Virtual blocks (see Virtual Blocks) do not have run-time objects. Blocks eliminated during model compilation as an optimization also do not have run-time objects (see Block reduction). A run-time object exists only while the model containing the block is running or paused. If the model is stopped, get_param returns an empty handle. When you stop a model, all existing handles for run-time objects become empty.
One application for the block run-time API is to collect diagnostic data at key points during simulation, such as the value of block states before or after blocks compute their outputs or derivatives. The block run-time API provides an event-listener mechanism that facilitates such applications. For more information, see the documentation for the add_exec_event_listener command. For an example of using method execution events, enter
at the MATLAB command line. This Simulink model contains the S-function adapt_lms.madapt_lms.m, which performs a system identification to determine the coefficients of an FIR filter. The S-function's PostPropagationSetup method initializes the block run-time object's DWork vector such that the second vector stores the filter coefficients calculated at each time step.
In the Simulink model, double-clicking on the annotation below the S-function block executes its OpenFcn. This function first opens a figure for plotting the FIR filter coefficients. It then executes the function add_adapt_coef_plot.madd_adapt_coef_plot.m to add a PostOutputs method execution event to the S-function's block run-time object using the following lines of code.
% Get the full path to the S-function block blk = 'sldemo_msfcn_lms/LMS Adaptive'; % Attach the event-listener function to the S-function h = add_exec_event_listener(blk, ... 'PostOutputs', @plot_adapt_coefs);
The function plot_adapt_coefs.m is registered as an event listener that is executed after every call to the S-function's Outputs method. The function accesses the block run-time object's DWork vector and plots the filter coefficients calculated in the Outputs method. The calling syntax used in plot_adapt_coefs.m follows the standard needed for any listener. The first input argument is the S-function's block run-time object, and the second argument is a structure of event data, as shown below.
function plot_adapt_coefs(block, eventData) % The figure's handle is stored in the block's UserData hFig = get_param(block.BlockHandle,'UserData'); tAxis = findobj(hFig, 'Type','axes'); tAxis = tAxis(2); tLines = findobj(tAxis, 'Type','Line'); % The filter coefficients are stored in the block run-time % object's second DWork vector. est = block.Dwork(2).Data; set(tLines(3),'YData',est);
You can use run-time objects to obtain the value of a block output and display in the MATLAB Command Window by entering the following commands.
rto = get_param(gcb,'RuntimeObject') rto.OutputPort(1).Data
However, the displayed data may not be the true block output if the run-time object is not synchronized with the Simulink execution. Simulink only ensures the run-time object and Simulink execution are synchronized when the run-time object is used either within a Level-2 MATLAB S-function or in an event listener callback. When called from the MATLAB Command Window, the run-time object can return incorrect output data if other blocks in the model are allowed to share memory.
To ensure the Data field contains the correct block output, open the Configuration Parameters dialog box, and then clear the Signal storage reuse check box on the Optimization > Signals and Parameters pane (see Signal storage reuse ).