SFunStaticLib
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 illustrates how TwinCAT modules are generated using SFunctions from Simulink models, for which no source code is available. In this case, the SFunction functionality can be integrated into the generated TwinCAT module via static libraries. However, this presupposes that suitable libraries are 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 user-created 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
- SFunctions are generated with suitable TwinCAT libraries
- such libraries are made available (e.g. to customers)
- such libraries are used in own models
Project directory overview
TE1400Sample_SFunStaticLib contains all the files necessary to reproduce this example:
TctSmplSFunStaticLib.mdl | contains the model that references the SFunction. |
BuildLibsAndSFunction.m | contains an M-script that creates the static library for all currently available TwinCAT platforms and creates the SFunction. |
OpenLibProject.m | contains an M-script that defines the MATLAB build environment for Visual Studio, such as MATLAB Include and library directories. The static library is then opened in Microsoft Visual Studio 2010 with the predefined environment variables. |
Subdirectory SFunLibProject | contains the SFunction project. |
Subdirectory BuildScripts | contains several M-scripts for "BuildLibsAndSFunction.m" and "OpenLibProject.m". |
_PrecompiledTcComModules | This subdirectory contains readily compiled TwinCAT modules that were generated from the enclosed Simulink models. They enable the integration of a module in TwinCAT to be tested, without having to generate the module first. They can be used in situations where a MATLAB license is not yet available, for example. A quick reference guide for module installation on the development PC is also enclosed. Info: To start the module on an x64 target system, the system must be switched to test mode! |
_PreviousSimulinkVersions | The MDL files described above are stored in the file format of the current Simulink version. This subdirectory additionally contains the models in the file format elder Simulink versions. |
Build SFunction and appropriate static link libraries
Build requirements
It is recommended to have TwinCAT 3 installed on your system to build the binaries, but not required. Requirements are:
|
Windows Driver Kit |
installed on your system and the environment variable WinDDK set to its path. |
|
TwinCAT SDK |
installed on your system and the environment variable TwinCatSdk set to its path. |
For more information about this requirement, see the system requirements in the TwinCAT 3 documentation.
Creating binary files manually
The binary files 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.
TwinCAT xx(xxx) | Creates the platform-specific static library, which is linked to the generated TwinCAT module. |
Win32 | Creates the .MEXW32 SFunction for running the simulation of the model with Simulink in 32-bit MATLAB. It can only be created if Visual Studio was started from 32-bit MATLAB. |
x64 | Creates the .MEXW64 SFunction for running the simulation of the model with Simulink in 64-bit MATLAB. It can only be created if Visual Studio was started from 64-bit MATLAB. In order to create the MEX files used in this example for 32- and 64-bit MATLAB, Visual Studio must be started from both MATLAB versions. |
Build the binaries via build script
Alternatively to the manual build procedure, in order to speed up the build procedure for a quick overview, run BuildLibsAndSFunction.m. This prepares the build environment variables and invokes MSBUILD multiple times to build the .LIB and .MEXWxx files for each TwinCAT platform and for the current MATLAB platform architecture (32 or 64 Bit). To build the MEX files of this example for 32 and 64 Bit MATLAB BuildLibsAndSFunction.m has to be executed with both MATLAB variants.
After the build procedure, all the build output files are copied to the subfolder LibProject\TctSample_SFunLib\BuildOutput. All necessary binaries are additionally copied to LibProject\TctSample_SFunLib\LibPackage.
Deliver the binaries
LibProject\TctSample_SFunLib\LibPackage is the folder which can be delivered to customers who want to use the now built - TwinCAT Target compatible - SFunction. Copy the content of this folder to the users system, more precisely to the folder %TwinCat3Dir%Functions\TE1400-TargetForMatlabSimulink\Libraries. If BuildLibsAndSFunction.m was used for building the binaries, this has already been done for the local system. The content of this folder should be:
|
Subfolders TwinCAT xx (xxx) |
contain the static link libraries for different TwinCAT platforms. These are used when generating TwinCAT modules from appropriate Simulink models. |
|
Subfolders Win32 / Win64 |
contain the MEX files (and optionally some static link libraries) for the different MATLAB platform architectures (32 and/or 64 Bit). Either subfolder Win32 or Win64 is added to the MATLAB path when setting up TwinCAT Target via SetupTwinCatTarget.m. Thus, SFunction MEX files are found by MATLAB can be used directly from this location. |
Run simulation
To check if everything works, open "TctSmplSFunWrappedStaticLib.mdl" and start simulation. If the simulation starts without error messages, everything is prepared as needed.
Generate TwinCAT module
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:
- 1. Copy the sample folder
- 2. Replace the MDL file by your own
- 3. Rename the VCXPROJ file to the desired name of your SFunction
- 4. Copy your source files to the directory where the VCXPROJ file is located
- 5. Adapt the scripts BuildLibsAndSFunction.m and OpenLibProject.m to the new project name
- 6. Open the VCXPROJ file using OpenLibProject.m
- 7. Remove the existing CPP files from the project
- 8. Add your own CPP files to the project
- 9. Adapt the DEF file contents to the new project name
- 10. If necessary, add include directories, dependency directories and libraries to the compiler and linker settings
- 11. Build the project (for different platforms and/or configurations)
- 12. Close the VCXPROJ file
- 13. Run BuildLibsAndSFunction.m