Beckhoff TE1000 Users guide
Manual | EN
TE1000
TwinCAT 3 | C++
2020-10-26 | Version: 1.13
Table of contents
Table of contents
1 Foreword ....................................................................................................................................................9
1.1 Notes on the documentation..............................................................................................................9
1.2 Safety instructions ...........................................................................................................................10
2 Overview...................................................................................................................................................11
3 Introduction..............................................................................................................................................12
3.1 From conventional user mode programming to real-time programming in TwinCAT ......................14
4 Requirements...........................................................................................................................................20
5 Preparation - only once...........................................................................................................................22
5.1 "Microsoft Windows Driver Kit (WDK)" installation (only <= Build 4022) .........................................22
5.2 Visual Studio - TwinCAT XAE Base toolbar ....................................................................................24
5.3 Prepare Visual Studio - Configuration and Platform toolbar............................................................25
5.4 Driver signing...................................................................................................................................25
5.4.1 Operating system............................................................................................................. 26
5.4.2 TwinCAT .......................................................................................................................... 31
6 Modules ....................................................................................................................................................35
6.1 The TwinCAT Component Object Model (TcCOM) concept ...........................................................35
6.1.1 TwinCAT module properties ............................................................................................ 37
6.1.2 TwinCAT module state machine...................................................................................... 44
6.2 Module-to-module communication ..................................................................................................46
7 Modules - Handling..................................................................................................................................49
7.1 Versioned C++ Projects...................................................................................................................49
7.2 Non-versioned C++ projects............................................................................................................49
7.2.1 Export to TwinCAT 3.1 4022.xx ....................................................................................... 50
7.2.2 Import up to TwinCAT 3.1 4022.xx .................................................................................. 51
7.3 Starting Modules..............................................................................................................................52
7.4 TwinCAT Loader..............................................................................................................................53
7.4.1 Test signing ..................................................................................................................... 53
7.4.2 Encrypting Modules ......................................................................................................... 55
7.4.3 Return Codes................................................................................................................... 57
7.4.4 TcSignTool - Storage of the certificate password outside the project.............................. 57
8 TwinCAT C++ development ....................................................................................................................58
9 Quick Start................................................................................................................................................60
9.1 Create TwinCAT 3 project ...............................................................................................................60
9.2 Create TwinCAT 3 C++ project .......................................................................................................62
9.3 TwinCAT 3 Driver ............................................................................................................................63
9.3.1 Creating a TwinCAT 3 C++ module in the TwinCAT Driver Project ................................ 63
9.3.2 Implement TwinCAT 3 C++ project.................................................................................. 66
9.3.3 Create TwinCAT 3 C++ Module instance ........................................................................ 67
9.3.4 Create a TwinCAT task and apply it to the module instance ........................................... 69
9.3.5 Compiling/building a TwinCAT 3 C++ project .................................................................. 71
9.3.6 TwinCAT 3 enable C++ debugger ................................................................................... 72
9.3.7 Activating a TwinCAT 3 project........................................................................................ 73
TE1000 3Version: 1.13
Table of contents
9.3.8 Debug TwinCAT 3 C++ project........................................................................................ 74
9.4 TwinCAT 3 Versioned Project .........................................................................................................78
9.4.1 Create TwinCAT 3 C++ project........................................................................................ 78
9.4.2 TwinCAT 3 C++ Configure project................................................................................... 80
9.4.3 Implement TwinCAT 3 C++ project.................................................................................. 81
9.4.4 Publish TwinCAT 3 C++ project in version 0.0.0.1 .......................................................... 83
9.4.5 Implement and publish TwinCAT 3 C++ project version 0.0.0.2...................................... 83
9.4.6 Create TwinCAT 3 C++ Module instance ........................................................................ 85
9.4.7 Activating a TwinCAT 3 project........................................................................................ 87
9.4.8 TwinCAT 3 C++ Implement project Online Change......................................................... 89
10 Debugging ................................................................................................................................................91
10.1 Details of Conditional Breakpoints...................................................................................................94
10.2 Visual Studio tools ...........................................................................................................................96
11 Wizards .....................................................................................................................................................99
11.1 TwinCAT C++ Project Wizard..........................................................................................................99
11.2 TwinCAT Module Class Wizard.....................................................................................................100
11.3 TwinCAT Module Class Editor (TMC)............................................................................................103
11.3.1 Overview........................................................................................................................ 105
11.3.2 Basic Information ........................................................................................................... 106
11.3.3 Data Types .................................................................................................................... 107
11.3.4 Modules ......................................................................................................................... 124
11.4 TwinCAT Module Instance Configurator........................................................................................146
11.4.1 Object ............................................................................................................................ 147
11.4.2 Context .......................................................................................................................... 148
11.4.3 Parameter (Init).............................................................................................................. 148
11.4.4 Data Area....................................................................................................................... 149
11.4.5 Interfaces ....................................................................................................................... 149
11.4.6 Interface Pointer ............................................................................................................ 149
11.4.7 Data Pointer................................................................................................................... 150
11.5 Customer-specific project templates .............................................................................................150
11.5.1 Overview........................................................................................................................ 150
11.5.2 Files involved ................................................................................................................. 151
11.5.3 Transformations............................................................................................................. 152
11.5.4 Notes on handling.......................................................................................................... 153
12 Programming Reference .......................................................................................................................156
12.1 TwinCAT C++ Project properties...................................................................................................157
12.1.1 Tc SDK .......................................................................................................................... 159
12.1.2 Tc Extract Version ......................................................................................................... 160
12.1.3 Tc Publish ...................................................................................................................... 160
12.1.4 Tc Sign........................................................................................................................... 161
12.2 File Description..............................................................................................................................162
12.2.1 Compilation procedure................................................................................................... 164
12.3 Online Change...............................................................................................................................164
12.4 Limitations .....................................................................................................................................166
12.5 Memory Allocation .........................................................................................................................167
TE10004 Version: 1.13
Table of contents
12.6 Multi-task data access synchronization .........................................................................................168
12.7 Interfaces.......................................................................................................................................172
12.7.1 Return values................................................................................................................. 173
12.7.2 Interface ITcCyclic ......................................................................................................... 173
12.7.3 Interface ITcCyclicCaller................................................................................................ 174
12.7.4 Interface ITcFileAccess ................................................................................................. 176
12.7.5 Interface ITcFileAccessAsync........................................................................................ 184
12.7.6 Interface ITcIoCyclic ...................................................................................................... 186
12.7.7 Interface ITcIoCyclicCaller............................................................................................. 187
12.7.8 ITComOnlineChange interface ...................................................................................... 189
12.7.9 Interface ITComObject................................................................................................... 190
12.7.10 ITComObject interface (C++ convenience) ................................................................... 195
12.7.11 Interface ITcPostCyclic.................................................................................................. 196
12.7.12 Interface ITcPostCyclicCaller......................................................................................... 197
12.7.13 Interface ITcRTimeTask ................................................................................................ 199
12.7.14 Interface ITcTask........................................................................................................... 200
12.7.15 Interface ITcTaskNotification ......................................................................................... 204
12.7.16 Interface ITcUnknown.................................................................................................... 205
12.8 Runtime Library (RtlR0.h)..............................................................................................................207
12.9 ADS Communication .....................................................................................................................208
12.9.1 AdsReadDeviceInfo ....................................................................................................... 208
12.9.2 AdsRead ........................................................................................................................ 210
12.9.3 AdsWrite ........................................................................................................................ 212
12.9.4 AdsReadWrite................................................................................................................ 214
12.9.5 AdsReadState................................................................................................................ 216
12.9.6 AdsWriteControl............................................................................................................. 218
12.9.7 AdsAddDeviceNotification ............................................................................................. 220
12.9.8 AdsDelDeviceNotification .............................................................................................. 222
12.9.9 AdsDeviceNotification.................................................................................................... 224
12.10 Mathematical Functions.................................................................................................................225
12.11 Time Functions ..............................................................................................................................227
12.12 STL / Containers............................................................................................................................228
12.13 Error messages - understanding ...................................................................................................228
12.14 Module messages for the Engineering (logging / tracing) .............................................................229
13 How to...?................................................................................................................................................233
13.1 Using the Automation Interface .....................................................................................................233
13.2 Windows 10 as target system up to TwinCAT 3.1 Build 4022.2....................................................233
13.3 Publishing of modules ...................................................................................................................233
13.4 Publishing modules on the command line .....................................................................................234
13.5 Clone .............................................................................................................................................234
13.6 Access Variables via ADS .............................................................................................................235
13.7 TcCallAfterOutputUpdate for C++ modules...................................................................................235
13.8 Order determination of the execution in a task..............................................................................235
13.9 Setting version/vendor information ................................................................................................236
13.10 Renaming TwinCAT C++ projects .................................................................................................237
13.11 Delete Module ...............................................................................................................................239
TE1000 5Version: 1.13
Table of contents
13.12 Add revision control and Online Change subsequently .................................................................240
13.12.1 C++ Project -> Revision control..................................................................................... 240
13.12.2 C++ Module -> OnlineChange....................................................................................... 243
13.13 Initialization of TMC-member variables .........................................................................................248
13.14 Using PLC strings as method parameters .....................................................................................248
13.15 Third Party Libraries ......................................................................................................................249
13.16 Linking via TMC editor (TcLinkTo).................................................................................................249
14 Troubleshooting ....................................................................................................................................252
14.1 Build - "The target ... does not exist in the project"........................................................................252
14.2 Debug - "Unable to attach" ............................................................................................................252
14.3 Activation – “invalid object id” (1821/0x71d)..................................................................................253
14.4 Error message - VS2010 and LNK1123/COFF .............................................................................254
14.5 Using C++ classes in TwinCAT C++ module ................................................................................254
14.6 Using afxres.h................................................................................................................................254
15 C++-samples ..........................................................................................................................................255
15.1 Sample01: Cyclic module with IO..................................................................................................257
15.2 Sample02: Cyclic C++ logic, which uses IO from the IO Task ......................................................258
15.3 Sample03: C++ as ADS server .....................................................................................................258
15.3.1 Sample03: TC3 ADS Server written in C++................................................................... 259
15.3.2 Sample03: ADS client UI in C#...................................................................................... 263
15.4 Sample05: C++ CoE access via ADS ...........................................................................................267
15.5 Sample06: UI-C#-ADS client uploading the symbolic from module ..............................................268
15.6 Sample07: Receiving ADS Notifications........................................................................................273
15.7 Sample08: provision of ADS-RPC.................................................................................................274
15.8 Sample10: module communication: Using data pointer ................................................................277
15.9 Sample11: module communication: PLC module invokes method of C-module...........................278
15.9.1 TwinCAT 3 C++ module providing methods .................................................................. 279
15.9.2 Calling methods offered by another module via PLC .................................................... 294
15.10 Sample11a: Module communication: C module calls a method of another C module ..................306
15.11 Sample12: module communication: Using IO mapping.................................................................306
15.12 Sample13: Module communication: C-module calls PLC methods ...............................................307
15.13 Sample19: Synchronous File Access ............................................................................................310
15.14 Sample20: FileIO-Write .................................................................................................................311
15.15 Sample20a: FileIO-Cyclic Read / Write .........................................................................................311
15.16 Sample22: Automation Device Driver (ADD): Access DPRAM .....................................................312
15.17 Sample23: Structured Exception Handling (SEH) .........................................................................314
15.18 Sample24: Semaphores ................................................................................................................316
15.19 Sample25: Static Library ...............................................................................................................317
15.20 Sample26: Order of execution in a task ........................................................................................318
15.21 Sample30: Timing Measurement...................................................................................................320
15.22 Sample31: Functionblock TON in TwinCAT3 C++ ........................................................................321
15.23 Sample35: Access Ethernet ..........................................................................................................322
15.24 Sample37: Archive data ................................................................................................................323
15.25 TcCOM samples ............................................................................................................................324
15.25.1 TcCOM_Sample01_PlcToPlc........................................................................................ 324
TE10006 Version: 1.13
Table of contents
15.25.2 TcCOM_Sample02_PlcToCpp ...................................................................................... 334
15.25.3 TcCOM_Sample03_PlcCreatesCpp.............................................................................. 338
16 Appendix ................................................................................................................................................343
16.1 ADS Return Codes ........................................................................................................................343
16.2 Retain data ....................................................................................................................................348
16.3 Creating and handling C++ projects and modules ........................................................................350
16.4 Creating and handling TcCOM modules .......................................................................................354
TE1000 7Version: 1.13
Table of contents
TE10008 Version: 1.13
Foreword
1 Foreword
1.1 Notes on the documentation
This description is only intended for the use of trained specialists in control and automation engineering who
are familiar with applicable national standards.
It is essential that the documentation and the following notes and explanations are followed when installing
and commissioning the components.
It is the duty of the technical personnel to use the documentation published at the respective time of each
installation and commissioning.
The responsible staff must ensure that the application or use of the products described satisfy all the
requirements for safety, including all the relevant laws, regulations, guidelines and standards.
Disclaimer
The documentation has been prepared with care. The products described are, however, constantly under
development.
We reserve the right to revise and change the documentation at any time and without prior announcement.
No claims for the modification of products that have already been supplied may be made on the basis of the
data, diagrams and descriptions in this documentation.
Trademarks
Beckhoff®, TwinCAT®, EtherCAT®, EtherCAT G®, EtherCAT G10®, EtherCAT P®, Safety over EtherCAT®,
TwinSAFE®, XFC®, XTS® and XPlanar® are registered trademarks of and licensed by Beckhoff Automation
GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own
purposes could violate the rights of the owners.
Patent Pending
The EtherCAT Technology is covered, including but not limited to the following patent applications and
patents:
EP1590927, EP1789857, EP1456722, EP2137893, DE102015105702
with corresponding applications or registrations in various other countries.
EtherCAT® is a registered trademark and patented technology, licensed by Beckhoff Automation GmbH,
Germany
Copyright
© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to
others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a
patent, utility model or design.
TE1000 9Version: 1.13
Foreword
1.2 Safety instructions
Safety regulations
Please note the following safety instructions and explanations!
Product-specific safety instructions can be found on following pages or in the areas mounting, wiring,
commissioning etc.
Exclusion of liability
All the components are supplied in particular hardware and software configurations appropriate for the
application. Modifications to hardware or software configurations other than those described in the
documentation are not permitted, and nullify the liability of Beckhoff Automation GmbH & Co. KG.
Personnel qualification
This description is only intended for trained specialists in control, automation and drive engineering who are
familiar with the applicable national standards.
Description of symbols
In this documentation the following symbols are used with an accompanying safety instruction or note. The
safety instructions must be read carefully and followed without fail!
DANGER
Serious risk of injury!
Failure to follow the safety instructions associated with this symbol directly endangers the life and health of
persons.
WARNING
Risk of injury!
Failure to follow the safety instructions associated with this symbol endangers the life and health of persons.
CAUTION
Personal injuries!
Failure to follow the safety instructions associated with this symbol can lead to injuries to persons.
NOTE
Damage to the environment or devices
Failure to follow the instructions associated with this symbol can lead to damage to the environment or
equipment.
Tip or pointer
This symbol indicates information that contributes to better understanding.
TE100010 Version: 1.13
2 Overview
This chapter is all about TwinCAT 3 implementation in C/C++. The most important chapters are:
• Start from scratch
Which platforms are supported? Additional installations to implement TwinCAT 3 C++ modules?
Find all answers in Requirements [}20] and Preparation [}22]. Limitations are documented here
[}166].
• Quick start [}60]
This is a “less than five minutes sample” to create a simple incrementing counter in C++ being
executed cyclically. Counter value will be monitored and overwritten, debugging capabilities will be
presented etc.
• MODULES [}37]
Modularization the basic philosophy of TwinCAT 3. Especially for C++ Modules it is required to
understand the module concept of TwinCAT 3.
Minimum is to read one article about the architecture of TwinCAT modules.
• Wizards [}99]
Documentation of visual components of the TwinCAT C++ environment.
This includes on the one hand tools for creating projects and on the other hand tools for editing module
and configuring instances of modules.
Overview
• Programming Reference [}156]
This chapter contains detailed information for programming in TwinCAT C++. For Example Interfaces
as well as other TwinCAT provided functions for ADS communication and helper methods are located
here.
• The How to …? [}233] Chapter contains useful hints while working with TwinCAT C++.
• Samples
Some Interfaces and their usage is best described by working code, which is provided as download
including source code and solution.
TE1000 11Version: 1.13
Introduction
3 Introduction
The method of emulating classic automation devices such as programmable logic controllers (PLC) and
numerical controllers (NC) as software on powerful standard hardware has been the state of the art for many
years and is now practiced by many manufacturers.
There are many benefits, but the most important is without doubt the fact that the software is mostly
hardware-independent. This means, firstly, that the performance of the hardware can be specially adapted to
the application and, secondly, that you can automatically benefit from its further development.
This particularly applies to PC hardware, whose performance is still increasingly at a dramatically fast rate.
The relative independence from a supplier that results from this separation of software and hardware is also
very important for the user.
Since the PLC and Motion Control – and possibly other automation components – remain independent logic
function blocks with this method, there are only a few changes in the application architecture in comparison
with classic automation technology.
The PLC determines the machine's logical processes and transfers the implementation of certain axis
functions to the Motion Control. On account of the improved performance of the controllers and the
possibility to use higher-level programming languages (IEC 61131-3), even complex machines can be
automated in this way.
Modularization
In order to master the complexity of modern machines and at the same time to reduce the necessary
engineering expenditure, many machine manufacturers have begun to modularize their machines. Individual
functions, assemblies or machine units are thereby regarded as modules, which are as independent as
possible and are embedded into the overall system via uniform interfaces.
Ideally a machine is then structured hierarchically, whereby the lowest modules represent the simplest,
continually reusable basic elements. Joined together they form increasingly complex machine units, up to the
highest level where the entire machine is created. Different approaches are followed when it comes to the
control system aspects of machine modularization. These can be roughly divided into a decentralized and a
centralized approach.
In the local approach, each machine module is given its own controller, which determines the PLC functions
and possibly also the motion functions of the module.
The individual modules can be put into operation and maintained separately from one another and scaled
relatively independently. The necessary interactions between the controllers are coordinated via
communication networks (fieldbuses or Ethernet) and standardized via appropriate profiles.
The central approach concentrates all control functions of all modules in the common controller and uses
only very little pre-processing intelligence in the local I/O devices. The interactions can occur much more
directly within the central control unit, as the communication paths become much shorter. Dead times do not
occur and use of the control hardware is much more balanced, which reduces overall costs.
However, the central method also has the disadvantage that the necessary modularization of the control
software is not automatically specified. At the same time, the possibility of being able to access any
information from other parts of the program in the central controller obstructs the module formation and the
reusability of this control software in other applications. Since no communication channel exists between the
control units, an appropriate profile formation and standardization of the control units frequently fall by the
wayside.
The best of both worlds
The ideal controller for modular machines uses elements from decentralized and centralized control
architecture. A central, powerful computer platform of the most general kind possible serves 'as always' as
the control hardware.
The benefits of centralized control technology:
• low overall costs
• available
TE100012 Version: 1.13
Introduction
• fast, modular fieldbus system (keyword: EtherCAT)
• and the possibility to access all information in the system without loss of communication
are decisive arguments.
The above-mentioned benefits of a decentralized approach can be implemented in the centralized control
system by means of suitable modularization of the control software.
Instead of allowing a large, complex PLC program and an NC with many axes to run, many small ‘controllers’
can co-exist in a common runtime on the same hardware with relative independence from one another. The
individual control modules are self-contained and make their functions available to the environment via
standard interfaces, or they use corresponding functions of other modules or the runtime.
A significant profile is created through the definition of these interfaces and the standardization of the
corresponding parameters and process data. Since the individual modules are implemented in a runtime,
direct calls of other modules are also possible – once again via corresponding standard interfaces. In this
way the modularization can take place within sensible limits without communication losses occurring.
During the development or commissioning of individual machine modules, the associated control modules
can be created and tested on any control hardware with the appropriate runtime. Missing connections to
other modules can be emulated during this phase. On the complete machine they are then instanced
together on the central runtime, which only needs to be dimensioned such that the resource requirements of
all instanced modules (memory, tasks and computing power) are fulfilled.
TwinCAT 3 Run-Time
The TwinCAT runtime offers a software environment in which TwinCAT modules are loaded, implemented
and managed. It offers additional basic functions so that the system resources can be used (memory, tasks,
fieldbus and hardware access etc.). The individual modules do not have to be created using the same
compiler and can therefore be independent of one another and can originate from different manufacturers.
A series of system modules is automatically loaded at the start of the runtime, so that their properties are
available to other modules. However, access to the properties of the system modules takes place in the
same way as access to the properties of normal modules, so that it is unimportant to the modules whether
the respective property is made available by a system module or a normal module.
TE1000 13Version: 1.13
Introduction
In contrast to the PLC, where customer code is executed within a runtime environment, TwinCAT C++
modules are not within such a hosted environment. As a consequence TwinCAT C++ modules are executed
as Kernel Modules (.sys) – thus they are built with the kernel mode libraries.
3.1 From conventional user mode programming to realtime programming in TwinCAT
This article describes the conceptual differences between standard user mode programming in a
programming language such as C++, C# or Java, and real-time programming in TwinCAT.
The article particularly focuses on real-time programming with TwinCAT C++, because this is where previous
knowledge with C++ programming comes to the fore and the sequence characteristics of the TwinCAT realtime system have to be taken into account.
TE100014 Version: 1.13
Introduction
With conventional user mode programming, e.g. in C#, a program is created, which is then executed by an
operating system.
The program is started by the operating system and can run independently, i.e. it has full control over its own
execution, including aspects such as threading and memory management. In order to enable multitasking,
the operating system interrupts such a program at any time and for any period. The program does not
register such an interruption. The operating system must ensure that such interruptions remain unnoticed by
the user. The data exchange between the program and its environment is event-driven, i.e. non-deterministic
and often blocking.
The behavior is not adequate for execution under real-time conditions, because the application itself must be
able to rely on the available resources in order to be able to ensure real-time characteristics (response
guarantees).
TE1000 15Version: 1.13
Introduction
The basic idea of PLC is therefore adopted for TwinCAT C++: The TwinCAT real-time system manages the
real-time tasks, handles the scheduling and cyclically calls an entry point in the program code. The program
execution must be completed within the available cycle length and return the control. The TwinCAT system
makes the data from the I/O area available in the process images, so that consistent access can be
guaranteed. This means that the program code itself cannot use mechanisms such as threading.
TE100016 Version: 1.13
Concurrency
Introduction
With conventional programming in user mode, concurrency is controlled by the program. This is where
threads are started, which communicate with each other. All these mechanisms require resources, which
have to be allocated and enabled, which can compromise the real-time capability. The communication
between the threads is event-based, so that a calling thread has no control over the processing time in the
called thread.
TE1000 17Version: 1.13
Introduction
In TwinCAT, tasks are used for calling modules, which therefore represents concurrency. Tasks are
assigned to a core; they have cycle times and priorities, with the result that a higher-priority task can interrupt
a lower-priority task. If several cores are used, tasks are executed concurrently in practice.
Modules can communicate with each other, so that data consistency has to be ensured in concurrency
mode.
Data exchange across task boundaries is enabled through mapping, for example. When direct data access
via methods is used, it must be protected through Critical sections, for example.
Startup/shutdown behavior
The TwinCAT C++ code is executed in the so-called "Windows kernel context" and the "TwinCAT real-time
context", not as a user mode application.
During startup/shutdown of the modules, code for (de)initialization is initially executed in the Windows kernel
context; only the last phase and the cyclic calls are executed in the TwinCAT real-time context.
Details are described in the "Module state machine [}44]" section.
Memory management
TwinCAT has its own memory management, which can also be used in the real-time context. This memory is
obtained from what is referred to as the "non-paged pool", which is provided by the operating system. In this
memory the TcCOM modules are instantiated with their memory requirement.
TE100018 Version: 1.13
Introduction
In addition, the so-called "router memory" is provided by TwinCAT in this memory area, from which the
TcCOM modules can allocate memory dynamically in the real-time-context (e.g. with the New operator).
If possible, memory should generally be allocated in advance, not in the cyclic code. During each allocation a
check is required to verify that the memory is actually available. For allocations in the cyclic code, the
execution therefore depends on the memory availability.
TE1000 19Version: 1.13
Requirements
4 Requirements
Overview of minimum requirements
The implementation and debugging of TwinCAT 3 C++ modules requires:
The following must be installed on the engineering PC:
• Microsoft Visual Studio 2010 (with Service Pack 1), 2012, 2013 or 2015
Professional, Premium or Ultimate
◦ When installing Visual Studio 2019 or 2017, the Desktop development with C++ option must be
manually selected, as this option is not selected with the automatic installation:
◦
◦ When installing Visual Studio 2015, the Visual C++ development option must be manually
selected, as this option is not selected with the automatic installation:
• TwinCAT 3 installation (XAE engineering)
• XaeShell is sufficient for the integration and use of existing binary C++ modules in a TwinCAT 3 PLC
environment (Visual Studio is not required.)
TE100020 Version: 1.13
Requirements
On the runtime PC:
• IPC or Embedded CX PC with Microsoft operating system (Windows 7 / 10).
• Microsoft Visual Studio does not have to be installed.
• TwinCAT 3 installation (XAR runtime)
Limitations on the runtime PC
• TwinCAT 3.0 only supports 32-bit operating systems as target platform (runtime PC).
TC3.0 can be used as engineering platform on x64 PCs. The program can be transferred to a 32bit
(x86) remote PC over the network and executed there.
• TwinCAT 3.1 also supports x64-bit operating systems as target platform (runtime PC). To do this, the
drivers must be signed as documented under Driver signing [}25].
• The runtime PC must be either a Windows 7 or Windows 10 system.
Also see about this
2 "Microsoft Windows Driver Kit (WDK)" installation (only <= Build 4022) [}22]
TE1000 21Version: 1.13
Preparation - only once
5 Preparation - only once
A PC for the engineering of TwinCAT C++ modules must be prepared. You only have to carry out these
steps once:
• Install the Microsoft Windows Driver Kit (WDK) [}22].
• Configure the TwinCAT Basis [}24] as well as the configuration and platform [}25] toolbar.
• On x64 PCs, sign modules so that they can be run; see Documentation for the setup of a test signing
[}25].
• If the operating system of the target system requires enhanced validation for drivers, for example,
through a SecureBoot, carry out a corresponding signing [}31] with Microsoft.
5.1 "Microsoft Windows Driver Kit (WDK)" installation (only <= Build 4022)
NOTE
WDK installation only up to TwinCAT 3.1 Build 4022
The installation of the WDK described here is only necessary up to TwinCAT 3.1. Build 4022. From Build
4024.0, either the WDK must be uninstalled or the previously set system variable WINDDK7 must be renamed so that TwinCAT ignores the WDK.
Installation of WDK 7 for TwinCAT 3.1. 4022 and earlier
The installation is only necessary for the TwinCAT 3 engineering environment in order to be able to create
and edit C++ modules. The WDK installation is not required on the target system (XAR).
1. Download the Windows Driver Kit 7.1 from the Microsoft Download Center https://www.microsoft.com/
en-us/download/details.aspx?id=11800
2. Following the download, either burn a CD of the downloaded ISO image or use a virtual (software-based)
CD drive.
3. Start KitSetup.exe of the ISO image that has been downloaded or burnt on CD (on Windows 7 PCs, start
the installation with Run As Administrator...).
TE100022 Version: 1.13
Preparation - only once
4. Select the option Build Environment – none of the other components are required by TwinCAT 3 – and
click on OK to continue.
5. After accepting the Microsoft EULA license, select the destination folder for the installation.
By default, the root folder "C:\" is selected – i.e. "C:\WinDDK\7600.16385.1" is proposed.
The digits "7600…." may be different in the case of a newer version of the Windows Driver Kit.
6. Start the installation with OK.
7. In future TwinCAT 3 will take care of the following step, but for now it must be done manually: Navigate
to Start-> Control Panel -> System and select Advanced system settings.
8. Select the Advanced tab and then click on Environment Variables…
TE1000 23Version: 1.13
Preparation - only once
9. In the lower area of System variables, select New.. and enter the following information:
Variable name "WINDDK7"
Variable value "C:\WinDDK\7600.16385.1"
The path may differ with a different version of the Windows Driver Kit or if a different installation path is
specified.
10. Following the installation, log in again or restart the PC to confirm the new environment variable settings.
Also see about this
2 Programming Reference [}156]
5.2 Visual Studio - TwinCAT XAE Base toolbar
Efficient engineering through TwinCAT XAE base toolbar
TwinCAT 3 integrates its own toolbar in the Visual Studio menu for better efficiency. It assists you in the
creation of C++ projects. This toolbar is automatically added to the Visual Studio menu by the TwinCAT 3
setup. If you wish to add it manually, however, do the following:
1. Open the View menu and select Toolbars\TwinCAT XAE Base
TE100024 Version: 1.13
Preparation - only once
ð The selected toolbar appears below the menu.
5.3 Prepare Visual Studio - Configuration and Platform toolbar
Add the toolbar "Solution Configuration and Solution Platform"
With the Configuration and Platform toolbar you can specify the target platform for the creation of your
project. This toolbar is automatically added to the Visual Studio menu by the TwinCAT 3 setup. If you wish to
add it manually, however, do the following:
1. Open the View menu and select Toolbars\Customize.
2. Navigate to the Commands tab.
3. Activate the Toolbar option field and then select the Standard toolbar from the list.
4. Click on Add Command...
5. Select the Build category, select the Solution Configurations command and then click on OK.
6. Repeat the last step for the Solution Platforms command.
7. Click on Close.
ð The two commands now appear below the menu bar.
5.4 Driver signing
TwinCAT C++ modules must be signed with a certificate so that they can be executed.
The signature ensures that only C++ software whose origin can be traced is executed on productive
systems.
For test purposes, certificates that cannot be verified can be used for signing. However, this is only possible
if the operating system is in test mode so that these certificates are not used on productive systems.
Engineering requires no signing
Only the execution requires certificates - the engineering does not.
TE1000 25Version: 1.13
Preparation - only once
There are two ways to load modules, different certificates are used for signing:
• Operating system: The C++ modules are loaded as normal kernel drivers and must therefore also have
a signature.
◦ With TwinCAT 3.1. 4022 or earlier, only this procedure is available.
◦ Windows 7 (Embedded) x86 (32bit) does not require signing.
• TwinCAT: The C++ modules are loaded by the TwinCAT runtime system and must be signed with a
TwinCAT user certificate.
◦ With TwinCAT 3.1. 4024 and higher, this method is also available.
◦ This procedure is required to perform new functions such as versioned C++ projects [}49] and
thus also the C++ Online Change [}164].
Since a published module should be executable on various PCs, signing is always necessary for publishing.
Organizational separation of development and production software
Beckhoff recommends working organizationally with (at least) two certificates.
1. A certificate which is not countersigned, thus the test mode is needed for the development process.
This certificate can also be issued individually by each developer.
2. Only the software that has passed the corresponding final tests is signed by a countersigned certificate. This software can thus also be installed on machines and delivered.
Such a separation of development and operation ensures that only tested software runs on productive
systems.
5.4.1 Operating system
For the implementation of TwinCAT 3 C++ modules on x64 platforms, the driver (*.sys file) must be signed
with a certificate if it is to be loaded by the operating system.
The signature, which is automatically executed during the TwinCAT 3 build process, is used by 64-bit
Windows operating systems for the authentication of the drivers.
A certificate is required to sign a driver. This Microsoft documentation describes the process and
background knowledge for obtaining a test and release certificate that is accepted by 64-bit Windows
operating systems.
To use such a certificate in TwinCAT 3, configure the step after compiling your x64 build target as
documented in "Creating a test certificate for test mode [}27]".
Test certificates
For testing purposes, self-signed test certificates can be created and used without technical limitations.
The following tutorials describe how to activate this option.
To create drivers with real certificates for production machines, this option must be disabled.
• Creating a test certificate for test mode [}27]
• Delete (test) certificates [}29]
Further references:
MSDN, test certificates (Windows driver),
http://msdn.microsoft.com/en-us/library/windows/hardware/ff553457(v=vs.85).aspx
MSDN, MakeCert test certificates (Windows driver),
http://msdn.microsoft.com/en-us/library/windows/hardware/ff548693(v=vs.85).aspx
TE100026 Version: 1.13
Preparation - only once
5.4.1.1 Test signing
Overview
Implementing TwinCAT 3 C++ modules for x64 platforms requires signing the driver with a certificate.
This article describes how to create and install a test certificate for testing a C++ driver.
Note the procedure when creating test certificates
Developers may have a wide range of tools for creating certificates. Please follow this description
exactly, in order to activate the test certificate mechanism.
The following commands must be executed from a command line that has been opened in either way:
• Visual Studio 2010 / 2012 prompt with administrator rights. (Via: All Programs -> Microsoft
Visual Studio 2010/2012 -> Visual Studio Tools -> Visual Studio Command Prompt, then right-click
Run as administrator)
• Developer Command Prompt of Visual Studio 2017 / 2019 with administrator rights. (Via: All
Programs -> Visual Studio 2017 -> Visual Studio Command Prompt for VS 2017/2019, then right-
click on Run as administrator)
• Only if the WINDDK has been installed:
Normal prompt (Start->Command Prompt) with administrator rights, then change to directory
%WINDDK7%\bin\x86\, which contains the corresponding tools.
1. On XAE:
in the engineering system enter the following command in the Visual Studio 2010 / 2012 prompt with
administrator rights (see note above):
makecert -r -pe -ss PrivateCertStore -n CN=MyTestSigningCert
MyTestSigningCert.cer
(If you do not have access rights to the PrivateCertStore, you can use a different location. This
must also be used in the PostBuild event, as described here. [}30])
ð This is followed by creation of a self-signed certificate, which is stored in the file
"MyTestSigningCert.cer" and in the Windows Certificate Store.
ð Check the result with mmc (Use File->Add/Remove Snap-in->Certificates):
2. On XAE:
configure the certificate so that it is recognized by TwinCAT XAE on the engineering system.
Set the environment variable TWINCATTESTCERTIFICATE to "MyTestSigningCert" in the engineering
system or edit the post build event of Debug|TwinCAT RT (x64) and Release|TwinCAT RT (x64).
The name of the variable is NOT the name of the certificate file, but the CN name (in this case
MyTestSigningCert).
NoteFrom TwinCAT 3.1 4024.0, the configuration of the certificate to be used is carried out under Tc
Sign in the project properties. To use signing via the operating system, as described here, please
pay attention to the project settings:
TE1000 27Version: 1.13
Preparation - only once
3. On XAR (and XAE, if local test)
activate the test mode so that Windows can accept the self-signed certificates. This can be done on both
engineering systems (XAE) and runtime systems (XAR).
4. Execute the following using the "Run as administrator" option:
bcdedit /set testsigning yes
and restart the target system.
ð If test signing mode is enabled, this is displayed at the bottom right of the desktop. The PC now
accepts all signed drivers for execution.
5. You may have to switch off "SecureBoot" for this, which can be done in the bios.
6. Test whether a configuration with a TwinCAT module implemented in a TwinCAT C++ driver can be
enabled and started on the target system.
TE100028 Version: 1.13
ð Compilation of the x64 driver generates the following output:
Preparation - only once
References:
MSDN, test certificates (Windows driver)
MSDN, MakeCert test certificates (Windows driver),
Also see about this
2 TwinCAT C++ Project properties [}157]
2 Tc Sign [}161]
5.4.1.2 Delete test certificate
This article is about how to delete a test certificate.
Overview
A certificate can be deleted with the Microsoft Management Console:
1. Start the management console MMC.exe via the Start menu or the user interface.
TE1000 29Version: 1.13
Preparation - only once
2. Click in the menu on File -> Add/Remove Snap-in.. and select the certificate snap-in for the current
user; conclude with OK.
ð The certificates are listed in the node under PrivateCertStore/Certificates.
3. Select the certificate to be deleted.
5.4.1.3 Customer Certificates
Configuration Certificate
From TwinCAT 3.1 4024.0, the configuration of the certificate to be used is carried out under Tc
Sign [}161] in the project properties.
If the TwinCAT C++ class wizard is used, the project is prepared for x64 targets using the test certificate
procedure described above.
This test signing system can be used for the entire engineering and test process.
TE100030 Version: 1.13
Loading...