Integration of C code in Engee model using C Function block

This example shows different ways to integrate C code into the Engee model using the C Function block.

Before we start, let's connect the necessary libraries:

Use the macro @__DIR__ to find out the folder where the interactive script lies:

Basics of Using the C Function Block

Let's look at simple examples of using the C Function block to illustrate the basics of integrating C code into the Engee model.

1. Working with multidimensional signals, passing parameters and using #define directive

In the model cCodeIntegration_basics.engee we have added the block C Function, which inputs a sinusoidal signal in:

Suppose we want to increase the amplitude of the sinusoid in by a factor of gain and shift it by a value of bias. That is, the output signal should be determined by the formula out = gain * in + bias.

Let's go to the settings of the C Function block, where in the Ports tab we will familiarise ourselves with the definition of the block input and output. This is where the source code variables are linked to the ports of the C Function block:

1. The scalar variable x of type double is bound to the first input port in;
2. Vector (3 elements) variable y of type double is bound to the first output port out.

The gain array is also defined in the settings of the C Function block ( Parameters tab ):

It is worth noting that once a variable is passed as a parameter, it becomes:

1. Global - gain can be accessed from any tab of the source code editor;
2. With the qualifier const - an error will be received when trying to change the value of gain.

The offset value bias is determined by the identifier #define bias, which is set in the tab Build options:

In this example, the offset is 5.

Let's go to Main of the C Function block settings and click the "Edit Source Code" button. In the opened source code editor on the tab OutputCode the code executed at each step of the model calculation is given:

In the loop for (for each of the three output signals), the value of the variable y is determined at each step of the model calculation.

Let's simulate the system:

Let's close the model:

Import the results of the simulation:

Plot the graph:

2. Using integer data types and static variables

In the model cCodeIntegration_integers.engee we implement a simple counter using the C Function block, the output of which is a positive integer denoting the number of the current iteration:

Let's analyse the contents of the Ports and Build Options tabs in the C Function block settings:

The names of integer data types in the C Function block are defined according to the header file <stdint.h> of the C language standard library. This file is connected in the line Headers of the tab Build options.

The tab Ports binds a 64-bit variable without the sign out (the type is set as uint64_t, not long, see the previous paragraph about <stdint.h>) of the source code to the first output port of the C Function block.

The Output code tab of the source code editor of the C Function block contains the code executed at each step of the simulation:

The static variable counter is initialised to 0 in the first step of the simulation, after which at each iteration its value is incremented by 1 and assigned to the variable out.

Let's simulate the system:

Let's close the model:

Import the results of the simulation:

Plot the graph:

For more information about the purpose of the source code editor tabs, plotting options, and available data types, see in the documentation Engee.

Integrating external source code

Task statement

Let's consider a more interesting engineering problem.

Suppose we need to control a stable second-order object that is subject to external disturbances, given the measurement noise. Consequently, we need to solve the problem of filtering the output signal of the control object, and fortunately, Engee has a tool that is perfect for this!

The files alphabetafilter.c and alphabetafilter.h offer a C implementation of the alpha-beta filter.

The contents of the file alphabetafilter.c:

The contents of the file alphabetafilter.h:

Integrate this source code into our Engee model.

Analysis of the model

Model cCodeIntegration_source.engee:

This model consists of:

1. The control object Plant;
2. Subsystem realising the second-order PID controller Controller;
3. Blocks Band-Limited White Noise ProcessNoise and MeasurementNoise, modelling the external influence and measurement noise;
4. Block C Function Filter, realising the alpha-beta filter.

The parameter Sample Time of the block Filter is equal to the step of the model solver Ts:

Let's analyse the contents of the Build options tab of the Filter block settings:

In the rows of this tab:

• Source files - connected source code file alphabetafilter.c;
• Iinclude directories - the path to the folder containing the header file is set;
• Headers - connected header file alphabetafilter.h.

In the Ports tab of block settings source code variables are linked to input and output ports of the block Filter.

In the source code of the Filter block, the OutputCode tab contains cyclically executable code:

At each step of the model calculation, the functions determineAlphaBeta() and alphabetafilter() are called sequentially, after which the filtered value is stored in the variable out, corresponding to the output port x of the block Filter.

Simulation start

Let's simulate the system:

Let's close the model:

Simulation results

Import simulation results:

Plot the graph:

Integration of static and dynamic libraries

Task Statement

Often source code is not supplied explicitly, but as part of static or dynamic libraries. C API libraries integrate into Engee models as easily as external source code!

Let's compile a static (alphabetafilter.a) and dynamic (alphabetafilter.so) library from the files alphabetafilter.c and alphabetafilter.h using MakeFile.

The contents of the file Makefile:

Let's start compiling the libraries:

Integrate the static and dynamic library into our Engee model.

Static library: Analyse the model

By its structure, the model cCodeIntegration_library_static.engee does not differ from the previously considered cCodeIntegration_source.engee; only the directives on the Build options tab of the Filter block settings differ. Let's analyse its contents:

The following construction options are defined here:

• Include directories - the path to the folder containing the header file is specified;
• Library directories - the path to the folder containing static library is set;
• Headers - connected header file alphabetafilter.h;
• Libraries - static library alphabetafilter.a is connected.

Static library: Start simulation

Let's simulate the system:

Let's close the model:

Static Library: Modelling Results

Import the simulation results:

Plot the graph:

Dynamic Library: Model Analysis

By its structure, the model cCodeIntegration_library_dynamic.engee does not differ from the previously considered cCodeIntegration_source.engee; only the directives on the Build options tab of the Filter block settings differ. Let's analyse its contents:

The following construction options are defined here:

• Include directories - the path to the folder containing the header file is specified;
• Library directories - the path to the folder containing the dynamic library is set;
• Headers - the header file alphabetafilter.h is connected;
• Libraries - connected dynamic library alphabetafilter.so.

In the Start code tab of the source code editor of the Filter block, the function initializeStaticVariables() is called:

The function initializeStaticVariables() is declared in the file alphabetafilter.h and is intended to initialise the static variables xk_1 and vk_1, used in the dynamic library. This is necessary so that when the simulation is restarted, the variables do not save their last calculated value, but are reset to the initial value (in this case to 0).

Dynamic Library: Running a Simulation

Let's simulate the system:

Let's close the model:

Dynamic Library: Modelling Results

Import the simulation results:

Plot the graph:

Integration of code generated from the Simulink model

Problem Statement

Let's generate C code from the Simulink model alphabetafilter.slx and integrate it into our Engee model cCodeIntegration_cg_simulink.engee.

The model alphabetafilter.slx, which implements the alpha-beta filter, is built in Simulink from simple blocks and consists of subsystems determineAlphaBeta and filterInputSignal.

Top level of the model:

Subsystem determineAlphaBeta:

Subsystem filterInputSignal:

Let's generate the code using Simulink Embedded Coder:

Model Analysis

By its structure, the model cCodeIntegration_cg_simulink.engee does not differ from the previously considered cCodeIntegration_source.engee; only the directives on the Build options tab of the Filter block settings differ. Let's analyse its contents:

The following construction options are defined here:

• Source files - connected source code files alphabetafilter.c and alphabetafilter_data.c;
• Include directories - the path to the folder containing header files is set;
• Headers - header files alphabetafilter.h, alphabetafilter_types.h and rtwtypes.h are connected.

Cyclically executable code is given on the Output code tab of the source code editor of the Filter block:

At each step of the model calculation is performed:

• Initialisation of the structure alphabetafilter_U with variables in, processNoiseVariance and measurementNoiseVariance (input signals);

• Calling the function alphabetafilter_step();

• Assignment to the variable out (output signal) of the result x, stored in the structure alphabetafilter_Y.

In the Start code tab of the source code editor of the Filter block, the function alphabetafilter_initialize() is called:

In the Terminate code tab of the source code editor of the Filter block, the function alphabetafilter_terminate() is called:

Simulation start

Let's simulate the system:

Let's close the model:

Simulation results

Import simulation results:

Plot the graph:

Integration of code generated from the Engee model

Task Statement

Let's generate C code from the model Engee alphabetafilter.engee, built from simple blocks and implementing the alpha-beta filter, and integrate it into our model Engee cCodeIntegration_cg_engee.engee.

Top level of the model:

Subsystem determineAlphaBeta:

Subsystem filterInputSignal:

Let's generate the code using the Engee code generator:

Model Analysis

By its structure, the model cCodeIntegration_cg_engee.engee does not differ from the previously considered cCodeIntegration_source.engee; only the directives on the Build options tab of the Filter block settings differ. Let's analyse its contents:

The following construction options are defined here:

• Source files - connected source code file alphabetafilter.c;
• Include directories - the path to the folder containing header files is set;
• Headers - connected header file alphabetafilter.h.

Cyclically executable code is given on the Output code tab of the source code editor of the Filter block:

At each step of the model calculation is performed:

• Initialisation of the structure alphabetafilter_U with variables in, processNoiseVariance and measurementNoiseVariance (input signals);

• Calling the function alphabetafilter_step();

• Assignment to the variable out (output signal) of the result x, stored in the structure alphabetafilter_Y.

In the Start code tab of the source code editor of the Filter block, the function alphabetafilter_init() is called:

In the Terminate code tab of the source code editor of the Filter block, the function alphabetafilter_term() is called:

Simulation start

Let's simulate the system:

Let's close the model:

Simulation results

Import simulation results:

Plot the graph:

Conclusions

This example demonstrates the features of using the C Function block and the different ways to integrate C code into the Engee model:

1. Integration of external source code;
2. Integration of static and dynamic libraries;
3. Integration of code generated from the Simulink model;
4. integration of code generated from the Engee model.