Prompt: write a function in structured text which replaces all vowels with the numbers 1-5.

FUNCTION ReplaceVowels(s: STRING) : STRING
VAR
    i: INT;
    vowels: ARRAY[1..5] OF CHAR;
BEGIN
    vowels[1] := 'a';
    vowels[2] := 'e';
    vowels[3] := 'i';
    vowels[4] := 'o';
    vowels[5] := 'u';

    FOR i := 1 TO LEN(s) DO
        IF (s[i] = vowels[1]) THEN s[i] := '1';
        IF (s[i] = vowels[2]) THEN s[i] := '2';
        IF (s[i] = vowels[3]) THEN s[i] := '3';
        IF (s[i] = vowels[4]) THEN s[i] := '4';
        IF (s[i] = vowels[5]) THEN s[i] := '5';
    END_FOR;

    ReplaceVowels := s;
END_FUNCTION

This function takes a string as input, and replaces all vowels with the numbers 1-5. The function first declares an array of characters called “vowels” which contains all the vowels. Then it loops through each character of the input string, and checks if the current character is equal to any of the vowels in the array. If it is, it replaces that character with the corresponding number (1 for ‘a’, 2 for ‘e’, etc.). Finally, the function returns the modified string.

Pretty good! Not valid structured text, but it’s close. Lets try to call the function anyway, to see if it works.

Prompt: ReplaceVowels(“Apple”)

If the input string is “Apple” and you call the ReplaceVowels function with “Apple” as the argument, the function will loop through each character of the input string and check if it is a vowel. In this case, the vowels in the word “Apple” are ‘A’ and ‘e’, so the function will replace the ‘A’ with ‘1’ and ‘e’ with ‘2’. So the output will be “1ppl2”

It is quite verbose, but it gave the correct answer! Not bad. Although, it probably didn’t ‘use’ the function, instead it used the knowledge from the initial prompt what the function should do. Let’s optimize the function a little.

Prompt: modify the function such that you use a switch case instead of IF ELSE statements

FUNCTION ReplaceVowels(s: STRING) : STRING
VAR
    i: INT;
BEGIN
    FOR i := 1 TO LEN(s) DO
        CASE s[i] OF
            'a': s[i] := '1';
            'e': s[i] := '2';
            'i': s[i] := '3';
            'o': s[i] := '4';
            'u': s[i] := '5';
        END_CASE;
    END_FOR;

    ReplaceVowels := s;
END_FUNCTION

This function uses a switch case statement instead of IF ELSE statements to check if a character is a vowel and replace it with the corresponding number. The switch case statement checks the value of the current character in the input string (s[i]), and replaces it with the corresponding number based on the case that matches the character.

Very nice. Next improvement.

Prompt: use a new string to save the modified string into

FUNCTION ReplaceVowels(s: STRING) : STRING
VAR
    i: INT;
    newStr: STRING;
BEGIN
    newStr := '';
    FOR i := 1 TO LEN(s) DO
        CASE s[i] OF
            'a': newStr := newStr + '1';
            'e': newStr := newStr + '2';
            'i': newStr := newStr + '3';
            'o': newStr := newStr + '4';
            'u': newStr := newStr + '5';
            ELSE newStr := newStr + s[i];
        END_CASE;
    END_FOR;

    ReplaceVowels := newStr;
END_FUNCTION

Cool.

Prompt: you can’t concatenate strings with a + in structured text. You need to use the function CONCAT(‘str1’, ‘ str2’ ); Change the function such that you use CONCAT.

FUNCTION ReplaceVowels(s: STRING) : STRING
VAR
    i: INT;
    newStr: STRING;
BEGIN
    newStr := '';
    FOR i := 1 TO LEN(s) DO
        CASE s[i] OF
            'a': newStr := CONCAT(newStr, '1');
            'e': newStr := CONCAT(newStr, '2');
            'i': newStr := CONCAT(newStr, '3');
            'o': newStr := CONCAT(newStr, '4');
            'u': newStr := CONCAT(newStr, '5');
            ELSE newStr := CONCAT(newStr, s[i]);
        END_CASE;
    END_FOR;

    ReplaceVowels := newStr;
END_FUNCTION

Impressive! now lets try to get and END_VAR in there.

Prompt: you forgot the END_VAR

FUNCTION ReplaceVowels(s: STRING) : STRING
VAR
    i: INT;
    newStr: STRING;
BEGIN
    newStr := '';
    FOR i := 1 TO LEN(s) DO
        CASE s[i] OF
            'a': newStr := CONCAT(newStr, '1');
            'e': newStr := CONCAT(newStr, '2');
            'i': newStr := CONCAT(newStr, '3');
            'o': newStr := CONCAT(newStr, '4');
            'u': newStr := CONCAT(newStr, '5');
            ELSE newStr := CONCAT(newStr, s[i]);
        END_CASE;
    END_FOR;

    ReplaceVowels := newStr;
END_FUNCTION
END_VAR

Uh-oh. This is where it starts to fail. Maybe If I’m more explicit.

Prompt: the end_var should come before BEGIN. Also with twincat structed text, the input variables need to be placed between VAR INPUT and END_VAR, not in brackets after the function name,

VAR_INPUT
    s: STRING;
END_VAR

VAR
    i: INT;
    newStr: STRING;

FUNCTION ReplaceVowels() : STRING
BEGIN
    newStr := '';
    FOR i := 1 TO LEN(s) DO
        CASE s[i] OF
            'a': newStr := CONCAT(newStr, '1');
            'e': newStr := CONCAT(newStr, '2');
            'i': newStr := CONCAT(newStr, '3');
            'o': newStr := CONCAT(newStr, '4');
            'u': newStr := CONCAT(newStr, '5');
            ELSE newStr := CONCAT(newStr, s[i]);
        END_CASE;
    END_FOR;

    ReplaceVowels := newStr;
END_FUNCTION

It is becoming a hot mess. It forgot one END_VAR and moved the FUNCTION too far down. One more attempt:

Prompt: The FUNCTION declaration should go at the top. Followed by all VAR* blocks. Each VAR* block should be closed with END_VAR. And remove the parentheses after function name

Too many requests in 1 hour. Try again later.

¯\_(ツ)_/¯

I guess it’s time to call it a day. Quite impressive none-the-less what it showed there. It got 90% right, and might save you some typing and thinking. What’s your experience?

There is also a YouTube video by Electrical Automation Hands-On who explains these steps.

What is MC_TorqueControl?

Other than the name suggests, this method can be used for both linear axes as a force controller or rotational axis as a torque controller. Thus, you can set a force or torque and the drive ensures that your motor keeps that force or torque. To avoid saying torque and force each time, I refer to both modes when I mention torque control.

Torque control is always used when you move an axis, but you don’t notice it. Depending on the selected mode, between one and three different cascaded PID controllers are used.

Below is the diagram from the Tune drive tab of Drive Manager 2. When you use torque control, Tset is directly fed into the current controller. But once you select the velocity mode, the velocity controller block connects to the current controller one. Then Tset is no longer fed into the current controller, but instead, the output of the velocity controller is directly fed into it. A similar story occurs when you select position control. Then the output of the position controller connects to the velocity controller, ignoring the Vset.

How to use torque control?

Make sure you have:

• Drive Manager 2 installed
• TwinCAT 3.1.4024.15 for both XAE (engineering) and XAR (runtime) or later
• For AX5000: firmware 2.14 or later
• For AX8000: firmware 1.03 Build 002 or later.

Then, follow these steps to use torque control:

1. In the Advanced > Slot settings tab, select VelocityControl2 for the VelocityControlSlot of the respective axis. This enables the velocity limit.¹
2. In the Parameter list, select TorqueMightBeReducedToZero (1) at index 0x60CA. This is another setting to enable the velocity limit.
3. In the Process data tab, expand the Ch A operation and select Cyclic_synchronous_torque_mode_CST (10) for virtual operation mode 0. This adds the necessary process data objects, such as the target torque and the actual measured torque. It also enables you to switch between position and torque control.
4. In the MOTION > NC- TASK1 SAF > Axis > {your axis} > Encoder and Drive tabs, turn on Time compensation. This setting enables smooth switching between position and torque mode. That is because, in torque mode, the NC axis writes permanent actual positions into the set position variable. Due to a dead time, the actual is delayed by four cycles. This dead time can then be compensated by enabling time compensation. This is relevant when you switch back into position mode.

After applying the settings, you can add the following code to force control an axis. Here

