Newsletters - MATLAB Digest
Making Your Own Multiport Simulink Blocks with CMEX S-functions
Have you ever needed to implement some action in Simulink® but found that the built-in blocks did not do exactly what you wanted? As you become more familiar with Simulink, you will find that S-functions are often the solution. This article will introduce you to some of the basics of S-functions. At the same time, it will look at a simple example of a multiport S-function.
Introduction
Like M-files in MATLAB® programming, S-functions have a wide range of uses, from creating custom animations, to including legacy C code in your model and programming complex behavior. S-functions are not ideal for every situation; usually, if you can do something easily using built-in blocks, you should. However, learning to write S-functions can add new and interesting behavior to your Simulink models.
S-functions can be written in M-code, C code, or Fortran. We will focus on C code, but the same principles apply to both M-code and Fortran. Specifically, we will look at one of the new features of C S-functions, multiple input and output ports on the S-function block. Our S-function will be a modified Gain block. Although we could implement this S-function with built-in blocks, it provides an instructive example of the functionality of S-functions.
C code or CMEX S-functions are unique in that they allow full integration with Real-Time Workshop® to create embeddable C code from your entire model. CMEX S-functions also allow you to include legacy C code into your model by creating a wrapper S-function.
CMEX S-functions are written in C and then compiled using the MEX command in MATLAB to make a MEX-file (MATLAB executable). More instructions on using the MEX command can be found in the Application Program Interface Guide, and a list of supported compilers can be found in Technical Note 1601: Which Compilers Are Supported?.
Several examples and templates of the different types of S-functions not discussed in this article are available in the MATLAB directories $MATLAB/toolbox/simulink/blocks (for M-files) and $MATLAB/simulink/src (for C and Fortran). Extensive documentation for creating S-functions is available in Chapter 8 of the online version of Using Simulink.
S-function Structure
When writing S-functions, it is important to remember the way Simulink works internally. The Simulink diagram you create is represented as an internal mathematical system. The system then communicates with the Simulink solvers to step through time with the appropriate responses.
S-functions communicate directly with the Simulink solver. The solver and S-function set up a dialog, exchanging information back and forth to one another. Different subroutines, or flags, determine the kind of information they exchange. The actual variable named flag is used within M-file S-functions; CMEX and FMEX S-functions use corresponding subroutines for each of the flags.
Six different flags, such as mdlInitialSizes(flag = 0) and mdlOutputs(flag = 3), are called during a conversation between the solver and the S-function. Each of the flags and their uses is documented in the above mentioned template files and in Using Simulink.
You can see a graphical description of how each of these flags and subroutines is used in your S-function. The template S-functions are a good place to look for the general structure of S-functions. For example, the C template file sfuntmpl.c.
Creating the Multiport Block
Our example will be a new Gain block that has three inputs and multiplies each by a different number. Since we are doing a simple input/output routine, we only need to handle two of the flags: initialization and outputs. After understanding this basic input/output S-function, you may want to look at the examples in the aforementioned directories and documentation that deal with the idea of states and show more advanced usage of the different flags.
We can create S-functions with multiple input and output ports by using the macros ssSetNumInputPorts and ssSetNumOutputPorts within the mdlInitializeSizes routine.
We will start out by creating a block that takes three inputs. The block will multiply the first input by two, the second input by three, and the third input by four.
The S-function is named sfun_mult234.c. Take a look at this file; the comments provide a more in-depth description of how the S-function was created. Also notice that we have just modified the basic template S-function for our desired behavior. Using sfuntmpl.c helps to avoid syntactical mistakes.
After using the MEX command to generate a MEX-file from your S-function (at the MATLAB command prompt type mex sfun_mult234.c), you can run the code using the S-function block from the Nonlinear library in a model like this:
Additional Parameters
We can now add parameters to make the block more flexible. In the following code, we have slightly modified our block to accept two parameters, a gain and an offset. For example, if gain = 3 and offset = 2, then our block multiplies the first input by 3, the second by 5, and the third by 7. A gain of 2 and an offset of 5 would multiply the first input by 2, the second by 7, and the third by 12.
As in the previous example, the commented code for this S-function is included in sfun_mult234go.c.
Note the use of SFcnParams to handle the new parameters in the block.
Compile this new S-function using MEX, and you can now run this block in a model such as:
Using Masks to Customize the Look
Now we can use Masks to develop an interface for our new block. We can mask the S-function block directly with the following steps:
- Select the S-function block by single-clicking on it.
- Type set_param(gcb,'mask','on') at the MATLAB command prompt.
- Select Edit Mask from the Edit pulldown menu.
This will bring up the mask dialog box where we can define our mask. See Chapter 6 of Using Simulink for details on how to mask blocks. Below is an example of what our mask block may look like. In this example block, if we change the gain and offset to 2 and 4 respectively, then the block appearance changes. The values 2x, 6x, and 10x will appear as inputs.
You can download this mask example here. After opening the model in Simulink, click on the Help button of this block for more details on how this mask was created.
Conclusion
This article outlined the basics of writing a simple input/output routine as an S-function block with multiple ports. In this example, we created a simple gain, but we could easily have included any other type of calculations in the mdlOutputs section of the code. S-functions can become much more complex than this, but the underlying concepts remain the same. These general guidelines will help you in your S-function writing:
- Use the template files to ensure proper syntax.
- Use the examples and online documentation provided.
- Keep track of which flags you need for your simulation.
You can use the Technical Support Solution Search Engine as a resource for any questions which may arise.
Training is also available from The MathWorks on selected products, including Simulink and S-functions. For more information on training, send e-mail to training@mathworks.com.
Good luck in your S-function writing!
