Main Content

Use a Bus with S-Function Builder to Create an S-Function

This topic will show you how to create a bus and connect it to an S-Function Builder. At the end, you will use the S-Function Builder to build a simple C MEX S-function.

The S-Function Builder is a Simulink® block that integrates C/C++ code to build an S-function from specifications and C code that you supply. The S-Function Builder also serves as a wrapper for the generated S-function in models that use the S-function. To learn more on S-Function Builder, see Build S-Functions Automatically Using S-Function Builder. To see more examples on how to use S-Function Builder, type sfundemos in the MATLAB® Command Window, then navigate to C-file S-functions > S-function Builder.

  1. Start building your S-function by setting the current folder to the folder in which you want to create an S-function. Then, add this folder to the MATLAB path.

    mkdir newSfun
    addpath(fullfile(pwd,'newSfun'))
    cd('newSfun')

  2. If you wish to connect a bus to the input or output port of the S-Function Builder block, you must first create a bus object. You can create a bus object interactively using the Simulink Type Editor. Alternatively, you can use Simulink.Bus:

    1. In the MATLAB Command Window, enter:

      a = Simulink.Bus

      As a result, the HeaderFile for the bus defaults to the empty character vector:

      a =
       
      Simulink.Bus
          Description: ''
           HeaderFile: ''
             Elements: [0x1 double]
    2. If you want to specify the header file for the bus, then at the MATLAB Command Window, enter the following:

      a.Headerfile = 'Busdef.h'

      If you do not specify a header file, Simulink automatically generates Sfunctionname_bus.h

    This image illustrates the decision tree for setting header files for bus objects. If not specified, the bus object sets header file as Sfunctionname_bus.h.

    For a demonstration on how to use the S-Function Builder with a bus, enter the following command at the MATLAB Command Window:

    open_system(fullfile(matlabroot,...
        '/toolbox/simulink/sfuntemplates/sfbuilder_bususage'))

  3. Create a new Simulink model. Click on the canvas and type S-Function Builder to create an instance of the S-Function Builder block. Alternatively, drag an S-Function Builder block from the User-Defined Functions library in the Library Browser into the new model.

  4. Click on the canvas and type S-Function Builder or copy an instance of the S-Function Builder block from the User-Defined Functions library into the new model.

    Simulink canvas with an S-Function Builder block

  5. Double-click to open the S-Function Builder editor.

  6. Use the specification and code entry panes on the S-Function Builder dialog box to enter information and custom source code required to tailor the generated S-function to your application.

  7. Check whether the bus is in between the specified upper and lower saturation limits. To do this, create two input and two output ports, and assign the ports according to the table below:

    Table with name, scope, data type, dimensions, and complexity information

  8. Fill the Outputs_wrapper function with the logic of your code. See the example code:

    void sfbuilder_bus_Outputs_wrapper(const SFB_COUNTERBUS *u0,
                                       const int32_T *u1,
                                       const SFB_COUNTERBUS *y0,
                                       int32_T *y1)
    {
    /* Output_BEGIN */
    int32_T limit;
      boolean_T inputGElower;
      
      /* limit is sum of SFB_SIGNALBUS.input and the second input(u1) */
      limit = u0->inputsignal.input + *u1;
      
      /* check if SFB_SIGNALBUS.limit is >= LIMITBUS.lower_saturation_limit */
      inputGElower = (limit >= u0->limits.lower_saturation_limit);
    
      if((u0->limits.upper_saturation_limit >= limit) && inputGElower) 
      {
          *y1 = limit;
      } 
      else 
      {
          if(inputGElower) 
          {
              limit = u0->limits.upper_saturation_limit;
          } else 
          {
              limit = u0->limits.lower_saturation_limit;
          }
          *y1 = limit;
      }
    
      y0->inputsignal.input = *y1;
      y0->limits = u0->limits;
    /* Output_END */
    }
  9. Click the arrow under Build and Select Generate TLC wrapper to create a wrapper for your S-function for code generation.

  10. Click Build on the S-Function Builder to start the build process.

    The S-Function Builder builds a MEX file that implements the specified S-function and saves the file in the current folder (see How the S-Function Builder Builds an S-Function).

  11. Save the model containing the S-Function Builder block.

How the S-Function Builder Builds an S-Function

The S-Function Builder builds an S-function by generating the following source files in the current folder:

  • sfun.c — This file contains the C source code representation of the standard portions of the generated S-function.

  • sfun_wrapper.c — This file contains the custom code that you entered in the S-Function Builder dialog box.

  • sfun.tlc — This file permits the generated S-function to run in Simulink Rapid Accelerator mode and allows for inlining the S-function during code generation. In addition, this file generates code for the S-function in Accelerator mode which allows the model to run faster.

  • sfun_bus.h — If you specify any Input port or Output port as a bus in the Ports and Parameters table, but do not specify a header file, then the S-Function Builder automatically generates this header file.

After generating the S-function source code, the S-Function Builder uses the mex command to build the MEX file representation of the S-function from the generated source code and any external custom source code and libraries that you specified.

Deploy the Generated S-Function

To use the generated S-function in another model, first check to ensure that the folder containing the generated S-function is on the MATLAB path. Then, copy the S-Function Builder block from the model used to create the S-function into the target model. If necessary, set the target model's parameters to the values required by the target model.

Alternatively, you can deploy the generated S-function without using the S-Function Builder block or exposing the underlying C source file.

  1. Open the Simulink model that will include the S-function.

  2. Click the canvas to create an instance of the S-function block, or copy an S-Function block from the User-Defined Functions library in the Library Browser into the model.

  3. Double-click on the S-Function block.

  4. In the Block Parameters dialog box that opens, in the S-function name edit field, enter the name of the executable file generated by the S-Function Builder.

  5. Enter any parameters for the S-function into the S-function parameters edit field. Enter the parameters in the order in which they appear in the S-Function Builder dialog box.

  6. Click OK on the S-Function Block Parameters dialog box.

By creating a block from a generated S-function, you can also create a mask for your S-Function block. To learn more about how to add a mask for your S-function, see Create Block Masks. To see an example of how block masks are added to an S-function, enter the following command on the MATLAB Command Window.

open_system(fullfile(matlabroot,...
'/toolbox/simulink/sfuntemplates/sfcndemo_matadd'));

You can use the generated executable file in any S-Function block in any model as long as the executable file is on the MATLAB path.

See Also

|

Related Topics