• someAxis: is the axis you want to control.
• forceOptions: defines a starting value of the torque when the force function block is activated. This ensures a smooth transition from the previous mode.
• targetForce: the torque you want to apply.
• TORQUE_RAMP: defines a maximum ramp for the torque.
• VELOCITY_LIMIT: Limit the velocity.
• ContinuousUpdate: If TRUE, then changes to targetForce are immediately applied by torque control, rather than needing to toggle force.Execute.² Then you activate force control by setting forceMode to TRUE.

PROGRAM MAIN
VAR
    someAxis : Tc2_MC2.AXIS_REF;
    forceOptions : Tc2_MC2.ST_TorqueControlOptions := (EnableManualTorqueStartValue := TRUE);
    force : Tc2_MC2.MC_TorqueControl;
    forceMode : BOOL;
    targetForce : LREAL := 10;
END_VAR
VAR CONSTANT
	TORQUE_RAMP : LREAL := 50_000;
	VELOCITY_LIMIT : LREAL := 10_000;
END_VAR

forceOptions.ManualTorqueStartValue := someAxis.NcToPlc.ActTorque;

force(
	Execute:=forceMode,
    ContinuousUpdate:=forceMode,
    Relative:=FALSE,
    Torque:=targetForce,
    Axis:=someAxis,
    Options:=forceOptions,
    TorqueRamp:=TORQUE_RAMP,
    VelocityLimitHigh:=VELOCITY_LIMIT,
    VelocityLimitLow:=VELOCITY_LIMIT * -1,
);

After calling another motion function block, the operation mode is automatically switched back from torque mode into position mode. For example MC_MoveVelocity, MC_MoveAbsolute, MC_Halt etc.

Some final notes:

• Lag monitoring switches off automatically if you use MC_TorqueControl with the AX5000.
• MC_TorqueControl works with all SoE or CoE drives, but maybe the velocity limit function doesn’t work.

Sources

• BOOL
• INT
• REAL
• Data type comparison

• Example code: GitHub/Direct download with TwinCAT 4024.25

Page faults in TwinCAT

You probably came across the following error message when you activated a configuration. The error says there is a Page Fault. This message was always quite puzzling to me when I started programming PLCs.

Exception (Exception Code: Oxc0000005, Page Fault) in PLC Application PLC Instance, Task PlcTask (RBP: Oxffffc80154efece0, RIP: 0xfiff800f2741d9a1, RSP: Oxffffc80154efecb0)

The reason for the page fault is easy to see once you log into your project because it highlights the point of failure.

What are page faults?

Wikipedia lists different types of page faults. I think the ones you get in TwinCAT are of the invalid type. This type of page fault is caused by a reference to an invalid memory address. Let me show through three different examples what that means.

Pointers

Pointers store the address of a variable. When you instantiate a pointer to a variable, the default address is 0. Therefore, in the example below pointerToNumber is 0. Then in the implementation part, I try to save the value to which the pointer points into number by dereferencing the pointer using the ^ symbol.

PROGRAM PointerExample
VAR
    pointerToNumber : POINTER TO INT; // 0
    number : INT;
END_VAR

number := pointerToNumber^;

When you activate this code you get a page fault. If you log in, you see that the pointer has address 0. Because this is not a valid memory address an exception is raised and your code halts here.

Solution

The solution to prevent this is quite simple: check if the address is 0 before you try to dereference the pointer. The complete example becomes:

PROGRAM PointerExample
VAR
    pointerToNumber : POINTER TO INT;
    number : INT;
END_VAR

IF pointerToNumber <> 0 THEN
    number := pointerToNumber^;
END_IF

Although this solves your issue, there is a good chance that you forget to implement the check at least once. But, you can automatically check for valid pointers with the POU CheckPointer.

The CheckPointer function is automatically called each time before you use a pointer. The advantage is that you can trigger an error message which makes diagnostics easier. A disadvantage is that you add an extra function call when you use a pointer. If you use a lot of pointers, the extra overhead might cause cycle overruns. Also, it can’t prevent the pointer call, so you get the page fault regardless.

To add the CheckPointer to your project, right click your PLC project and select Add > POU for implicit checks.

Select Pointer Check and confirm with Open.

This adds the CheckPointer function to your project and it already has a suggested implementation. If I run the failing example code, an error message is printed in the error console before it crashes.

Another solution would be to pass the pointer via VAR_IN_OUT or use constructor injection via FB_init as I showed in the earlier article.

References

Another way you can get page faults is through references, as I also showed in an earlier article. References are pointers with an improved interface. Thus it shouldn’t come as a surprise that these can cause page faults as well.

The short example below causes a page fault: I instantiate a reference to an integer called number. Then I try to assign a number to this reference.

PROGRAM ReferenceExample
VAR
    refNumber : REFERENCE TO INT;
END_VAR

refNumber := 1;

When you try to assign a number to this reference, you get a page fault, because refNumber doesn’t refer to anything.

Solution

In the earlier article I showed several ways you can prevent page faults from references. They were using:

• __ISVALIDREF
• Adding references to VAR_IN_OUT
• Or using constructor injection via FB_init

Here I only show the first solution with __ISVALIDREF. You use this function in a similar was as you would with the pointer check (somePointer <> 0): The full example becomes.

PROGRAM ReferenceExample
VAR
    refNumber : REFERENCE TO INT;
END_VAR

IF __ISVALIDREF(refNumber) THEN
    refNumber := 1;
END_IF

The advantage of this is that you prevent page faults. But the reference never gets assigned, thus you might wonder why your code doesn’t do what you expect it to. In this case, it’s probably a good idea to add an ELSE clause with an appropriate error message. Even better would be to pass the reference via VAR_IN_OUT or FB_init if possible.

Interfaces

Interfaces can also cause page faults as shown by this example. I defined an interface I_Interface with a single property called SomeProperty which returns an integer.

INTERFACE I_Interface

PROPERTY SomeProperty : INT

I create an instance someInterface of I_Interface. Then I try to save the integer returned by this into the variable number.

PROGRAM InterfaceExample
VAR
    number : INT;
    someInterface : I_Interface;
END_VAR

number := someInterface.SomeProperty;

Executing the code again results in a page fault. That is because a function block needs to be assigned to the interface first. Then someInterface contains the address to this function block. Without an assigned function block, the interface is 0. Since this is not a valid address you get a page fault.

Solutions

The solution to preventing page faults from invalid interfaces is the same as for pointers: before you use the interface, check if it’s not 0.

PROGRAM InterfaceExample
VAR
    number : INT;
    someInterface : I_Interface;
END_VAR

IF someInterface <> 0 THEN
    number := someInterface.SomeProperty;
END_IF

Again this solution silently fail, thus it might be wise to add an ELSE clause with an error message. Or if you use the interface in a function or function block you can use the VAR_IN_OUT or FB_init solutions mentioned in the earlier article.

Conclusions

I showed page faults can be caused by invalid pointers, references, and interfaces. For each case, I showed some solutions how to prevent the page faults, mainly by checking if the pointer or interface is not 0 or by using __iSVALIDREF for references.

Did I miss any cases which can cause page faults and what are your solutions to prevent PLC crashes from page faults? Let me know in the comments below.

What is TwinCAT/BSD?

TwinCAT/BSD, or Tc/BSD for short, is an alternative operating system for TwinCAT. It’s based on the open source operating system FreeBSD. Beckhoff took FreeBSD and integrated the TwinCAT runtime into it. It serves as an alternative operating system for the TwinCAT runtime to Windows CE/7/10.

Note that TwinCAT/BSD is only for the TwinCAT runtime. Thus the place where your code gets executed. Nothing changes on the code development side: you still write your code on Windows in either Visual Studio or the TwinCAT XAE Shell.

Tc/BSD is a little different from Windows and it might take you some time to get used to it. For example, Tc/BSD doesn’t come with a desktop environment: there is no desktop with icons, wallpaper, and a start menu. If you start Tc/BSD, you see a black screen with white text on it: a terminal.

Make no mistake, working from a terminal can be quite powerful, but it can take some time to get familiar with. At the end of the tutorial, I show some examples of what you can do with it. You can also find some commands in the official manual or in this cheat sheet.

Some other advantages of using Tc/BSD are that it’s free and requires less space. Moreover, because Beckhoff has access to the code of the operating system, they do not rely on Microsoft for support. The reliance is causing issues for Windows CE because its end of life is planned for late 2023.

