TwinCAT 2 to TwinCAT 3 Conversion

TwinCAT 3 is Beckhoff’s flagship software suite for configuring and programming Beckhoff’s PC-based hardware and controllers. Introduced as a significant upgrade over TwinCAT 2, it offers a wide array of technology modules, debugging tools, and Visual Studio integration to make programming even easier.

With the advances in TwinCAT 3 and the eventual discontinuation of TwinCAT 2 support in the coming years, now is a great time to upgrade your TwinCAT 2 projects to TwinCAT 3. TwinCAT 2 requires a 32-bit operating system, and as of early 2026, most 32-bit operating systems are nearing end-of-support. Luckily, conversion is an easy process, and most conversions can be accomplished seamlessly with just a few clicks.

This guide provides step-by-step instructions for upgrading your TwinCAT 2 Project to TwinCAT 3, including information on converting Safety and Motion projects.

Section 1: Hardware Selection / Considerations:

1. Take inventory of your controls hardware, including controllers, I/O, drives, and checking support/sales status. Beckhoff publishes a list of End-of-Life products along with successor products on their Service Products page.
   • Reach out to your local Beckhoff Sales Engineer for more personalized recommendations on product upgrade paths.
2. Upgrade any legacy K-Bus I/O to EtherCAT, which is faster, more performant, and easier to maintain. Alternatively, consider replacing any K-Bus IO couplers with the BK1120, which allows an upgrade to EtherCAT without re-terminating any I/O points.
3. Consider your safety system as part of the upgrade plan. Some TwinCAT 2 systems use the KL6904 Safety Controller, which is not programmable within TwinCAT 3 and will not be convertible to a TwinCAT 3 Project.
   • This should be replaced with a TwinSAFE Logic-capable EtherCAT terminal, like the EL6910.

What You’ll Need:

If you are interested in converting an entire TC2 Project (PLC project and related Motion, IO, and System information), you will need the TC2 project’s .tsm/.wsm, .pro files, and any referenced libraries. Then follow the instructions in Section 2.

If you only wish to convert a library or a PLC project by itself, you will only need the .pro or .lib file) and to follow the instructions in Section 3.

Please note: Beckhoff provides some additional information on restrictions and warnings on TC2 Conversion projects on Infosys. These can help resolve some compilation errors. 

Section 2: TwinCAT Project Conversion (System, Motion, IO, PLC):

1. Ensure that you have the .tsm and .pro files for the TwinCAT 2 Project
   • The TwinCAT 2 project must successfully compile before attempting the conversion.
   • If you have a .wsm file instead of .tsm, the file can be easily converted using TwinCAT System Manager by clicking “Save As…” and choosing the .tsm file format.
2. Ensure that you have the .lib file for any custom libraries used in the Tc2 project available for conversion
   • Any missing libraries will need to be re-created or replaced
3. If you are planning on using TwinCAT 3 4026, the conversion from TwinCAT 2 MUST occur in 4024 first. After conversion, the 4024 project can then be migrated to 4026.
   • This guide will be for converting using TwinCAT 3 4024 installed through the Full XAE Installer.
   • Doing the conversion using an Engineering PC with TwinCAT Package Manager may be possible with the 4024 Remote Manager, but for the smoothest process, use an Engineering PC with 4024 installed.
4. Create a new XAE Shell project for the new TC3 Project
5. Right-click the XAE Project and select “Load Project from TwinCAT 2.XX Version …”
   • 
   • Note: By loading the project here, the .tsm project will also be converted.
     • If you want to convert only the PLC code (.pro file), that is detailed in section 3: “Convert TC2 PLC Code / Libraries to TC3.
6. In the pop-up window, select the .tsm file of the TwinCAT 2 Project
   • Reminder: If you have a .wsm file, this needs to be re-saved as a .tsm file in TwinCAT System Manager (Tc2 IDE)
   • 
7. Select OK in the confirmation pop-up
   • 
8. XAE Shell will now begin converting the project
9. If there are any custom libraries in the TC2 Project, you will receive the following warning message that it cannot find certain libraries. Please press no.
   • 
   • Any libraries with available source code (.lib file) can be converted and added to the project later in the guide.
10. A new pop-up will appear with a list of all missing libraries
    • 
11. During the conversion, there may be unrestored links. Press Yes to keep this information.
    • 
    • Later in the guide, we will go through this list to ensure no IO is unlinked.
12. After this, information in SYSTEM, MOTION, PLC, Visu, and I/O should be populated from the converted project.
    • I recommend going through the project to make sure there are no missing files or IO that were missed in the conversion.
13. Congratulations! Most of the project is now converted. Now, we just need to resolve any issues that came from the conversion.
14. If there were any external libraries in the TC2 Project that were not converted, we will add them now.
    • If no external libraries need to be converted, skip to Step 20.
15. Follow the instructions in section 3 “Convert TC2 PLC Code / Libraries to TC3” below to convert the library. Once complete, return to this step.
16. After converting the external library, right-click the library’s .plcproj and click “Save As Library” or “Save as Library and Install…”
    • 
