Standardising the pseudocode of design documentation for process control platforms
Even though control systems mostly implement variations of the IEC61131-3 standard, there is no universal standard for pseudocode in design documentation. There is an ISA (S5.6) standard for functional requirements documentation for control software applications specification. The intent of this standard is to specify a control system sufficiently to outline how it is supposed to work, but not how it will actually be implemented on a proprietary target platform.
See the excerpt from the standard below:
The screen grab from S5.6 outlines how the standard proposes that sequential logic be documented. However, the reality of control system specification is somewhat more varied, and in the case of integrating different control systems from different equipment vendors, even more challenging. Three different approaches are outlined below.
Approach 1 : PLC equipment module implemented on a Siemens Step 7 platform
This approach directly references PLC variables and as such, is closer to a software design specification document than a functional specification document. It will be favoured by software engineers (but disliked by process engineers)
Approach 2 : A Phase FDS sample excerpt from a modern DCS transfer out phase
In this approach, there is an attempt to satisfy both the process engineer (with the process actions section) and the software engineer (with the phases actions section). This is a form of company unique pseudocode. Its not easy to see what happening as variables are referenced instead of actual values (For example, ‘message 1’ is defined elsewhere in the document.
Approach 3 : a different approach on the same target platform as approach 2.
In this approach, there is an emphasis on process actions rather than software actions. As a result, it is easier to read for a process engineer (but may make the programming more arduous as the requisite detail is not there). This form of pseudocode is broadly in line with the ISA-S5.6 standard outlined above.
And another sample:
Alternative approach – use a model with its own scripting language
Approximately 50% of the programming is simply setting values, receiving values, disabling or enabling alarms or interlock, prompting the user, writing batch report values etc. We figured that the eminently readable language ‘Python’ would be a good fit for documenting these control system requirements.
We must accept that some level of programming is required in order to specify a control system. Some engineers feel that the best code description is in fact, the code itself. Provided that all variables are sensibly named, there’s no reason why the code cannot form the basis of the design specifications as outlined below. The engineer can then run the code to ensure it is behaving as required, before exporting the functional requirements.
Alternative approach – model based python code (self documenting) export from Spike
Conclusion
Modern pseudocode is not standardised and design documentation and specifications vary vastly in terms of fitness for purpose. Some companies maintain that the design specification should be readable from a process engineering perspective, and platform specific detail should only be housed in specific software design documents. However that means more documents to manage. An alternative approach is to get all design specifications generated automatically from a model in the ‘universal’ pseudocode of Python; a popular easy to learn programming language.
If you are trying to marshal multiple equipment and control system vendors through a common integrated design documentation structure and approach , then a prototype model and python syntax for the design specification is a good place to start.
Python syntax has similarities to the ISA.S5.6 syntax so its not a huge departure (however engineers will need some object oriented basics). Ultimately, better requirements capture results in better software quality. Better software quality means less bugs and thus cheaper project implementations.
See Spike in action or try it yourself, no sign up or login required. .
Terms:
FDS: functional design specification.
PLC: programmable logic controller.