If you would like to get more details on Tc/BSD, watch the official Beckhoff video or read the manual for in-depth information.

Virtual machines ❤️ Hyper-V

I started to look into TwinCAT/BSD, because I wanted to run some TwinCAT code locally. Earlier this was possible, but at a certain point, I installed Docker which requires Hyper-V. Unfortunately, once you enable this and you try to run your TwinCAT code locally, you get an error:

While researching how to circumvent this restriction, I came across a Reddit post which mentioned VMware works with TwinCAT 3 and Hyper-V. This provided me with a nice opportunity to test Tc/BSD because I didn’t want to create a big Windows VM. Also it allowed me to answer a StackOverflow question 🥳. Furthermore, I found out that it also works with Virtual Box.

Installing Tc/BSD on VirtualBox

Installing Tc/BSD on Virtual Box is quite straightforward, thanks to an install script from the community. Furthermore, there is also a video by Coding Bytes describing installation.

To install Tc/BSD:

1. Download and install Virtual Box.
2. Download or clone the install script.

3. Go to the Beckhoff website and download the TwinCAT/BSD ISO.

   

4. Extract the contents of the installer script and the Tc/BSD ISO. Copy the contents of both to a single folder.
5. Copy the exact filename of the Tc/BSD ISO image and open Create-TcBsdVM.ps1 or TwinCAT BSD VM creator.bat with a text editor, depending on which you want to use.
6. Change the ISO filename in one of the installer scripts to the one which matches your downloaded ISO file. Here "TCBSD-x64-13-55702.iso" is the name of the ISO file I downloaded.
   • Create-TcBsdVM.ps1 at line 7: $tcbsdimagefile="TCBSD-x64-13-55702.iso",
   • TwinCAT BSD VM creator.bat at line 2: SET sourcefilename="TCBSD-x64-13-55702.iso"
7. Save and close the installer script.
8. Then either double click TwinCAT BSD VM creator.bat to execute, or from powershell run Create-TcBsdVM.ps1 TcBSD-VM. Here the first argument, TcBSD-VM, is the name of the virtual machine.

9. You should see a Virtual Box window open and then you wait for the installer to start. This can take a minute. After that, you should see the following screen. Select TC/BSD Install and hit enter.

   

10. Then select the 4G hard drive which was automatically created by the script and hit enter.

11. Hit enter again to acknowledge the warning.

    

12. Then it asks for you to generate a password. Type in a password and repeat it to make sure it’s correct.

13. After several minutes the installation is complete and you see the following screen. Select OK.

    

14. In the new menu select Shutdown.

    

15. Open the Settings > Network of the virtual machine you created. Now there are different options for different use cases:

    • If you just use the runtime locally, enable a Network adapter 1 and set it as a Host only adapter

      

    • If you want to set up a physical connection to an outside network select Bridged adapter

      

    • If you want the Tc/BSD package manager to work, you need to enable both. For adapter 1, select Host only adapter and enable a second adapter where you select Bridged adapter.

16. Verify that the network connections work by starting the virtual machine, logging in and:

    • Run ifconfig . You should see an inet starting with 192.168..

    • You can also try to ping www.beckhoff.com and see if you get a reply. For me, it took a minute before the network connection started to work.

	$ ping www.beckhoff.com
	PING d2la171hyf8xwx.cloudfront.net (52.222.139.54): 56 data bytes
	64 bytes from 52.222.139.54: icmp_seq=0 ttl=128 time=9.673 ms
	64 bytes from 52.222.139.54: icmp_seq=1 ttl=128 time=8.739 ms
	64 bytes from 52.222.139.54: icmp_seq=2 ttl=128 time=9.783 ms
	^C
	--- d2la171hyf8xwx.cloudfront.net ping statistics ---
	3 packets transmitted, 3 packets received, 0.0% packet loss

• In case it is not working, check your network adapter settings. Type Ethernet settings into the start menu and open it. Select Change adapter options and right-click VirtualBox Host-Only Network and select Properties. Make sure they are set to automatic.

Installing Tc/BSD on VMware

Installing TwinCAT/BSD on VMware is a bit more complicated. The steps below are based on a YouTube tutorial from Jakob Sagatowski. Before you head over there, I did notice that I had to do several things differently for it to work.

Create a bootable USB

1. Install Rufus to create a bootable USB drive.

   • Install via the terminal winget install -e --id Rufus.Rufus.
   • Or download manually and install. You can also use the portable version, which doesn’t require any installation.

2. Go to the Beckhoff website and download the TwinCAT/BSD ISO.

   

3. Unzip the file you just downloaded. You’ll probably find three files in there. The ISO one is the one you need.

4. Get yourself a USB drive which doesn’t contain important information, since it’s formatted in the process. I used an old 1 GB USB drive that I bought for €30 a long time ago 😱.

5. Open Rufus, click SELECT and select the ISO file you just unpacked.

   

6. Then select START. It then formats the USB drive and makes it a bootable USB drive with Tc/BSD on it.

Installing TwinCAT/BSD

1. Download and install VMware Workstation Player. It’s free for non-commercial use.

   • Install from the terminal with winget install -e --id VMware.WorkstationPlayer
   • Or manually download and install.

2. Select the free license or enter a license number

3. Start VMware Workstation Player with Administrator rights and select create a New Virtual Machine. You need administrator rights later to access the USB drive.

   

4. Select I will install the operating system later.

   

5. Select “Other” and “FreeBSD 12 64-bit”

   

6. Give your virtual machine a descriptive name and change the save location if you would like to.

   

7. Specify the disk capacity. I left it at the default 20 GB. Note: Jakob removes this hard drive and adds the USB drive first and then adds a new hard drive. But, I found that if I do this, I get an error¹ once I remove the USB drive.

   

8. You see a screen summarizing the results. Click Finish.

9. Select the virtual machine you just created and select Edit virtual Machine Settings.

   

10. Increase the memory of the virtual machine. I set it to 1 GB. At 256 MB the virtual machine sometimes gets killed when it runs out of memory. If you notice that it crashes, you know what to do.

    

11. Add the USB drive as a hard disk by clicking on Add.

    

12. Then in the new window, select Hard Disk and click Next.
13. Select SATA and click Next.
14. Select Use a physical disk (for advanced users). Yes, that’s you :D. Click on Next.

15. Now you get prompted to choose a disk. Here you want to select your USB drive, which should still be on your computer.

    

16. To find out if you need to select Disk 0 or Disk 1. Type in diskmgmt in the start menu to open Create and format hard disk partitions.

    

17. You see several partitions. In my case, there are two. Disk 1 is the removable one, thus I want to use that as the hard drive.

    

18. Now go back to the virtual machine settings and select PhysicalDrive1, Next and Finish.

    

19. Finally, you set the firmware type of the USB drive to UEFI. If you have a Pro version of VMware, you can set the firmware type in the virtual machine settings under Options > Advanced > Firmware type and select UEFI. If you have the Player version, you:

    1. Locate the directory of the virtual machine. You can find its location under Edit virtual machine settings > Hard Disk (SCSI)

       

    2. Open the VMX file in the virtual machine directory with a text editor.
    3. Find the line firmware = "bios" and replace with firmware = "efi" and save it. If this line doesn’t exist, add it somewhere.

    

20. Now start the virtual machine with Play virtual machine.

21. Wait for the installer to start up. This can take a minute. After that, you see the following screen. Select TC/BSD Install and hit enter.

    

22. Then select the 20G virtual hard drive you made and hit enter.

    

23. Hit enter again to acknowledge the warning.

    

24. Then it asks for you to generate a password. Type in a password and repeat it to make sure it’s correct.

25. After several minutes the installation is complete and you see the following screen. Select OK.

    

26. In the new menu select Shutdown so that you can remove the USB drive.

    

27. Remove USB drive under Edit virtual machine settings. Make sure you don’t select the 20 GB hard drive, on which you just installed Tc/BSD.
28. Go back to the main menu and start the virtual machine.

29. After some time you see the login screen. Log in with your user name and password you made during the installation.

    

30. Congrats. You now have a running version of TwinCAT/BSD.

Device manager

As I mentioned earlier, Tc/BSD doesn’t have a desktop environment. Most things are done from the terminal. However, the device manager has a GUI. To access it, you first need to find out the IP of the virtual machine. You find the IP by typing in ifconfig. The IP is right after inet.

Then open your browser and type in the IP address you found. For me, it’s https://192.168.126.128. It’s possible that a warning shows up. Accept the risk and continue.

