How to create Arduino S-Function in Simulink with LED blink example

Simulink S-Functions block allows users to create custom simulink block that can be used to implement functions, algorithm, import libraries, implement drivers and interfaces to hardware like Arduino. Consider for example you are working on a Simulink model with Arduino hardware and you need to add or integrate library functionality for LCD, motor, various sensors etc. There are lots of libraries for LCD, motor I2C libraries for Arduino. Now in order to model system in simulink that includes Arduino and to use the libraries that aren't there in Simulink we can use S-Function block.

Here we want to share simple example of how to create Arduino S-Function in Simulink with LED blink example. We will show, step by step, how to create S-Function for Arduino and that turns on and off a LED. This simple guide will illustrate the process of implementing Arduino sketch into a S-Function using the automatic S-Function builder block.

Hardware connection

We just need Arduino and a LED for this work. Connect the LED with current limiting resistor like 220Ohm to the digital pin 9 on the Arduino. This is as shown below.

Simulink Model

Start by creating a new Simulink model and save the model with some name within a new folder with some folder name. Open simulink library browser and go to Simulink>User-Defined Functions section and place the S-Function builder block into the newly created model.

Double click on the S-Function Builder block to open its properties window.
At the top provide some name for the S-Function block. Here we have named it LEDControlSF. The Language is left in default which is "Inherit from model settings". In the Initialization tab, S-Function settings provide number of discrete state as 1. The sample mode is set to default value which is "Inherited". See the following picture.

Next click on the Data Properties tab. In the Input Ports section you should see initially a name for default input u0. You can delete that default name and provide your own name for input port. Here we need just one input port for switch input and we have named the input port as ledinp. Leave other properties for the input port in their default values. See the following picture.

Click to the next tab which is the Output Ports tab and delete the default port y0 as shown in the figure below. We don't need any output port here. 

Next go to the Parameters tab. There we have to specify the digital pin where we have connected the LED. In our case we have used digital pin 9. So we add parameter named LED with Data Type as uint8. At the top we also have to specify the pin number as 9 in the Value field. See the following picture for this.


Doing this essentially writing alias for pin names in Arduino sketch. That is doing this is similar to writing the following in Arduino sketch.

int LED = 9

Now go to the Data type attributes tab. There we have to specify the data type for the input port ledinp we had created earlier. In the Data type field select uint8. See below.



Next click on the Libraries tab. In this section, we have to add the libraries header and C++ files which you will be working with. In our case, for just LED blinking purpose, we just need to add the Arduino.h header file. To add header files/C++ files in the S-Function builder block we need to use the #ifndef and #endif preprocessor statements. Below picture shows where to add the following statements.

#ifndef MATLAB_MEX_FILE
#include <Arduino.h>

The next thing we have to do is to specify the main code. This is specified into the Outputs tab. Here in the Outputs tab, we write the code that we would normally write in the void loop() function in the Arduino sketch. Type in the following code into the Output field:
<

if (xD[0]==1){
    # ifndef MATLAB_MEX_FILE
        digitalWrite(LED[0],ledinp[0]);
    # endif
}

The xD[0] is a state where 0 means the first state. This is the default state. In the program code above, we use the if statement to check whether the state of the S-function is in the state 0 and if it is then the program code statements are executed. Here we have used the Arduino digitalWrite() function with the LED parameter with state 0 as the pin to write and provided the input to the S-function, the ledpin with state 0 as the input. Again as explained before, to write Arduino C/C++ statements enclosed within the ifndef with endif statements.

See below picture for this step.

Next click on the Update tab. Here we specify the code required for the void setup() function in Arduino sketch. Type in the following code in the Update code field.

 if (xD[0]!=1){ 
    # ifndef MATLAB_MEX_FILE
        pinMode(LED[0],OUTPUT);
    # endif
        xD[0]=1;
}

As you can see above the pinMode() function which is used in the setup() function in Arduino sketch is used in this Update code section of the S-Function builder. The if statement checks where the state of the S-Function code is using the state variable xD[]. If the state is not in the main loop with state 0 then this section of code is executed where the pin input output mode is set and then enters the state 0.

See the following picture to see where to add the code.

At this point we have configured the S-Function builder for using Arduino hardware for sending switch state to the digital pin 9. Now we have to build the code. 

Click on the Build button as shown in the figure below and you will see code generated message in the Build info tab.

 

Now we have to rename a C file generated by the S-Function builder and add extern "C" line to two functions in that file. 

The S-Function builder will generate couple of files but in one file where we need to add extern "C" line to two functions and change the file extention from c to cpp. This file name is <S-Function name>_wrapper.c. This file will be created in the same folder where you created the simulink project. See the following picture.

Open this c file and look for the line with,

void <S-Function name>_Outputs_Wrapper() 

where <S-Function name> is the name you have provided for the S-Function builder block. This is as shown below,

This function corresponds to the Output code field in the S-Function builder. Before the void word add the extern "C" as shown below.

Next find the second function in the same file, which is called:

void <S-Function name>_Update_Wrapper() 

This is as shown below.

 

And like before add extern "C" before the word void as shown below.

Finally change the file name of the <S-Function name>_wrapper.c to <S-Function name>_wrapper.cpp as shown below.

 

Next we have to add switch input to the S-Function block which is programmed to turn on and off a LED via Arduino board. Find and place a Constant block(Simulink > Commonly Used Blocks) and a Slider Switch block(Simulink > Dashboard). Connect the Constant block to the input ledinp of the S-Function block we created. Also connect the Slider Switch to the Constant block. This is as shown below.

Open the Constant block property by double clicking and change the output signal data type to uint8.

 

If you have not already, configure the Arduino board for code deployment or/and simulation. Here we have selected Arduino Uno. This is as shown below.

Once the board configuration is completed we can then start the simulation. On the Hardware tab click on the Monitor & Tune button to start the compilation, building and initialization process, that will upload the code into the Arduino and run the real time simulation.

Once the program is running in Arduino board, you should use the switch to change the state of the LED. By turning on and off the slider switch, the LED will turn on and off. 

Video Demonstration

You can watch the following video for demonstration of this.

 

Summary & Conclusion

S-Function builder is a feature in Simulink that can be used to create custom block to add functionality that is not available in the simulink library. Here we have used this S-Function builder feature to create a block that accepts inputs from within Simulink via slider switch to turn on and off a LED connected to Arduino Uno board. Thus we have shown how to create Arduino S-Function in Simulink with LED blink example.

Although there are other ways to program Arduino using Simulink and Matlab to do the same thing, that is using Matlab/Simulink support for Arduino Hardware library we can also do it without the add-on blocks by using S-Function. For example in the LED blinking - Programming Arduino using Matlab tutorial we have used matlab program code and in the tutorial Servo Motor control using Simulink and Arduino we have used pre-available blocks to control servo motor.

The advantage of S-Function builder shines when we want to use libraries for Arduino. Because we don't have to manually write all the code and adjust files. Thus S-Function builder and S-Function saves time and effort for faster model and prototyping development.