Part 11 - Creating your own Libraries

Video: https://youtu.be/rWWPWuUYFbg

#PLC #TwinCAT3 #Beckhoff #IEC_61131-3 #Industrial_Automation

🔙 Previous Part | Next Part 🔜

↩️ Go Back

Table of Contents:

A) Objectives

Welcome back PLC programmers!

In the previous  part we played a little bit with hardware but now it's again time to go back to the software  parts of TwinCAT 3.

When you start to develop PLC software and you've worked for a few projects you  will come to a point where you will notice that certain parts of the software like function  blocks will be copied between the projects.

You'll either do it by simply rewriting  the same functions or function blocks again or you will simply copy and paste  it from one project to another.

Also, once a project gets big enough you will  want to utilize something called libraries.

With libraries you can organize code in such a way that  it can be used by multiple projects that might not have any connection to each other, but that have  shared functionality.

Then you can have code that is specific for a project or program only within  that particular program.

Libraries are very common in other programming environments, TwinCAT is no  different. Let's look a little deeper into this.

B) Introduction to Libraries

B.1) Why use Libraries?

Let's imagine you are developing a PLC program for a machine.

Let's call it PLC-Program #1.

When developing this  program you will implement various function blocks that make up the functionality of the program.

In this case it's a simple program with three function blocks FB_A, FB_B and FB_C

Now let's imagine that you develop another PLC program for another machine at the same time or later, so for example PLC-Program #2.

This  program will have three function blocks FB_A, FB_B and FB_D

The function block FB_A and FB_B are identical with the one in PLC-Program #1.

In this case you might for example have copied them manually from PLC-program #1 to PLC-Program #2 :

FB_C is specific for the first  machine, while FB_D is specific for the second machine.

Now instead of having duplicates of function block FB_A and FB_B, you can create a library and move the two function blocks to that library.

Once you have the library you can then make  the PLC-programs reference that library instead.

By putting the function blocks in the library it's easier to reuse code.

We can have several projects share our common codebase of pre-programmed functions and function blocks.

The value of a library lies in the reuse of standardized program elements. When a program invokes a library, it  gains the behavior implemented inside that library, without having to implement  that behavior itself. Libraries encourage the sharing of code in a modular fashion  and ease the distribution of the code.

By putting certain parts of our logic into libraries, we will have to modularize our code in such a way that we can test the library  code independently of the actual application code.

Note: We will look more into testing in part 17 of this tutorial

One disadvantage with libraries is that we have  another software artifact to version control and keep track of, which really isn't a disadvantage  until you've got a few libraries and get into something called dependency hell, which is a topic  that is outside of that scope of this tutorial.

B.2) Previous Libraries used

Libraries are actually not something new for  us. We have already been using several libraries which are made by Beckoff.

All these libraries are just standard TwinCAT 3 libraries, albeit pre-installed with the TwinCAT 3 installer.

In a previous part of the tutorial we were using the Tc2_Utilities library, where we for example used the memory ring buffer function block in Part 9 - TwinCAT utilities library (RingBuffer, Profiler and NT_StartProcess)

There is no reason to reinvent the wheel when  Beckhoff already has done the work for us.

What we'll do now is get into the action, and learn how you create your own TwinCAT 3 libraries.

C) TUTORAL 22 - How to create a Library for our IFM Distance Sensor //FILE -->O5D100 & IO ✍️

Ok it's enough with theory. Now we should do a little bit of practice.

This is the project we finished with in the last part of this tutorial.

Let's now just imagine that we want to use this IFM sensor in more than one machine.

The project from the previous part is running with a specific PLC configuration, and with a specific IO configuration.

But let's now imagine that we're building a second machine, that has the exact same sensor.

One way to do it is to create an identical project like this one, and just copy/paste this function block, so we just take this function block and copy  it over to the second project.

But that's not what we're gonna do.