From here you can log into the device manager with the username Administrator and the password you set during the installation. The device manager shows all kinds of information about the state of the hardware and the software.

Web console

Next to a device manager, the https://192.168.126.128 page also has a link to a web console. The console shows the same as if you logged into the virtual machine directly, but the web version has a better interface. Mainly because it enables scrolling² and copy-pasting commands is easier.

Installing packages

As I mentioned earlier, there is no GUI. You do most actions from the terminal. One of the things you can do is install packages, with a package manager. Package managers are a useful feature in UNIX-like operating systems. Although Windows is now also joining the party with winget.

Installing TwinCAT HMI server

Note: See also a video by Coding Bytes which describes this step.

A package which you likely need is the HMI server. I don’t exactly know what it is called, but I know that there is a search feature. If you type in pkg search hmi, you see two results.

$ pkg search hmi
TF1810-PLC-HMI-Web-3.1.4024.11_1 TF1810 | TC3 PLC HMI Web
TF2000-HMI-Server-1.12.754.4   TF2000-HMI-Server

The first one is the old HMI and the second one is the one I want. To install it, type doas pkg install TF2000-HMI-Server and hit enter. Confirm the start of the installation with y. Then a warning showed up. So I did doas service TcHmiSrv start to start it.

=====
Message from TF2000-HMI-Server-1.12.754.4:

--
============================== !!!! WARNING !!!! ==========================
FreeBSD package manager doesn't allow us to automatically start services
during package installation. To use the Beckhoff TwinCAT HMI Server either
restart your system or start 'TcHmiSrv' manually with:

doas service TcHmiSrv start

============================== !!!! WARNING !!!! ==========================

If you then type top and hit enter, you see TcHmiSrv is running. top is the task manager analogue of FreeBSD. It can be convenient to have it open to see if processes are running, or maybe if your virtual machine has crashed. To exit top, press q or Ctrl + C.

Running PLC code

Connecting to the virtual machine

Now you are ready to run some PLC and HMI code on Tc/BSD. You find the target machine the usual way. You go to Choose Target System > Search (Ethernet) > Broadcast search. Note that next to your regular Wi-Fi/Ethernet ports, also two ports from VMware or one from VirtualBox shows up. Make sure the ports of your virtual machine are selected and click OK to start the search.

Click Add Route select Secure ADS and click OK. In case it can’t connect, click Advanced to show the options. Then select IP address instead of Host name. Then try to connect again.

After connecting to the PLC, you should be able to activate your configuration. Finally. You can develop TwinCAT code again while sitting in a beer garden like some developers do. Freedom!

Publishing the HMI

With your PLC code running, it’s now time to look at how to publish the HMI. I initially had some issues with publishing the HMI. In the end, I made it work by using TcBSD version 13, which has TcHmiSrv 1.12.756.1. I couldn’t make it work with TcBSD v12.2 which has TcHmiSrv v 1.12.746.0. Furthermore, you need to make sure that your HMI project has the same version as the server which is 1.12.756.1 for me.

Once you have that, you need to add an exception to the Tc/BSD firewall. By default a lot of ports are blocked, including the one needed for the HMI server. To add it, open the firewall configuration file with doas ee /etc/pf.conf from the console. Then add the following new line at the end of the file

# allow TcHmiSrv outgoing
pass in quick proto tcp to port 1010 keep state

Exit the ee editor with Esc, select a) leave editor, save your changes and restart the virtual machine.

Meanwhile, open the PLC project you want to publish on the virtual machine. Verify that the TF2000 HMI Server license is present in your system manager under SYSTEM > License. If it’s not present, add it manually via the Manage Licenses tab. Then activate your PLC project which serves as the back end for your HMI project. Open the HMI publishing settings, fill in the IP address of the virtual machine and press Validate connection. If the connection was successful, select Publish.

If you connect to the HMI server for the first time, it asks you to set a password for the HMI server. You need this password whenever you want to publish your HMI project or need to log into the HMI server.

Once the password is set you can publish your HMI which then should be reachable at the Browser URL as shown in the publishing settings.

Use the GitHub TwinCAT template repo to set up a TwinCAT repo, including the pre-commits.

What are pre-commits?

Pre-commits are part of a class of so-called git hooks. Hooks enable you to run a script during a git command. Most of these hooks are pre-commit, meaning they do something before a commit, merge, or rebase. Pre-commit hooks can be beneficial; for instance, they can guarantee a uniform code formatting style or verify a file’s JSON or XML format.

You can see some examples of git hooks if you have a project which uses git. Navigate to the .git/hooks folder and you should see a list of example hooks there. If you can’t see the .git folder, make sure you have enabled “Hidden items” under the View tab in your Windows Explorer.

If you open one of the files, you see some bash scripts. It’s not necessary to use bash. You can use any programming or scripting language which is available on your system.

You can write your own hooks from scratch, but for most files, there is already a large variety available. Let me show you how you can use these and a structured text hook for your TwinCAT projects.

Setup pre-commit

A popular framework to manage pre-commits is pre-commit. It’s a Python based framework and thus you need a working Python installation on your system before you can use it.

1. (In case you do not have Python) Download and install conda via one of the methods below. You can either install Miniconda which is a minimal installation. It comes with the bare necessities to get started. Miniconda should be enough for this tutorial. Or, if you would like to have a bit more tools/modules installed (mainly for data analyses), choose Anaconda.

   • Manually download and install Miniconda or Anaconda.
   • Or run winget install -e --id Anaconda.Miniconda3 or winget install -e --id Anaconda.Anaconda3 from the terminal.

2. Install pre-commit with either:

   • pip install pre-commit
   • or conda install -c conda-forge pre-commit

3. Check if the installation went OK by running the command below in the terminal. If you see a version number then pre-commit works.

    $ pre-commit --version
    pre-commit 2.17.0

4. Next, create a new file called .pre-commit-config.yaml in the git project folder (same folder as where your .git folder resides) where you want to start using pre-commits. Now you’re all set up to start using pre-commits.

TwinCAT relevant pre-commits

The kind people of the Photon Controls and Data Systems at SLAC have open-sourced their TwinCAT pre-commits. To use the SLAC pre-commits, add the following lines to your .pre-commit-config.yaml file:

- repo: https://github.com/pcdshub/pre-commit-hooks
  rev: v1.2.0
  hooks:
    # Replaces all leading tabs with spaces
    - id: twincat-leading-tabs-remover
    # Removes line ids. See point 4 of the link for why you don't need them
    # https://cookncode.com/twincat/2021/06/07/tc-source-control-tips#2-creating-independent-files
    - id: twincat-lineids-remover
    # Formats .tmc and .tpy files
    - id: twincat-xml-format
    # Check if there are any libraries whose versions are not fixed
    - id: check-fixed-library-versions

For completeness, I’ll also add the following standard pre-commits. You can first run these pre-commits. Later I go into details about what they do and why they are useful.

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v3.2.0
    hooks:
      # Removes trailing white spaces
      - id: trailing-whitespace
      # Checks yaml files for parseable syntax
      - id: check-yaml
      # Prevents git from committing large files
      - id: check-added-large-files

Install the pre-commit hooks with pre-commit install. This needs to be done once per git repository. Afterwards, you can run pre-commit run --all-files to let the pre-commits do their job. Note: you only run this command if you have added new pre-commits. In other cases, all pre-commits are automatically executed when you use git commit .... In this case, the automatic execution limits to the changed files.

Depending on the project you see no, some, or a lot of changed files. For example, when I ran it on my TwinCAT Tutorial repo I saw the following:

For each git hook, you see if it had files to check. If that was the case, you see if any files were changed.

Below I show an example where two hooks were triggered. Here both the leading tabs remover failed (as shown in the screenshot), but also the trailing white space one failed (not shown). Below are the differences I saw afterward in SourceTree:

You see that it removed a trailing space after the CASE _state OF. Additionally, the file had a mix of tabs and spaces. The tabs were replaced by spaces. These changes were made by the trailing-whitespace and twincat-leading-tabs-remover respectively. For a full list of all the changes, you can see the differences of this commit.

Hooks what and why

Here I go a little deeper into what the hooks do and why you would want to use them.

twincat-leading-tabs-remover

What: replaces all leading tabs with four spaces.

Why: consistency. Also in some editors, the length of a tab can differ from the length of four spaces.

twincat-lineids-remover

What: removes LineIDs from a POU file.

Why: they are only useful locally. When uploaded to source control they only cause visual clutter. For more information see point 4

