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.
The product example
sf_cruise_control shows a cruise control system (Figure 1).
The inputs to the controller fall into two distinct categories: user and sensor inputs (Figure 2).
The user inputs are:
The vehicle sensor inputs are:
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.
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.
The first test case addresses the startup requirement:
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.)
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.
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).
For Requirement 3, we test whether the controller will return to the target speed when the Resume button is depressed:
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.
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.
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.
To test Requirements 5–9, defined in Table 1, we can construct test cases 6–10 in a similar manner to those already shown.
|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.
We need to vary the accelerator pedal position to test Requirement 10:
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.
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
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
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.