What we're gonna do instead is to  create a library for this functionality so we'll move this function block to a new library  and then we will make sure to use this library in every PLC program instead.

C.1) Step 1 - Creating a New Project (for the Library) 🔍

The first thing I will do is that I will create a new project that will only be for the library, so it will be a library project where we will just store all our function blocks, so the business logic  of our code.

So we create a new project,

And here I would recommend to create a project with something that describes a little bit what the library is used for so... This sensor that we have here is a sensor (duh) but we could also have actuators.

So I would recommend for example to create a library for different inputs and outputs, so we can just call this "IO".

Now create a new PLC project just as usual,

Call this IO as well.

I would already recommend you  to clean this project up a little bit because for example we will in a library project, we will  never have any motion control stuff.

Note: we can have motion control stuff in the sense that we can  have function blocks to control drives and motors. But we will never have anything that's related  to the actual execution of the motion control, so this we can hide.

We can hide the safety.

We can hide C++.

Also Analytics.

Unfortunately we can't hide I/O.

It would make sense to hide this as well. Because again the I/O is part of the configuration of the actual executable. This will just hold the function blocks for the business logic.

And now we can put our different function blocks here,

so what  I would do is...I would just simply right click...copy...

and paste.

Now we can ask the question "Do we  need a main program here?"

and the answer to that right now is "no".

We don't need any program in the library, because the library in itself will never be an executable. It will be compiled into an executable so it will be part of an executable, but the library itself is just a  collection of function blocks or functions or data unit types, but it in itself will never  hold an executable.

So we could delete this program.

We will get back to this in part 17 when we talk about test-driven development and unit tests. We will actually have a program even in the library that is just there to test the different function blocks. This is part of the stuff that I'm advocating a lot about in modern software development practices for PLCs, to always have unit tests for function blocks.

But for this you will simply have to wait for part 17.

Right  now we'll just get rid of this program,

We can get rid of this as well.

I would generally get rid of all the folders that you're not using.

C.2) Step 2 - Define the Project as Library 🔍

Now to define a library, it's actually very easy.

You go to the PLC project, right click on it, select properties,

Here you enter the details about the library  that you want to create.

So "Company", just enter the the company name that you're working for.
I'm just going to make up a stupid name here... "MyCompany AB".

And "Title"...so this  is the title of the library. We can call it inputs and outputs, or IO... whatever.

The version is basically a numbering scheme, so you can create one yourself. There are some standards and recommendations of how you should call what the version should   mean, so what a bigger and lower number means. In this case I'm just going to create "0.1.0.0". This will be incremented for every time you do a new release of the library. It has to be done manually I've been working with companies where they have  a build server that does this automatically so it automatically increments this version, but  for now we will just create a version manually. You just have to make sure to increment this  every time you do a new release of the library.

The released flag is basically telling the  library that "Hey! Once this is set then you can't change anything in the library!". It's just a protection so you have to remember to change the  version after it has been released. If I set this  to released it means I can't change anything in it which forces me to change the version, or at  least reminds me to change the version before doing any changes. Right now we're not going to  set that.

"Library Categories"...I'm going to get back to very soon.

The "Namespace" is quite convenient and  good to use. This is to avoid this problem when for example you create a functional or function block that already exists in another library. By using namespace, then when you call the function block or the function you can be explicit and say "Hey! This functional function block should  come from this particular library". We're going to see this in action soon, so we can actually  call this IO.

Normally I would recommend to call the namespace whatever you call the library.

In the "Author" field, just enter your name.

Here you can add a tiny description.

Then I would also recommend you to add the global version structure here,

because then you automatically get the global  variable file,

which holds the version of this  library,

which can be useful for example when  you use this library in another project, then you can just expose this information and say "Hey! This  executable holds this version of the library".

We're not going to get too much into that but I would still just as default always include it. There's really no reason not to include it.

Okay. And  this is basically all you need to do.

C.3) Step 3 - Compile and Install the Library 🔍

