Draft PLC software guidelines May 2022
Donze Expires 19 November 2022 [Page]
Published:
Intended Status:
Standards Track
Expires:
Author:
M.D. Donze, Ed.
CERN

BE-CEM-MRO PLC software coding guidelines

Abstract

This document describes PLC development guidelines and standards to be used in the BE-CEM-MRO section.

Status of This Memo

This document is a CERN Draft.

CERN Drafts are working documents of the CERN community. Note that other groups may also distribute working documents as Drafts.

CERN Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Drafts as reference material or to cite them other than as "work in progress."

This Draft will expire on 19 November 2022.

▲

Table of Contents

1. Introduction

This document describes what technologies MUST be used and how PLC software MUST be architectured in BE-CEM-MRO section. Guidelines in this document MUST be followed by every person developping PLC projects in the section.

1.1. Requirements Notation

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, [RFC2119].

2. Choosing hardware

To keep a small number of spare parts and to avoid mixing technologies, PLC-based projects MUST use Siemens automation hardware everywhere it's possible.

New PLC projects MUST use S7-1500 product family, S7-1200 products MAY also be used if the PLC project is simple and compact.

The PLC CPU SHOULD have a built-in display for on-site diagnostics and configuration.

Fieldbus communication MUST be based on Profinet. Older projects MAY use Profibus communication. Other fieldbuses MAY be used if some components doesn't support standards mentionned above.

3. Development software

New PLC software projects MUST be developed using Siemens TIA-Portal software suite. To avoid migrating projects version, it was choosed to stay at TIA-Portal version 16.

If a new hardware component doesn't support this software version the project SHOULD use a newer version of the TIA portal application.

Older existings projects using Step 7 software suite must be kept with this version until supported on actual operating system.

WinCC MUST be used to develop panels graphical user interfaces but MUST NOT be used for creating expert or piquet interfaces.

VersionDog and Git [git] is also used for code versioning. See the Section 4 chapter.

4. Code versioning workflow

In order to keep track of PLC project modifications during development phase but also during production stage, two code versioning tool MUST be used.

Git [git]MUST be used for storing PLC code changes during development phase. This tool is well-known from all software developers and it's usage is out of this document's scope.

The code repository location MUST be located in MRO PLC Git repository [git_repo], so other developers can review the PLC project.

When the PLC project goes to production phase, the operational PLC project must be stored using VersionDog [cern_versiondog] software.

The MRO PLC Git repository [git_repo] master branch SHOULD match the one stored in VersionDog. If some modifications are required on the PLC project after being deployed in production, the developer MUST create a new Git branch to implement changes. When changes are tested, validated and considered to be put in production, the branch MUST be merged into the master branch and a new version will be created in VersionDog.

5. PLC software coding guidelines

This chapter provides information on PLC coding guidelines.

5.1. PLC objects naming convention

PLC objects and tag names (for function variables see Section 5.4.2) MUST start with a predefined prefix (see bellow) depending on object type, followed by an underscore (_) character and a short exhaustive name written in upper camel case [camel_case] convention (with first letter capitalized). No spaces are allowed in names.

Table 1: PLC objects naming convention
Type Prefix Description
Hardware inputs I Hardware inputs symbols MUST start with the I prefix. There is no distinguish between analog or digital signal types.
Hardware outputs O Hardware outputs symbols MUST start with the O (capital 'o' letter, not zero) prefix. There is no distinguish between analog or digital signal types.
Organization blocks OB Organization blocks MUST start with the OB prefix. For example, a good name for OB1 is OB_Main.
Functions FC Functions MUST start with the FC prefix.
Functions blocks FB Functions blocks MUST start with the FB prefix.
Data blocks DB Data blocks MUST start with the DB prefix. There is no naming difference between instance data-blocks and global data-blocks.

Some examples of valid objects names:

5.2. PLC hardware configuration guidelines

It is RECOMMENDED to properly named PLC hardware objects (modules, deported stations, network segments). Name of these objects must be kept short and in camel case [camel_case] convention. Giving proper names of hardware modules ease the diagnostic and troubleshoting on-site (using the CPU display).

If the PLC is connected to the CERN network, the IP configuration MUST NOT be set in the PLC project. The "IP address is set directly at the device" option MUST be selected as shown in this picture:

Figure 1: Proper IP configuration setting

Using this technique, we can easily apply IP configuration provided by IT in case of PLC relocation. Another positive point of this option is to use a common PLC project for multiple PLC installations.

This requirement MAY be ignored whenever this option is not possible, if a UDP, ISO-on-TCP, ISO-Transport or TCP connection is setup, but such cases SHOULD be validated.

5.3. PLC software architecture guidelines

To keep the PLC project easy to maintain (new features, bug fixes) and to understand by everyone, some rules MUST be followed when creating the software architecture:

5.4. Coding rules

This chapter describes how PLC code MUST be written

5.4.1. PLC programming language

Siemens PLCs can be programmed using different languages (LAD, FDB, STL, GRAPH, SCL). Each programming language has its own advantages, but also drawbacks. Except for the safety part, PLC software MUST be written in the SCL language, for the following reasons:

  • Text based : Text based language allows powerful operations like find/replace, regular expressions, easy comparison. copy/paste in other text-based software (chat, notepad...)
  • Compiled : The SLC compiler provided by Siemens shows good results of optimizing code thus reducing the PLC cycle time.
  • Portability : SCL is a compiled software and can be easily moved from a project to another.
  • Comprehensible : A person without PLC experience but with basic programming knowledge can understand the code.

Unfortunatly Siemens doesn't provide (for technical reasons, not explained here) a SCL compiler for safety program part (safety PLC only). In this case, the safety PLC program MUST be written using the ladder (LAD) software. Siemens made a guideline for safety programming. Document is available here [siemens_safety].

5.4.2. Variables naming convention

Properly naming variables is the key of a readable software. These rules MUST be followed:

  • Name should be short (less than 20 characters) and MUST describe its purpose.
  • lower camel case [camel_case] convention (with first letter lowercase).
  • Spaces MUST NOT be used.
  • Comments metadata must be filled to provide short documentation of variable purpose.

5.4.3. Constants naming convention

Uses of constants in SCL code makes the code more readable and allow easier code modification. These rules MUST be followed:

  • Name SHOULD be short (less than 20 characters) and MUST describe its purpose.
  • Name MUST be in uppercase, using the snake case [snake_case] convention.
  • Comments metadata MUST be filled to provide short documentation of constant purpose.

5.4.4. Functions

Functions code MUST be short and small. It MUST NOT access global data-blocks, mementos or hardware I/O. Input, outputs, inputs/outputs and return value of these functions are the only way to exchange data. All these parameters MUST have a detailled description in the Comment field.

5.4.5. Function blocks

With their associated static data, a FB is close to object programming.

The static data of a FB can host other child instance DB, so a real (and portable) hierarchy is achieved.

Function blocks attributes SHOULD be configured with Optimized block access (this is the case by default). Enabling the Optimized block access attribute disables direct addressing and removes some TIA portal memory optimization. A common usage requiring to disable Optimized block access is to use the AT operator for 'casting' data structures.

The AT operator was used in some old PLC projects to decode bit fields and MUST be replaced by calls to GATHER and/or SCATTER built-in functions.

As for functions (Section 5.4.4), the code inside FB MUST NOT access global data-blocks, mementos or hardware I/O. Static variables can be read/write outside FB scopre, however it is RECOMMENDED to use inputs, inputs/outputs and outputs parameters of the FB.

Each function block SHOULD implement a process functionnality, it MUST also keep track of its own state by making use of its static variables (see Section 5.4.5.1).

5.4.5.1. State machine

To reduce PLC cycle time and avoid unnecessary PLC computations, implementing a state machine for the process is RECOMMENDED.

State machines can easily be implemented in SCL using an int static variable and a CASE statement.

Known states MUST be declared as CONSTANT FB values. By using constants, it's easy to add or remove new states from the state machine without renumbering all steps.

A default (ELSE) statement SHOULD be implemented to fallback to a known state (or to a fault state, depending on project requirements). This special case is useful if the variable is forced to a non-valid value during development and commissioning. Here is a short example of how to implement a state machine in SCL:

FUNCTION_BLOCK "FB_LightControl"
{ S7_Optimized_Access := 'TRUE' }
VERSION : 0.1
  VAR_INPUT
      pushButton : Bool;   // Push button input (True : button pressed)
  END_VAR

  VAR_OUTPUT
      lightRelay : Bool;   // Light relay output
  END_VAR

  VAR
      state : Int;   // State machine
      nbPush : Int;   // Number of push detected
      R_Trig {InstructionName := 'R_TRIG'; LibVersion := '1.0'} : R_TRIG;   // Rising edge detector
  END_VAR

  VAR_TEMP
      risingEdge : Bool;   // Is rising edge detected
  END_VAR

  VAR CONSTANT
      STATE_IDLE : Int := 0;   // Idle state, waits for user input
      STATE_ON : Int := 1;   // On state
      NB_PUSH_ON : Int := 4;   // Number of pushes before switching on
      NB_PUSH_OFF : Int := 2;   // Number of pushes before switching off
  END_VAR

BEGIN
  (*
      Simple state machine example
      It waits for 4 users button press, switch the relay on
      then waits for 2 button presses then switch relay off
  *)
  #R_Trig(CLK:=#pushButton,
          Q=>#risingEdge);

  CASE #state OF
      #STATE_IDLE:
          //Waits for button to be pressed
          IF (#risingEdge = TRUE) THEN
              #nbPush := #nbPush + 1;
              IF (#nbPush >= #NB_PUSH_ON) THEN
                  #lightRelay := TRUE;
                  #nbPush := 0;
                  #state := #STATE_ON;
              END_IF;
          ELSE
              #lightRelay := FALSE;
          END_IF;
      #STATE_ON:
          IF (#risingEdge = TRUE) THEN
              #nbPush := #nbPush + 1;
              IF (#nbPush >= #NB_PUSH_OFF) THEN
                  #nbPush := 0;
                  #lightRelay := FALSE;
                  #state := #STATE_IDLE;
              END_IF;
          END_IF;
      ELSE  // Unhandled state
          #state := #STATE_IDLE;
  END_CASE;

END_FUNCTION_BLOCK
Figure 2: Implementing a state machine in SCL.
5.4.5.2. Timers

With S7-1500 family, timers functions (TP, TON, TOF, TONR) are not anymore linked to a hardware timer number. These functions MUST be used for all timer related operations.

However, on previous CPU generation (S7-300 and S7-400), timers were linked to a timer number, making the code unportable. To avoid this problem, a function block FB_Timer was created in the past.

This function implemented a 0.1s accuracy timer by counting rising edge of a clock memento bit.

This document will not cover the usage and implementation of this function but the PLC developer MUST use this function if he has to develop S7-300 or S7-400 PLC software.

5.5. Code review

Before deploying PLC code to an operational equipment, the PLC implementation MUST be reviewed by section's PLC experts for approval.

This code review exercise is the opportunity to discover potential issues and ensure the code respects standards defined in this document.

The code review goal MUST NOT be to blame the PLC developer, it is a moment to improve common knowledge about PLC technologies, additional reviews and or support MAY be requested to PLC experts (and is welcomed).

6. Contributors

7. References

7.1. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.

7.2. Informative References

7.3. URL References

[camel_case]
Wikipedia, "Camel-case definition", <https://en.wikipedia.org/wiki/Camel_case>.
[cern_versiondog]
CERN, "CERN VersionDog support", <https://readthedocs.web.cern.ch/display/ICKB/VersionDog>.
[git]
Git community, "Git distributed version control system", <https://git-scm.com>.
[git_repo]
CERN, "MRO PLC Git repository", <https://gitlab.cern.ch/mro/controls/plc>.
[siemens_safety]
Siemens, "Siemens safety programming guidelines", <https://assets.new.siemens.com/siemens/assets/api/uuid:1a7ce755-79a1-494e-ae14-5e5f72c29205/safety-programming-guideline-for-simatic-s7-1200-and-1500.pdf>.
[snake_case]
Wikipedia, "Snake-case definition", <https://en.wikipedia.org/wiki/Snake_case>.

Appendix A. Change Log

A list of changes

Appendix B. Open Issues

A list of open issues regarding this document

Author's Address

CERN
Mathieu Donze (editor)
1, Esplanade des Particules
CH-1217 Meyrin
Switzerland