How to document a PLC program

May 20, 2019
Documentation for PLC programs exists externally and internally in several forms, so don't forget the specification and tag names

So, you have a PLC, and you need to program it to run an automated machine. If you want to be a programming hack, just sit down and start writing the ladder logic and debug it. While you may understand your methods, others won’t, at least not quickly. So, if you want to do it like the big integrators do, there are some things to focus on to ensure efficient development of PLC-based control systems.

There is more to it than just writing the PLC program. The architecture of the program must first be defined, and, once written, it will need to be debugged, tested and accepted, often by different individuals. Outside of the program itself, this documentation includes a machine controls programming specification and acceptance documents.

When spearheading the control software design effort, there should be a strong emphasis on creating software that is documented, organized, structured and reusable. This emphasis helps to ensure efficient development of PLC-based control systems.

Many senior controls engineers will focus on the step sequence that controls the repeatable automatic sequence of the machine. In my column on how to write a PLC step sequence program, I suggested it’s best practice to "define a machine's control modes, main cycles and sequence steps before a program is written, or you'll just write scatter code and confuse others."

One of the key points is to write it down. Documenting the program before it is written, as a programming specification, not only helps program development, the documentation can then be edited into an acceptance testing document. It also helps the understanding of the control system over the 10-plus years it will be in operation for the other guy's benefit. After the program has been running for five years and edits are needed due to manufactured product changes, the controls programming specification for the machine should help ensure program logic added is consistent with the original program.

Automatic, manual and step cycles controlling manageable-sized, logical sequences is a must. An overall machine cycle often helps to synchronize individual station or equipment sequences, such as pick up part, place part and index conveyor.

There is much more to the documentation beyond the machine operation modes, machine cycle control and the machine sequences themselves. Outside of the sequence, it is important to document the hardware and software (firmware and version) used to create the program, as well, that information is especially important five years from now, so make sure it is updated, as-built.

Inside the program, there is much documentation, as well. Many controllers are now capable of storing and displaying the rung and device descriptions. The days of lost documentation are past. However, there are ways to make the program more readable, and that should be documented both outside and inside a program, as well.

Reading down tag names or descriptions on the coils in the rungs of the ladder logic should read like a machine sequence of operation. While there are many parts to a PLC program that needs to be written, if the auto cycle sequence—the part that repeats every machine cycle—isn't clearly written, it's likely an example of how to confuse the next guy who looks at it.

There is much more to writing a best-case example of a PLC program, and that includes defining how to create self-documenting memory, programs and functions. In the past, the PLC memory was fixed. The manufacturer controlled variable naming and often limited the number of variables. Inputs (I), Outputs (O), Bits (B), Integers (I), Floating point (F) and String (S) variable names all started with an identifying letter, for example I:0/1, O:1/0, B3:0/15. The type of variable is indicated in the name, but not the function. In this case, a description is added to define the variable function, such as "System air pressure ok."

With most newer PLCs and PACs, tag-based variable naming is used. The contacts, coils, timers and counters can be self-defining, and how it is done should be documented to be consistent.

And careful variable naming will help with the auto complete function that groups variables together when selecting them from a drop-down list during program development.

For example, in a system with three stations, the variable name local to each station can start with S100, S200 and S300. These prefixes can make it easy to copy and paste programs and then search and replace the prefix, as needed. It's a form of reusable code. Another example is a robot that has multiple pick-and-place motions that set a "busy" local bit when each motion is in cycle. It may be helpful to have the word, “busy,” in the first part of the variable name. In this case, the auto-complete feature displays all the busy bits together, (for example, b_BusyR1PickNest1, b_BusyR1PickNest2, b_BusyR1PlaceTest1, b_BusyR1MoveToClear). In this case the b_ indicates the variable type is a bit. Some choose not to use these variable type identifiers, and it's documented.

Alternatively, the prefix vlb_ could be used to indicate variable local bit and vpb_ to indicate a variable program (global) bit. The point is variable naming should be defined so others can understand the naming convention used. And, no matter the naming convention, if the variable tag name is not self-defining, add a descriptor, such as “Robot 1 is busy picking from nest 1,” and there are many other examples. These self-defining names or descriptors or both are for the next guy. Be a courteous programmer and document things.

About the author: Dave Perkon

Control Design Newsletters

About the Author

Dave Perkon | Technical Editor

Dave Perkon is contributing editor for Control Design. He has engineered and managed automation projects for Fortune 500 companies in the medical, automotive, semiconductor, defense and solar industries.