Now you need to compile this library and install it.

There's a very easy way to do it. The way you go about it is that you right click on the PLC project. Click "Save as library and install".

What this does is that it's going to create the library. It's going to create a file which is the library.Then it's going to install it in a folder that TwinCAT has access  to.

Now we need to provide a place where the library should be saved.

This is just a temporary place, because what TwinCAT will do is that it will take this file once it's  stored in...for example the desktop. And then it's gonna copy it to TwinCAT 3 folder. So if you do like this...we save it.

Now it's installed in the system.

C.3.1) Removing Temp File

One more thing I could mention is that the file that was created when we compiled the library can be removed, so if you go to the desktop. This IO.library. It can be removed,

because this guy is actually copied over to here.

This is just for TwinCAT to temporarily store it somewhere before it's installed in the system.

C.3.2) Where are the Libraries Stored?

I just wanted to show you quickly that all of these libraries are stored  in this folder on the C:\TwinCAT\3.1\Components\Plc\Managed Libraries.

Here you can see that MyCompany AB shows up,

and the name of the library,

and then the  version.

Here is the actual library.

C.4) Step 4 - Reuse the Library in a New Project 🔍

What we're gonna do next is that we will create a project that actually uses this library so this will be the PLC-Program #1 as I showed in the presentation.

So you create a new project. So this will be the executable and we call it... "PLC_Program_1". This is the PLC program for machine  number one or whatever.

I just wanna demonstrate how to use this library, forgive me for the bad names I am using.

Now we need to create an executable. So again... "Program_1".

In here we will have our MAIN program. Here is where we will actually have to use our library,

But before doing that we have to create a reference to the library that we just created. To do that we go to "References". "Add library".

Then you get this window.

This is showing part of the library manager. If you look around here then you can get confused and think "But where is my library?"

Then you'll get into this window. If  you look at miscellaneous...

Here you have the inputs and outputs from MyCompany AB.

I don't think it looks particularly nice. While we're at it I'm gonna show you  how to make sure that this library doesn't pop-up in the "Miscellaneous".

C.4.1) How to Set-up the Library Categories

To do that we have to use exactly this thing called library categories So library categories is something that you have to create.

You have to create a category for your library. To do that we have to create it. When you click here...

there's no way to create it.

You have to add one from a description file,

so you  have to create a file for this library category.

To do that you can go to my GitHub.
Link: https://github.com/sagatowski/TwinCAT-LibraryCategories

And then you have "TwinCAT-LibraryCategories".

You need to have this file and use this file as a template and adjust it to create  your own category,

So just download this file.

If you can't download it just  take the raw content,

copy it, create a new file and call it "OurLibraryCategory".

And the way it works is, you can have a main category and then you can have sub-categories. So for example you could have a main category called MyCompany and then you can have a category called "Motors" for  that company.

Here we're just going to keep it simple and create the main category and only  have one category so I'll remove the other stuff.

Then we have this ID. It's called a GUID, I would just generate a new one. For this there is you can Google "guid generator"

"How many do you want?" One. Generate. And Copy this guy.

This is just to get an unique category. You can use the one I have from from the file, you don't actually need to change it, but yeah it's recommended.

Link: https://www.guidgenerator.com/

So save this file.

I accidentally saved it as an txt, so rename it to .libcat.xml

Then again...in your library categories... we need to add one from description file

Point it to the file on the desktop.

There we go "Unexpected token?"

Oh, bummer! The XML is wrong here...

Let's fix it,

Let's try again,

There we go.

And now anyway, the reason I wanted to add this is because now if we install this library...

Let's overwrite the file,

Now if we go to our PLC-program-#1. And we add a library.

It doesn't work properly....

Because there is of course some bug in TwinCAT.

At least in this version, so we have to restart the development environment.
Close everything and start it again.

I wouldn't say that there are more bugs in TwinCAT than any other PLC program development environment. Everyone has their problems.

