Beckhoff TwinCAT 3 C/C++ Manual (Version 1.19.1) — Programming Guide PDF (EN)

Table of contents

Table of contents Table of contents 1 Foreword.................................................................................................................................................... 7 1.1 Notes on the documentation ............................................................................................................. 7 1.2 For your safety .................................................................................................................................. 8 1.3 Notes on information security............................................................................................................

9 1.4 Documentation issue status .............................................................................................................. 9 2 Overview .................................................................................................................................................. 10 3 Introduction ............................................................................................................................................. 11 3.1 Difference between user mode and real time programming ...........................................................

13 4 Installation ............................................................................................................................................... 17 4.1 System requirements ...................................................................................................................... 17 4.2 Installation ....................................................................................................................................... 17 5 Preparation - only once ..........................................................................................................................

20 5.1 Visual Studio - TwinCAT XAE Base toolbar.................................................................................... 20 5.2 Module signing ................................................................................................................................ 20 5.2.1 TwinCAT .......................................................................................................................... 21 5.2.2 Operating system.............................................................................................................

30 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 Starting Modules ............................................................................................................................. 50 7.3 TwinCAT Loader .............................................................................................................................

50 7.3.1 Test signing...................................................................................................................... 51 7.3.2 Encrypting Modules.......................................................................................................... 53 7.3.3 Return Codes................................................................................................................... 54 7.3.4 TcSignTool - Storage of the certificate password outside the project.............................. 55 8 TwinCAT C++ development....................................................................................................................

56 9 Quick Start ............................................................................................................................................... 58 9.1 Create TwinCAT 3 project............................................................................................................... 58 9.2 Create TwinCAT 3 C++ project ....................................................................................................... 59 9.3 TwinCAT 3 C++ Configure project ..................................................................................................

63 9.4 Implement TwinCAT 3 C++ project ................................................................................................. 64 9.5 Publish TwinCAT 3 C++ project in version 0.0.0.1.......................................................................... 66 9.6 Implement and publish TwinCAT 3 C++ project version 0.0.0.2 ..................................................... 66 9.7 Create TwinCAT 3 C++ Module instance........................................................................................ 68 9.8 TwinCAT 3 enable C++ debugger...................................................................................................

70 9.9 Create a TwinCAT task and apply it to the module instance .......................................................... 71 9.10 Activating a TwinCAT 3 project ....................................................................................................... 73 9.11 TwinCAT 3 C++ Implement project Online Change ........................................................................ 74 TwinCAT 3 3 Version: 1.19.1

Стр. 3

Table of contents

Table of contents 10 Debugging................................................................................................................................................ 75 10.1 Details of Conditional Breakpoints .................................................................................................. 78 10.2 Visual Studio tools........................................................................................................................... 79 10.3 Working with TwinCAT Task Dumps...............................................................................................

81 10.4 Examining dump files using WinDbg............................................................................................... 82 10.5 Debugging the state machine with the Usermode Runtime ............................................................ 83 11 Wizards .................................................................................................................................................... 85 11.1 TwinCAT C++ Project Wizard .........................................................................................................

85 11.2 TwinCAT Module Class Wizard ...................................................................................................... 86 11.3 TwinCAT Module Class Editor (TMC) ............................................................................................. 88 11.3.1 Overview .......................................................................................................................... 90 11.3.2 Basic Information ............................................................................................................. 91 11.3.3 Data Types.......................................................................................................................

91 11.3.4 Modules.......................................................................................................................... 109 11.4 TwinCAT Module Instance Configurator ....................................................................................... 129 11.4.1 Object............................................................................................................................. 130 11.4.2 Context........................................................................................................................... 131 11.4.3 Parameter (Init) ..............................................................................................................

131 11.4.4 Data Area....................................................................................................................... 132 11.4.5 Interfaces ....................................................................................................................... 132 11.4.6 Interface Pointer............................................................................................................. 132 11.4.7 Data Pointer ................................................................................................................... 132 11.5 Customer-specific project templates .............................................................................................

