Module generation (Tc Build)
The Publish mechanism can be used to compile TwinCAT C++ projects for several TwinCAT platforms and export them to a central Publish directory. In the first step, the modules for all selected platforms are built. Then, all files required for instantiation and execution of the module under TwinCAT 3 are copied to the Publish directory.
The section "Export TC3 modules" under TC3 Engineering > C/C++ > Modules Handling describes how the publish mechanism is applied to TC3 C++ modules. The following section describes how Simulink has to be configured in order to export TwinCAT modules directly after the code has been generated with the aid of the Publish mechanism.
Publish directory
The files relating to exported modules are copied to the directory %TwinCat3Dir%CustomConfig\Modules\<MODULENAME>\. To instantiate the module on another development PC, this folder can be copied to the appropriate directory on the other computer.
Application
It makes sense to publish modules only once they have reached a stage at which they are only rarely modified, and if they are used in several TwinCAT projects. Otherwise, it may be more efficient to integrate the whole C++ project in the TwinCAT project, e.g. if the Simulink model is still under development and regular modifications are therefore to be expected, or if the module is only used in a special TwinCAT project.
Configuration in Simulink
The publish mechanism can be configured at Tc Build: (Export options for TwinCAT modules)
Publish module:
- disabled: The module generator is stopped once the C++ project has been generated. The generated C++ project has to be compiled manually, so that the module can be executed in TwinCAT 3. This can be done directly from the TwinCAT development environment, once the generated C++ project has been integrated into the TwinCAT project.
- enabled: "Publish" is executed automatically, once the C++ project has been generated. The module is then available on the development PC in compiled form for all TwinCAT projects and can be instantiated directly in the TwinCAT development environment (XAE). The other Publish settings relate to the target platforms for which the module is intended. Due to the sequential building for the different platforms, these settings can have a significant effect on the module generation duration.
 | "Generate code only" option The option Generate code only (in the Build process part of the window for the Code Generation settings) has no function, because the TwinCAT Publish mechanism is used instead of the MATLAB Make mechanism. |
Platform toolset:
Enables selection of a certain platform toolset (compiler) for building the module drivers. The options available for selection depend on the VisualStudio versions installed on the system. If Auto is selected, a compiler is selected automatically.
Publish configuration:
Select Debug here in order to enable debugging of the exported block diagram in TwinCAT 3. If no debugging is required, e.g. in a release version, Release can be selected here.
- Publish binaries for platform „<PLATFORMNAME>“:
- Select all TwinCAT platforms on which the module is intended to run. The drivers are then built successively for all selected platforms.
- Lowest compatible TwinCAT build:
- Enter the build number of the oldest TwinCAT version, with which the module is still to be compatible. If the module is subsequently used with an older TwinCAT version, it may fail to start. Also, the generated code may be uncompilable, if the SDK of an older TwinCAT version is used.
The following table provides an overview of main TwinCAT version-dependent properties of the generated module:
Property | TC3 Build | Description |
|---|---|---|
Large DataAreas | < 4018 | DataAreas > 16 MB are not supported |
>= 4018 | DataAreas > 16 MB utilize the data areas of several DataArea IDs, using the "OBJDATAAREA_SPAN_xxx" macros. | |
Project subdirectory"_ModuleInstall" | < 4018 | During instantiation of a module that was a previously exported via "Publish", only the TMC description is imported into the TwinCAT project. The module instance still refers to files within the Publish directory. To load the TwinCAT project on other development computer, the Publish directories of the modules in use have to be copied manually into to the corresponding directories of the other computers. Otherwise the project cannot be activated, and the block diagram is not displayed. |
>= 4018 | During instantiation of an exported module, all associated files are copied to subdirectory "_ModuleInstall" of the project directory. The project can now be opened on another development PC (even if it is compressed as an archive), without having to copy additional files manually. Another advantage is that the files in the Publish directory are now completely decoupled from the TwinCAT project. The module description, which is part of the TwinCAT project after it is instantiated, and the associated files (e.g. the drivers) are kept consistent. Files in the Publish directory can be overwritten, while the project uses a different version of the module up to "Reload TMC" and can still be re-activated on a target system. |
PreCodeGeneration / PostCodeGeneration / PostPublish callback:
MATLAB functions can be entered here, which are called before and after the code generation, or after Publish: (callback sequence)
To execute model- or module-specific actions, the structure cgStruct can be accessed here. It contains the following subelements:
Name | Value | Comment |
|---|---|---|
ModelName | Name of the Simulink model |
|
StartTime | Return value of the MATLAB function "now ()" at the start of the code generation |
|
BuildDirectory | Current build directory | From "PostCodeGeneration" |
ModuleName | Name of the generated TwinCAT module | From "PostCodeGeneration" |
ModuleClassId | ClassId of the generated TwinCAT module | From "PostCodeGeneration" |
<UserDefined> | Additional custom fields can be added to the structure, in order to transfer additional information to subsequent callbacks. |
|
For example, in the simplest case additional information could then be output between the individual module generation phases:
See also: Callback samples
Signing Certificate for x64 Windows Loader:
Defines the certificate used for signing of the driver for the "TwinCAT RT (x64)" platform. The default value $(TWINCATTESTCERTIFICATE) refers to the environment variable TWINCATTESTCERTIFICATE, which is described under "Driver signing" (TC3 Engineering > C/C++ >Preparation). Alternatively, the certificate name can be entered directly here, or different placeholders can be used, depending on the desired signing behavior:
Value | Behavior |
|---|---|
$<ENVIRONMENT VARIABLE> | This placeholder is resolved at an early stage during code generation. The value is written into the generated C++ project. If the specified environment variable is not found, the code generation process terminates with a corresponding error message. |
$(ENVIRONMENT VARIABLE) | This placeholder is not resolved until the generated C++ project is built. If the environment variable is not found, only a warning appears. The x64 driver can then still be built, although it cannot be loaded by the Windows loader on a target system. |
CertificateName | The name of the certificate is written into the generated C++ project. |
| If the field remains empty, only a warning appears. The x64 driver can then still be built, although it cannot be loaded by the Windows loader on a target system. |