Waterfall Tasks

Scope Trigger Function

The diagram below explains the different states of the Waterfall scope triggering process.

You can create custom scope trigger functions to control when the scope starts, stops, or begins waiting to capture data.

These functions must be valid MATLAB^® functions and be located either in the current folder or on the MATLAB path.

Each scope trigger function must have the form

y = functionname(blk,t,u),

where functionname refers to the name you give your scope trigger function. The variable blk is the Simulink^® block handle. When the scope trigger function is called by the block, Simulink automatically populates this variable with the handle of the Waterfall block. The variable t is the current simulation time, represented by a real, double-precision, scalar value. The variable u is the vector input to the block. The output of the scope trigger function, y, is interpreted as a logical signal. It is either true or false:

• Begin recording scope trigger function

  • When the output of this scope trigger function is true, the Waterfall block starts capturing data.

  • When the output is false, the block remains in its current state.

• Stop recording scope trigger function

  • When the output of this scope trigger function is true, the block stops capturing data.

  • When the output is false, the block remains in its current state.

• Re-arm trigger scope trigger function

  • When the output of this scope trigger function is true, the block waits for a triggering even to begin recording again.

  • When the output is false, the block remains in its current state.

    Note

    The Waterfall block passes its input data directly to the scope trigger functions. These functions do not use the transformed data defined by the Transform parameters.

The following function is an example of a scope trigger function. This function, called trigPower, detects when the energy in the input u exceeds a certain threshold.

function y = trigPower(blk, t, u)

y = (u'*u > 2300);

The following function is another example of a scope trigger function. This function, called count3, triggers the scope once three vectors with positive means are input to the block. Then the function resets itself and begins searching for the next three input vectors with positive means. This scope trigger function is valid only when one Waterfall block is present in your model.

function y = count3(blk, t, u)

persistent state;
if isempty(state); state = 0; end
if mean(u)>0; state = state+1; end
y = (state>=3);
if y; state = 0; end

Scope Transform Function

You can create a scope transform function to control how the Waterfall block transforms your input data. This function must have a valid MATLAB function name and be located either in the current folder or on the MATLAB path.

Your scope transform function must have the form

y = functionname(u)

where functionname refers to the name you give your function. The variable u is the real or complex vector input to the block. The output of the scope transform function, y, must be a double-precision, real-valued vector. When it is not, the simulation stops and Simulink displays an error. Note that the output vector does not need to be the same size as the input vector.

Exporting Data

You can use the Waterfall block to export data to the MATLAB workspace:

1. Open and run the dspanc example in Acoustic Noise Cancellation (LMS).

2. While the simulation is running, click the Export to Workspace button.

3. Type whos at the MATLAB command line.

   The variable ExportData appears in your MATLAB workspace. ExportData is a 40-by-6 matrix. This matrix represents the six data vectors that were present in the Waterfall window at the time you clicked the Export to Workspace button. Each column of this matrix contains 40 filter coefficients. The columns of data were captured at six consecutive instants in time.

   You can control what data is exported using the Data logging parameter on the Data history tab of the Parameters dialog box. For more information, see Data History.

Capturing Data

You can use the Waterfall block to interact with your data while it is being captured:

1. Open and run the dspanc example in Acoustic Noise Cancellation (LMS).

2. While the simulation is running, click the Suspend data capture button.

   The Waterfall block no longer captures or displays the data coming from the Downsample block.

3. To continue capturing data, click the Resume data capture button.

4. To freeze the data display while continuing to capture data, click the Snapshot display button.

5. To view the Waterfall block that the data is coming from, click the Go to scope block button.

   In the Simulink model window, the Waterfall block that corresponds to the active Waterfall window flashes. This feature is helpful when you have more than one Waterfall block in a model and you want to clarify which data is being displayed.

Linking Scopes

You can link several Waterfall blocks together in order to capture the effect of a model event in all of the Waterfall windows in the model:

1. Open the dspanc example in Acoustic Noise Cancellation (LMS).

2. Drag a second Waterfall block into the example model.

3. Connect this block to the Output port of the LMS Filter block as shown in this figure:

   

4. Run the model and view the model behavior in both Waterfall windows.

5. In the dspanc/Waterfall window, click the Link scopes button.

6. In the same window, click the Suspend data capture button.

   The data capture is suspended in both scope windows.

7. Click the Resume data capture button.

   The data capture resumes in both scope windows.

8. In the dspanc/Waterfall window, click the Snapshot display button.

   In both scope windows, the data display freezes while the block continues to capture data.

9. To continue displaying the captured data, click the Resume display button.

Selecting Data

1. To select a particular set of data, click the Select button.

2. Click on the Time Bar at the bottom right of the axes to select a vector of data.

   The Waterfall block highlights the selected trace.

   

   While the simulation is running, in the bottom right corner, the Waterfall window displays the relative index of the selected trace. For example, in the previous figure, the selected vector is two sample times away from the most current data vector. When the simulation is stopped, the Waterfall window displays both the relative index and the simulation time associated with the selected trace.

3. To deselect the data vector, click it again.

4. Click-and-drag along the Time Bar.

   Your selection follows the movement of the pointer.

You can use this feature to choose a particular vector to export to the MATLAB workspace. For more information, see Data History.

Zooming

You can use the Waterfall window to zoom in on data:

1. Click the Zoom camera button.

2. In the Waterfall window, click and hold down the left mouse button.

3. Move the mouse up and down and side-to-side to move closer and farther away from the axes.

4. To resize the axes to fit the Waterfall window, click the Fit to view button.

Rotating the Display

You can rotate the data displayed in the Waterfall window:

1. Click on the Orbit camera button.

2. In the Waterfall window, click and hold down the left mouse button.

3. Move the mouse in a circular motion to rotate the axes.

4. To return to the position of the original axes, click the Restore scope position and view button.

Scaling the Axes

You can use the Waterfall window to rescale the y-axis values:

1. Open and run the dspanc example in Acoustic Noise Cancellation (LMS).

2. Click the Rescale amplitude button.

   The y-axis changes so that its minimum value is zero. The maximum value is scaled to fit the data displayed.

Alternatively, you can scale the y-axis using the Y Min and Y Max parameters on the Axes tab of the Parameters dialog box. This is helpful when you want to undo the effects of rescaling the amplitude. For more information, see Axes.

Saving Scope Settings

The Waterfall block can save the screen position and viewpoint of the Waterfall window:

1. Click the Save scope position and view button.

2. Close the Waterfall window.

3. Reopen the Waterfall window.

   It reopens at the same place on your screen. The viewpoint of the axes also remains the same.