Technical Articles and Newsletters

Creating Test Cases to Verify Your Simulink Design Using the Signal Builder Block

By Jason Ghidella, MathWorks and Bill Aldrich, MathWorks

The Signal Builder is a source block in the Simulink library that lets you quickly develop and modify test input data that you want to incorporate with your model. You create and modify signal groups via the Signal Builder dialog editor, which also lets you view sets of inputs on a common time scale so that you can identify sequences of events and logic. The Signal Builder was first introduced with Simulink 5 and has been updated to expand its capability. This article demonstrates the Signal Builder by creating a series of test cases to test and verify an automobile cruise controller design.

Cruise Controller Design

The product example sf_cruise_control shows a cruise control system (Figure 1).

Figure 1. Cruise control example model (sf_cruise_control). Click on image to see enlarged view.

The inputs to the controller fall into two distinct categories: user and sensor inputs (Figure 2).

The user inputs are:

  • Increment (sometimes referred to as accel)—when activated, will accelerate the vehicle to a faster set speed
  • Decrement (sometimes referred to as coast)—when activated, will decelerate the vehicle to a slower set speed
  • Set—defines the speed the vehicle should maintain
  • Resume—reactivates the cruise control and returns to set speed
  • Power (on/off)—turns the cruise control on or off

The vehicle sensor inputs are:

  • Brake pedal indicator—indicates if the brake pedal has been pressed
  • Accelerator pedal position—indicates pedal angle as a percentage between 0 and 100%
  • Vehicle speed—identifies the current vehicle speed
Figure 2. The cruise control inputs and outputs.

The main output of the controller is the throttle command (Throt_cmd), which is used as a set point for the mechanical system that controls the throttle plate.

The Cruise Controller design was based on 10 high-level requirements. To ensure that the controller meets those requirements, we need to build test cases that check the design against each requirement.

Constructing the Test Cases

For the 10 requirements we need to construct test cases to prove the design meets them. However, the way that the actuator signals are modeled (Figure 3) makes it difficult, if not impossible, to test these requirements. The input blocks are all constant, and although a constant value can be changed during a simulation, it is extremely difficult to coordinate multiple changes of value, which we need to do to test the requirements.

We will use the Signal Builder block to construct all the input signals together in the same interface, on the same time scale.

Figure 3. Original input blocks for the cruise control model. Click on image to see enlarged view.

Test Case 1

The first test case addresses the startup requirement:

When the cruise control is powered on it shall enter and stay in an idle mode until a target speed is greater than 30 mph, at which point it moves to the active control mode.

We use the Signal Builder block to add multiple signals to the test case. We can select from the standard waveforms Constant, Step, Pulse, and others, and we have full control of their amplitude, frequency, and sample rates. We can also load our own custom data from the MATLAB workspace, using the custom signal option. (See the documentation for more details.)

The input signals for this first test case are relatively simple. All the user inputs are 0, and we need to set the Power to 1 at some time greater than 0 seconds. Figure 4 shows how this is done in the Signal Builder. We select the Power signal to graphically move it to the desired value (in this case, 1) and we similarly adjust the time at which this occurs (in this case, 1 second). (See the documentation for more details.)

Figure 4. Test Case 1: Adjusting the Power signal value to test Requirement 1. Click on image to see enlarged view.

Test Case 2

Requirement 1 demands that we not only test whether the controller will move into an idle mode when the power is switched on, we must also ensure that it does not move into active control if the vehicle speed is less than or equal to 30 mph. To do this, we need another test case where we set the cruise controller at or below 30 mph. Test case 2 requires the accelerator pedal input to be set to a value greater than 0 in order for the vehicle to gain speed.

It is easy to add a test case. To build Test Case 2, we copy Test Case 1 by right-clicking on the tab and selecting Copy. To modify the signals, we can select each signal and use the Signal menu Replace with option to switch the signal with another type. We can also edit the existing signal by using the Shift key in combination with the left mouse-button click to add new data points. Figure 5 shows Test Case 2. Power comes on at 1 second, the accelerator pedal is 40% from 0 to 20 seconds and then goes to 0, and the Set button is pushed at 20 seconds.

Figure 5. Requirement 1/Test Case 2: Does controller stay in idle mode when vehicle speed does not exceed 30 mph? Click on image to see enlarged view.

Test Case 3

When the Set button is depressed while the cruise control is on and the current vehicle speed is greater than 30 mph, it shall set the target speed to the current vehicle speed.

This is a similar test to Test Case 2, except the vehicle needs to go faster than 30 mph. This can be achieved by increasing the value of the accelerator pedal. In the Signal Builder, you can drag the horizontal segments up and down to set new values (Figure 6).

Figure 6. Test case for Requirement 2 is constructed by copying Test Case 1 and adjusting the accelerator pedal value from 40 to 60%. Click on image to see enlarged view.

Test Case 4

