Table of Contents

1. Installation
2. Configuration
3. Workloads and Packages
4. Conclusion

TwinCAT Package Manager is Beckhoff’s new innovative way of managing packages within the TwinCAT environment. Released with their latest build 4026, Package Manager allows for quick and easy downloads of TwinCAT versions and workloads (collections of one or more packages), as well as individual packages. Let’s get started with some of the key features of the TwinCAT Package Manager.

Installation

Download the latest version of the TwinCAT Package Manager from the Beckhoff website. This blog will use the full installation, which includes the UI. If you would prefer the command-line-only install, some common commands are available on Beckhoff Infosys.

Follow the installation procedure to install TwinCAT Package Manager.  

Configuration

Once TwinCAT Package Manager is installed successfully, open it. If this is your first time launching Package Manager, you should be greeted with the Introduction screen. If you have previously launched Package Manager, but want to follow along, you can access this screen with the Settings button (gear icon) in the bottom left.

Introduction

If you’re installing Package Manager on a system with a previous build of TwinCAT already installed, there will be a migration tab instead of a location tab. We will deal with that in a later section. Click Next.

Feeds

The next section is for configuring the feeds for Package Manager. Click the “Add new feed” button to add one of these feeds.

By default, Beckhoff provides three feeds: the stable feed, the outdated feed, and the testing feed. The stable feed contains officially released Beckhoff products and is typically the main feed for most workloads and packages. Select the URL that ends with “/stable” to add the stable feed. The feed name should auto-populate, but can be changed. Enter your valid myBeckhoff account credentials and click Save to add the feed. You can create your own myBeckhoff account if you don’t already one.

You’re also able to create your own feed, which you can access here. This would allow you to easily share custom libraries with other developers on your team. We won’t go in depth on how to do that in this blog, but the Beckhoff community GitHub repo has an example structure.

You should now see the feed added. You’re able to disable, edit, or delete the feed from this view if needed.

The outdated feed contains previous TwinCAT builds. If you used TwinCAT prior to build 4026, this is essentially the new version of Remote Manager. The testing feed contains test versions of workloads and packages. It’s most commonly used if you need access to an unreleased feature or are testing packages with Beckhoff engineers.

Follow the steps above for the stable feed to add the outdated and testing feeds, making sure to use their respective URLs.

Once you add the outdated and testing feeds, your Feeds tab should look like the one above. You can reorder the feed priorities using the up and down arrows on the right side. It’s recommended to keep the stable feed as priority 1 since it contains the officially released packages. If you reordered the feeds, click the save button in the top right. If you click next with unsaved changes, you will get this warning.

If you see this warning, click “Yes” to save changes. Click “Next.”

Integration

The next screen asks which versions of TwinCAT XAE to install. Since TwinCAT XAE is built on Visual Studio, it requires the same Visual Studio version (32-bit or 64-bit) to be installed. If you’re working on a project in build 4026 or newer, it’s recommended to use the 64-bit version when possible. If you’re working on a project in a build prior to 4026 or on a 32-bit computer system, the 32-bit version of TwinCAT XAE is the only option. You can always add or remove these XAE versions later, so for now, let’s install both. Click “Next.”

Migration

If you had a previous build of TwinCAT, you will be prompted to complete a Migration screen. If you did not have a previous build of TwinCAT, feel free to skip to the Location section.

The migration tool will attempt to capture existing user settings on previous versions of TwinCAT, uninstall previous versions, install the latest versions, and reapply the user settings. Let’s click “Start Migration” to get started.

When getting to step 2 of the preparation screen, you may see a notification that you need to install the MigrateCli package. Click “Yes” to continue.

Once the migration tool is installed, click “Start Simulation.”

Once the migration simulation runs, you should see a list of all existing products in the system and how TwinCAT Package Manager plans to upgrade them to packages and workloads.

Assuming all the products can be upgraded to packages and workloads, we are ready to start the migration. Click Start Migration.

Depending on the products you have installed, you may need to reboot your system. Press Ok and the TwinCAT Package Manager should automatically start up after rebooting and continue the migration.

Once the migration is complete, click Finish. You should see all the latest versions of the products you had previously installed on the system.

Location

If you did not have a previous version of TwinCAT installed, the final screen asks where to install TwinCAT. The default location is fine unless you have a reason to install it elsewhere. Click Finish.

Workloads and Packages

The workload view should be the default view when opening Package Manager for the first time. It can be navigated to by hovering over the package icon with a W in the bottom right and selecting workloads.

Workloads

Workloads are groupings of packages that closely align with Beckhoff’s licensing structure. For example, if you’re planning on using Beckhoff XTS in your solution, you can search for “XTS” to find the TF5850 | TwinCAT 3 XTS workload. This will install the necessary packages to work with XTS. If you are using XTS in your solution, check out our blog series on XTS to help get started!

The workloads in the general section are the ones we should install first. Let’s start by installing the latest version of TwinCAT Standard Engineering and the latest versions of TwinCAT XAE Shell 32-bit and 64-bit. If you’re installing the latest version, simply click on the blue download button associated with that workload.

You’ll see the planned installations added to the right side of Package Manager under selected products. Click Apply Modifications to start the installation.

Some workloads will require a restart. The TwinCAT Standard installation is one of them. Click Accept to continue.

If a pop-up appears asking you to allow the TwinCAT Package Manager to make changes to your device, click “Yes.”

The installation may take a few minutes, but Package Manager will give you a download and installation status.

Once the installation completes, Package Manager will show a check mark next to the workloads that were successfully installed.

We didn’t explicitly install TwinCAT Standard Remote Manager or TE9000 | TwinCAT 3 Safety Editor. Why are they showing as installed? TwinCAT Package Manager will install all dependencies needed to install the selected workloads! These workloads are dependencies for TwinCAT Standard and are automatically installed for us.

Workloads (Other Versions)

One of the nice things about TwinCAT Package Managers is the ability to access prior versions of all the workloads. Each workload has an ellipsis on the right side. Clicking on this provides the option to select other versions.

Click on the other versions option for TwinCAT Standard.

