Contents

This is the online version of the software control mechanism (SCM) that dictates the revision and version control strategies used to develop the PAL software. This software included both the Controller based software modules that are the main products of the PAL and also the website pages (and associated files) that accompany the software.

This and the following pages explain how the software and website are managed within the Git and GitHub version control systems, how the various revisions are numbered in a meaningful (and human readable) format and how the whole workflow is managed.

These pages also explain storage mechanism for all software, website files and project documentation generate by the PAL.

This document is the Software Control Mechanism (SCM) and is applicable to all Simatic Controller software developed for the Practical Series Automation Library of software modules (the PAL).

The Practical Series Automation Library (PAL) is a library of software modules and templates that have been made available for the Siemens Simatic S7-1500 range of controllers (and to a lesser extent the S7-1200 range).

The PAL software is configured and deployed using the Siemens Simatic TIA Portal programming environment.

The library is freely available under the MIT Open Source licence.

This document, the Software Control Mechanism, has been produced by Michael Gledhill, under his authority as the lead engineer of the Practical Series Automation Library of software modules project.

There are two principal requirements for the PAL Software Control Mechanism:

1. Establish a mechanism for numbering and storing the various software module versions throughout the development, test and qualification phases of the Project

2. Establish a mechanism for the storage and tracking of software module revisions within a formal Version Control System (VCS)

Expanding on these subjects:

The Validation Plan (VP) [Ref. 001] , established that software version control was a necessary requirement for the project and that all software modules within the Project must have individual revision and status information that covers all phases of the software development:

• Software development (system build)

• Testing (at both a modular and integrated level)

• Qualification

• Release for use

The revision system must also be applicable to the TIA Projects as a whole (rather than just the individual modules within the projects); to clarify, the software modules do not exist within their own right, each software module is stored in TIA Portal project that expands as each new software module is developed.

These TIA Portal projects are backed up and multiple revisions may be in used at the same time, all of these TIA Projects must also be part of the Software Control Mechanism (SCM).

A version control system (VCS) is a mechanism for recording changes made to any files within a software project. It records all the changes, what files were affected by each change and a reason explaining why those changes were made. It also records who made the change and the time and date of the change.

The VCS keeps a record of every change made within the project and allows any file that has been modified to be reverted back to a previous state. It means that if a software module is changed, the original module can always be recovered by the VCS.

Version control systems generally have other facilities too, they are able to show the differences between two different versions of the software (even down to lines within a file), they allow multiple people to work on the project at the same time—even to work on the same file at the same time, and they provide mechanisms for resolving conflicts (where two different people have modified the same section of a file).

Version control systems can be applied to any kind of project; it can be a website, a documentation project, a software application, engineering control system—anything at all, as long as it’s a collection of files that can be stored on computer.

The version control system does not itself edit or modify any of the files within the project; it simply records the changes and, where it recognises a file type, is able to display those changes that have occurred to it.

The version control system does not care what software application is used to modify files within the project, it can be anything: text editor, word processor, file manager, graphics editor, specialist programming application &c. It cares only, that a file under its control has been modified and why the modification was made.

Version control systems simply record any change made within a collection of files (the project), who made it, when it was made and the reason why. That is all.

A VCS could be applied to TIA Portal projects, these are stored as archived files (essentially zip files); however, these types of files are proprietary and are not directly accessible to the VCS. The VCS could, under these conditions, store each archived file, it would not, however, be able to access the internal components of the file to determine what changes have been made to any particular part of it (i.e. it could not identify a particular change to a particular module).

With the advent of TIA Portal V16 , Siemens introduced the concept of Workspaces, these are environments (essentially, just Windows folders) into which the programmable aspects of a TIA Project (blocks, data types and tags) can be exported (or imported) as XML^†1 files.

This is a new concept, previous versions of TIA Portal did not offer the facility of exporting software modules in a widely accessible (text based) format, the software could only be read by the proprietary TIA Portal package itself.

The benefit of this new Workspace facility is that the exported files are stored as XML files, and XML files are an ideal format for version control systems (VCSs), version control systems can read every aspect of an XML file and identify any changes that have been made, and, just as importantly, keep track of all these changes. Additionally, each block, data type and tag table is exported as its own XML file and as such allows the tracking of each individual element within the software library. It would for example, be possible to identify all the changes made to a particular Function (e.g. FC01001) and determine at which point in the revision history each change was made.

This was the purpose of Siemens adding this Workspace facility to TIA Portal, it allows proper version control of the software being developed in a TIA Portal project. It also does not require a proprietary Siemens VCS, any and all VCS systems can track text-based files (it is fundamentally, what they were designed to do).

To make things easier, Siemens also allow third-party “add-ins” to be created that can interface with these new Workspaces. One such add-in (created by Siemens) provides an interface to the version control system Git and its online partner GitHub.

The Git add-in allows TIA Portal to interface with a Git controlled Workspace, Git also supports various graphical user interfaces, in particular, Git can be controlled and managed from within the Visual Studio Code (VSC) text editor, VSC is widely used within the PSP and will be the preferred solution for providing a VCS interface for the PAL software.

This document is applicable to all software modules developed as part of the PAL, it explains the mechanisms used to document and control the different versions of each software module as it progresses through the various project phases. It also details the Git version control system and its application within the Project to track all software changes and provide regression mechanisms to access earlier software versions.

Broadly, this document covers the following:

1. Software revision numbering system

• Software development (system build)

• Testing

• Deployment (commissioning) & Qualification

• Release

2. Git Version Control System

• Purpose of

• A tracking and development philosophy

3. GitHub Online repository

• Purpose

• Accessing and control

This document is an ancillary document for the Project, the ownership of the document (those whom control it and are able to modify it), its status within the Project and its relationship to all other primary documents are important factors and are explained below:

This document has been produced, and is controlled and maintained by the Practical Series of Publications (PSP).

This document and all the documents that it references are subject to the change control management procedures for this project.

This document is an internal PSP document and is not a deliverable item under the terms of the project.

This document expands on the software revision tracking and control and revision numbering mechanisms discussed in the Functional Specification (FS) [Ref. 002, § 4.5] and the Software Design Specification (SDS) [Ref. 003, § 5.2.4].

Its place in the document structure for the Project is shown in Figure 1.1.