133 11.5.1 Overview ........................................................................................................................ 133 11.5.2 Files involved ................................................................................................................. 134 11.5.3 Transformations ............................................................................................................. 134 11.5.4 Notes on handling ..........................................................................................................

136 12 Programming Reference ...................................................................................................................... 139 12.1 TwinCAT C++ Project properties .................................................................................................. 140 12.1.1 Tc SDK........................................................................................................................... 142 12.1.2 Tc Extract Version..........................................................................................................

143 12.1.3 Tc Publish ...................................................................................................................... 143 12.1.4 Tc Sign........................................................................................................................... 144 12.2 File Description ............................................................................................................................. 145 12.3 Online Change ..............................................................................................................................

148 12.4 Limitations for TwinCAT C++ modules.......................................................................................... 149 12.5 Memory allocation ......................................................................................................................... 150 12.6 Static variables.............................................................................................................................. 152 12.7 Multi-task data access synchronization.........................................................................................

153 12.7.1 CriticalSections .............................................................................................................. 154 12.7.2 Semaphores................................................................................................................... 156 12.7.3 FIFO template classes ................................................................................................... 157 12.8 Interfaces ...................................................................................................................................... 158 12.8.1 Interface ITcPostCyclicCaller.........................................................................................

159 12.8.2 Return values................................................................................................................. 161 TwinCAT 3 4 Version: 1.19.1

Стр. 4

Table of contents

Table of contents 12.8.3 Interface ITcCyclic.......................................................................................................... 161 12.8.4 Interface ITcCyclicCaller ................................................................................................ 162 12.8.5 Interface ITcFileAccess.................................................................................................. 164 12.8.6 Interface ITcFileAccessAsync........................................................................................ 171 12.8.7 Interface ITcIoCyclic.......................................................................................................

172 12.8.8 Interface ITcIoCyclicCaller ............................................................................................. 174 12.8.9 ITComOnlineChange interface....................................................................................... 175 12.8.10 ITComObject interface ................................................................................................... 177 12.8.11 ITComObject interface (C++ convenience).................................................................... 181 12.8.12 Interface ITcPostCyclic ..................................................................................................

182 12.8.13 Interface ITcRTimeTask................................................................................................. 183 12.8.14 Interface ITcTask ........................................................................................................... 183 12.8.15 Interface ITcTaskNotification.......................................................................................... 187 12.9 ADS Communication..................................................................................................................... 189 12.8.16 Interface ITcUnknown ....................................................................................................

187 12.9.1 AdsReadDeviceInfo ....................................................................................................... 190 12.9.2 AdsRead ........................................................................................................................ 192 12.9.3 AdsWrite......................................................................................................................... 194 12.9.4 AdsReadWrite................................................................................................................ 196 12.9.5 AdsReadState................................................................................................................

198 12.9.6 AdsWriteControl............................................................................................................. 200 12.9.7 AdsAddDeviceNotification.............................................................................................. 201 12.9.8 AdsDelDeviceNotification............................................................................................... 203 12.10 Mathematical Functions ................................................................................................................ 206 12.9.9 AdsDeviceNotification ....................................................................................................

205 12.11 Time Functions.............................................................................................................................. 207 12.12 STL / Containers ........................................................................................................................... 208 12.13 Error messages - understanding................................................................................................... 209 12.14 Module messages for the Engineering (logging / tracing)............................................................. 209 13 How to...?

............................................................................................................................................... 213 13.1 Using the Automation Interface..................................................................................................... 213 13.2 Windows 10 as target system up to TwinCAT 3.1 Build 4022.2 ................................................... 213 13.3 Publishing modules on the command line..................................................................................... 213 13.4 Clone.............................................................................................................................................

213 13.5 Access Variables via ADS............................................................................................................. 214 13.6 TcCallAfterOutputUpdate for C++ modules .................................................................................. 214 13.7 Order determination of the execution in a task ............................................................................. 214 13.8 Setting version/vendor information................................................................................................ 214 13.9 Renaming TwinCAT C++ projects.................................................................................................