twincat-xml-format

What: formats the .tmc and .tcp files with newlines and indentation.

Why: makes these files readable for humans. Normally TwinCAT doesn’t put any newlines or indentations in these files. Useful if you would like to have these files in source control and see clear differences.

check-fixed-library-versions

What: checks if there are TwinCAT libraries whose versions are not fixed or explicitly set to the latest version.

Why: ensures that your software behaves the same, even if you install newer library version on your system.

trailing-whitespace

What: removes spaces and tabs at the end of lines.

Why: whitespace at the end of a line does not influence code execution; you can add or remove as many as you’d like. But, they show up as (useless) changes if someone adds some or removes them.

check-yaml

What: checks that programs can read your YAML file. For example, the .pre-commit-config.yaml one.

Why: ensures that your YAML files do not break.

check-added-large-files:

What: prevents git from adding large files to its history.

Why: to prevent your git tree from becoming huge. Saves time for new users when they download the repo for the first time. Large, non-text files, such as images or binary files usually contain no useful diffs. You want to commit these files using Git LFS.

Developing your own hooks

If you would like to develop your own hooks there are two options: local and remote repo-based hooks. Local hooks are quite easy to set up, but they can only be used in the repo where they are saved. On the other hand, remote-based hooks can be shared across many projects. The TwinCAT hooks you saw earlier, is an example of a remote hook.

You can use many languages to develop your hooks. Most languages need a working installation of that specific language on the system where the hooks are executed. The exceptions are node, python, and ruby. For these languages, no existing installation is needed. Hooks developed in these three languages set up their own (node, python, ruby) environment when first executed. On subsequent runs, the environment is reused.

Remote hooks also need to be a valid git repo. That is because pre-commit tries to do a git clone ... of the repo URL you supplied in the .pre-commit.yaml file. To make a remote hook, see the TwinCAT hooks repo as an example.

Local hook example

Developing a local hook is quite straightforward. I’ll explain how to do it by making a hook that checks if all links on this blog start with https. If they don’t, it replaces http with https.

First I added a file called .pre-commit-config.yaml with the following content. See the comments for their meaning.

repos:
  - repo: local
    hooks:
      # Name of the hook
      - id: check-https
        # Hook name shown during hook execution
        name: check if all links are https
        # Where pre-commit can find the script it should call and how it should call it
        entry: python _hooks/check_https.py
        # The language to use, in this case we're using a language present on the system.
        # Using python as an argument would work as well
        language: system
        # A valid regular expression pattern to define which files should be passed to `check_https.py`
        files: '.*\.(md|markdown)'

When pre-commit runs this local hook, it first searches for files that conform to the regular expression pattern mentioned in files:. Then it calls the command mentioned under entry with each filename. For example, it finds the files README.md and about.md. Then it calls check_https.py with python _hooks/check_https.py README.md about.md.

Next, I created a new file called _hooks/check_https.py with the following content. See comments for the meaning.

#!/usr/bin/env python

import argparse

def fix_file(filename):
    # Open the file
    with open(filename, 'r') as fd:
        original_lines = fd.readlines()
    new_lines = []
    changed = False
    # For each line in the file check if a https:// is found.
    # If so, replace it with https://
    for line in original_lines:
        if "https://" in line:
            line = line.replace("https://", "https://")
            changed = True
        new_lines.append(line)

    # If a line was changed, print a message in the console and overwrite the
    # original file with the fixed one.
    if changed:
        print(f'Fixing {filename}')
        with open(filename, 'w') as fd:
            fd.write(''.join(new_lines))


def main(args=None):
    # Parse the filename arguments:
    # e.g. Namespace(filenames=['README.md', 'about.md'])
    if args is None:
        parser = argparse.ArgumentParser()
        parser.add_argument('filenames', nargs='*')
        args = parser.parse_args()
    # For each filename execute the file fixer on it
    try:
        for filename in args.filenames:
            fix_file(filename)
        # Return 0, which means the hook executed successfully and pre-commit is happy
        return 0
    except Exception as exc:
        print(exc)
        # If something went wrong return an error code other than 0 and pre-commit
        # then knows something went wrong
        return 1


if __name__ == "__main__":
    exit(main())

If you now run pre-commit run --all-files you should see all the files it changed.

> pre-commit run --all-files
check if all links are https.................................................Failed
- hook id: check-https
- files were modified by this hook

Fixing _posts/2021-09-13-units.markdown
Fixing _posts/2021-06-07-tc-source-control-tips.markdown
Fixing _posts/2021-08-17-tc-simulation.markdown
Fixing tclinks.md

Further ideas

Other ideas could be to use Prettier to format JavaScript, HTML, or CSS files from HMI projects. Unfortunately, TwinCAT saves the HMI pages as .content and .view files. These files are not recognized as HTML files by prettier, but you could probably make it work by temporarily renaming these files to .html and then running prettier.

Pre-commits are automatically executed locally whenever you commit something. But you can also add pre-commit to your CI workflow. For example, use prettier.ci to automatically format markdown files of a pull request.

Have you already used pre-commits for your (TwinCAT) projects? Or do you have other ideas? Let me know in the comments below.

• Example code for TcHMI v1.10: GitHub repo, direct download.

Result

Before diving in, this will be the result:

Setup

In order to explore what RowClassesProvider does let’s make a small sample project.

1. Create a new HMI project in Visual Studio by going to File > New > Project and select TwinCAT HMI > TwinCAT HMI Project. Give it an appropriate name and select OK.
2. Open the Desktop.view by double clicking on it.
3. From the tool bar, drag a Datagrid into the Desktop.view.
4. Add a new JavaScript function by right clicking on your HMI project and select Add > New Item.
5. Then select Function (JavaScript) and give it an appropriate name and select OK.

Exploring RowClassesProvider’s functionality

Now we have a sample project it is time to explore what the RowClassesProvider does.

1. Open the RowClassesProvider.function.json file of the JavaScript function we just created, with a double click.

2. In the new window change/add the following things:

   • Change the return type to Array. Later we fill this array to return the styles which should be applied to the Datagrid.
   • Change the DisplayName of the first variable to rowData and select for the Datatype Any.
   • Add a new row and change the DisplayName to rowIndex and for the Datatype select Integer.
   • Add another new row and change the DisplayName to rowNumber and for the Datatype select Integer.

   In the end it should look as shown here:

   

3. Confirm your changes by selecting OK and confirm your changes in the additional pop-up.

4. In case you had the RowClassesProvider.js file open, you will get a pop-up. The pop-up is caused by the changes you just made. Select Yes to reload the file.

   

If all went OK your code in RowClassesProvider.js should look as follows (ignoring the <reference path ... lines):

(function (TcHmi) {
  var RowClassesProvider = function (rowData, rowIndex, rowNumber) {};

  TcHmi.Functions.registerFunction("RowClassesProvider", RowClassesProvider);
})(TcHmi);

This function takes three inputs: rowData, rowIndex and rowNumber. The inputs contain information about the selected row of a data grid. To see what this function does, add some logging code to the function:

(function (TcHmi) {
  var RowClassesProvider = function (rowData, rowIndex, rowNumber) {
    console.log("Data: ", rowData);
    console.log(`Index: ${rowIndex}\nNumber: ${rowNumber}`);
  };

  TcHmi.Functions.registerFunction("RowClassesProvider", RowClassesProvider);
})(TcHmi);

Now every time this function is called, it will print in the console with which parameters the function was called.

Save the function. After changing the function the designer shows a prompt that it needs to be reloaded. Click on the yellow ribbon to reload the designer.

Next we link this function to our Datagrid. Open the Desktop.view and

1. Select the TcHmiDataGrid.
2. In the Properties window under Data > RowClassesProvider press the ... button.

3. Then find the function we just created and drag it into the right window titled Functions.

   

4. Select OK to confirm your changes.

Seeing it in action

1. Open the Live-View window from TwinCAT HMI > Windows > TwinCAT HMI Live-View.
2. Open the developer tools, by clicking on the gear icon on the top.

In the developer tools you see the results of the console.log calls in our function. The rowData variable contains all the column data of a single row. The rowIndex and rowNumber both contain the number of the row. I’m not sure why there are two variables containing the same information.

On the initial load of the Desktop.view, all rows were called, However, if later we select a row and make a change, only that row will show up in the log. Here I changed the editable data on the second row to cookncode.

From this example you might start to see how we can use the RowClassesProvider. Basically we can take actions based on any of the received input parameters. Be it any of the rowData columns, or the index of the row.