17. You may get a warning and be asked to fill in Library Information. If so, fill out the 3 bolded sections and click Save.
    • 
18. Try “Save as Library …” or “Save as Library and Install …” again
    • After this, the library should now be installed as TwinCat 3 library and can be added to our PLC project.
    • Example of the converted library below:
    • 
19. Once the library has been installed, we can delete the library’s PLC project from our solution.
    • 
20. Once all external libraries have been converted and installed, we can now perform some library management.
    • Some of the Beckhoff-provided libraries may be obsolete and should be replaced.
    • One common replacement needed is the TcMC library. This should be upgraded to the TcMC2 Library.
      • Beckhoff provides great documentation on what is needed for this upgrade in the Infosys.
21. This guide does not cover any hardware changes needed, but the IO tree will need to include any changes made to the hardware configuration.
22. After this, you can attempt to compile the code and work through any errors that may come up.
23. Once the code successfully compiles, your PLC Project should be complete!
24. Please check the Safety or Motion sections of this guide to set up those sides of the project.
25. Tips and Tricks:
    • All GVLs will come with attribute {attribute ‘Tc2GvlVarNames’} and all GVL tag references will not include the GVL’s namespace.
      • This can make the converted code unclear, as global variables may appear as local variables.
      • I recommend that you add the GVL namespace to all global variables in the converted code if possible.
      • More info on this attribute can be found on Infosys.

Section 3: Convert TC2 PLC Code / Libraries to TC3 Section:

This section of the guide will cover how to convert a single PLC project or a library file to TwinCAT 3.

1. Ensure that you have the .pro or .lib file that you wish to convert. Start with the .lib files.
2. Open the TwinCAT project that you wish to add the PLC project to.
3. Right-click the PLC Project node, and select “Add Existing Item…”
   • 
4. Then select either the .pro file if PLC project, or the .lib file if converting a library
   • The default selection in the file explorer will allow both file formats.
   • 
5. Once added, XAE Shell will convert the code to TC3, and add it as a separate .plcproj to the solution.
   • 
6. Look through the converted project to ensure there are no errors or mis-conversion. This should be unlikely, as XAE Shell does a good job of converting.
7. If you are converting a library, you can now return to Step 15 of the TwinCAT Project conversion section to continue with the System Configuration conversion.
   • If you are only converting PLC code, you are done!

It is possible even if only converting the .pro file that when importing into TC3 the system will ask about converting libraries. You should go back and convert libraries first, then use the installed library with the second option in the dialog to avoid issues. 

Section 4: Safety / TwinSAFE Projects:

Safety projects are not automatically converted when converting the .tsm file covered in Section 2, so we will need to manually import the project from TwinCAT 2.

Note: If the TwinCAT 2 Project is using the KL6904 Controller, that will need to be replaced as it is not configurable through TwinCAT 3. To see a listing of acceptable terminals with both logic and output like the KL6904, see the TwinSAFE product overview page.

1. Open the TSM file in TwinCAT System Manager and navigate to your IO Configuration.
2. Inside your IO configuration, identify your Safety Controllers
   • TwinCAT 2 Compatible safety controllers are:
     • EL6900
     • EL6930
     • KL6904 – see note above about TC3 compatibility
3. From your TSM file in TwinCAT 2, open your safety controller and click the “TwinSAFE Logic” Tab. Then click the “Export…” button and save the export as an XML file.
   • 
4. With the XML export, go to the Safety Node of the TwinCAT project and select “Add Existing Item…”
   • 
5. In the pop-up, select the XML export of the Safety Project(s). Make sure to change the file format options to include XMLs.
   • 
6. In the pop-up, select your Safety Controller
   • 
7. Then restore all the links in the Safety Project
   • 
   • 
   • Finished Example:
   • 
8. With the safety project converted, double-check that all connections and TwinSAFE FBs are correct.

Section 5: Motion

While the Motion tasks and axes are automatically converted by XAE Shell with the TSM configuration, the PLC control of the axes may need manual adjustments. This section of the guide covers how to re-link the Axes to the TcMC2 data types.

1. If the TwinCAT 2 Project used TcMC, please follow the instructions in Step 20 of the TwinCAT Project Conversion section regarding the PLC code changes recommended by Beckhoff.
   • The NCTOPLC and PLCTONC AXIS_REFs have been combined into a single AXIS_REF struct
   • Old:
     • 
   • New:
     • 
2. Once completed with these changes, the AXIS_REF structs will need to be linked back to the axes.
   • Note: If you do not see the Axis when linking, try rebuilding your PLC Project.
   • Linking:
     • 

Congratulations, your TwinCAT 2 Project is now ready for a TwinCAT 3 PLC!

You can follow our other guides: Getting Started with a Beckhoff PLC to continue with your PLC upgrade.

Ready to take your project to the next level? Contact us today to learn more about DMC’s Beckhoff and TwinCAT 3 Programming solutions and how we can help you achieve your goals.