216 13.10 Delete Module ............................................................................................................................... 218 13.11 Add revision control and Online Change subsequently ................................................................ 219 13.11.1 C++ Project -> Revision control ..................................................................................... 219 13.12 Initialization of TMC-member variables......................................................................................... 227 13.11.2 C++ Module -> OnlineChange .......................................................................................

222 13.13 Using PLC strings as method parameters .................................................................................... 227 13.14 Third Party Libraries...................................................................................................................... 228 TwinCAT 3 5 Version: 1.19.1

Стр. 5

Table of contents

Table of contents 13.15 Linking via TMC editor (TcLinkTo) ................................................................................................ 228 13.16 Online Change per ADS................................................................................................................ 230 14 Troubleshooting.................................................................................................................................... 232 14.1 Using C++ classes in TwinCAT C++ module ................................................................................

232 14.2 Activation – “invalid object id” (1821/0x71d) ................................................................................. 232 15 C++-samples.......................................................................................................................................... 233 15.1 Sample01: Cyclic module with IO ................................................................................................. 236 15.2 Sample02: Cyclic C++ logic, which uses IO from the IO Task...................................................... 237 15.3 Sample03: C++ as ADS server .....................................................................................................

237 15.3.1 Sample03: TC3 ADS Server written in C++................................................................... 238 15.4 Sample05: C++ CoE access via ADS ........................................................................................... 246 15.3.2 Sample03: ADS client UI in C# ...................................................................................... 242 15.5 Sample06: UI-C#-ADS client uploading the symbolic from module .............................................. 247 15.6 Sample07: Receiving ADS Notifications ....................................................................................... 252 15.7 Sample08:

provision of ADS-RPC ................................................................................................ 253 15.8 Sample10: module communication: Using data pointer................................................................ 256 15.9 Sample11: Module communication: method call PLC module to C++ module ............................. 257 15.9.1 TwinCAT 3 C++ module providing methods .................................................................. 258 15.9.2 Calling methods offered by another module via PLC..................................................... 272 15.10 Sample11a: Module communication: Method call C++ module to C++ module ...........................

284 15.11 Sample12: module communication: Using IO mapping ................................................................ 285 15.12 Sample13: Module communication: Method call C++ module to PLC module ............................. 286 15.13 Sample19: Synchronous File Access............................................................................................ 289 15.14 Sample20: FileIO-Write................................................................................................................. 290 15.15 Sample20a: FileIO-Cyclic Read / Write......................................................................................... 290 15.16 Sample22:

Automation Device Driver (ADD): Access DPRAM..................................................... 292 15.17 Sample23: Structured Exception Handling (SEH)......................................................................... 293 15.18 Sample24: Semaphores................................................................................................................ 295 15.19 Sample25: Static Library ............................................................................................................... 296 15.20 Sample26: Order of execution in a task ........................................................................................ 298 15.21 Sample30:

Timing Measurement .................................................................................................. 300 15.22 Sample31: Functionblock TON in TwinCAT3 C++........................................................................ 301 15.23 Sample35: Access Ethernet.......................................................................................................... 302 15.24 Sample37: Archive data ................................................................................................................ 303 15.25 TcCOM samples............................................................................................................................

304 15.25.1 TcCOM_Sample01_PlcToPlc ........................................................................................ 304 15.25.2 TcCOM_Sample02_PlcToCpp....................................................................................... 314 15.25.3 TcCOM_Sample03_PlcCreatesCpp .............................................................................. 318 16 Appendix................................................................................................................................................ 323 16.1 ADS Return Codes........................................................................................................................

323 16.2 Retain data.................................................................................................................................... 326 16.3 Creating and handling C++ projects and modules ........................................................................ 329 16.4 Creating and handling TcCOM modules ....................................................................................... 333 16.5 Third-party components ................................................................................................................ 337 TwinCAT 3 6 Version: 1.19.1

Стр. 6