We can see that the latest version is currently installed and can be uninstalled here if needed. If we wanted to install a previous version, say 4026.21.2, we could click the icon next to that version. That icon is the downgrade icon. This would uninstall 4026.22.0 and downgrade TwinCAT Standard to 4026.21.2.  However, TwinCAT Standard Remote Manager can be used when working on multiple solutions across different versions.

Click the triple-dot icon next to TwinCAT Standard Remote Manager, then select other versions.

The icons here are install icons instead of downgrade icons, even though we already have the latest version installed. This is because the TwinCAT Standard Remote Manager supports multiple versions, as indicated by the AllowMultiple attribute in the top left. Installing from here will allow both versions to coexist on the same system. To illustrate this, I’ll install version 4026.21.2.

The Package Manager workload for TwinCAT Standard Remote Manager now shows a [ + 1 ] to indicate multiple builds are installed.

When opening TwinCAT XAE, we now have multiple builds to select from!

Installing Pre-4026 Builds

If you haven’t already, make sure you’re connected to the Beckhoff outdated feed. You can configure your feeds by clicking on the settings icon in the bottom left.

Once you have the outdated feed configured, hover over the package icon with the database in the bottom right. Select the “Beckhoff Outdated Feed.”

The only workload associated with the Beckhoff Outdated Feed is the TwinCAT Standard Remote Manager. From the outdated feed, we can install pre-4026 builds of TwinCAT.

I’ll install build 4024.75.4 to illustrate.

After installing build 4024.75.4 on TwinCAT Package Manager, it is now selectable in the build dropdown.

*NOTE: This is only available in the 32-bit XAE. The 64-bit version of XAE only supports builds 4026 and newer.

Packages

So far, we’ve been dealing with Workloads. Workloads are groupings of packages that TwinCAT organizes primarily according to Beckhoff’s licensing structure. TwinCAT projects reference packages directly. Let’s open a new TwinCAT XAE project to see this.

In the References folder of a brand new TwinCAT project, there are the Tc2_Standard, Tc2_System, and Tc3_Module packages.

Let’s switch back to the package manager. On the left, you should be able to go to the package view menu and select Packages.

This will show the individual packages that are available and installed on the system. Let’s search for Tc2_Standard.

We can see that Tc2_Standard is installed.

How To Deal with a Missing Package

If you have a missing package on a TwinCAT project, you will be greeted with a warning sign that looks something like this:

The package with the warning symbol next to it is missing from the project. Double-clicking on the package shows that the library is not available and does not have an effective version listed.

Right-click on the missing package and open the properties window. The resolution will show the version of the package that the TwinCAT PLC project is expecting.

If we go back to Package Manager and search for the Tc2_System package, we can see that although it is installed, it is not the same version the PLC project expects.

Click the ellipses next to the package, then select other versions.

Similar to Workloads, Packages have multiple versions that can be installed onto the same system. In this scenario, we have Tc2_System v3.10.1 installed already, but do not have v3.9.1. Tc2_System allows for multiple versions to be installed, indicated by the AllowMultiple tag. Let’s install v3.9.1 and see if that resolves our issue. Click the download button next to v3.9.1 and click “Apply modifications.”

If you see a message about “TwinCAT XAE / Visual Studio stop required,” be sure to close all open XAE windows before clicking Accept. Once the package is installed successfully, we can check the previously missing package.

The library is now available and has an effective version of v3.9.1. We have installed our missing package through Package Manager!

Conclusion

The TwinCAT Package Manager is a huge improvement in how engineers can manage the various Packages and Workloads that make up a TwinCAT solution. TwinCAT Package Manager is just the start of the improvements that TwinCAT build 4026 brings to development. A complete list of changes is offered on the Beckhoff website. If you’re starting a project in 4026 or upgrading an existing solution to 4026, reach out to DMC and see how we can help! We have extensive experience with upgrading and developing across all TwinCAT builds.

The post Getting Started with Beckhoff TwinCAT Package Manager appeared first on DMC, Inc..

Beckhoff TwinCAT 3 gives us a couple of options for performing this task. This blog will introduce both methods and, at the end, discuss some pros and cons of each method. I’ve also included basics on linking motion hardware — if you’re only interested in linking standard inputs/outputs, feel free to skip the “Motion” sections.

Table of Contents

1. Hardware Linking Basics
   • Motion
2. Method 1: Manual Linking
   • Motion
3. Method 2: Attribute Linking
   • Single Variables
   • Nested Variables
   • Mismatched variable sizes/types
   • Motion
4. Comparisons
5. Project Variants
6. Further Reference

Hardware Linking Basics

Back to Table of Contents

Before we get into the two hardware linking methods, let’s discuss some basics that we’ll need for either method. 

In order to link a variable to hardware, we need to declare that variable as an input or output. A variable can be declared as an input by placing AT%I* before the type. Likewise, an output is declared by placing AT%Q* before the type. 

VAR
    boolInput1  AT %I* : BOOL;
    boolOutput1 AT %Q* : BOOL;

    intInput1   AT %I* : INT;
    intOutput1  AT %Q* : INT;
END_VAR

VAR
    boolInput1  AT %I* : BOOL;
    boolOutput1 AT %Q* : BOOL;

    intInput1   AT %I* : INT;
    intOutput1  AT %Q* : INT;
END_VAR

We can declare IO of any type, including structures and function blocks. If we declare a structure or function block as IO, all memory within that item will be included as IO — so this probably makes more sense for structures than it does for function blocks. Also, all variables within that structure will either be an input or an output — both cannot be included when declaring this way.

// Type definition
TYPE ST_Inputs :
STRUCT
    boolInput : BOOL;
    intInput  : INT;
END_STRUCT
END_TYPE


// Declaration
VAR
    structAsInput AT %I* : ST_Inputs;
END_VAR

// Type definition
TYPE ST_Inputs :
STRUCT
    boolInput : BOOL;
    intInput  : INT;
END_STRUCT
END_TYPE


// Declaration
VAR
    structAsInput AT %I* : ST_Inputs;
END_VAR

We can also declare IO within structures/function blocks, which allows us to include both inputs and outputs, as well as variables that are neither inputs nor outputs.