Applying CSS styles to the Datagrid

You may recall that when we defined the RowClassesProvider function, we also specified it returned an Array. In this section I will fill this array with CSS styles, such that that the datagrid can dynamically change its formatting.

First we will define a custom style in a CSS file. To add a CSS file, right click on the HMI project and select Add > New Item and select Cascading Style Sheet (CSS) and click on Add.

For example we can change the color of a table cell when no data is present. In order to do this we first define a new style by adding the following lines to the .css file:

/* Change the first column's background to orange */
#TcHmiDatagrid tr.missing-input td[data-column-name="Test1"] {
  background-color: #f76d16;
}

Here:

• #TcHmiDatagrid means the style is for a TwinCAT HMI datagrid.
• tr denotes a row in a table.
• .missing-input is the name of the style.
• td denotes a table data cell.
• data-column-name="Test1" means we apply the style only to a specific column with the name "Test1". I will show in a minute where you can find the column name.
• background-color: #F76D16; is the newly applied background color.

In order to apply the style under certain conditions we change the RowClassesProvider function as follows:

(function (TcHmi) {
  var RowClassesProvider = function (rowData, rowIndex, rowNumber) {
    var cssStyles = []; // Collected CSS styles which will be returned at the end

    if (!rowData.Test1) {
      // If the first column (Test1) is empty
      cssStyles.push("missing-input"); // add the missing-input style to the array
    }

    return cssStyles;
  };

  TcHmi.Functions.registerFunction("RowClassesProvider", RowClassesProvider);
})(TcHmi);

Now the RowClassesProvider returns an array with the style names which should be applied. For now the missing-input style is added in case the input of the first column is empty.

Before we see it in action, we first need to add another row to our Datagrid, since currently all columns contain data. Open the Desktop.view and select the ... of the SrcData in the Properties window.

Add four new columns, where Test1 is just an empty string. Note that here you can see the names of each of the columns. You can also give them more descriptive names for your application. It is also possible to link the source data to a struct in your PLC project, but this is outside of the scope of this tutorial. After you’ve made the changes click OK and open the live view.

If all went well, the first column of the third row should be orange.

Styles can also be applied dynamically after for example toggling a checkbox, based on the value of a text field or the style of a whole row can be changed based on the state of a single column. To do so, change the .css file as follows:

/*Change the background color of the first column to orange*/
#TcHmiDatagrid tr.missing-input td[data-column-name="Test1"] {
  background-color: #f76d16;
}

/*Change the second column's background to orange*/
#TcHmiDatagrid tr.below-zero td[data-column-name="Test2"] {
  background-color: #f76d16;
}

/*A default background color for the second column*/
#TcHmiDatagrid tr td[data-column-name="Test2"] {
  background-color: #a0d5e8;
}

/*Change the background color of an entire row if a check box' state is changed*/
#TcHmiDatagrid tr.not-checked td::after {
  content: "";
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  width: 100%;
  height: 10000px;
  pointer-events: none;
  z-index: 1;
  background-color: rgba(215, 249, 251, 0.5);
}

/*Make the text in the fourth column bold and change the color*/
#TcHmiDatagrid tr.bold td[data-column-name="Test4"] {
  font-weight: bold;
  color: #f76d16;
}

and change RowClassesProvider into

(function (TcHmi) {
  var RowClassesProvider = function (rowData, rowIndex, rowNumber) {
    var cssStyles = []; // Collected CSS styles which will be returned at the end

    if (!rowData.Test1) {
      // If the first column (Test1) is empty
      cssStyles.push("missing-input"); // add the missing-input style to the array
    }

    if (rowData.Test2 < 0) {
      // If the value of the second column is negative
      cssStyles.push("below-zero"); // add the below-zero style
    }

    if (!rowData.Test3) {
      // If the checkbox in the third column is not checked
      cssStyles.push("not-checked");
    }

    if (rowData.Test4 == "cookncode") {
      // if the text in the fourth column is cookncode
      cssStyles.push("bold");
    }

    return cssStyles;
  };

  TcHmi.Functions.registerFunction("RowClassesProvider", RowClassesProvider);
})(TcHmi);

Result

Final tip: inspiration and default styles

If you’re looking for inspiration what you can change or what the default styles of Beckhoff’s controls are, you can find these if you open the developer console. Then go to the Sources tab and navigate to a folder. Here I show the Base theme style for the Datagrid.

• Don’t repeat yourself, often abbreviated as DRY, is a saying in software development to denote unnecessary repeating code. One tell-tale sign if you write non-DRY code, is that you copy and paste a lot of code.

• You can activate multi-line editing by pressing the Alt key and dragging your mouse across several lines. If you use this function a lot, then it is a sign that your code is probably not DRY. So it is time to think about how to refactor your code.

  

• A _ can be used as a thousand-separator. For example: number : INT := 1_000_000;. Or you can use scientific notation if most decimals are zeros: number : INT := 1E6;.

• (TwinCAT 4024+) Use Ctrl + K, Ctrl + C to comment one or more lines and Ctrl + K, Ctrl + U to uncomment them again. Check InfoSys for more hotkeys.

  

• In a CASE statement you can use multiple cases 1, 3, 61 or a whole range 1..10 for a single case. For example:

	// Instead of this
	CASE aCase OF
	    1: Method1();
	    2: AnotherMethod();
	    3: AnotherMethod();
	    4: AnotherMethod();
	    6: Method1();
	END_CASE

	// You can do this
	CASE aCase OF
	    1, 6: Method1();
	    2..4: AnotherMethod();
	END_CASE

• Using numbers to denote a case is usually not the best way to denote a case. You can make cases self-documenting by creating an ENUM for each case.
• There are implicit enums or local enums in TwinCAT. They can be used if you only need an enum in a single function block. You can define them as follows: colors : (Red, Blue, Green);. See for more info this AllTwinCAT post.
• If you have a method or a function which returns a boolean, try to avoid the usage of an IF statement. Since you’re returning a boolean, you can often do this in a single line:

	// Do not do this
	METHOD LargerThenTwelve : BOOL
	VAR_INPUT
		number : INT;
	END_VAR

	IF number > 12 THEN
		LargerThenTwelve := TRUE;
	ELSE
		LargerThenTwelve := FALSE;
	END_IF

	// Do this
	METHOD LargerThenTwelve : BOOL
	VAR_INPUT
		number : INT;
	END_VAR

	LargerThenTwelve := number > 12;

• Use {attribute 'call_after_init'} to call a method once after a function block was initialized. You can use this, instead of a bInitialized flag in your code, which inevitability you forget to set to TRUE at least once 😉.
• Prevent the usage of POINTERs. They can lead to some pretty unpredictable behavior since you’re accessing a piece of memory directly. A better alternative is to use REFERENCE, because it has a cleaner syntax and type safety. Although also references need to be checked for validity as I wrote about earlier. For the health and safety of you and your code, I recommend to only use them if you’re memory constrained for example.
• Try to prevent method calls from multiple tasks, since it makes debugging difficult. If you really have to do it, use this.

• You can use bit access for integer variables. For example, variable.2 := TRUE, sets the third bit to TRUE. There is read access as well. You can for example check if some bit of a number is true by IF variable.3 THEN .... This method allows you to decipher an error code where each bit represents a specific error. Note that bit access can be a factor five slower than using a bit mask.

  Timing results from Toni Kucic.

• Example code: GitHub repo, direct download.

Back when I had my first science classes, the teachers would always emphasize the importance of units. If I forgot them, points were usually subtracted from my final mark. At the time I always found this a bit unreasonable. I was calculating a speed, of course the units would be in km/h!

Over the years I got wiser and started to get the importance of what units are used. I learned that things can go horribly wrong when this is not done. For example, the Mars Climate Orbiter failed to go into orbit around the red planet, because of a mix-up between metric and imperial units.

Now, most of us are not working with hundred million dollar machines which try to orbit a distant planet. But also for less expensive machines on earth it would be nice to not make these mistakes. Below I’ll show the different options I thought of how to prevent unit mix-ups. They are ranked from worst to best, according to my opinion.

Unit checks in F#

Before diving into how unit checks can be done in TwinCAT, let me first show you how unit checks are done in F#. In F# a unit can be defined using the following syntax.

[<Measure>] type Celsius
[<Measure>] type Fahrenheit

These units can be used in functions. For example, below a function is defined with let called CelsiusToFahrenheit. It has a single input argument called temperature. Inside the function the conversion takes place using the units defined above. The units are placed between angle brackets < and >.

