Part 14 - Handling of different TwinCAT versions

Table of Contents:

A) Objectives

Hey developers!

Now that we know how to do basic version control for TwinCAT 3 projects, we can work on our projects and keep track of the entire history for the software.

After working for a few months and years you will be in a situation where you have to manage several PLCs and machines and they will all be running different versions of TwinCAT.

|300

But we've so far only installed one version of TwinCAT on our development machine.

What if we encounter a machine that runs an older or newer version of TwinCAT?

What do we do if there is an older version of a TwinCAT function, say the OPC-UA server on a PLC compared to what we have on our development machine?
*What do we need to think of?

If you're a traditional software developer and have been using modern build tool chains, you will find the TwinCAT way of doing it is not optimal.

I've been working in many different projects using TwinCAT over the years and in EVERY SINGLE ONE of them, PLC developers manage to get this wrong, myself included.

That's the reason why I decided to include this part.

And that's the reason why you now will learn how to effectively handle this.

Let's get started!

B) Handling of different TwinCAT versions

B.1) The Problem of using Different TwinCAT Versions

We've so far only worked with one version of TwinCAT, which is 3.1.4024.14

This is the version that we've been running both on:

the development machine, the XAE
and on the target machine, the XAR.

Now let's imagine for a moment that we're developing the software to be running on a machine which is running the XAR for the same version of our XAE. I would be fine maintaining that machine, as the version of the XAE and XAR are matching.

Let's imagine that we have to maintain some machines with either older or newer versions of TwinCAT.

Can we handle multiple versions of TwinCAT on our development machine?
And what do we need to think of?
How do we make sure that we can recompile an application that is running on a machine and be 100% sure that we get the exact same application, many years in the future if we need to?

B.2) How the XAE handle different versions

If you have a version of the XAE installed on your development machine you can install a newer version of the XAE, for example running with 4024.14 it's fine to install 4024.22 and any newer version.

All of these XAEs can be installed next to each other, which means that we can have all of these versions installed on our development machine simultaneously.

What is not possible to do is to install an older version of the XAE that is older than any of the XAEs that we already have installed on our computer.

So what do we do if we want to install an older version of TwinCAT than what we currently have?

B.2.1) Introduction to TC3 Remote Manager

In this tutorial we so far only been talking about the XAE and the XAR.

But there is a third component that's possible to download from the Beckhoff website, which is the TwinCAT remote manager.

If you download a remote manager version for a particular version of TwinCAT you can install it even if there is a newer version of TwinCAT installed on your system.

This begs the question; what is the difference between the XAE and the remote manager?

The XAE is a full-blown installation of TwinCAT bundled together with Visual Studio, the XAR, libraries and compiler.

The remote manager only includes the latter two of these. So the libraries and compiler that you need for a specific version of TwinCAT.

Warning

You can't install a remote manager of TwinCAT unless you already have an existing XAE installed on your machine.

If you go to the Beckhoff website, you can download the remote manager version for several different versions of TwinCAT builds.

If you need any special version that is not available on the website you can get it through the Beckhoff support.

B.2.2) Handling Libraries and Compilers

By combining different versions of the XAE and remote manager you can manage different versions of TwinCAT in your development environment.

When you install a version of TwinCAT there are certain versions of the various Beckhoff libraries installed with it. For example, with TwinCAT 4022.14 we get version 3.3.2.0 of the Tc2_standard library, that we have talked about in a previous part of this tutorial.

If we install a newer version of TwinCAT then newer versions of these libraries might be installed, which is the case here, where we've installed 4022.32 which is newer than 4022.14 above.

As can be seen, every single Beckhoff library has been updated.

The default for opening a project is that the latest version of a library that is installed on your machine is selected for that project. But it's not just the libraries that we have to think about.

When installing a version of TwinCAT there are certain versions of the IEC compiler that are installed together with it.

Here you see the various compilers that are included with TwinCAT 4022.14

If we install a newer version of TwinCAT, then newer versions of the compiler might be installed.

Note: In this picture TwinCAT 4024.14 is installed, which is newer than the version above.

Here we can see that we have two additional compilers installed.

The default when opening a project is that the latest compiler on your machine is selected for that project.

I will now show you a programming demo, where we start with our current version of TwinCAT, that is 3.1.4024.14 and install a newer version on top of it.

In other words, we will handle two different versions of TwinCAT and have a discussion of what you should think of when managing your PLC software for a specific version of TwinCAT.

