Project/Software documentation

Hello dear colleagues,

I would like to initiate a discussion about how you people document your PLC software. By saying this, I don't mean on operation manuals, user guide manuals, etc. I mean on a document which explains PLC software design and structure, like descriptions of function blocks, description of sequence, interface between different functions and function blocks, etc.

Many people say and recommend to write (even as a sketch) software design idea before you start coding. I know that this is a practice in IT programming and that they have developed powerful tools and ways for software documentation. But unfortunately, in the world of industrial automation, it seems like there is no such thing.

I have searched all over the Internet to find any document template, read many forums and posts, and everyone is just saying that PLC software needs to be documented, but no one says how. No one provides an example or template. People mention diagrams, but what kind of diagrams? I would prefer if on a diagram I could see which FB communicates with which FB or DB.

I see a huge advantage in actually having proper software documentation, in a situation where you created a software, but someone else needs to maintain it, or even you have to change something after several years and you don't want to waste time on recalling the idea or approach that you had when you initially wrote it.

So, if someone is in a mood for sharing tips and tricks, I would be more than glad to hear it. Any opinions, screenshots, pieces of advice, absolutely everything is welcome and the best thing would be if more people join the discussion.

If something like this doesn't exist, I am even into inventing a new way for writing documentation for PLC software which would be used by PLC programmers.

Looking forward to hearing from you,
Aleksandra

I always try and name tags and routines in such a way anyone familiar with the process can look at the code and know exactly what each section is doing.

Now it's common to get comments on uploads, this will last much longer as a tool to see what is going on than a word doc or a manual which generally get mis-laid or put somewhere safe.

Along with lots and lots and lots of comments.

janner_10 said:

I always try and name tags and routines in such a way anyone familiar with the process can look at the code and know exactly what each section is doing.

Now it's common to get comments on uploads, this will last much longer as a tool to see what is going on than a word doc or a manual which generally get mis-laid or put somewhere safe.

Along with lots and lots and lots of comments.

Click to expand...

Giving meaningful names for tags and blocks is a precondition for understanding software. But in software with lots of blocks and code, it can be time-consuming to look at cross-references and read comments in each block. I am interested in word-doc which contains both an overview of the programmer's approach in software design, as well as the part where every block functionality is described in detail.

In my experience I've worked in a company that had a programming guidelines that must be adhered to with regards to program structure, naming, numbering, etc...
Under that there was a word document explaining what the software blocks did inside each library and most importantly, their dependencies as the company would lock the blocks from being open. This worked quite well, sadly I left almost 6 years ago so don't have an example with me.

One example that comes to mind is the Open Library. https://openplclibrary.com/

They too have documentation explaining the functioning of their blocks and how to work with them. It might not be exactly what you're looking for, but should be close.

I agree that writing software should be the last thing to do and some brain storming done beforehand will cut down development considerably. In the process industry (what that open library targets), this is somewhat easy as you have easily defined devices that you need to code and is then a matter of deciding how they're operated and how they interface with SCADA or HMI.
For dedicated machines, it's not as straightforward, but having a plan and division will also allow the coding to be split between two or more people since the interfaces between functions and scope will have been agreed.

Put a table of contents in your program and index it. If I'm doing something that is more than a couple hundred lines, I will make that table of contents in the comments and put a specific, indexed string in the different sections of my program so that I can easily go where I need to.

Aleksandra said:

Giving meaningful names for tags and blocks is a precondition for understanding software. But in software with lots of blocks and code, it can be time-consuming to look at cross-references and read comments in each block. I am interested in word-doc which contains both an overview of the programmer's approach in software design, as well as the part where every block functionality is described in detail.

Click to expand...

Where are you going to store this word doc? If OEM A builds a machine and Integrator B is called in to make changes long after they have gone - it is useless.

If as Sparkie says, your comments are organised - then problem solved - it's all in the PLC.

janner_10 said:

Where are you going to store this word doc? If OEM A builds a machine and Integrator B is called in to make changes long after they have gone - it is useless.