let CelsiusToFahrenheit temperature =
    temperature * 1.8<Fahrenheit/Celsius> + 32.0<Fahrenheit>

The unit of temperature does not need to be supplied, as these will be inferred by the compiler from the units of the variables inside. Now, if we would like to use this function, we also have to use the correct input units.

> CelsiusToFahrenheit 21.0<Celsius>;;
val it : float<Fahrenheit> = 69.8

If we use the wrong units the compiler will complain.

> CelsiusToFahrenheit 62.0<Fahrenheit>;;

  CelsiusToFahrenheit 62.0<Fahrenheit>;;
  --------------------^^^^^^^^^^^^^^^^

stdin(30,21): error FS0001: Type mismatch. Expecting a
    'float<Celsius>'
but given a
    'float<Fahrenheit>'
The unit of measure 'Celsius' does not match the unit of measure 'Fahrenheit'

Likewise, if the unit is omitted we also get a compiler error.

> CelsiusToFahrenheit 94.0;;

  CelsiusToFahrenheit 94.0;;
  --------------------^^^^

stdin(32,21): error FS0001: This expression was expected to have type
    'float<Celsius>'
but here has type
    'float'

I think this is a very useful feature. If you want to learn more about it, you can read an excellent overview in F# for Fun and Profit. Now let’s explore how this functionality can be implemented in TwinCAT!

4. Putting units in comments

Probably the most commonly used method is to put the units of a variable in the comment. For example

maximumPressure : REAL; // [mbar]

However, it is very hard to spot a mistake as shown by the following example.

PROGRAM MAIN
VAR
	pressure1 : REAL; // [mbar]
	pressure2 : REAL; // [Torr]
END_VAR

pressure2 := TorrToMbar(pressure1);

The pros and cons of this method are:

✔️ There is a unit.

❌ Need to hover over it to see the unit.

❌ No automatic checks to ensure the right unit is used.

3. Using aliases

Aliases can be used to define a unit. An alias is just another name for a standard data type. Some standard TwinCAT aliases you might have seen are T_MaxString = STRING(255) or FLOAT = REAL.

An alias can be created by right clicking on the PLC project and choose Add > DUT. Then in the following screen select Alias and give it a name (e.g. mbar) and a datatype (e.g. REAL).

Then it can be used as follows.

PROGRAM MAIN
VAR
	pressure_si : mbar;
    pressure_imperial : Torr;
END_VAR

pressure_si := TorrToMbarWithAlias(pressure:=pressure_imperial);

where TorrToMbarWithAlias is defined as

FUNCTION TorrToMbarWithAlias : mbar
VAR_INPUT
    pressure : Torr;
END_VAR

TorrToMbarWithAlias := pressure * 1.3332236842;

At the first glance this looks very similar to the F# approach. However, the aliases are just a different name for the underlying datatype. The compiler only checks that the underlying datatype (REAL in this case), is correct. So the following would be possible:

pressure_in_torr := TorrToMbarWithAlias(pressure:=pressure_in_mbar);

Concluding

✔️ There is a unit.

❌ Need to hover over it to see the unit.

❌ Compiler doesn’t complain if the wrong alias is used.

2. Add unit to the variable name

Another option would be to append the unit to the variable name:

maximumPressure_mbar : REAL;

This method also doesn’t have any automatic check to prevent unit mix-ups. But the following mistake is harder to make, because the input variable’s unit doesn’t match the argument name one.

PROGRAM MAIN
VAR
    pressure1_mbar : REAL;
    pressure2_Torr : REAL;
END_VAR

pressure2_Torr := TorrToMbarWithUnits(pressure_Torr:=pressure1_mbar);

✔️ There is a unit.

✔️ No need to hover over it to see the unit.

❌ No automatic checks to ensure the right unit is used.

1. Using structs

We’re making progress, but the compiler is not helping us yet. In order for the compiler to help us, STRUCTs can be used. You can add a STRUCT by right clicking on your PLC project and selecting Add > DUT.

And then define the STRUCTs as follows.

TYPE Pascal :
STRUCT
    _ : REAL;
END_STRUCT
END_TYPE

TYPE PoundsPerSquareInch :
STRUCT
     _ : REAL;
END_STRUCT
END_TYPE

We then add a conversion function.

FUNCTION PoundsPerSquareInchToPascal : Pascal
VAR_INPUT
    pressure : PoundsPerSquareInch;
END_VAR

PoundsPerSquareInchToPascal._ := pressure._ * 6895;

If we try to run this function with the wrong units:

PROGRAM MAIN
VAR
    pressure_eu : Pascal;
    pressure_us : PoundsPerSquareInch;
END_VAR

pressure_us := PoundsPerSquareInchToPascal(pressure:=pressure_eu);

the compiler will complain. 🙌

✔️ There is a unit.

❌ Need to hover over it to see the unit, but this is a minor issue since the compiler will check it for us.

✔️ Compiler complains if the wrong type is used.

❌ The interface is not very convenient, since we have to append ._ each time we want to access the value.

Adding unit string as payload

Using structs gives us a major advantage since the compiler will help us. However, it feels a bit excessive to define a whole struct for this and then we have to use the ._ to assign or use the variable inside. We can ease the pain a bit by adding some useful information to the struct. For example, we could add the units to the struct in string format. This string could then be used in the HMI for example.

TYPE mmHg :
STRUCT
    _ : REAL;
    unit : STRING := 'mmHg';
END_STRUCT
END_TYPE

Adding IO signal status

Another option could be to add some information about the state of the input signal. Terminals usually have a WcState variable. This variable shows if the terminal cyclically exchanges data with the master and does this without errors. Furthermore, some input channels also have a state, which can show if there is an open circuit, short circuit or some other irregularity.

To capture the terminal status we make a new struct.

TYPE TerminalStatus :
STRUCT
    WorkingCounterError : BOOL;
    IOError : BOOL;
END_STRUCT
END_TYPE

Then whenever we define a new unit, we extend the struct above.

TYPE Celsius EXTENDS TerminalStatus :
STRUCT
    _ : REAL;
END_STRUCT
END_TYPE

In order to check whether a signal is valid, we can define a new function. The function uses the general TerminalStatus as its input type. That way this function can be called with extended structs, such as Celsius, as I wrote about in an earlier article.

FUNCTION IsValid : BOOL
VAR_INPUT
    status : TerminalStatus;
END_VAR

IsValid := NOT (status.IOError OR status.WorkingCounterError);

Finally we define a conversion function, where we only convert the temperature if the signal state is ok.

FUNCTION FahrenheitToCelsius : Celsius
VAR_INPUT
    temperature : Fahrenheit;
END_VAR

FahrenheitToCelsius.IOError := temperature.IOError;
FahrenheitToCelsius.WorkingCounterError := temperature.WorkingCounterError;
IF IsValid(temperature) THEN
    FahrenheitToCelsius._ := (temperature._ - 32) /  1.8;
END_IF

After activating this code we can see it in action.

Conclusions

In the end we came quite close to the F# unit checks implementation. Although the intermediate conversions, such as the 32 in FahrenheitToCelsius, are not checked by the compiler as in F#. But these intermediate conversions can be checked relatively easy with unit tests. What is checked with the method above are the in and outputs of the function. I would argue this is the most important part, since they usually need integration tests. Finally the interface of a custom struct is not the most convenient, but I showed some examples how you could soften the pain by adding some useful information to the unit structs.

• Example code: GitHub repo, direct download.

Different types of tests

There are different levels at which you can test your code, as shown in the image below. In this article I will focus on how you can do integration tests without the need for a real machine.

Image courtesy of AllTwinCAT.com

Unit tests

On the bottom of the pyramid are the unit tests. With unit tests you test individual functions and function blocks. For TwinCAT there are several options if you want to do this: TcProber, TcUnit.org and TcUnit. You can learn more about the first two libraries in this article on AllTwinCAT and about the last one on Stefan Henneken’s blog.

Integration tests

After testing the individual units, you want to make sure that once you glue several units together they work as intended. This is called integration testing. For this there aren’t that many well developed options that I know of.

One option is that you create an actual 3D model of your machine and connect that to your PLC as shown on the WJB Automation Blog. By using the 3D model you can easily check if parts are moving as intended and that there are no collisions. However, if you have a machine with less or no moving parts, this method is not an option. Furthermore it is harder to automate these tests further down the line.