// Type definition
TYPE ST_IncludingIO :
STRUCT
    boolInput  AT %I* : BOOL;
    boolOutput AT %Q* : BOOL;

    intInput   AT %I* : INT;
    intOutput  AT %Q* : INT;

    notIOBool  : BOOL;
    notIOInt   : INT;
    notIOReal  : REAL;
END_STRUCT
END_TYPE


// Declaration
VAR
    structWithIO : ST_IncludingIO;
END_VAR

// Type definition
TYPE ST_IncludingIO :
STRUCT
    boolInput  AT %I* : BOOL;
    boolOutput AT %Q* : BOOL;

    intInput   AT %I* : INT;
    intOutput  AT %Q* : INT;

    notIOBool  : BOOL;
    notIOInt   : INT;
    notIOReal  : REAL;
END_STRUCT
END_TYPE


// Declaration
VAR
    structWithIO : ST_IncludingIO;
END_VAR

Inputs/outputs can be declared like this pretty much anywhere in the program, with a few exceptions: methods and functions. This gives us the flexibility to architect our program however we like. For example, we could put all of the IO in a GVL for the convenience of having it all in once place, or we could nest our IO within the function block structure of our software for good organization.

Once the program is compiled, all the IO variables that have been declared will appear under the PLC instance inputs and outputs. In this example, all our IO variables are declared in the VAR memory of the MAIN program, which is indicated in the path of each IO variable.

Once our IO variables are declared and the project is compiled, we are ready to start linking standard IO.

Motion

Back to Table of Contents

Basic motion axis linking is a little different than standard IO. 

Standard IO variables can still be directly linked to PDOs to/from drive hardware, which is often done for more advanced motion functionality or certain functionality with third-party (i.e., non-Beckhoff) drives; however, most NC axis control is done through the NC task, a separate task on the Beckhoff PLC used specifically for motion control. Basically, the PLC communicates with the NC task, and the NC task directly communicates with the drive hardware. The NC task takes care of low-level motion control functionality, so we can abstract out to high-level, simple, PLCopen-style control within the PLC program.

This means we need to link the PLC task to the NC task. Everything we need for this is included in the AXIS_REF type from Beckhoff’s Tc2_MC2 library.

VAR
    axis1 : AXIS_REF;
END_VAR

VAR
    axis1 : AXIS_REF;
END_VAR

We’ll talk about how to link this AXIS_REF structure in the linking methods sections later, but one more thing must be done, regardless of which linking method is used. As mentioned previously, the NC task needs to be directly linked to the hardware. To do this, we’ll first need to create the NC task and axis. This may have been done already if an axis had been added to the hardware configuration previously. If it hasn’t, use the following steps:

1. [Solution] > MOTION > Right Click > Add New Item…
2. Select NC/PTP NCI Configuration and click Ok.
3. [Solution] > MOTION > [NC Task] > Axes > Right Click > Add New Item…
4. Enter the Axis name and click Ok.

Once the NC task/axis has been created, click on the axis and go to the Settings tab. The Link To I/O button will allow us to link the axis item in the NC task to an actual drive in the hardware configuration. Click on this button and select the desired hardware to link the NC axis to that hardware.

The linked hardware will appear in the field, and the Axis Type will change appropriately.

At this point, the NC axis is properly configured and ready to be linked to the PLC code using one of the methods in the following sections! Alternatively, if we wanted to create a simulation on the axis, we could leave this unlinked and make sure the Axis Type is Standard (Mapping via Encoder and Drive).

Method 1: Manual Linking

Back to Table of Contents

The first method for hardware linking is manual linking, which is a fairly straightforward process. First, expand the task inputs/outputs and select the desired variable. Right-click on it and select Change Link, or double-click and select the Linked to button on the Variable tab. This will open the link selection dialog box.

From this dialog box, we can select the hardware card and specific channel to which the selected IO variable will be linked. The search bar and filters at the side of the dialog box like Only Unused and Matching Type/Size can be helpful in finding the proper/available hardware quickly. Select the proper channel and click Ok to link the variable.

We can also do this from the other direction – if we want to start from the hardware configuration, we can select a certain channel and open a similar dialog box to select the IO variable to which it should be linked.

Once a variable or hardware channel is linked, a small square icon with an arrow will appear at the corner of the icon in the solution explorer. When variables are linked manually, this icon is gray.

Helpfully, we can easily navigate between the now-linked items by right-clicking and selecting Go To Link Variable. 

Motion

Back to Table of Contents

For AXIS_REF structures, linking to the PLC is done from the NC task. Return to [Solution] > MOTION > [NC Task] > Axes > [Axis] > Settings and use the Link To PLC button to select the desired AXIS_REF structure.

Once linked, the AXIS_REF variable will appear in the field, and the NcToPlc and PlcToNc members of the AXIS_REF structure will show gray boxed arrows in the PLC Instance inputs and outputs, indicating they are properly linked.

Method 2: Attribute Linking

Back to Table of Contents

The second method for hardware linking is attribute linking using the TcLinkTo, TcLinkToOSO, and TcNcAxis attributes. This isn’t as straightforward as manual linking, but it has its advantages — especially when using version control.

Single Variables

For most linking, we can just use the basic TcLinkTo attribute. Here are a few examples.

VAR
    {attribute 'TcLinkTo' :=
        'TIID^Master_EtherCAT^Coupler_EK1100^Term1_EL1008^Channel 4^Input'}
    boolInput2 AT %I* : BOOL;

    {attribute 'TcLinkTo' :=
        'TIID^Master_EtherCAT^Coupler_EK1100^Term2_EL2008^Channel 4^Output'}
    boolOutput2 AT %Q* : BOOL;

    {attribute 'TcLinkTo' :=
        'TIID^Master_EtherCAT^Coupler_EK1100^Term3_EL3008^AI Standard Channel 4^Value'}
    intInput2 AT %I* : INT;

    {attribute 'TcLinkTo' :=
        'TIID^Master_EtherCAT^Coupler_EK1100^Term4_EL4008^AO Outputs Channel 4^Analog output'}
    intOutput2 AT %Q* : INT;
END_VAR