B.3) How to Identify the Latest TwinCAT Version Installed 🔍

Right click on the small icon,

Here is the Version,

And we can confirm which Build is used,

C) TUTORAL 23 - Working with Two Different TwinCAT Versions //Using 3 VMs ✍️

C.1) Example: XAE and XAR Setup explained

This live programming is going to be a little bit different, because we're gonna use three virtual machines at the same time.

And what we have here is two virtual machines with the XAE so the full development environment. And one virtual machine just running the XAR so the runtime.

All of them are based on the version that of TwinCAT that we have been using so far which is 4024.12.

What I want to show here is simply to have these two virtual machines, and then upgrade the other virtual machine with an additional version of TwinCAT.

So I'm going to download the latest version of TwinCAT as of today so that this machine will have two versions of TwinCAT, so 4024.12 and the version that we're gonna download soon.

Then we will see what will happen when we have these two machines developing software for one PLC

C.2) Running the PLC Project on XAE-1

What I've done here is that I've created a simple application that just uses some different libraries, just to show on the concept of what happens when you run different versions of TwinCAT.

What I've also done here is that I've created an ADS route to the to the runtime, to the XAR

As you can see we have a link to the PLC (10.0.2.15.1.1), so we can run and deploy our PLC software on this virtual machine up here.

First I just want to show you that I have used some different libraries.

And this project is loaded with version 4024.12,

What I'm simply going to do is to activate this PLC project.

And run this project on the PLC,

So let's log into the PLC

and start the project.

So now this is running and we can actually see it,

So it's running on this PLC.

C.3) Running the PLC Project on XAE-2

C.3.1) Cloning the PLC Project on XAE-2

What I'm gonna do now is to transfer this application to this other XAE environment and log in from this environment as well.

And I just want to show that this is an application that's available in a Git repository. So what we learned the last time.

Now we just have to clone this very same application. So we're going to do that. We're going to Git-clone this guy.

And I'm gonna open it here as well

So again...the way you should think about this is that we have two computers, right? You have one computer and then your colleague has another computer and both of you want to work in the same machine. Or maybe you've had an application. This computer is on computer that you had five years ago and now you're trying to reconstruct the same... very same machine to...if you want to do some software maintenance for example. This would be this machine.

So here is the same application opened,

This XAE environment also has a connection to this virtual PLC, to this XAR. So we will connect to it

And now I will also do a login.

And no problem. So this means that there's actually no difference between what we have compiled in our machine and what has been previously in the PLC,

because when we log in the XAE always compares with the target. Is there any difference of this compiled binary? Compared to what is on the target.

And in this case we could log in, we didn't get any popups or anything. It just worked. So this is fine.

C.3.2) Installing the Latest TwinCAT version on XAE-2

But now we can see there is a problem...
What will happen if this machine would have an additional version of TwinCAT on it?

So what I'm gonna do is that I'm gonna go to the Beckhoff website and install an upgrade of the TwinCAT XAE.

We can see that the latest version as of today is 4024.29, so much newer than the version that we're using here.

|700

So let's download the new one,

Ok, it's downloaded. Now I will just quickly install it

Ok, and now it's installed.

After installation. we need to reboot this machine

Ok, machine has been rebooted This machine should now have a newer version of TwinCAT installed.

Yeah, which it has. So this one has now 4024.29

C.3.3) Trying to Open the Project with the Latest TwinCAT version on XAE-2

Now we're going to open the same project again.

And then you kind of assume that because you have both of these versions installed here,

TwinCAT will open it with the version that it was created with.

So TwinCAT will open the project with the version that that it was initially created with, but as we will see this is not the case.

What you can see here is the remote manager and it's with this guy here that you can actually select which version of TwinCAT that you want to be loaded before you open a project. But now I just open the project and then it automatically just selects the latest version that is installed on the machine ( unless you specify otherwise)

But if you go here now you can actually see that we both have 4024.29, which is the loaded one and 4024.12.

Before I show you what to do about this I will simply log in to the target.

C.3.3.1) Online Change Warning on XAE-2

I mean I haven't changed application at all. It's exactly the same application, everything is the same.

So, I can compile as well of course, I can rebuild it.

But if I log in now to the PLC...

Then we get this message. "Application change since last download, what do you want to do?"

So there is obviously a difference between the application that has been compiled in XAE2 and the application that has been compiled in XAE1, because it wants to do on online change, which we might or might not want to do.

In this case for example if you have deployed a machine, if you have worked with a machine and it's been delivered to a customer then....

you normally will not want to upgrade the whole TwinCAT.

|300

If you just want to do a minor change in the application, then you want to make sure that you're always able to rebuild the whole application from scratch, with exactly the same version that you used when you wrote the application the first time.

So why doesn't it work now?
Why do I get this message, even though the only thing I've done is that I installed an additional version of TwinCAT?

Well, there can be at least two reasons.
First, we can get a little more information if we go to "Details" here,

because here we can actually see the changes made by the different versions....

This is actually quite a good window because it shows a lot about what the differences are.

But I'm going to press cancel here,

and the simple reason in this case is that there's a difference between the libraries.

C.3.3.2) Comparing Libraries between TC3 versions on XAE-1 and XAE-2 (using Placeholders)

So if you go here to references, you can see all the different libraries that are being used

So for every library there is something called Placeholders, which specify which version of a specific library should be used throughout the application.

If you don't specify anything then it's per default the latest version.

And what happened here is that when we installed the newer version of TwinCAT, then a later version of the library was also installed.

The old version is still kept on the development environment, so all the libraries that followed with this version of TwinCAT are still here.

But we also got newer versions.

We can see that TwinCAT wants to use the latest version of the library by this star " * "

What the star says is "just use whatever latest version you have".

And what we can see here is that for example in XAE-1 the Tc2_EtherCAT library has version 3.3.15.0, while XAE-2 has 3.3.19.0.

So again these are libraries that are pre-installed together with the TwinCAT XAE.

So this is why we get a difference because when we compile this application then these libraries are also included in that executable binary.

C.3.3.3) Comparing the Compilers between TC3 versions on XAE-1 and XAE-2 (part 1)

But it's not just the libraries that can differ, it's also the compiler, because what Beckhoff do is that...is that they use a compiler from CODESYS (they maybe do some adjustments to it, I'm not entirely sure).

So, when you download a newer version of TwinCAT then you can also get a new version of the compiler.

C.3.3.3.1) How to Identify the Compiler Version Installed 🔍

The compiler version is available if you go to properties here for the PLC project,

Click on Compile. And then it also says here "Compiler version: newest version".

So that is saying to just use whatever version that is the newest installed on this system, which of course can differ between different versions of TwinCAT, if Beckhoff for some reason have decided to include a newer version of the compiler with a newer version of the XAE.

C.3.3.3) Comparing the Compilers between TC3 versions on XAE-1 and XAE-2 (part 2)

So we can see it's the same processes on the other XAE. If you go to compile it's the newest version.

In this case, if you go here you can actually see which one is the newest version and in here it's called 3.1.4024.0,

While here it's the same.

Note: It happens to be the same but it doesn't have to be.
This is also something that we have to remedy so to speak.

C.3.3.4) Freezing Libraries to Specific TC3 versions (using Placeholders) 🔍

The solution to deal with different versions is to simply freeze the libraries for the particular version that you want to develop for.

In this case we want to make sure that when we open the project also on XAE-2 then this machine should use the libraries that are delivered together with 4024.12.

So the version of TwinCAT that was installed in XAE-1.

Then you might ask:

"How do I know which version of the libraries are installed together with a specific version of TwinCAT?"
- The answer is "you don't".

There is no official documentation from Beckhoff how to do this. There is an unofficial GitHub repository that states all the different library versions of every version of TwinCAT. Read more here: https://github.com/RumstiBumsti/TcLibraryVersions/

But Beckhoff doesn't provide this. The only way to do this is to simply install a specific version of TwinCAT and check which libraries are installed with only this version of TwinCAT, which we have here.

Because in this machine we only have 4024.12,

so we know these libraries are included with this version.

All of these libraries are installed together with the TwinCAT XAE but there might also be libraries installed together with with supplements or TwinCAT functions.

So for example if you install the OPC-UA client supplement then you get a certain set of libraries with that supplement, with that function, which means that you also need to keep track of which version of the supplement that I use. Because if you download a newer version of the OPC-UA supplement the function, then there might be a newer version of the libraries together with that.

So it's very important for you to kind of bundle and keep track of your whole development environment. So that you can easily rebuild the whole machine from scratch, if you would need to.

But to solve the library problem we go to the placeholders.

In the placeholders...that's where you can specify that you want to fix the library to a specific version. So if we go here we can click on this guy,

