How to Design and Create Standard Software Modules

The end result is a standard software module that can be stored in a version control system and used across many projects to improve software quality and increase engineering efficiency.

In this part of the series, I will take you through the process for creating a technical design for a single standard module – the Photoelectric Cell Control Module identified previously. Them, we will use this technical design as a basis for implementing the software module.

In the last part of the series, I showed how OEMs can analyze their machines to identify standard modules. I also described how OEMs can define requirements for the standard modules which are inputs for the technical design. You can find that part of the series here .

Software Standardization for OEMs is a series of articles that explains, in a step-by-step way, how OEMs can standardize their automation software.

Advantages of Standardized Modules

The key advantages of using standardized modules are that standardized modules ensure high software quality and reduce engineering effort for OEMs. Let’s look at each of these advantages in detail.

Software Quality

Despite best intentions, new software tends to be buggy. There are always edge situations that developers didn’t think of and physical behavior that is different to what’s observed in test environments.

For this reason, creating new software is risky and OEMs should try to leverage proven, tested software as often as possible.

Standard modules allow OEMs to reuse software across many projects while continuously improving the functionality of those modules. Bug fixes deployed on one project are captured and shared across all projects in the form of a new version of the module. Since every project is using and improving the same module, the quality of the module improves over time.

Engineering Effort

Standard modules reduce engineering effort by improving the reusability of software. This makes sense – every standard module in your company’s software library is a module that an engineer doesn’t have to develop from scratch.

By reusing software, you can reduce the effort involved in realizing projects and free up engineers to focus on what they do best – solving hard engineering problems, not copy pasting code from on project to the next.

Requirements of the Module

In the last part of the series, we defined the following requirements for a Photoelectric Cell Control Module, hereby known as CM_PEC:

Functional Requirements

• The Control Module must read the input of a physical Photoelectric Cell
• The Control Module must detect when a Photoelectric Cell is flickering (almost out of alignment, dirt build-up, obstruction on the belt)
• The Control Module must detect when the Photo Electric Cell is damaged and report the error
• The Control Module must have a configurable on and off delay

Non-functional Requirements

• The Control Module must not add more than 2 microseconds to the scan time when called

Technical Design Process Overview

The requirements for a module define what a module has to do. The technical design describes how a module will achieve that functionality.

One very important aspect of the technical design of a software module is the interfaces available for the module. The interface design is particularly important since it affects how easily the module can interact with other modules and how easily the module can be configured with settings. This means that the interface design directly affects how easily the software module can be integrated in a project and therefore, how easily a module can be reused across multiple projects.

In the rest of this section, we’ll take a step by step approach to implementing the technical design for the Photoelectric Cell Control Module.

Interface Design

The interface of a module defines how a module can exchange data with other modules in a project. The exchange of data should always be made via the interfaces.

When designing the interface of a module, you must find a balance. Interfaces should be compact to ensure ease of use but also flexible enough to allow the module to be used in many different circumstances and projects.

I recommend that you pass related information to the module via UDTs. The use of UDTs helps to prevent users of the modules from connecting incorrect parameters to the module and simplifies the process of parameterizing a module.

When designing the interface for a software module, you should ask:

• Which modules exchange data with this module?
• What data is exchanged?

I believe that a good interface for a Photoelectric Cell module includes the following parameters:

• Input of photoelectric cell, i_HW_PEC. This is the input signal of the photoelectric cell.
• Input of IO Available, i_IO_Available. This input is used for error suppression in the module.
• Input of reset command, i_CMD_Reset. This input is used to reset error conditions in the module.
• Input of displacement, i_Cnv_Displacement. This input is used for filtering and error detection.
• Output of PEC Latch, o_PEC_Latch. This output is the filtered photoelectric cell signal to be used in the PLC program.
• Input Output of Settings, io_Settings. This is a UDT which contains the settings for the module.
• Input Output of Status, io_Status. This is a UDT which contains the status for the modules to be used by the visualization.

Note that the structure of the parameters and the naming of parameters should be largely governed by your company style guide. The style guide defines rules for naming parameters and for commenting parameters.

Here, input output parameters are selected for exchanged structured data at the module interface. This type of parameter is chosen for performance reasons since input output parameters are passed by reference and not by value in the PLC program. Again, the use of input output parameters should be governed by your company style guide.

When implemented in the software, the interface for this block looks as follows:

Module Interface

In the early stage of design, the temporary and static members of the function block are not defined. These members will be implemented when we define the data storage strategy of the module in the next step of the technical design.

Data Storage

The data storage strategy of a module defines what data the module stores and how it stores it.

The best practices for data storage focus on storing data that is used throughout the PLC program in global locations. Data that is only used inside the module, such as current values of timers, should be stored in the internal memory of the module.

When designing a data storage strategy, you should think carefully about which variables should be temporary and which should be static. Static variables use more memory but are accessible externally for monitoring or tracing.

For our Photoelectric Cell module, the following data storage strategy is chosen:

• Settings need to be accessed by the user and are stored in a global DB.
• Status needs to be accessed by the visualization and are stored in a global DB 
• Counters for the on/off filter, flicker detection, and blockage detection are stored internally in the module as static variables
• Results of counters are stored in temporary variables

Based on this data storage design, the interface of the function block can be extended to include variables for storing data:

Module Interface, extended based on data storage design

The interface may be extended with additional signals during later phases of the design, but this extended interface represents the required signals that are identified at this stage.

Operation

The operation design defines how a module fulfils the functionality set out in the requirements.

The operation design should include descriptions of how operators and other modules interact with this module. For example, how are error conditions reset and when can error conditions be reset?

The operation design should describe how the module is programmed and why it is programmed that way. Basically, this section of the design documents the decisions that are made in the programming of the module.

For example, our functional requirements mention that the module must detect when the Photocell is damaged and report the error condition. To fulfil this requirement, we may use a normally closed Photocell and report an error if the Photocell is blocked for a long period of time.

However, the Photocell may be covered for a long period of time if a unit is stopped on the conveyor belt due to a downstream issue. Therefore, reporting errors based on time can create some false positive situations.

A better solution is to report an error when the Photocell is blocked for a certain distance that the conveyor moves through. This operation design helps to avoid the false positives mentioned above.

In the operation design, it would be mentioned that the module takes the displacement of the conveyor into the module via the interface and uses this displacement to determine the distance that the Photocell has been covered for. When the distance exceeds a certain threshold, then an error condition is created. The operation design would also describe why displacement is chosen over time.

Every decision made in the design of the software for the module should be described in the operation design.

In our example, the blockage detection of the module is programmed as follows, based on the decisions described in the technical design:

PEC Blockage Detection

Documentation

The documentation for a module falls into two broad categories – internal documentation and external documentation.

Internal documentation is the documentation that is distributed with the module. Typically, this will include a version number, a description of the functionality of the module, and a revision history of the module. This internal documentation allows a user to quickly figure out how to use a module and to understand what changes have been made to the module since it was originally created.

In our example, the internal documentation is stored in the header of the Function Block CM_PEC:

Internal Documentation

External documentation is a more comprehensive document that explains the design decisions for the module in detail. This external documentation should capture all of the previous topics that we have discussed and should be kept up to date to enable future extension and maintenance of software modules.