SFunWrappedStaticLib

Use cases

Encapsulating own code within static libraries can be useful to

• speed up module generation, if the code contains algorithms, which are not changed frequently
• deliver TwinCAT Target compatible SFunction algorithms to customers, without the need to hand out the source code but only the compiled libraries

Description

The following example shows the configuration of the module generator when using Sfunctions that depend on statically linked libraries. For this type of code integration, a suitable library must be available for all TwinCAT platforms for which the module is to be created.
The following diagram illustrates the typical workflow when using third-party algorithms in a custom Simulink model:

In this example, the source code for the "algorithm development side" is available and can be compiled for all TwinCAT platforms. It shows how

• dependent libraries are created
• such libraries are made available (e.g. to customers)
• such libraries are used in own models

Overview of project directory

TE1400Sample_SFunWrappedStaticLib contains all the files necessary to reproduce this example:

Build requirements

It is recommended to have TwinCAT 3 installed on your system to build the binaries, but not required. Requirements are:

For more information about this requirement, see the system requirements in the TwinCAT 3 documentation.

Creating static libraries manually

The static libraries can be created manually with Visual Studio. To do this, execute OpenLibProject.m. This prepares the required environment variables and opens the SFunction project in Visual Studio. Create a project for all platforms that should be supported. The output file for all platforms is a static library:

Build the static link libraries via build script

Alternatively to the manual build procedure, run BuildLibsAndSFunction.m. This prepares the build environment and invokes MSBUILD multiple times to build the lib files for each platform.. Afterwards, all the build output files are copied to the subfolder LibProject\TctSample_WrappedStaticLib\BuildOutput. The .LIB files, which are necessary to build the SFunction and the generated TwinCAT modules are additionally copied to LibProject\TctSample_WrappedStaticLib\LibPackage.

Deliver the static libraries

LibProject\TctSample_WrappedStaticLib\LibPackage is the folder which can be delivered to users, which want to use this library inside their own - TwinCAT Target compatible - SFunctions. Copy the content of this folder to the users system, more precisely to the folder %TwinCat3Dir%Functions\TE1400-TargetForMatlabSimulink\Libraries. This is also done by BuildLibsAndSFunction.m for the local system. The content of this folder should be:

Compile mex file code

Before the SFunction can be used inside the Simulink model, it has to be built, too. Of course this can be done manually, as in any other SFunction. However, the MEX compiler has to be advised to link the static library to the SFunction.
When executing BuildLibsAndSFunction.m, this is also done automatically. Afterwards the file "SFunStaticLib.mexw32" should be located inside your working folder.
To check if everything works, open "TctSmplSFunWrappedStaticLib.mdl" and start simulation. If the simulation starts without error messages, everything is prepared as needed.

Configuring a model

The general settings for generating a TwinCAT module must be set, e.g. a fixed-step solver must be configured, and the system target file "TwinCAT.tlc" must be selected under the "General" tab in the model coder settings. For further information on the general configuration of the TwinCAT module generator see Quickstart.
In addition, the code generator must know which static libraries have to be linked to the generated code and where to find them. Enter this information in the corresponding option fields of the Simulink coder, as shown in the figures below.

The Include folder should already have been created automatically by TwinCAT Target. The Libraries setting must contain the names of the static libraries to be linked.

Background information for these settings:

In this example (and in most other cases) there are several instances of these libraries in the specified folders. MSBUILD decides which version is linked to the module when the generated TwinCAT module binary files are linked.

How to use this example as a template

The following list provides a short overview of the easiest way, to create an own TwinCAT Target compatible SFunction dependency: