[EN] PLC programs development guidelines

PLC programs development guidelinesItris Automation SquareJanuary 20th 2012 - Version 1.6.7http://www.automationsquare.com

PLC programs development guidelines2/19 January 20th 2012 - Version 1.6.7

Contents1 Document purpose 52 Document structure 6 2.1 Rules classiﬁcation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.2 Presentation of each rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Coding Rules 7 3.1 Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.1.1 PLCs common Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.2.1 PLCs common Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.3 Writing code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.3.1 PLCs common Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.3.2 Unity Pro speciﬁc rules (Schneider Electric). . . . . . . . . . . . . . . . . . . . . . . . . 10 3.4 Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.4.1 PLCs common Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.5 Useful Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.5.1 Useful information for all PLCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.6 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.6.1 Unity Project Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Annexes 17 4.1 Summary of Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 4.2 Document history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3/19

PLC programs development guidelines4/19 January 20th 2012 - Version 1.6.7

Chapter 1Document purposeThis document contains coding style guidelines for PLC programming, to improve readability, maintainability andthe consistency of PLC programs. It describes simple rules which allow to get meaninful quality indicators fromthe ﬁrst day of development. All rules in this document are checked automatically with PLC Checker, which supports PL7 PRO and UnityPro from Schneider Electric, STEP7 from Siemens and Rockwell Automation RSLogix 5000 PLCs. This document was written by IAS’ seasoned consultants, based on analysis results of many codes used byItris Automation Square’s customers in several industries and using various ranges of PLCs. It also reﬂects somebest practices from other computer engineering domains such as embedded systems, which have been applyingstandard sets of programming guidelines for years. 5/19

Chapter 2Document structure2.1 Rules classificationThe rules described in this document are classified into several categories: Naming, Comments, Writing and Struc-ture. The last part of this document also provides useful information which are not only about coding rules, but alsoallow improvements of the programs’ quality. The last part is about the rules on the options of the PLC workbench. Each category is divided into two parts:1) The rules that may be applied independently of the PLC for which the program is developed.2) The rules that are only relevant for a specific PLC or that need to be adapted in order to be applicable.2.2 Presentation of each ruleThe rules are numbered according to their implementation in ”PLC Checker”. For each rule, we find an identicalstructure made up of a title, an explanation of the rule, a justification of its importance and, when relevant, a codeexample to facilitate understanding of the rule. 6/19

Chapter 3Coding Rules3.1 NamingThe elements manipulated in PLCs have mnemonics. Elements are, for example, variables, routines (sections,subroutines, FCs . . . ) or function blocks (FB). The purpose of this section is to make sure that the symbols followrules ensuring readability, maintainability and allow for greater code perenity. Generally, the libraries elements areexcluded from naming veriﬁcation. Of course, when the workbench allows this, we don’t recommend to changethe elements’ names deﬁned in the libraries.3.1.1 PLCs common RulesN.1 - All program elements should have a mnemonicAll program’s elements should have a mnemonic (program, modules, variables, DFB, FB, OB, SR, routine, Add-On).. Comment : When all programs elements have a mnemonic, maintenance is easier and it is easier to understandprogram content. Moreover, not using mnemonic makes an implicit link between a code and an hardware imple-mentation.N.2 - Elements names length should be in a given rangeThe names of program elements must contain at least 3 characters and no more than 15 characters. Comment : A minimum number of characters ensures more meaningful naming. A maximum number ofcharacters allows: • In Schneider Unity, Schneider PL7pro and Rockwell RSLogix : to avoid the mnemonics being truncated in display or export, . . . • In Siemens Step7: to improve readabilityN.3 - Topological physical address should not be used as part of a mnemonicThe mnemonics shall not contain a reference to their physical address (for instance, ”MW2”, ”FB4”. . . ). Comment : The reference to the physical address of the entity in the code may have bad properties : read-ability is worse, and it may induce dangerous confusion. It should be noted that with the evolution of softwareworkbenches, referencing the elements names by their physical address is not necessary anymore. Eventhoughsuch a reference to the physical address may be unintentional, it is prohibited. Example : 7/19

