PLC From Draft to Software - 04
- Paulo Ricardo Siqueira Soares
- Sep 2
- 4 min read
What Are User Requirements and How to Apply Them with PLCs?
User requirements describe functional and non-functional requirements in a way that is understandable to the system’s users. In other words, they are written in a non-formal style—sometimes even including hand-drawn sketches or short notes—since users typically do not have technical knowledge. In summary, they describe the external behavior of the system and outline characteristics of the system design.
Example in documents:
“- When I press the start button, the operator light changes from green to red, the clamps close, and the table turns.”
Notice that this kind of statement can be confusing:
If you have more than one signal tower, which one changes state? Both?
Is there a sequence for loading parts?
Is there an order for the clamps to close?- Does the table only have two positions?
User requirements naturally raise questions, and that’s normal. But they capture the user’s expectations.
In an ideal world, the project owner would refine these requirements, transforming these small “user stories” into software requirements written in a more formal language, including screen prototypes, and so on.
In IT, we have the role of the requirements analyst to perform this type of description. Unfortunately, in industrial automation, we are still crawling in this area. And in most cases, the programmer—that’s right, my friend!—is the one who, besides developing the software, must also run after the requirements.
But we’ll see that some tools used in automation projects can (and should) help refine requirements.
Great, now we know what user requirements are. But how do we apply them to our software?
How do we transform a user requirement into a functional part of the software?
First step: Separate the requirements.
What do you mean???
Inside a single user sentence, we can often find multiple requirements!
Example:“- When I press the start button, the operator light changes from green to red, the clamps close, and the table turns.”
User Requirement ID | Description | Details |
001 | Operator guidance light | The operator guidance light changes state after the Start button is pressed, turning from green to red. |
002 | Close clamps | The clamps close after the Start button is pressed and the guidance light turns red. |
003 | Table rotates | The table rotates after the Start button is pressed and the clamps are closed. |
Notice that in this division, there hasn’t yet been refinement. However, once all requirements are identified, we can begin refining them, which leads to the creation of use cases, test cases, and other documentation—in other words, documentation that will actually be used in development.
How would this refinement look?
Some project documents themselves can help. Take Requirement 001 – Operator Guidance Light as an example.
How many operator guidance lights are there?
→ The electrical design may answer this, followed by standard company operation and safety documents (if available), company software standards (if available), or regulations such as NR12 (Brazilian Machinery Safety Regulation) or OSHA, which addresses signaling.
What type of signaling? Signal tower or dome light LED that changes color?
→ The electrical design will answer this. (If you don’t know what a dome light is, just Google it—you’ll find lots of images 😉).
Does the lamp change state, or must it wait for another action?
→ A process diagram or cycle diagram may answer this, and they can be complemented with operational documents or company programming standards (if available).
Additionally, brainstorming sessions and conversations with the people who wrote the user requirements can help clarify doubts. (We discussed this in the previous article: https://www.plcengsoft.com/post/plc-to-draft-03)
User Requirement ID | Description | Details | Refinement |
001 | Operator guidance light | The operator guidance light changes state after the Start button is pressed, turning from green to red. | Dome Light type. Automatically, after the operator presses the Start button, its state changes from green to red according to the company's operating documentation. This means the operator is prohibited from entering the loading area. The outputs to be used for the lamp can be found on page 20 of the electrical diagram ELX-2020. |
The above is just a small example of how a quick refinement could be performed before formalization.
Once requirements are separated into functional and non-functional (which we’ll discuss later), a formal document can be created. For example, functional requirements can be organized as follows:
[FR 01] – Requirement Name
Module: {Module to which it belongs}
Date: 04/08/2019
Revision: 04/08/2019
Author: {Person responsible for revision}
Original Author: {Creator of the first version}
Priority: {Priority to help with task sequencing}
Description: {Detailed description of the requirement}
Another way to describe a user requirement is through user stories, a format widely used when applying agile methods, but which can be adopted in any methodology.
Documents that can assist in identifying and clarifying requirements:
Simulations
Screens from previous projects
Prototyping
Videos and photos of previous projects
Lessons learned documentation
Client and/or integrator programming standards
Everything we’ve discussed here is a quick introduction. Requirement gathering and analysis is a complex and in-depth process, and it is definitely worth studying.
Remember: the operator will be the one running the system, not you!
A significant mistake in writing requirements is failing to put yourself in the operator’s shoes—the one who will be dealing with the machine. Even worse is not validating with the client’s operations team about the difficulties they face today. Although not always possible, this should ideally be considered and planned by project management.
What may seem intuitive and straightforward to you might not be so for the operator. The same goes for the code—most likely, you won’t be the one maintaining it later! Someone else will. That’s why it’s critical to:
Develop consistent software that is maintainable by others, not just by you.
Apply good programming practices and clean code principles, and create coherent documentation for the software.
Keep in mind that the operator is the end user, not you. Consult with operations during development, take current issues into account, and provide a clear and easy-to-understand operating manual.
See you in the next article!
References:
https://www.devmedia.com.br/artigo-engenharia-de-software-introducao-a-engenharia-de-requisitos/8034
https://www.devmedia.com.br/introducao-a-engenharia-de-requisitos/29454
https://www.devmedia.com.br/artigo-engenharia-de-software-alguns-fundamentos-da-engenharia-de-software/8029
Análise e gestão de requisitos de software: Onde nascem os sistemas - Felipe Nery Rodrigues Machado – ISBN: 978-8536516066 – Editora ÉricaIEEE 610.12-1990 – IEEE Standard Glossary of Software Engineering
https://capeprojectmanagement.com/blog/
Comments