VAR
    {attribute 'TcLinkTo' :=
        'TIID^Master_EtherCAT^Coupler_EK1100^Term1_EL1008^Channel 4^Input'}
    boolInput2 AT %I* : BOOL;

    {attribute 'TcLinkTo' :=
        'TIID^Master_EtherCAT^Coupler_EK1100^Term2_EL2008^Channel 4^Output'}
    boolOutput2 AT %Q* : BOOL;

    {attribute 'TcLinkTo' :=
        'TIID^Master_EtherCAT^Coupler_EK1100^Term3_EL3008^AI Standard Channel 4^Value'}
    intInput2 AT %I* : INT;

    {attribute 'TcLinkTo' :=
        'TIID^Master_EtherCAT^Coupler_EK1100^Term4_EL4008^AO Outputs Channel 4^Analog output'}
    intOutput2 AT %Q* : INT;
END_VAR

By placing the attribute line above the declaration, we are telling the compiler the hardware item to which we want the variable to be linked. The path to that hardware item must be exact and have the correct syntax. The easiest way to get the syntax for this path is to navigate to the hardware item in the solution explorer and copy the syntax from the Full Name field.

After properly setting up the attribute, compiling the project should link the variables to their respective hardware. This can be confirmed by examining the instance inputs/outputs in the Solution Explorer. Again, we should see a small square icon with an arrow on linked variables, but this time it will be blue. We can still use the Go To Link Variable context menu option to jump to linked hardware item. 

Nested Variables

Back to Table of Contents

IO variables nested within one or many layers of structures/function blocks can also be linked, with some extra syntax added to the TcLinkTo attribute. This is very powerful because it means that, even if we have IO variables declared within structures or function blocks, we can still link every instance of those reusable items individually.

To link nested variables, we just need to add the path to the variables within the structure or function block to our attribute. Here is an example using the same structure definition as above:

VAR
    {attribute 'TcLinkTo' := '
        .boolInput  := TIID^Master_EtherCAT^Coupler_EK1100^Term1_EL1008^Channel 5^Input;
        .boolOutput := TIID^Master_EtherCAT^Coupler_EK1100^Term2_EL2008^Channel 5^Output;
        .intInput   := TIID^Master_EtherCAT^Coupler_EK1100^Term3_EL3008^AI Standard Channel 5^Value;
        .intOutput  := TIID^Master_EtherCAT^Coupler_EK1100^Term4_EL4008^AO Outputs Channel 5^Analog output;
    '}
    structLinkedByAttribute : ST_IncludingIO;
END_VAR

VAR
    {attribute 'TcLinkTo' := '
        .boolInput  := TIID^Master_EtherCAT^Coupler_EK1100^Term1_EL1008^Channel 5^Input;
        .boolOutput := TIID^Master_EtherCAT^Coupler_EK1100^Term2_EL2008^Channel 5^Output;
        .intInput   := TIID^Master_EtherCAT^Coupler_EK1100^Term3_EL3008^AI Standard Channel 5^Value;
        .intOutput  := TIID^Master_EtherCAT^Coupler_EK1100^Term4_EL4008^AO Outputs Channel 5^Analog output;
    '}
    structLinkedByAttribute : ST_IncludingIO;
END_VAR

Mismatched Variables Size/Types

Back to Table of Contents

In certain cases, our IO variables may not have the same size as the hardware variable to which we want to link them; for example, accessing bits in a byte or combining separate bytes into a word. It may be simpler/more readable to just make sure the IO variable does match the type of the hardware variable and handle any interpretation within the PLC. But, in the event that this isn’t possible, there is a solution. 

The TcLinkToOSO attribute allows us to select exactly which bit range from our hardware will be mapped to our IO variables in the PLC program. “OSO” stands for “Offset, Size, Offset,” which is the extra information we will have to supply. The syntax is <x,y,z>, where: 

x = Bit-offset of the PLC variable 

y = Number of bits to map 

z = Bit-offset of the hardware variable 

For example:

VAR
    {attribute 'TcLinkToOSO' := '
        <0,16,0>TIID^Master_EtherCAT^Coupler_EK1100^Term4_EL4008^AO Outputs Channel 6^Analog output;
        <16,16,0>TIID^Master_EtherCAT^Coupler_EK1100^Term4_EL4008^AO Outputs Channel 7^Analog output;
    '}
    dintLinkedTo2Ints AT %Q* : DINT;
END_VAR

VAR
    {attribute 'TcLinkToOSO' := '
        <0,16,0>TIID^Master_EtherCAT^Coupler_EK1100^Term4_EL4008^AO Outputs Channel 6^Analog output;
        <16,16,0>TIID^Master_EtherCAT^Coupler_EK1100^Term4_EL4008^AO Outputs Channel 7^Analog output;
    '}
    dintLinkedTo2Ints AT %Q* : DINT;
END_VAR

Here we are linking a larger PLC variable to two smaller hardware variables. We specify that the first 16 bits of the PLC DINT (x=0, y=16) should be linked to the first 16 bits of the specified 16-bit integer input channel (y=16, z=0). The result is the prefix of the first line, with <0,16,0>. 

Then, starting at bit 16 in the PLC DINT (x=16), we link the next 16 bits (y=16) to the first 16 bits of a separate 16-bit integer input channel (y=16, z=0). The result is the prefix of the second line, with <16,16,0>.

Another example, this time linking 2 smaller PLC variables to a larger hardware variable: 

VAR
    {attribute 'TcLinkToOSO' :=
        '<0,8,0>TIID^Master_EtherCAT^Coupler_EK1100^Term4_EL4008^AO Outputs Channel 8^Analog output'}
    byte0LinkedToInt AT %Q* : BYTE;

    {attribute 'TcLinkToOSO' :=
        '<0,8,8>TIID^Master_EtherCAT^Coupler_EK1100^Term4_EL4008^AO Outputs Channel 8^Analog output'}
    byte1LinkedToInt AT %Q* : BYTE;
END_VAR

VAR
    {attribute 'TcLinkToOSO' :=
        '<0,8,0>TIID^Master_EtherCAT^Coupler_EK1100^Term4_EL4008^AO Outputs Channel 8^Analog output'}
    byte0LinkedToInt AT %Q* : BYTE;

    {attribute 'TcLinkToOSO' :=
        '<0,8,8>TIID^Master_EtherCAT^Coupler_EK1100^Term4_EL4008^AO Outputs Channel 8^Analog output'}
    byte1LinkedToInt AT %Q* : BYTE;
END_VAR

Here, we link the first 8 bits of the first PLC byte (x=0, y=8) to the first 8 bits of the specified 16-bit integer input channel (y=8, z=0). The result is the attribute for the first variable, <0,8,0>.

Then, we link the first 8 bits of the second PLC byte (x=0, y=8) to the second 8 bits of the same specified 16-bit integer input channel (y=8, z=8). The result is the attribute for the second variable, <0,8,8>.

Variables linked with TcLinkToOSO can also be placed within structures/function blocks.

// Type definition
TYPE ST_IntSplitToBytes :
STRUCT
    byteArr : ARRAY[0..1] OF BYTE;
END_STRUCT
END_TYPE


// Declaration
VAR
    {attribute 'TcLinkToOSO' := '
        .byteArr[0] := <0,8,0>TIID^Master_EtherCAT^Coupler_EK1100^Term3_EL3008^AI Standard Channel 6^Value;
        .byteArr[1] := <0,8,8>TIID^Master_EtherCAT^Coupler_EK1100^Term3_EL3008^AI Standard Channel 6^Value
    '}
    structOSOLinking AT %I* : ST_IntSplitToBytes;
END_VAR

// Type definition
TYPE ST_IntSplitToBytes :
STRUCT
    byteArr : ARRAY[0..1] OF BYTE;
END_STRUCT
END_TYPE


// Declaration
VAR
    {attribute 'TcLinkToOSO' := '
        .byteArr[0] := <0,8,0>TIID^Master_EtherCAT^Coupler_EK1100^Term3_EL3008^AI Standard Channel 6^Value;
        .byteArr[1] := <0,8,8>TIID^Master_EtherCAT^Coupler_EK1100^Term3_EL3008^AI Standard Channel 6^Value
    '}
    structOSOLinking AT %I* : ST_IntSplitToBytes;
END_VAR

Motion

Back to Table of Contents

Linking AXIS_REF structures uses a different attribute, TcNcAxis. All that is needed in this case is the axis name from the MOTION NC task setup, instead of the hardware path.

VAR
    {attribute 'TcNcAxis' := 'Axis2'}
    axis2 : AXIS_REF;
END_VAR

VAR
    {attribute 'TcNcAxis' := 'Axis2'}
    axis2 : AXIS_REF;
END_VAR

AXIS_REF structures can also be linked from within structures/function blocks.

// Type definition
TYPE ST_Axis :
STRUCT
    axis : AXIS_REF;

    some      AT %I* : BOOL;
    other     AT %I* : INT;
    variables AT %I* : INT;

    included  : REAL;
END_STRUCT
END_TYPE


// Declaration
VAR
    {attribute 'TcNcAxis' := '
        .axis := Axis3;
    '}
    structAxis : ST_Axis;
END_VAR

// Type definition
TYPE ST_Axis :
STRUCT
    axis : AXIS_REF;

    some      AT %I* : BOOL;
    other     AT %I* : INT;
    variables AT %I* : INT;

    included  : REAL;
END_STRUCT
END_TYPE


// Declaration
VAR
    {attribute 'TcNcAxis' := '
        .axis := Axis3;
    '}
    structAxis : ST_Axis;
END_VAR

Combining Linking Attributes

Back to Table of Contents

We can mix and match the different linking attributes as we like; however, we can only use each attribute once — all subsequent uses of that attribute will be ignored. Of course, within a single use of an attribute, we can link multiple variables.

For example, to link the rest of the variables in the above structure:

VAR
    {attribute 'TcNcAxis' := '
        .axis := Axis3;
    '}

    {attribute 'TcLinkTo' := '
        .some  := TIID^Master_EtherCAT^Coupler_EK1100^Term1_EL1008^Channel 8^Input;
        .other := TIID^Master_EtherCAT^Coupler_EK1100^Term3_EL3008^AI Standard Channel 7^Value;
    '}

    {attribute 'TcLinkToOSO' := '
        .variables := <0,4,0>TIID^Master_EtherCAT^Coupler_EK1100^Term3_EL3008^AI Standard Channel 8^Value;
    '}

    structAxis : ST_Axis;
END_VAR

VAR
    {attribute 'TcNcAxis' := '
        .axis := Axis3;
    '}

    {attribute 'TcLinkTo' := '
        .some  := TIID^Master_EtherCAT^Coupler_EK1100^Term1_EL1008^Channel 8^Input;
        .other := TIID^Master_EtherCAT^Coupler_EK1100^Term3_EL3008^AI Standard Channel 7^Value;
    '}

    {attribute 'TcLinkToOSO' := '
        .variables := <0,4,0>TIID^Master_EtherCAT^Coupler_EK1100^Term3_EL3008^AI Standard Channel 8^Value;
    '}

    structAxis : ST_Axis;
END_VAR

Comparisons

Back to Table of Contents

Now that we have multiple methods for linking PLC variables to hardware, why might we choose one over the others? Here are some pros/cons for each method — if you have other thoughts, please leave them in the comment section below! 

Manual

Pros

• When variables are manually linked, the link will automatically update if the name of a hardware card/channel changes. With attribute linking, such a name change will break the hardware link until the attribute hardware path is updated in the PLC declaration code.
• As mentioned above, when linking variables, we can start from either direction — PLC to hardware or hardware to PLC. Since attribute linking must be done within the PLC source code, it can only be done from PLC to hardware. The flexibility of manual linking might come in handy when reading from large IO sheets that are organized for electrical cabinet wiring. 

Cons

• Manual hardware links are stored in an XML format in .tsproj or .xti files (depending on a project’s independent project files settings). These files may change often and contain plenty of other information not related to hardware linking. Also, the XML that defines the hardware mapping is not as directly readable as the hardware paths used for attribute linking. For these reasons, changes in hardware linking are less visible in version control — it may be harder to look through commit histories and find where these changes were made and what they mean.
• Because manual hardware links are stored in XML format, manual hardware linking is more easily lost during merges. This can cause headaches, especially when working with a multi-developer team.

Attribute

Pros

• Perhaps the biggest positive of using attribute linking is its compatibility with version control. Attribute linking exists within source code rather than being stuck in the XML of project files; therefore, it merges as easily as source code does and is much more visible for tracking/finding changes. 
• Manual linking is, well, manual, and must be set up one variable at a time. Attribute linking exists within code, with a predictable syntax. For this reason, depending on the architecture of our program, it may be very easy to write a simple program (in Python, for example) to automate our hardware linking for us. The program could take in a CSV of hardware points/IO variable names and output the attribute linking syntax required. Then updating IO linking is a breeze – just make updates to the CSV, run the Python program, and copy and paste the resulting attribute/declaration code into the project. 

Cons

• Attribute linking requires precise syntax, which can be tedious to get right. 
• If the name of a hardware card/channel changes, the link will not automatically update. The attribute linking source code must be updated to reflect this change. If this is a higher-level component, like an EtherCAT Master, this could mean editing a lot of code – or automating the update using find and replace or a custom program like mentioned above.

Project Variants

Back to Table of Contents

One of TwinCAT’s unique and powerful features is the concept of project variants, and one of their uses is to allow modification of hardware mapping depending on the selected variant. This can be used regardless of which linking method is used. For manual mapping, follow these instructions. For attribute mapping, we can use conditional pragmas. Here is an example of how one might use these pragmas to change hardware linking based on the selected project variant. Keep in mind that we will have to build the project with a certain variant selected for that variant’s hardware linking to appear in the solution explorer.

VAR

    {IF defined(Variant1)}
        {attribute 'TcLinkTo' := '
            .boolInput  := TIID^Master_EtherCAT^Coupler_EK1100^Term1_EL1008^Channel 6^Input;
            .boolOutput := TIID^Master_EtherCAT^Coupler_EK1100^Term2_EL2008^Channel 6^Output;
        '}
    {END_IF}

    {IF defined(Variant2)}
        {attribute 'TcLinkTo' := '
            .boolInput  := TIID^Master_EtherCAT^Coupler_EK1100^Term1_EL1008^Channel 7^Input;
            .boolOutput := TIID^Master_EtherCAT^Coupler_EK1100^Term2_EL2008^Channel 6^Output;
        '}
    {END_IF}

    variantsExample : ST_IncludingIO;

END_VAR

VAR

    {IF defined(Variant1)}
        {attribute 'TcLinkTo' := '
            .boolInput  := TIID^Master_EtherCAT^Coupler_EK1100^Term1_EL1008^Channel 6^Input;
            .boolOutput := TIID^Master_EtherCAT^Coupler_EK1100^Term2_EL2008^Channel 6^Output;
        '}
    {END_IF}

    {IF defined(Variant2)}
        {attribute 'TcLinkTo' := '
            .boolInput  := TIID^Master_EtherCAT^Coupler_EK1100^Term1_EL1008^Channel 7^Input;
            .boolOutput := TIID^Master_EtherCAT^Coupler_EK1100^Term2_EL2008^Channel 6^Output;
        '}
    {END_IF}

    variantsExample : ST_IncludingIO;

END_VAR

Unfortunately, since each linking attribute can only be used once, every single variable link for a structure must be included in the conditional statement for every variant — regardless of whether a particular variable link changes depending on the project variant. This can be more tedious than manual linking while using project variants, but it’s a lot more explicit — since the two link lists are explicitly in code, rather than hidden away in the solution explorer menus.

Further Reference

Back to Table of Contents

For more information on the topics discussed in this blog, please see the following:

• TcLinkTo / TcLinkToOSO Infosys Page
• TcNcAxis Infosys Page
• AXIS_REF Infosys Page
• Tc2_MC2 Infosys Section
• Simulation Axis Infosys Page
• TwinCAT with Version Control Blog
• TwinCAT Project Variants Blog

That’s about all you need to know to get started with hardware linking in your TwinCAT projects! If you’ve got any further tips and tricks regarding this topic, please share them in the comments below!

Learn more about DMC’s Beckhoff and TwinCAT 3 Programming expertise and contact us today for your next project.

The post How to Link Hardware / IO in Beckhoff TwinCAT 3 appeared first on DMC, Inc..

If you’ve ever gone through a project archive, found something that looks like the following:

• Project_20180807
• Project_20180813
• Project_20180813_Final
• Project_20180813_FinalB
• Project_20180813_FinalFinal
• Project_20180813_Newest_I_SWEAR

…and been confused about what the most recent version of the project is, then you’ve experienced one of the many reasons to use version control systems! 

From backing up code to tracking changes to concurrent multi-user development, version control systems (VCS) offer so many advantages that they should be an essential tool for any software engineer. Yet the automation industry has struggled to effectively use all the advantages that VCS offer. 

Proprietary and binary file formats that are common in the automation industry prevent the full use of many VCS, which generally provide the most benefit when tracking text-based files.

Luckily, Beckhoff TwinCAT 3 stores project files and code in text-based file formats, making it a great candidate for use with version control software. This blog will discuss tips and tricks for optimizing the use of TwinCAT with version control and for development with multiple users. 

I’ve also written a companion blog with an easy, step-by-step guide to setting up a TwinCAT project for use with version control, so be sure to check that out!

A couple quick disclaimers:

DMC leverages Git (specifically Gitlab) as a VCS to use with TwinCAT, but much of the information discussed in this blog will be applicable across many VCS.

This blog will discuss many of the things DMC has learned through the years that have made our lives easier. By no means is our workflow the only workflow; one of the many beauties of version control is that it is flexible – use it however works best for you, and take or leave as many of our tips as you like!

Alright, let’s get started.

Table of Contents:

1. TwinCAT Project Settings
   1. Separating Project Components into Individual Files
   2. Keep Unrestored Links
2. TwinCAT Version Management
   1. Pinning Library Effective Versions
   2. Standardizing Versions of TwinCAT and Add-On Modules
3. Tips for using Git with TwinCAT
   1. Gitignore
   2. Merging
      1. General Workflow
      2. Conflicts
      3. Separating LineIDs
4. Other Tips
5. Further Reference

TwinCAT Project Settings

Back to Table of Contents

There are some settings you can configure when setting up your TwinCAT solution that will optimize your project for use with version control. Instructions for this setup are detailed in my companion blog Setting up a TwinCAT 3 Project for Version Control; however, I’ve included additional details here to give background on why these settings are helpful.

Separating Project Components into Individual Files

Back to Table of Contents

Many TwinCAT project components, such as hardware configuration or variable mapping, default to being grouped together into project files. In the context of version control, this means changes to these files will happen often. 

The version control software will still track these changes, but it may be harder to follow the thread of changes to a specific component in the bulk project file. Furthermore, if every developer is making constant changes to the bulk project file, it increases the chances of merge conflicts and the headaches that may arise because of them.

Many of these elements can be separated out into their own individual files. Much like the creation of this article, it is DMC’s best practice to save as many elements as possible in separate files to better track and merge changes with them. Instructions for doing so can be found in Step 1 of the companion blog.

Keep Unrestored Links

Back to Table of Contents

TwinCAT automatically deletes variable links that are found to be invalid in the process image. This can cause problems when merging branches.

The process image is only updated when code is recompiled after a merge, not during the merge itself; therefore, although links might be valid after compilation occurs, they can be considered invalid just after a merge and then get deleted.

Instructions to prevent this from happening can be found in Step 2 of the Setup Blog. This step also includes a method of exporting variable mappings so that they can later be reimported if they are lost.

TwinCAT Version Management

Back to Table of Contents

Beckhoff often releases new versions of TwinCAT along with various additional modules. Sometimes this causes problems when developing on a team with multiple engineers.

•  Accidental Project/Component Upgrades

Developers might work across several projects simultaneously, many of which could be on different TwinCAT versions. TwinCAT Remote Manager can be a great help in this situation – at least for PLC development –  but developers with newer TwinCAT versions installed might inadvertently upgrade projects – causing problems for other developers.

• Library Mismatches

Sometimes, new TwinCAT versions come with improvements to Beckhoff’s standard libraries. Generally, projects are configured to use the most recent library version by default; however, if two engineers have different most recent versions, it can prevent one of them from going online even with otherwise identical code.

• Supporting Legacy Machines

Legacy machines might use older versions of TwinCAT. In machine-down events or even less critical troubleshooting, dealing with project versioning/upgrades might eat up critical time. Some hardware may not even be compatible with upgraded versions. All around, it’s less of a headache to just have the proper versions available to get online and solve problems with these machines quickly.

The following are some actions you can take to ensure smooth support of many projects with varied TwinCAT versions by a team of multiple engineers.

Pinning Project Version

Back to Table of Contents

TwinCAT XAE Projects can be pinned to a certain version of TwinCAT. By doing this, you ensure that the Remote Manager will automatically load the proper TwinCAT build  whenever you open the project (so long as that build is installed on your system).

This will prevent you from accidentally upgrading the project because you forgot to manually select the proper build in Remote Manager. Again, very helpful for a team of multiple engineers that might have many different TwinCAT versions installed on their computers.

Instructions for pinning project versions can be found in Step 3 of the Setup Blog.

Pinning Library Effective Versions

Back to Table of Contents

Libraries in TwinCAT projects are set to use the newest version available on a developer’s computer by default. This can be a problem, however, if one developer downloads to a PLC with one library version but another developer has a different library as their newest library version. The latter developer will not be able to log into the PLC without changes. At DMC we’ve encountered this problem several times when multiple developers are onsite supporting a line.

The solution to this is to pin the libraries’ versions. It generally doesn’t matter which library version is picked for each library (unless newer versions have bugfixes that are necessary), so we usually just pick the newest library version available at the time of project creation or deployment.

This can create a new problem (especially when supporting legacy machines) if some developers do not have the proper library versions available on their computers. These versions will need to be obtained and installed.

Instructions for obtaining, installing, and pinning library versions can be found in Step 4 of the Setup Blog.

Standardizing Versions of TwinCAT and Add-On Modules

Back to Table of Contents

Each of the above recommendations for keeping items in the project pinned rely on you having the proper TwinCAT/add-on module versions available on your computer in the first place.

You can generally determine the project version before opening it by opening the project file in a text editor. For example, the .tsproj file for the XAE project shows the project version at the top of the XML.

 TE2000 TCHMI projects should also have version info in the .hmiproj file.

 You can also determine what version of TwinCAT/add-on modules are installed through your control panel’s apps & features list.

For TwinCAT, it’s generally not harmful to upgrade to the most recent minor revision of a build (ex: 4018.33 –> 4018.58) – though there are exceptions. It is not necessarily possible to upgrade between major revisions of builds (ex: 4018.33 –> 4024.22). 

Beckhoff offers downloads for the TwinCAT Remote Manager of the most recent versions of major revisions for exactly this use, which is very handy.

The Remote Manager is not available for additional modules including: 

• TE2000 TCHMI Engineering
• TF2000 TCHMI Runtime
• TF6100 OPC UA
• TE9000 Safety Editor

Upgrading usually works fairly well, so long as all developers install the same engineering version of each module (if applicable) on their development computers, but there may be situations (like legacy machines or multi-user projects) where upgrading is not practical or possible. For these situations, I recommend hanging onto the installers for the different components of a project and storing them in a central server or repository the whole team can access. This way developers can grab them and install them when necessary. 

However, BE WARNED! You cannot install an older version of TwinCAT on a machine where a newer version is installed. If Remote Manager does not satisfy your needs, you will need to set up a new development environment with the proper build or uninstall the newer builds before you install the old one.

It is important to enforce that all developers have the same versions of the project components installed in their development environment. This will ensure the smoothest collaboration between multiple developers.

If you’d like to learn more about library/TwinCAT versioning, I’d recommend reading this excellent blog.

Tips for using Git with TwinCAT

Back to Table of Contents

DMC commonly uses Git as a VCS with TwinCAT for the many benefits Git offers for text-based version control. The following topics are by no means a thorough discussion of using Git (there are plenty of resources you can Google for that), but I’ve included some tips DMC has discovered along the way that might help you to use Git with TwinCAT.

Again, I’ll state the disclaimer: by no means are these tips the only or the best way to use Git with TwinCAT! Not even everyone here at DMC uses Git in the same way – if you’ve got suggestions or a workflow that works very well for you, we’d love to hear down in the comments!

Gitignore

Back to Table of Contents

The .gitignore file is used to tell Git which files it can ignore to prevent the repository from becoming bloated by tracking unnecessary changes. This can be very helpful with TwinCAT project folders which contain items like user-specific Visual Studio configuration files and builds that can be recompiled at will from the source code in the repository.

A basic TwinCAT 3 gitignore template created by Jakob Sagatowski has been added to Github’s gitignore collection. Of course, this is a basic template and may not cover everything you need to ignore in your project. Another good example, with more items included, is the gitignore for TcUnit, by the same creator.

The above gitignore examples include the *.tclrs file type, which holds license information. Oftentimes at DMC we store these license files in our repositories as a backup for our clients, so we opt not to include this in our gitignores. You can also remove any file types you’d like to track as you see fit from your gitignore.

After setting up a gitignore in your repository, you may still find that some temporary, user-specific, or unnecessary files are still tracked and not included in the gitignore. Feel free to add them to the gitignore file, but do so with caution. Make sure, if you’re going to add something to the gitignore, you have a good reason for doing so and know that a file doesn’t need to be tracked! 

Some files in TwinCAT projects, like .xti files, might update often, even when it seems like you’ve made no changes to the project. However, some of these files also include crucial information that you don’t want to get lost (for example, IO links), so don’t ignore them unless you know you can do so without losing information.

In the event you do add a rule to your gitignore, you may find that files are still being tracked that match that rule. This is probably because these files were tracked before the change to the gitignore and need to be manually removed from tracking. Follow the instructions here to do so.

Merging

Back to Table of Contents

The ability to merge changes from different development branches into one project is one of the greatest strengths of using a VCS with TwinCAT. Other automation platforms may or may not have their own merge tools, but TwinCAT has an advantage with its plaintext file formats. This means we can leverage Git’s built-in merging functionalities to make our lives much easier.

Again, this is not an in-depth explanation of merging (which would require a much longer article), but it is just some tips and tricks DMC has found along the way.

General Workflow

Back to Table of Contents

Beckhoff recommends configuring TcProjectCompare, TwinCAT’s merge tool, to merge projects and deactivating automatic merging.

In general, DMC has not found this to be necessary. Although problems can occur, we often find that most merges done directly through Git are successful, especially when splitting the project into individual files. 

Merges involving hardware linking or multiple developers making changes to the same aspects of project configuration can sometimes be more suspect. They might require a closer eye on the merge result. In general, it is good practice to ensure the project compiles properly after a merge and that changes to project configuration are preserved. But for typical changes to POUs, DUTs, and other code objects, the merging process is generally quite smooth.

If you’ve run into situations where you often find items are lost in merges or have configured TcProjectCompare as a merge tool and have some thoughts, please leave a comment below!

Conflicts

Back to Table of Contents

Inevitably during multi-user development, you will run into conflicts when two developers have edited the same piece of code. To manually resolve them, a mergetool is needed. Mergetools allow you to manually indicate which portions of conflicting code you’d like to keep. 

DMC often uses VS Code as a mergetool for TwinCAT development. To configure VS Code as a mergetool, see these instructions. Of course, you can use whichever mergetool you prefer.

One common merge conflict that is specific to TwinCAT is conflicts in the “LineID” XML elements at the end of code files. POUs, DUTs, and other code objects are stored in an XML format. Sometimes, if extensive changes have been made in two separate branches to that code object, conflicts occur in these elements. Using VS Code as a mergetool, these conflicts look like this:

In this scenario, it generally doesn’t matter which change is accepted. Accept one of the two changes, then make sure to open the project/code object in TwinCAT and compile before committing the in-progress merge. 

When opening the code object, TwinCAT should handle properly correcting the format of these XML elements. If there aren’t problems in the compilation, you should be good to go.

Separating LineIDs

Back to Table of Contents

Alternatively, to avoid these conflicts and LineIDs appearing in source control altogether, you can activate the Separate LineIDs option in your TwinCAT XAE environment.

LineIDs are required for breakpoint handling and to ensure code lines can be assigned to machine code instructions. But instead of storing them with the source code (as is done by default), this option separates them into a file called LineIDs.dbg – a binary file which is rebuilt when the project is modified/saved.

If you paid close attention to the aforementioned gitignore templates, you might have noticed that LineIDs.dbg can be safely ignored by source control since it is constantly being rebuilt. Comparing the same source code file generated with this setting deactivated and with it activated, we can see that the only difference is the removal of the LineIDs section – which should prevent us from tracking changes and running into merge conflicts in this section.

A word of caution – if you plan to use this setting with a multi-developer team, you'll need to make sure all developers have the same value for this setting in their development environments. Otherwise you may wreak havoc on your source control, with some developers constantly saving their files with separate LineIDs and others constantly saving their files with included LineIDs.

Instructions for setting the Separate LineIDs setting can be found in Step 5 of the Setup Blog.

Other Tips

Back to Table of Contents

It’s generally a good idea to close the project before switching branches/performing merges. TCXAE will sometimes detect if the project has been externally modified (ex: by Git), but sometimes it won’t. To make sure you’re not accidentally editing the wrong project version, close the project and re-open after you’re done performing Git operations.

Further Reference

Back to Table of Contents

For more information on version control in general and with TwinCAT, please see the following links:

• Setting up a TwinCAT 3 Project for Version Control: A Step-by-Step Guide
• TwinCAT Source Control Infosys Section
• TwinCAT Remote Manager Infosys Section
• TwinCAT Versioning Blog
• Version Control Introduction
• Git For Windows
• VS Code
• Configuring VS Code as a Mergetool
• Atlassian’s Gitignore Tutorial
• TwinCAT Gitignore Blog
• TwinCAT LineIDs Infosys Page

If you’ve got any other suggestions for tips and tricks to use TwinCAT with version control and/or multiple users, please leave them in the comments below! DMC is always committed to improving our workflow, so we’d love to hear your thoughts.

Learn more about DMC's Beckhoff and TwinCAT 3 programming expertise and contact us for your next project. 

The post Version Control and Multi-user Development with Beckhoff TwinCAT 3 appeared first on DMC, Inc..