For Requirement 3, we test whether the controller will return to the target speed when the Resume button is depressed:

When the Resume button is depressed, it shall set the target speed to the last value set by the vehicle speed since the control was powered on.

Test Case 4 is derived from Test Case 3 by replacing the brake and Resume signals with pulses. We need to depress the brake pedal after the cruise controller has set the target speed, and then push the Resume button after the brake has been released. Using the Signal Builder you can drag vertical segments to new time values. Figure 7 shows Test Case 4.

Figure 7. Test Case 4/Requirement 4: Adjusting the sequence of pulses for the different inputs is easily accomplished by dragging the segments with the mouse. Click on image to see enlarged view.

This test case highlights the importance of having all input signals together on a common timescale to coordinate the sequence in which buttons and pedals are depressed and released.

Test Case 5

When the controller is in the override mode and the Set or Resume button is depressed, the controller shall return to active control.

Requirement 4 calls for two tests, where either the Set or Resume button is pressed to return the controller to active mode. Test Case 4 actually tests for the case when the Resume button is pressed, so there is no need to replicate that test. Test Case 5 uses a second pulse of the Set button to move the controller back to active mode.

To create this test case, we copy Test Case 4 and modify the Set and Resume signals. We replace the Resume signal with a constant 0 signal, and for the Set signal, we need to insert a second pulse after the brake has been released. To do this, we use the Shift key in combination with the left mouse button, and click on the signal line where we want to add addition data points. For the pulse we need to add two points. We drag the new segment up to a value of 1 (additional points are added in for us), then adjust the width. Figure 8 shows the result.

Figure 8. Test Case 5: Adding a second pulse to the Set signal. Click on image to see enlarged view.

Requirements 5–9

To test Requirements 5–9, defined in Table 1, we can construct test cases 6–10 in a similar manner to those already shown.

Req.# Definition
5 Pressing and releasing the Increment button in less than 1 second when the control is active shall cause the target speed to increase by 1 mph.
6 Holding the Increment button depressed when the control is active shall cause the target speed to increase by 1 mph every second.
7 Pressing and releasing the Decrement button in less than 1 second when the control is active shall cause the target speed to decrease by 1 mph.
8 Holding the Decrement button depressed when the control is active shall cause the target speed to decrease by 1 mph every second.
9 When the brake pedal is greater than zero and the cruise control is active, the cruise control shall enter the override mode.

Table 1. Cruise Controller Functional Requirements 5–9.

Custom Signals

We need to vary the accelerator pedal position to test Requirement 10:

When the cruise control is not actively controlling speed, the throttle position shall be set to the same value as the accelerator pedal.

We could use the built-in square, sine, or Gaussian random noise signals, but by using a custom signal we can use actual test data or use MATLAB to construct a sophisticated signal.

We copy Test Case 1 and replace the Power signal with a constant 0 and the accelerator pedal signal with a custom signal. The custom signal is created with the MATLAB script create_custom_data.m, which adds a sin wave, cos wave, and Gaussian noise with a constant offset. Figure 9 shows how you import custom data into the Signal Builder.

Figure 9 also illustrates how signals can be hidden. As the accelerator pedal is the only signal with nonzero values, we choose to focus the display by hiding the other signals. You toggle the visibility of the signals by double-clicking their names in the list at the bottom right corner.

Figure 9. Accelerator pedal signal constructed in MATLAB and loaded into the Signal Builder using the custom waveform signal. Click on image to see enlarged view.

Command Line API

The Signal Builder command line API, added in Simulink 6, provides further customization and automation possibilities beyond the custom signal support. You can use the API to read signal data, signal labels, and group labels into the MATLAB workspace. You can automatically create one or more signals and automatically add one or more groups. You can define individual signal values in a specific signal group using the set and get commands.

The API function is contained in the MATLAB command signalbuilder. As this function is invoked from MATLAB it can be incorporated into scripts that automatically create and modify Signal Builder blocks based on any data available in the workspace.

You can get more information about the API from the command line help:

>> help signalbuilder

Running the Tests

We can run individual test cases by pushing the Play button on either the Signal Builder or the Simulink model itself; this will run the currently selected Test Case group. We can run through all the tests by pressing the Play all button on the Signal Builder.

You can also access the Signal Builder programmatically from MATLAB through the Signal Builder command line API (as described in the previous section). You can create MATLAB scripts to select test cases and run each of them, collecting and post-processing results as you go.

To assess if the design has passed or failed the test, we can use the Verification blocks in the Simulink library, or we can compare the outputs in MATLAB by writing a script. However, we still need to evaluate whether we have created enough test cases to test all the requirements, whether the requirements are described in enough detail to describe the design, or whether we have tested all of the design. Simulink Verification and Validation (transitioned at R2017b) can enhance the functionality of the Verification blocks, link the test cases to the requirements, and measure how well the test cases have tested the design.

Published 2005