PLC programs development guidelines Physical ad- Mmnemonics comment dress %MW23 Cde 23 Never link the naming of the variable to its physical addressN.4 - Debug mnemonics should not be part of the final programSome mnemonics (test, toto, titi, tata, tutu, to delete , todo,. . . ) are forbidden, and the comments should not con-tain debug expressions (like: to do later, to delete, todo ) Comment : Leave debug items in the final program reduces its readability and may have different behaviorthan expected. The list of prohibited elements is configurable (of course, it is language specific).N.5 - Special or graphical characters are prohibited in mnemonics ` ´ ¸The special characters set (e.g : a, e, c. . . ), space and accents are prohibited in the mnemonics names. Only al-phanumerical characters and the underscore are allowed. Comment : Using special characters, may generate some problems of portability to future workbench versionand / or to other platforms. It also reduces the readability in an international context. Finally, the restriction to onlyalphanumerical characters ensures a better distinction between variable names. Example :d´part := true; e# .... Lines of codedepart := false; #Using the spćial character’´’, leads to a confusion e e between mnemonics.N.6 - The programming language keywords should not be used as mnemonicsProgramming language keywords (for example “if”, “set”, “start”. . . ) should not be used as mnemonics. But it ispossible that mnemonics contain a keyword. Most cases are handled by PLC workbench, but there are exceptions. Comment : Using keywords as mnemonics lowers program readability and portability. Example :start := true; # mistaken mnemonic, "start" is a language keywordstart_motor := true; # Correct mnemonic3.2 CommentsIn addition to good naming practices, it is important to follow rules when commenting programs. In fact, the moreexplicit and detailed the comments are, the more the code will be understandable. Generally, the standard libraryelements comments are not checked.8/19 January 20th 2012 - Version 1.6.7

PLC programs development guidelines3.2.1 PLCs common RulesC.1 - All program elements should have a commentAll program elements must be commented (Program, Section, Modules, Variables, DFB, FB, OB, SR). Comment : If all the program elements are commented significantly, it is easier to read and understand theprogram, therefore its maintenance is less costly.C.2 - Comments should be longer than a given number of charactersThe comments of program elements must contain a minimum number of characters (7 for variables, 15 for codes)to avoid insignificant comments. Comment : Having a minimum length ensures that the comments are more meaningful.C.3 - Each network should have a commentThe networks must be commented. This rule is specific to some languages of the IEC61131 standard. Also pleasenote that the concept of network is not always present in PLC vendor IDEs. Comment : In addition to a good overall rate of comments, it’s important to ensure that comments are welldistributed within the program. Such a rule is also a guide that ensures consistency when copy/pasting code sec-tions.C.4 - Comments should not contain comment start markerComments should not contain comment start marker (e.g, ”/ *”, ”( *”). Comment : The presence of a comment start marker is often a symptom of a forgotten comment end marker,which can lead to commenting out of a part of program and thus a non intended behavior. Example:/* Any comment with the end marker has been forgottenCritical_section_that_must_be_executed_which_is_found_in_the comment();/* <- The start marker comment is commented because the end marker of the previous comment has beenforgotten */3.3 Writing code3.3.1 PLCs common RulesE.1 - All variables should be written before being readExcept for physical and communication inputs and system variables, all variables should be written before beingread during a PLC cycle. Comment : a variable that is read before being written, can increase program latency. Efficient code shouldrespect during one PLC cycle the following diagram: inputs reading -> processing -> update the outputs.January 20th 2012 - Version 1.6.7 9/19

PLC programs development guidelinesIn addition, make sure that the variables that are never written in the code have been initialized, otherwise they areupdated by other ways. In some cases it is justified to ignore this rule: • variables that were initialized in the database, • variables updated by a communications link, • state variables that store the value of a previous PLC cycle.Example:if urgentAlarme then alarmeTreatement();end if;# ...urgentAlarme := presenceDefault AND ...;In this example, the call of the alarm function “alarmTraitement” happens during the next PLC cycle, whichincreases the average response time. This delay is around one PLC cycle.E.2 - The parameters of the user functional blocks should be used correctlyThis rule is divided into three sub-rules : • E.2.a and b - Inputs of the user functional blocks should be read and not written. • E.2.c and d - Inputs/Outputs of the user functional blocks should be read and written. • E.2.e - Outputs of the user functional blocks should be written before being read.Comment : Parameters incorrectly used are evidence of unfinished code or a code that still contains unnecessaryelements of correct behavior. In some PLCs, misusing parameters may generate undesirable and potentially dan-gerous effects, such as data corruption. Please note that checking whether private parameters of user blocks areused is done by the rule S7.3.3.2 Unity Pro specific rules (Schneider Electric).E.U.1 - The functions of the Unity obsolete libraries should not be usedIn a new Unity Pro PLC Project, the functions of the obsolete libraries should not be used. Comment : In Unity, some libraries are obsolete and exist to ensure backward compatibility with previousversions of Schneider PLCs. In new applications, the usage of the functions of those libraries must be avoided forfuture portability problems. Furthermore, some of those functions can make the code nondeterministic (ex: shiftson signed integers shl int, shlz int, shr int, shrz int, rol int, ror int).10/19 January 20th 2012 - Version 1.6.7

PLC programs development guidelines3.4 Structure3.4.1 PLCs common RulesS.1 - Backward jumps are forbiddenBackward jumps are forbidden. Comment : Using a backward jump can trigger an infinite loop, which can lead to a PLC shutdown. Moreover,in general, jumps make the code less understandable and therefore their maintenance is more complex. Example: Example of jump which triggers an infinite loop Figure 3.1: Example of jump which triggers an infinite loopS.2 - A variable should be elaborated only in one routineA variable should be elaborated only in one routine. Comment : A simple and clear code architecture facilitates understanding of the code and therefore its main-tenance. Moreover, multiple variable elaborations can lead to erratic behavior of the code.S.3 - A variable should be written from one task onlyA variable should be written from one task only. Comment : writing a variable from several tasks leads to an nondeterministic behavior, such as a potentialaccess conflict.S.4 - A physical output should be written only once per PLC cycleA physical output should be written only once per PLC cycle. Comment : Multiple output writing may lead to problems of dependability. Also, a code where the outputsare written more than once is less easy to understand and maintain. It should be noted that writing in a loop isconsidered as multiple writing and therefore constitutes a violation of this rule. Example:January 20th 2012 - Version 1.6.7 11/19

PLC programs development guidelinesif very_complicated_condition then Critical_Output := TRUE;end if;#.... much later in the programif another_very_complicated_condition then Critical_Output := FALSE;end if;In the case where the output is not controlled where it should be, it is very difficult to identify which affectation isexecutedS.5 - Variables should not be localizedVariable memory mapping should be reserved to variables which elaboration or consumption is done out of theprogram : communication tags, I/O variables, special function variables. All internal variables should not belocalized. Detailed explanation : Using localized variables constraints program evolutivity, due to a more rigid memoryorganization. It reduces portability, as memory organization varies from one PLC to another. So the code cannotbe reused in another application, as in the other application the given memory zone may be reserved for otherpurposes. Moreover, it may lead to memory organization mistakes in which several variables will be saved in thesame memory cells. This bug may be silent during a long time and be encountered late in the development or inthe production cycle.S.6 - DFB/FBs instances should be called only onceComment : A functional block instance owns its variables used to save the FB state between two consecutivecycles. Each FB execution should modify those variables to show the state evolution. When executed more thanonce, it looks like the cycle is progressing twice quicker than the other instances. Often used more than once, the same instance is the result of a cut and paste not updated. It may lead to bugs hard to discover.S.7 - Declared variables should be usedVariables and defined types should be used, except for reserve variables. Reserve variables shall not be used. Comment : Variables (except reserves) and unused types are often a sign of a forgotten treatment or incompletedatabase cleaning. When reserve variables are used this is often the sign of a forgotten renaming.S.8 - Variables location shall not overlapThe overlapping variables are to be checked. Comment : Localized variables that overlap are equivalent to an implicit transfer of value between each other.This is sometimes a difficulty to code readability. It is also sometimes a localization error.S.9 - Complexity measureComplexity of the code shall be assessed. Loops (for, repeat, while ), jumps and a high level of imbrication arecriteria of code complexity. Comment : Parts of program are more complicated than others. This is specially the case when executionsequential flow is often cut. This rule searches for some root causes for flow discontinuation, like loops, backwardgoto and high complex instructions nested level.12/19 January 20th 2012 - Version 1.6.7

PLC programs development guidelinesS.10 - SCADA LimitationsSCADA software doesn’t support structures arrays. Such constructions shall be avoided for portability purposes. Comment : When using a SCADA which doesn’t support array of structures, it is important to not build a PLCdatabase based on these arrays of structures. This rule is used here to detect this kind of construction.3.5 Useful Information3.5.1 Useful information for all PLCsI.1 - Comments rateIt is recommended that the code contains a minimum percentage of comments. Comment : Itris Automation Square recommends a rate of 30% (# of commented instructions / total # ofinstructions). Such a minimum rate of comments ensures that the development was carried taking into account themaintainability of the code, and ensuring that it will be easy to understand when evolution is needed.I.2 - Code in the commentsIt is very important to check the possible presence of code as comments. Comment : Commenting out code is a typical test and debug strategy. The final program should not containcommented out code as maintenance technicians may be confused.I.3 - Dead codeProvision shall be made against the presence of dead code in the program. Clarification : Dead code affects the readability and maintainability of the program and can be a symptom of afunctional problem. Please note that when PLC Checker detects unreferenced functions and parts of isolated codeafter an unconditional jump, the completeness of the detection is not guaranteed (for example, dead code relatedto the evaluation of an expression).I.4 - List of locked elementsThe locked elements are not scanned by PLC Checker, they should be identified for manual review. Comment : In applications where the major part of the code is locked, it is important to know it.I.5 - Cyclomatic number v(G)A cyclomatic number gives information about complexity. It is important to keep it reasonably low. Comment : A cyclomatic number counts the number of different paths that can be executed in a routine. Thehigher this number is, the more difficult it is to validate the correct behavior of the routine. In such a case, theroutine should be divided in subroutines. Each of them having a cyclomatic number below the given threshold.I.6 - Essential Complexity ev(G)Essential complexity gives information about unstructured instructions. It is important to keep it reasonably verylow. Comment : Essential complexity counts the number of different unstructured instructions in a routine. Thehigher this number is, the more difficult it is to validate the correct behavior of the routine. Most of the time,unstructured instructions can normally be replaced by structured instructions.January 20th 2012 - Version 1.6.7 13/19

PLC programs development guidelinesI7 - Source Line of Code countThe source line of code counts number of instructions in a POU. It is important to keep it under control. Comment : Very big procedure or function blocks may be difficult to test, to read and to maintain. It may bebetter to split a very big procedure into two or more procedures of reasonable size.I8 - Sequential Function Chart (SFC) steps countThis is the count of steps in a given SFC. Comment : This rules returns the number of steps found by SFC. This number may be further used to detectcomplex SFCs or to give an overview of the relative size of SFCs.I9 - SFC branches countThis number sums the number of branches in each AND/OR divergence found in a given SFC. Comment : This rule calculates the number of branches available in a given SFC. This count gives informationabout SFC complexity. This number is equivalent to the v(G) applied to imperative coding languages.I10 - Copy/Paste detection ratioThis number detects the percentage of code which is redundant. Comment : Reusing the code by copying code is not a good practice. Maintenance and evolution are moreexpensive to perform because modifications and corrections should be applied at each copy/paste instance. More-over, the manual copy/paste is error prone : after doing the copy/paste, code should be modified. When code is notmodified correctly, it introduces subtle bugs hard to discover.3.6 Options3.6.1 Unity Project OptionsO.U.1 - SFC : ”Multiple Token” should not be AllowedIn the language extensions tab of project settings, the check-box ”Allow multiple token” shall be deactivated. Comment : The only purpose of the multiple token mode is to ensure backward compatibility with previousversions of Schneider PLCs. It should not be used in new projects because it can make the code indeterministic.SFC code with Multi Token is not compliant with IEC 61131-3. Example: In the following SFC code, if the condition ”A” is always true, after several PLC cycles, all stepsare simultaneously active.14/19 January 20th 2012 - Version 1.6.7

PLC programs development guidelines Figure 3.2: indeterministic SFC in multi-token modeO.U.2 - SFC : ”Keep previous steps in active state” should not be AllowedIn the language extensions tab of project settings, the check-box ”SetSteps: keep previous step(s) in active state”shall be deactivated. Comment : This option is only available if the ”Allow multiple token check-box is activated” - see O.U.1.O.U.3 - SFC : ”Parallel branches: allow jump in/out” should not be AllowedIn the language extensions tab of project settings, the check-box ”Parallel branches: allow jump in/out” shall bedeactivated. Comment : This option is only available if the ”Allow multiple token check-box” is activated - see O.U.1.O.U.4 - SFC : Only one evolutions by divergence of sequence selectionIn the language extensions tab of project settings, the check-box ”Allow multiple evolutions by divergence of se-quence selection” shall be deactivated. Comment : This option is only available if the ”Allow multiple token check-box” is activated - see O.U.1.O.U.5 - ST : ”Jump and label” should not be AllowedIn the language extensions tab of project settings, the check-box ”Allow Jump and label” shall be deactivated. Comment : In general, usage of jumps reduces the readability of the code and therefore its maintainability.O.U.6 - Identiﬁers: leading digits in names should not be AllowedIn the language extensions tab of project settings, the check-box ”Allow leading digits” shall be deactivated.January 20th 2012 - Version 1.6.7 15/19

PLC programs development guidelines Comment : In general, usage of leading digits in names reduces the readability and portability of the program.O.U.7 - Identiﬁers: the standard (IEC) character set shall be used in namesIn the language extensions tab of project settings, the check-box ≪standard≫ shall be deactivated. Comment : In general, usage of the non standard (IEC) character set in names , reduces the readability andportability of the program.O.U.8 - Graphical languages (FBD/LD): Usage of ST expressions should not be AllowedIn the language extensions tab of project settings, the check-box ”Usage of ST expressions” shall be deactivated. Comment : In general, usage of ST expressions in FBD reduces the readability of the program.O.U.9 - Upload information: Upload information with comments and animation tablesIn the Build tab of project settings (project generation settings) the following check-boxes shall be activated: 1. ≪ Include ≫ in the Upload information, 2. ≪ Comments (Variables and types) ≫ in the Upload information, 3. ≪ Animation tables ≫ in the Upload informationComment : If the PLC memory allows, the storage of all upload information ensures a smooth restoration of thesource of the project from the PLC, thus improving the long term maintainability (lost backup issues).O.U.10 - Ladder Diagram : Right-justify coilsIn the Editors tab of project settings, the check-box ”Right-justify coils” for Ladder Diagram (LD) shall be acti-vated. Comment : Right-justify coils allow a better readability of the program.16/19 January 20th 2012 - Version 1.6.7

Chapter 4Annexes4.1 Summary of RulesThis annexe summarizes all the rules and useful information contained in this document.Naming rules • N.1 - Non-specific - All elements of the program must be named • N.2 - Non-specific - Elements name length should be in a given range • N.3 - Non-specific - Topological physical address should not be used as part of a mnemonic • N.4 - Non-specific - Testing mnemonics should not be part of the final program • N.5 - Non-specific - Special or graphical characters are prohibited in mnemonics • N.6 - Non-specific - The programming language keywords should not be used as mnemonicsCommenting rules • C.1 - Non-specific - All program elements should have a comment • C.2 - Non-specific - Comments should be longer than a given number of characters • C.3 - Non-specific - Each network should have a comment • C.4 - Non-specific - Comments should not only contain the comment start markerWriting rules • E.1 - Non-specific - All variables should be written before being read • E.2.a, E.2.b - Non-specific - Inputs of the user functional blocks should be read and not written. • E.2.c, E.2.d - Non-specific - Inputs/Outputs of the user functional blocks should be read and written. • E.2.e - Non-specific - Outputs of the user functional blocks should be written before being read. • E.U.1 - SE Unity - The functions of the Unity obsolete libraries should not be used 17/19

PLC programs development guidelinesStructure rules • S.1 - Non-specific - Backward jumps are forbidden • S.2 - Non-specific - A variable should be elaborated only in one routine • S.3 - Non-specific - A variable should be written from one task only • S.4 - Non-specific - A physical output should be written only once per PLC cycle • S.5 - SE Unity - Variable should not be localized • S.6 - Non-specific - DFB/FBs instances should be called once • S.7 - Non-specific - Declared variables should be used • S.8 - Non-specific - Variables location doesn’t overlap • S.9 - Non-specific - Complexity measure • S.10 - Non-specific - SCADA LimitationsInformations Utilities • I.1 - Non-specific - Comments rate • I.2 - Non-specific - Code in the comments • I.3 - Non-specific - Dead code • I.4 - Non-specific - List of locked elements • I.5 - Cyclomatic number v(G) • I.6 - Essential Complexity ev(G) • I.7 - Source Line of Code count • I.8 - SFC steps count • I.9 - SFC branches count • I.10 - Copy/Paste detection ratioOptions • O.U.1 - SE Unity - SFC : ”Multiple Token” should not be Allowed === • O.U.2 - SE Unity - SFC : ”Keep previous steps in active state” should not be Allowed === • O.U.3 - SE Unity - SFC : ”Parallel branches: allow jump in/out” should not be Allowed === • O.U.4 - SE Unity - SFC : Only one evolutions by divergence of sequence selection === • O.U.5 - SE Unity - ST : ”Jump and label” should not be Allowed === • O.U.6 - SE Unity - Identifiers: leading digits in names should not be Allowed === • O.U.7 - SE Unity - Identifiers:Using the standard (IEC) character set in names === • O.U.8 - SE Unity - Graphical languages (FBD/LD): Usage of ST expressions should not be Allowed === • O.U.9 - SE Unity - Upload information: Upload information with comments and animation tables === • O.U.10 - SE Unity - Ladder Diagram : Right-justify coils ===18/19 January 20th 2012 - Version 1.6.7

PLC programs development guidelines4.2 Document history Date Changes 2010 Initial version Jul 12th 2010 Add Options chapter Dec 21th 2011 Add description for rules S5, S6, S7, S8, S9, S10, I5, I6, I7, I8, I9, I10 Nov 9th 2011 Add version number. Texts Corrections. Extend EU1 rule to all functions of the obsolete libraries Nov 21th 2012 Proofreading and corrections (grammar, spelling) by Pauline Jan 20thJanuary 20th 2012 - Version 1.6.7 19/19

[EN] PLC programs development guidelines

by Itris Automation Square on Jan 20, 2012

Accessibility

Categories

Upload Details

Usage Rights

Statistics

[EN] PLC programs development guidelines — Document Transcript