and select "I want to freeze it to this version",

because this version was the one that was delivered with this version of the XAE.

We do the same with standard,

and we do it with with all the libraries. Then Press ok.

And then you see that all the stars have been replaced with that particular version of the library.

It's also the same for all the dependencies inside the library. So for example utilities depends on Tc2_Standard. We can see that Tc2_Standard that we included is this version,

and now we can see that we're also forcing Tc2_Utilities to this version.

Through placeholders we can really kind of like freeze the library version, So that's the live version, that's all you actually have to do regarding libraries to make sure that TwinCAT is now freezed with this.

C.3.3.5) Pin the compiler to freeze its version 🔍

And the other thing we want to do is to pin the compiler. And the way you do it is that you go to "System",

and then you select "Pin version"

What this does is effectively pin this project to this particular version of TwinCAT.

If we did this and then we try to open this on a machine with a version of TwinCAT that doesn't have this version, in this case 4024.12, then we would get a warning that says "Hey you have to have this version of TwinCAT to open this project".

|200

Then you basically get a choice...do you either want to cancel, and say okay I don't have this then I probably shouldn't open this project. Or you get the option to open it with another version of TwinCAT that's installed on your computer.

But then you lose all the guarantees about you know...all the guarantees you have of freezing your software to that version of TwinCAT that you were using when you were developing the application.

So you pin it. Then we save this project and we can commit it.

C.3.4) Correctly Opening the Project with the Latest TwinCAT version on XAE-2

C.3.4.1) Using TortoiseGit for our repo

So let's just commit all of these changes.

We commit and push it ,

Note: Here I use TortoiseGit but you can use the built-in Git client in Visual Studio, it's your choice.

Now on the XAE, we close the project.

I'm just gonna do a revert here, because TwinCAT has decided to make some changes to this,

so I'll just revert all the local changes,

Now I will synchronize it. So I will get the latest changes from the repository,

So let's just pull it over,

And now if I open this project.

Now it's opened, and now we can see that it actually loaded the project with 4024.12, even though it has a newer version here, it opened it with this particular version.

We can also see that the library versions here...if we compare them, are the same.

Because we have frozen the libraries through placeholders. So we've frozen both the libraries and we've frozen the compiler that TwinCAT is going to use to compile this application.

So now if I log in,

No warning window. Nothing about an online change. It just logged in,

because it sees that "hey this compiled application that I compiled here in XAE-2 is exactly the same that's running on this machine (XAR)"

Because it is the exact same application, because we're using the same version of TwinCAT in both sides. Both the compiler and the library.

D) 💬 Best Practices and Conclusion

Understanding how to consistently rebuild your application using the same TwinCAT versions is crucial. This becomes increasingly important over time, especially when working with numerous machines. Keeping track of versions might be manageable in the short term, but over several years and with multiple machines, it can become quite chaotic. As you approach the delivery phase of a project, it's essential to 'freeze' all components: libraries, compiler versions, and ensure everything is properly committed. Utilizing tools like Git, you can create formal software releases, versioning your software effectively for future reference.

Maintaining a clean, rebuildable application is not just about the TwinCAT software. It extends to all additional functions and components you've incorporated, such as vision functions or TCP/IP communication tools. Secure and store these components as well, as they are integral to rebuilding the application if needed.

In this programming session, I aimed to highlight these practices.

Conclusion
For traditional software developers accustomed to modern build chains, TwinCAT's approach might seem less than ideal. Unlike contemporary software development, where build configurations and dependencies are managed and resolved automatically by tools, TwinCAT requires a more manual approach. This is partially due to TwinCAT's reliance on CODESYS as its platform, which influences these processes. However, the industry is evolving, and changes are already underway, suggesting a shift towards more streamlined methods in the future.

Next Chapter
Thank you very much for listening. In the next episode we will do a deep dive into Automation Device Specification (ADS), which is Beckoff's "middleware" for communication. Auf Wiedersehen!

🔙 Previous Part | Next Part 🔜

↩️ Go Back

Z) 🗃️ Glossary

File	Definition

Uncreated files	Origin Note
Automation Device Specification (ADS)	Part 14 - Handling of different TwinCAT versions
Next Part 🔜	Part 14 - Handling of different TwinCAT versions
Next Part 🔜	Part 14 - Handling of different TwinCAT versions
Placeholders	Part 14 - Handling of different TwinCAT versions