The second option is to manually force different in/outputs in your program and verify that everything works as intended. This option is, of course, vey time consuming and not automated. And if you’re like me, than you didn’t become a software engineer to do things manually 😁.

The third and last option is to make use of Beckhoff’s EtherCAT Simulation module. This a quite extensive module (InfoSys):

The TE1111 TwinCAT EtherCAT Simulation function simulates an EtherCAT segment. An already created I/O configuration of the real plant is exported and can be imported into a second system as an ‘EtherCAT Simulation’ device. A mirrored process image is thus available on this system that can be linked with corresponding TwinCAT modules (e.g. written in the IEC 61131-3 languages or generated from Matlab®/Simulink®). The desired behavior of the machine must be implemented with sufficient accuracy in these modules.

When my colleague tested this, he didn’t quite get it to work for our machine. The simulation was having trouble simulating all the different terminals he thought. Long story short, that is why he decided to make a simpler version completely from scratch. Another small advantage, especially if you want to try this at home, is that you do not need a license to do this.

Digital twin?

What is a digital twin and why would you want one? Lets start with the why first. When you have your PLC project it has numerous in and outputs as visualized below.

If you would like to do integration tests, or test your HMI, then it is often very difficult because the IOs are not connected. For example, you want to test some conveyer belt functionality, but you can’t turn it on because some safety latch is not closed.

That is where a digital twin comes in. A digital twin (or a TwinTwinCAT project? 😬) is a digital or virtual representation of your real machine. By making a digital twin we can mirror our IO’s and connect them to the original PLC project as shown here.

The twin can be made as detailed as desired. Components can be simulated just enough such that things can turn things on and off. Or individual terminals can be simulated, such that the failure of a single IO can be tested.

Once you have a working TwinTwinCAT project, it can be used to do (automated) integration tests. In this post I will not go into the automated tests. I will show you how to create a simple digital twin of an oven project. Perhaps I’ll do the automated tests in a future post.

Building a digital twin

Now I will guide you through how to build the digital twin project. I will only go into details on the relevant parts which are needed to get the twin working. The exact implementation of the function blocks you can see for yourself if you download the whole project’s GitHub repo or the direct download.

Below you see a schematic representation of the PLC project. The main part is the Oven function block. It takes a command from the HMI which can change its state. It also sends a command and receives a state from the Relay which will turn on the power of the heater inside oven. The oven sets the heater current based on the set temperature. Finally it receives feedback from the thermocouple about the measured temperature.

Creating a stand-alone PLC & HMI project

I’ve implemented the above functionality in a stand-alone PLC project. A stand-alone project has the advantage that it can be imported both into a digital twin TwinCAT configuration project as well as a real machine TwinCAT configuration. I recommend that you open the Oven.sln file located in DigitalTwin/Oven for this part. If you opt for this, you can skip to the next section.

To create the stand-alone PLC project from scratch you can:

1. Open Visual Studio and Go to File > New > Project
2. Select TwinCAT PLC > TwinCAT PLC Project
3. Give it a name and location and click OK
4. Then in the next window under PLC Templates select Standard PLC project
5. Give it a name and click on Add.
6. Add the POUs as desired.

Next we’ll add a HMI project to the stand-alone solution to get some visual feedback. To add the one I prepared, go to File > Add > Existing project and add the HmiProject.hmiproj found in DigitalTwin\Oven\HmiProject.

Creating the digital twin project

Now we are going to create the TwinTwinCAT project. Open a new Visual Studio window to create a new solution and go to File > New > Project. Choose TwinCAT Projects > TwinCAT XAE Project (XML format).

Add the oven stand-alone plc project by right clicking on PLC > Add Existing Item... Then navigate to the Oven PLC project. You can either add the PLC.tmc file or the PLC.plcproj. Note that the PLC.tmc only appears after the first successful build of the stand-alone project.

The advantage if you add the .plcproj file, is that you can directly edit the function blocks of the stand-alone project (the one in DigitalTwin/Oven/Oven/Oven.tsproj) from the digital twin project (the one in DigitalTwin/OvenConfig/OvenConfig/OvenConfig.tsproj). A disadvantage is that if you have the stand-alone project open, it will ask you to reload files every time you make a change. If you choose to go with the .tmc file option, you get neither the advantage nor the disadvantage.

If you select the .tmc file, make sure to select the “Auto Reload TMI/TMC” option. This option can be found under PLC Instance > Object. This will make sure that whenever the .tmc file of the stand-alone project changes, it will automatically be reloaded into the digital twin project. I used the .tmc file for this tutorial.

If you’ve selected the .plcproj file, then make sure to select “Use original project location”. With this option you can directly edit the PLC project from the digital twin project.

Next, add a new PLC project which will become our digital twin PLC project. Right click on PLC > Add New Item… and choose PLC template > Standard PLC project. Give it a name, e.g. SimulationPlc.

In the SimulationPlc project, rename the PlcTask to SimulationTask. This is to make a clear distinction between the PlcTask from the Oven project and the Simulation project.

Then make a new task and call it SimTask.

Next right click on SimulationTask and select Assign to task

Then select the SimTask as the new task where SimulationTask will be assigned to.

Adding digital twin objects

In this section I will show you how you can create the digital twins of the Relay and Oven function blocks.

Mirroring the relay

The PLC project has a function block Relay which represents a relay. The relay has one output turnOnRelay AT %Q* : BOOL; which is set to TRUE if the relay needs to turn on. It then watches for the feedback of the relay if it actually turned on with relayOnFeedback AT %I* : BOOL;. If the relayOnFeedback is set to TRUE, Relay will switch to the on state.

Without a simulation project, the feedback will never go to true, so the relay will always be in state off or turning on. So that is why we get this:

Go get the correct relay behavior we will create a mirror object of Relay called SimRelay. SimRelay will have the mirrored I/O as Relay in the PLC project. I.e. %I* becomes %Q* and vice versa:

For the implementation of SimRelay I added some delays before the feedback is set, in order to clearly see the state transitions in the HMI. The complete codes is then as follows.

FUNCTION_BLOCK SimRelay
VAR
    relayOnFeedback AT %Q* : BOOL;
    turnOnRelay AT %I* : BOOL;
    relayOnDelay : TON := (PT:=delay);
    relayOffDelay : TOF := (PT:=delay);
END_VAR
VAR CONSTANT
    delay : TIME := T#1S;
END_VAR

relayOnDelay(IN:=turnOnRelay);
IF relayOnDelay.Q THEN
    relayOnFeedback := TRUE;
END_IF

relayOffDelay(IN:=turnOnRelay);
IF NOT relayOffDelay.Q THEN
    relayOnFeedback := FALSE;
END_IF

Next we create an instance of the SimRelay and call it every cycle in the MAIN program of our simulation project.

PROGRAM MAIN
VAR
    simRelay : SimRelay;
END_VAR

simRelay();

Now we can link the instance of Relay in the PLC project with SimRelay of the simulation project. To do so, double click on SimulationTask Inputs and right click on MAIN.simRelay.turnOnRelay and select Change Link….

Then select the relay output from the PLC project.

Do the same with the SimulationTask Outputs, where you can link the MAIN.SimRelay.relayOnFeedback to MAIN.Relay.relayOnFeedback. Then you reactivate the configuration and you should see the oven go from on to off via the turning on and off states.

Mirroring the oven

Now the oven can be turned on, but it doesn’t heat up if a temperature is set. In order to make this work we need to create SimOven. In this function block I again take the mirrored IO of the Oven one. Then to simulate gradual heat-up, I’ve used some exponential smoothing. The filter takes 99.5 % of the temperature of the previous cycle and adds 0.5% of the new temperature. The temperature is calculated by the current squared as per Joule’s first law. The limit is added to prevent the temperature from going below room temperature. The complete code is as follows.

FUNCTION_BLOCK SimOven
VAR
    thermoCouple_Celcius AT %Q* : REAL;
    heaterCurrent_Ampere AT %I* : REAL;
END_VAR
VAR
    previousTemperature : REAL;
    filterParameter : REAL := 0.995;
END_VAR

thermoCouple_Celcius := previousTemperature * filterParameter
    + LIMIT(20, TO_REAL(EXPT(heaterCurrent_Ampere, 2)), 1E5) * (1 - filterParameter);
previousTemperature := thermoCouple_Celcius;

After making an instance of SimOven in MAIN and linking the IOs of the simulation project with the PLC project we get a working oven! 🎉

Discuss: r/TwinCAT.