This almost never happens, but today I get to share with you an undocumented Simulink capability! In R2009a the S-function builder has the ability to accept bus signals at its input and output ports.  We accidentally omitted the updated doc section when R2009a shipped.  You can find the missing documentation here, but I still want to tell you about how to use bus signals with S-function Builder.

What is an S-function?

If you want to build your own custom block in Simulink, we provide a couple ways to do it.  For now, I am going to ignoring masked subsystems and reference models and focus on block authoring in the truest sense, the S-function.  The "S" in S-function stands for System (or maybe Simulink).  S-functions define how a block works during the different parts of the simulation, for example: initialization, update, derivatives, outputs, and termination.  S-function are often used as a gateway to other simulation environments, interfaces to hardware or software.  There are a few ways to implement an S-function, such as using an M-file or a C-MEX file.   There are also tools like the S-function Builder Block and the Legacy Code Tool to make it easier to write S-functions.

The S-function must define itself as a system.  You have to define the interfaces and algorithm for the system.  The interfaces to the system are the ports and parameters of the block.  For a long time, users have asked for the ability to write an S-function that accepts a bus signal as the input, or provides a bus signal as the output.  This is the capability added in R2009a for the S-function Builder.

S-functions and Bus Signals

In January 2005, Tom Erkkinen posted the Legacy Code Tool (LCT) to the MATLAB Central File Exchange.  The Legacy Code Tool helps you integrate existing C functions into your Simulink model by generating an S-function.  LCT has been shipping with Simulink since R2006b.  One of the major capabilities of LCT is the ability to interface to bus signals.  If your function requires a structure input or returns a structure output, LCT can generate the wrapper S-function that handles a bus signal.

S-function Builder Bus Support

I think the S-function Builder block is the easiest way to bring a short C code algorithm into your Simulink model.  New in R2009a, the S-function Builder block now supports bus signals for the input and output ports.  There is a demo model called sfbuilder_bususage.  Here is how it works:

The S-function builder works like many software wizards, and leads you through the process of writing an S-function.  When you double click on the S-function builder block, you get a GUI that looks like this.

If you start on the left most tab, add information in each tab, by the time you have reach the last tab, you are done.  To include a bus input in the S-function builder, you need to define a bus object.  In a previous post, I talked about how to do use bus objects as interface specifications.  The Data Properties tab defines all the information for the ports of the S-function.  First, you have to define the inputs and outputs of your system.

To include a bus, turn the Bus property ON, and se the Bus Name to the bus object in the base workspace.  Next, you have to access elements of the bus using standard C structure indexing.  Here is a snippet from Outputs function that accesses signals from the bus.

That is all there is to it.  The bus object can optionally include a C header file that defines the C structure definition for the bus. You can specify this in the Bus Editor:

If you include the header file in your bus object, the S-function builder will use it.  If you don’t specify the header file, the S-function builder will generate one for you that looks like this:

Wait a second, why isn’t this in the doc?

It was just an oversight.  There were many changes made to the doc, and we forgot to include this one.  Luckily, when we realized the doc was not complete, technical support came to the rescue.  We have published a revised section of the S-function builder documentation through a solution titled:

How can I input and output Bus signals to and from an S-function created using the S-function builder in Simulink 7.3 (R2009a)?

Now it’s your turn

Do you write S-functions?  Have you tried this feature?  Leave a comment here and tell me about your experience.