If as Sparkie says, your comments are organised - then problem solved - it's all in the PLC.

Click to expand...

I am going to store the document for myself. If I write the PLC software and document it, as well as if I keep it updated after changes in software are made, then there is no problem. If someone else continues to maintain the software I will give him the document to reduce his effort of understanding what was my idea when I was designing that software.

I have been many times in a situation to receive a project, with no project documentation, only comments. I look at hundreds of FBs, FCs and DBs, with no idea how they interfere together, and lose thousands of hours trying to conclude the overall logic. Opening block by block and reading comments, I hope that you agree with me that this is very time-consuming.

If it is all about organized comments, why in the IT world there is the whole science on how to write software documentation? The main principle is "first make the plan, then start coding!"

Program design is best documented within or by itself.
Really good design does not need any explanation at all. Any changes afterwards just need to follow the existing style - no other document can help if someone doesn't understand that But for outsourcing it is necessary to define *everything* in a separate doc. Also for new programs within the company a doc can help, maybe you can't open program for plc model A before programming model B. We have a general standard in word to be followed by Omron and Siemens PLC. Each FB has a header saying a little about it.

For our B&R we program in c++ we try to use Doxygen for automatic printout of program comments. So if we make them good and say how different functions are used together, it will also come into a pdf.

When we get the machine specs, we design the program.
we write the program and do rung comments every 5 rungs or so.
we also detail the program operations in the user manual.

james

James Mcquade said:

When we get the machine specs, we design the program.
we write the program and do rung comments every 5 rungs or so.
we also detail the program operations in the user manual.

james

Click to expand...

One thing I do is sections.


I mean, for some pump logic I wouldn't go this in-depth, but for a large program I certainly would. Then I have good copypasta for the user manual.

Hey guys, thanks for participating in the discussion.

I regularly comment on my code sections and even put descriptions for functions/function blocks. But imagine a huge software with thousands of blocks where you have to open each one, and read comments...

My motivation for this post was exactly that! I have inherited a very huge and complex software to maintain, but the company which created this software didn't provide me any document. Everything I have is poorly commented code. Abbreviations used for naming variables, with no sign of what those abbreviations could mean. It's torture. Please don't misunderstand me, the code is written wisely, but for someone who sees it for the first time, it is very hard to understand because of its size. That is why I am persistent in inventing some kind of software documentation for PLC guys.

Aleksandra,

if that is the case may I suggest the following.

1. make a backup copy and put it in a place for safe keeping. if you delete
something, you can go back to the original.
2. make a spread sheet of all the I/o and give yourself enough room to
document what the I/o is. (this is for later)
3. go to the machine and watch the automatic cycle in detail.
4. write down the sequence of events in detail. add the I/o point address later.
5. get with maintenance and ask them and the operator what each sensor
means to them.
6. when you have some downtime, get maintenance to help you detailing the
I/o points using the plc inputs.
7. describe the I/o on your spreadsheet.
8. comment the program and make it your own.

you may want to get purchasing involved with your issue. they can see what the po to that company detailed and maybe able to help.

james

I don't know if this is lazy, we just print the logic and hole punch into a binder, haha.

I just started this the other day, after reading another thread about programmers vs. joe maintenance....or something like that.

I create a routine (in RSL5k) that is labeled "program notes" and each rung gives instruction as to program flow, followed by an NOP, along with the usual descriptions I place with each rung and each object. Time will tell if my electricians find this of benefit, when they commission a system. It will also help me! I can finish a commission, go back a month later and wonder what the heck I did. Lol

Hmm, so this is how you generate the documentation for a library using CODESYS.
https://help.codesys.com/webapp/documentation;product=LibDevSummary

My biggest annoyance is that the docu project it uses is made with the Sphinx program. Sphinx being famous for giving riddles, and if you can't answer the riddles you get eaten. I don't want my docu to be cryptic, and I don't want to get eaten if I can't figure it out.