I've gotten to a point in life where I'm starting to just don't  care. I just restart everything and go on with my life. Of just send an email to Beckhoff

Anyway so MyCompany AB shows up here, nice!

so we don't have this annoying misc anymore. Instead you have our own and this is just looks so much cleaner, especially once you work for a while for a company or if  you run your own consultant business you're gonna develop lots and lots of functionality over  and over again and then it just like looks so much cleaner if you can organize it into these categories.

C.4.2) How to create an instance of the Library

So let's finish it and create a reference to it.

Now if you go here, double click on it.

We  can actually see all the files that are in this library (one of the files  is the function block for the IFM sensor)

Again, this is going to be our executable so we want to create an instance of this   function block.

Right now we have a separate  project for the library,

so we maintain this It has its own life cycle. Maybe there's even gonna be some other developer maintaining this or another team developing it.

If you work for a very large organization you usually have some part of the company that's just maintaining  the "standard" type of libraries that everyone on the company should use.

And this is one  way to go about it.

Then you have your other programs that actually use these different libraries.

So now we can just instantiate the FB from the library in one of our programs,
(We can  also see that it's the library from our company).

C.4.3) Using the Explicit Namespace to choose which Library to use

Now the namespace is for example, again... If we would have created a function block or a function that's called CONCAT, which already  exists in the Tc2_Standard library then the compiler wouldn't know. "Should I use CONCAT from Tc2_Standard or CONCAT from our library?".

Then you can just use the namespace, which was...if you look  at the namespace, it's IO.

You can write IO and then you're explicit and say "Hey! Please use the  function block from this particular namespace"

In this program is where we do the actual link into the hardware, so in here we would as usually as I showed you in the previous part of this tutorial, we would add the EtherCAT master. We would link it and we would scan the bus. We would add the IFM master, and then we would add the IFM sensor and then we would add these input bytes to  the software.

So again if I compile this now. We get the instance here (from the FB),

and we get the aInputBytes which we're gonna link to the EtherCAT master. I'm not gonna do that because I already showed how to do that in the previous part.

D) Conclusion and Final Words

But that's basically everything I wanted to show .
Libraries are a very powerful tool to organize and manage your software artifacts. When you start developing TwinCAT 3 software, you will quickly find the use cases for using them

This was a brief introduction into libraries. We will get back to this topic in part 14 of this tutorial, when we are going to talk about  how to handle different versions of TwinCAT.

Goodbye for now and see you in the next part!

G) 💬 Summary

1. Transition to Software Libraries in TwinCAT 3: After exploring hardware aspects in the previous part, this segment focuses on the software side of TwinCAT 3, particularly on using libraries. Libraries in TwinCAT 3, like in other programming environments, allow for the organization and reuse of code across multiple, unrelated projects through common functions.

2. Reusability and Modularization of Code: The video emphasizes the importance of reusing code, such as function blocks, across different PLC (Programmable Logic Controller) projects. This is achieved by creating libraries, where common code segments can be stored and accessed by multiple projects, enhancing efficiency and reducing redundancy.

3. Example Scenario for Library Use: A practical scenario is presented where two different PLC programs for separate machines share common function blocks. Instead of duplicating these blocks in each program, they are stored in a library, demonstrating how libraries facilitate code sharing and modular development.

4. Creating and Managing Libraries: The tutorial guides through the process of creating a new library project in TwinCAT 3, detailing steps like setting up project properties, naming conventions, and organization. It also touches on the concept of namespaces to avoid conflicts and ensure clear referencing of library components.

5. Practical Application and Testing: The latter part of the video focuses on applying libraries in actual PLC programs, showing how to reference and use library components in different projects. It also previews that part 17 of the tutorial will delve deeper into testing these library components, highlighting the need for modular and independent testing of library code.

🔙 Previous Part | Next Part 🔜

↩️ Go Back

Z) 🗃️ Glossary