Contents

Engineering stations (ES) are used to develop the PAL software, they are generally high-powered machines with at least 512 GB of hard drive storage and 16 GB of RAM. Typically with a 10^th or 11^th generation i7 processor or equivalent (such as an AMD Ryzen 7).

Engineering stations should be equipped with dual 27" QHD (quad high definition) screens (these have a resolution of 2560 × 1440 pixels).

The configuration of an ES, including drive allocation, device naming, software package installation &c. is explained in the ES/WDP Configuration Manual [Ref. 006].

In summary, it is assumed that the ES has been configured in line with the above document and is equipped as follows:

The ES is equipped with three hard drive partitions (as a minimum):

	C:	OpSys	Operating system and application files
	D:	Projects	PSP project files
	E:	Licences	Storage area for licences &c.

The C: drive (OpSys) holds the operating system and all installed programmes and applications (the Siemens application software and any office applications will be installed on this drive). The C: drive should be at least 200 GB in size.

The D: drive (Projects) holds any Controller, HMI and SCADA projects developed using TIA Portal. This consists of the source code, archives, graphical images, runtime configurations and any other files needed to develop the control system software. The D: drive should fill the remainder of the hard drive, excepting 1 GB that should be reserved for the E: drive. The D: drive should be at least 200 GB in size.

The E: drive (Licences) holds all the licences needed to activate the Siemens TIA Portal software and its installed options.

The E: drive is generally very small, it need only be a few megabytes in size (in practice, a 1 GB partition is more than adequate).

The software applications and configuration below are required on an ES:

1. TIA Portal has been installed

• The TIA Portal settings have been set to the PAL configuration

• The TIA Portal Git add-in has been installed and enabled

2. A GitHub user account has been setup

• The account has been added as a contributor to the PracticalSeries organisation

3. Git SCM has been installed

• Notepad++ is installed as the Git default editor

• An SSH key link has been established between Git and GitHub

4. The Visual Studio Code text editor has been installed

• The standard set of Visual Studio Code extensions have been installed

The packages above are listed in the order in which they should have been installed on the engineering station. The exact details for installing and configuring the above application is given in the ES/WDP Configuration Manual [Ref. 006].

All the Controller software for the PAL is stored on the D: drive (Projects).

	1000 Software Projects	TIA Portal Projects folder
	2500 Git Projects	Git Workspace folder

The underlying structure is:

The software projects folder:

1000 Software Projects

is used to store the individual Controller projects that are opened and developed using TIA Portal. All such projects (within the PAL) are named as follows (see § 3.8):

PS2001-PAL-<commit tag>

The alternate branch on the D: drive is:

2500 Git Projects

This is used to store the Git repository that is used to store the TIA Portal Project Workspace.

These two folders:

	1000 Software Projects	TIA Portal Projects folder
	2500 Git Projects	Git Workspace folder

are examined further in the following sections.

There may be multiple projects under the

1000 Software Projects

Each project is identified by its project number (PSnnnn) followed by the name and some brief description of the project. In the case of the PAL software the project number is (PS2001) and the full project folder is (PS2001-PAL-Build-SW).

The PS2001-PAL-Build-SW folder holds all the TIA projects, these are the projects that can be downloaded via TIA Portal into a Controller.

The entire software development takes place in TIA Portal and is stored as a TIA project locally on the engineering station.

All TIA Projects are stored in the folder 31 SW TIA PAL:

Each TIA Portal project is stored in its own sub-folder under the 31 SW TIA PAL directory. Each project is named according to its commit point (see § 3.8 for information about file names).

An example is shown below:

The interior of a TIA Project folder has the following appearance:

The .ap16 file (highlighted in blue), if clicked would open the project in TIA Portal. The folder structure above is all part of the TIA Project and independent modification of this structure or any files within it may result in the corruption of the project.

The top-level folder of a project (in this case PS2001-PAL-D0003) should be considered to be the TIA Portal Project in its entirety, everything below this level is best left alone.

Figure 5.2 shows an additional folder under the PS2001-PAL-Build-SW directory, this is the 41 TIA PoC folder. This also holds TIA Projects; these are not formally part of the PAL software, they form “proof of concept” projects.

Proof of concept software is used to develop, test or demonstrate that a particular approach works within the PAL prior to that approach being formally adopted within the PAL.

Proof of concept projects can be considered a test bed or prototyping area for software.

The final folder under the PS2001-PAL-Build-SW directory is designated 81 SW Archive; this is used to store “archived” copies of each build of the TIA Project software.

Archived copies of a project are produced by TIA Portal, they are essentially zipped versions of the TIA Project folder with non-essential (or re-buildable) information removed

Archive files are a convenient way of transporting projects (and indeed, each archived copy of the software is available for download from the website, see below).

Project archive files all have the extension .zap16 (and are universally referred to as “zap” files), they are indeed zip files, if the extension were change from .zap16 to .zip, the contents could be extracted by Windows Explorer.

There is an archive file for all commit points (see § 3.8) within the software (both primary and secondary). These are accessible from the website at the following address:

https://practicalseries.com/2001-pal/31-git/81-00-archive.html

The ES stores all its Git repositories in the directory:

2500 Git Projects

Specifically, the PAL repository associated with the Controller software development is the PS2001-pal-software folder:

This folder is a Git repository, this can be seen by the hidden .git folder, this contains all the underlying repository structures required by Git and GitHub to control and manage the folder.

The .git folder is similar to the TIA Project folders, in that, no changes should ever be made directly to anything that is in there. The best thing to do is to never open it or look in it; just leave it alone, it looks after itself.

The remainder of the PS2001-pal-software folder holds the working files for the TIA Portal Workspace.

The top-level folder (CON100) is the Workspace equivalent of the controller in the TIA Project, this is also called CON100 (this is in accordance with the Siemens naming conventions discussed in the Software Design Specification (SDS) [Ref. 003, § 3.1.4])

The Workspace folder contains the XML versions of the TIA Project exportable objects, these objects are also stored in (pre-named) folders:

	Program blocks	Holds the XML versions of Controller blocks: FBs, FCs, OBs and DBs
	PLC tags	Holds any tag tables configured for the Controller
	PLC data types	Holds the User Data Type (UDT) structures

The linkage between the controller and the Workspace folder can be seen below:

The Workspace only holds the programmable objects from the Controller software (there is no hardware configuration, watch tables or traces &c.). It can be seen that each folder and object in the TIA Project (left-hand side) has an equivalent in the Workspace (right-hand side).

It can also be seen that the Workspace also holds some additional files: .gitinore, LICENCE.md and README.md; these are all files associated with the Git repository itself and have no associations within the TIA Project.

These association are explained further in the following section:

A Workspace is just a Windows folder located somewhere on the ES hard drive. It can be any folder and can have any name.

The folder can be created directly through Windows or when being define via TIA Portal.

In TIA Portal terms, a Workspace is simply a folder to which it will export copies of all the following types of objects (if they exist in the Project):

1. Program blocks:

• Organisation blocks (OBs)

• Functions (FCs)

• Function blocks (FBs)

• Data blocks (DBs) of any type including instance DBs

2. User (PLC) data types (referred to here, as UDTs)

3. PLC tag tables (referred to here as just tag tables)

TIA Portal exports them as text files, specifically as XML files.

In addition to this, TIA Portal keeps track of the files it has exported and identifies if differences exist between its internal Project files and those files in the Workspace. If differences do exist, TIA Portal is able to synchronise those files in either direction (it can make the Workspace files match the Project files or, it can make the Project files match the modified Workspace files).

The ES/WDP Configuration Manual [Ref. 006] contains a full description of how to create and link a Workspace to a TIA Portal Project.

Author’s note — How we got here

This isn’t a new concept for Siemens, although it is new to TIA Portal. The forerunner to TIA Portal was a PLC programming package called Simatic Manager (or, more commonly, Step 7), this was used to programme earlier ranges of PLCs called S7-300 and S7-400 (TIA Portal will also programme these PLCs). Simatic Manager had the facility to export (or import) programmable blocks in a readable format, referred to as Source Blocks, all blocks could be converted to Source Blocks and the resulting Source Blocks were all text files that held a version of the software written in a Pascal like language (actually called Structured Control Language or SCL). The Source Files were again very useful, they were text files and so could be stored easily and could also be incorporated in a version control system — they were also readable (by humans). When TIA Portal was introduced and Simatic Manager began to be phased out (you can still get it, but most people use TIA Portal now), the Source Block functions (or any such equivalent) was not included in TIA Portal, and this upset a lot of people — virtually everyone to whom version control was important. Siemens were reminded of their deficiencies by those people, “oh tut deary me” they said, “you seem to have forgotten this” or its Anglo-Saxon equivalent. Siemens have now addressed their shortcomings and have added the required features; the format is different: it exports thing as XML text files (rather than SCL text files), but it can be used in much the same way. I.e. version control systems can read the files and determine any changes that have been made. Siemens refer to the whole thing as part of their “openness” strategy. So, it’s arrived late, but at least it’s here now.

Looking once more at the Workspace in TIA Portal:

The CON100 folder (on the right) has been expanded out to show all the objects within it. On the right, the Program block folder has been opened showing the two blocks present within it. These are the XML equivalents of the blocks beginning OB00001 and FC61000 on the left.

Opening one of the XML files (in this case OB00001), gives something similar to:

The XML files, although not instantly comprehensible, can be read by the human eye and ultimately understood.

Looking once more at Figure 5.8, in the left pane, there are two columns, status and action. The status tells us the state of the object in the TIA Project compared with the state of the object in the Workspace folder. The green dot means the two version are identical (generally, this is the preferred state).

The status can have the following values:

	Symbol	Meaning	Description
		No differences	The compared versions of the object in the project and the Workspace are identical. If at a group level, all lower-level elements are identical in the project and in the Workspace.
		Lower-level differences	One or more lower-level elements are different in the project and the Workspace, open the group to see the affected files.
		Not in workspace	The object is only available in the project
		Project object modified	The compared versions of the object in the project and the Workspace are different. The TIA Portal object has been changed since the last synchronisation operation (Project is newer)
		Workspace object modified	The compared versions of the object in the project and the Workspace are different. The Workspace file has been changed since the last synchronisation operation (Workspace is newer)
		Both modified	The compared versions of the object in the project and the Workspace are different. Both the TIA Portal object and the Workspace file have been changed since the last synchronisation operation
		Not known	The comparison result is not known
	Table 5.1   Status symbols and meaning

The action allows us to do something with the files, the Action field can have the following values:

	Symbol	Meaning	Description
	Blank	Not applicable	Not applicable to this object (usually folders of groups, the folders or group must be expanded to see individual objects)
		No action	No action will be taken (do nothing)
		Export to Workspace	The object will be exported to the Workspace (Workspace object will be made identical to Project object)
		Import to Project	The object will be imported from the Workspace (Project object will be made identical to Workspace object)
	Table 5.2   Action symbols and meaning

If changes have been made to blocks within TIA Portal, these changes will be indicated within the workspace, for the sake of argument, let’s assume that OB00001 and UT38151 have been changed, the Workspace will now have the following appearance:

Point 1 is indicating that a difference exists at a lower level within the Program blocks folder. Point 2 shows that OB1 has been changed in TIA Portal (c.f. Table 5.1); the Project version is newer than the Workspace version (the star is on the left in the symbol). Points 3 and 4 show similar changes for the UT38151 data type.

By using the drop down in the action box next to each modified block, it is possible to select an action individually for each block.

Alternatively, the menu bar at the top of the left window:

allows the action for all the modified blocks to be selected in one go, clicking the icon (Export changes to Workspace) changes the action for the two blocks to . Nothing has happened at this point; the desired action has simple been selected (but not yet implemented).

To make the changes, the Synchronize button must be clicked. This carries out the selected actions on the modified blocks.

• Only complied blocks can be synchronised with the Workspace, if the blocks have not been compiled within TIA Portal, the user will be prompted to compile them as part of the synchronisation process.

Generally, it is better to compile the blocks first and separately to the synchronisation process, this allows any errors to be more easily addressed.

Simatic blocks can be protected in two ways: knowhow protect (an older form of access protection) and write protection (the current form of access protection).

Blocks with knowhow protection cannot be synchronised with the Workspace.

However, blocks with Write Protection can be synchronised; some blocks within the PAL require protection (see theValidation Plan [Ref. 001] Appendices for an explanation), where this is used, the protection will be Write Protection rather than knowhow protection.

In the previous example, the icon (Export changes to Workspace) was used to select the required action, the other symbols are as follows:

	Symbol	Meaning	Description
		Import changes to Project	Import changes from the Workspace to the Project (Workspace has the newer version)
		Export changes to Workspace	Export changes from the Project to the Workspace (Project has newer version)
		Import all	Where an object differs in the Project and Workspace, overwrite the object in the Project with the one from the Workspace (even if the Project holds the newer version)
		Export all	Where an object differs in the Project and Workspace, overwrite the object in the Workspace with the one from the Project (even if the Workspace holds the newer version)
		Discard all actions	Discard any actions that may have been applied (set everything back to “do nothing”)
		Synchronise	Implements the selected action
	Table 5.3   Action toolbar commands

• Actions can only be applied to an object when there is a difference between the object in the Project and the object in the Workspace

The difference between import/export changes and import/export all is subtle. If a block has been changed in the Project (left-hand side) then of the import/export changes buttons only the export changes will work, the import changes will leave the action set at do nothing. The reason for this is that there has been no change to the Workspace object, so you cannot import it.

There has, however, been a change to the Project object so it can be exported as a change.

Conversely, the import all button will work, this allows the modified object in the Project to be overwritten by the unmodified (and older) object in the Workspace. The import/export all buttons will always work on any two objects that are different.

There is a problem (Author: I’m not sure if this is a problem or if it is intentional, it is however peculiar) when creating a new block in TIA Portal (or indeed, creating a new block in the Workspace); if a new block were created in the Project (Block_1 for example, shown below):

The new block (Block_1) is present in the Project Window, but the status and action columns are empty, pressing any of the action buttons or trying to assign an action directly will not work, it won’t do anything.

The reason for this is that the object has not been “linked” to the Workspace. The way to link the object is to drag it from the Project side to the Workspace side (some care is needed; the block must be copied to the correct folder in the Workspace).

Once this is done, the Block_1 status will display the green dot, indicating the two files are synchronised and are the same.

(Author: It would seem better to me if the new block were treated as a modified block and it automatically gave the Project object modified status and it could just be synchronised, rather than having to actually drag it to a specific folder in the Workspace.)

Section 5.2.3 established that the Workspace was also a local Git repository; this means that when files are synchronised between the Project and the Workspace, any changes are logged by the Git VCS. At some point, these changes will be committed to the repository and permanently stored there. At the same time an archive copy of the TIA Project will also be made (see § 5.2.6).

The Workspace is configured using the Siemens Git add-in, this is installed and activated using TIA Portal (again the instructions for doing this are given in the ES/WDP Configuration Manual [Ref. 006]). The Git add-in has very limited functionality compared with the Visual Studio Code functionality and is not actually used directly to maintain the Workspace repository. It is installed purely, so that TIA Portal recognises the Workspace is a repository and hides the .git folder, preventing it from being visible and from being inadvertently modified.

The Workspace is maintained from within TIA Portal, all changes made to the software are synchronised with the Workspace in the manner described in § 5.2.4.

The repository aspect of the Workspace is maintained via the Visual Studio Code arrangement (again the instructions for installing Visual Studio Code are given in the ES/WDP Configuration Manual [Ref. 006]). The Visual Studio Code text editor provides a graphical user interface to the Git repository allowing development branches to be created and used with the Workspace.

All repository actions are carried out using the Visual Studio Code application. This includes committing changes to the local repository, creating and managing development branches and the bidirectional synchronisation of the local repository with the remote GitHub repository.

Whenever a commit is made to the repository, the TIA Project is saved and archived at that point, the archived version of the software is given the name:

PS2001-PAL-<commit tag>

The commit tag being the identifying tag given to the commit point (see § 3.8)

The archived copy of the software is stored in the Project folder

D:/1000 Software Projects/PS2001-PAL-Build-SW/81 SW Archive/31 TIA PAL Archive

All commit points (both primary and secondary, see § 3.2 and § 3.4) are stored as archive (.zap16) files in this directory.

There can be any number of engineering stations (ESs), generally, each software development engineer will have one.

There is however, only one Master Engineering Station (MES), this is usually the engineering station given to the lead software engineer on the Project.

All ESs have a local repository (the Workspace) and are constantly being synchronised with the remote repository on the GitHub servers, whenever a commit is made to a local repository, on any ES, that ES must first be synchronised with the remote repository (ensuring that any changes made by the local commit do not create a conflict with the any other changes that have been stored within the remote repository).

The remote repository is essentially, the master repository and it is this repository that holds all the commits made by any ES.

The GitHub servers are a third party facility (ultimately owned by Microsoft), and while they are considered secure by the Practical Series of Publications, it is felt that GitHub cannot be the sole storage location for the master repository (Microsoft may, for example, close down the site, make it prohibitively expensive, or indeed may sell it to some other party that the Practical Series of Publications does not trust).

To this end, the Master Engineering Station, each time it is synchronised with the master repository on GitHub, makes a complete copy of the repository on the PSP network accessible storage (NAS) drives.

The MES should be synchronised at least once a week with the remote repository.

This is done purely as an additional backup, the PSP does not think that the GitHub website will change dramatically in the future, or be sold to the Russians — however, there is the old engineering maxim: “better to not need a backup you have, rather than need a backup that you do not have”, or to put it another way “better safe than sorry”.

The Master ES repository backup mechanism is slightly convoluted. This is because the Git repositories, and in particular the .git folder with the repository are managed (ultimately) by the Git application and this is by-and-large, a Unix based application; and while this is not a problem and the application runs perfectly well on a Windows machine, some of the filenames it uses have a Unix feel to them.

An example being the .git folder itself. To some extent, Windows, and certainly some Windows application do not like files that start with a full stop, they expect there to be something before the full stop and everything after it is the extension (.pdf or .jpeg for example).

This is a problem with the PSP NAS drives, these NAS drives are all supplied by Synolgy (this is the PSP standard for NAS drives).

Synology NAS drives are all equipped with an application called Cloud Station Drive and this allows any folder on any PC to by synchronised in real time with any corresponding folder on the NAS drive itself. The link, once created, automatically keeps the folders in sync whilever the machine is connected to the internet. It is exceptionally easy to use and just works.

The problem with this arrangement is that certain files are not synchronised (temporary files for example or files with particular extensions) and this is the problem with the .git folder, Cloud Station Drive ignores certain files that Git considers essential and this leads to a corrupted copy of the repository on the NAS drive.

To overcome this problem, a slightly different approach is taken. On the Master ES, the 2500 Git Project folder is, itself, stored within a live Dropbox folder:

The Dropbox account (in this instance) is the PSP Dropbox account, this synchronises the entire 2500 Git Projects folder and all its content with the Dropbox cloud servers.

Synology NAS drives are equipped with a Cloud Sync package that allows a folder within a Dropbox account to synchronise with a partner folder on the NAS drive. In this case it is setup as follows:

The Local Path, point 1, is a directory on the Synology NAS drive, the Remote Path, point 2 is the Dropbox folder. It is possible to synchronise individual folders within the 2500 Git Projects folder if required.

This process does not suffer from the restrictions of the Cloud Station Drive application and will correctly synchronise all files within the repository without exception.

	Account Manager	Michael Gledhill
	Account Details	PSP Dropbox
	Contact Details	mg@practicalseries.com
	Table 5.4   PSP Dropbox account manager details

All ESs work with a remote repository that contains the current copy of all committed changes made on any of the ES machines. The remote repository is the master repository, it holds all the development branches (created by any ES) and the most up to date master branch.

Any development work that takes place on a development branch on an ES, will at some point be committed to the local repository (on the ES), before this can happen, the Visual Studio Code application making the commit will require that any changes that exist within the remote repository, but are not present on the local ES (i.e. changes that have been made by other users on other ESs) are pulled from the remote repository, before the local ES changes can be pushed back to the remote repository. This Pull before Push approach ensures that the user must resolve any conflicts between the user’s local repository on the local ES and the remote repository before pushing the resolved changes back to the remote.

There is an explanation of this process (and indeed the whole, Git and GitHub approach to version control) on the PracticalSeries website at the following address:

https://practicalseries.com/1002-vcs/08-00-remotes.html

To use the remote repository from a local ES, the two must be linked via a secure shell key link (SSH link), the process for doing this is explained in the ES/WDP Configuration Manual [Ref. 006], and again, on the website here:

https://www.practicalseries.com/1002-vcs/04-00-linking.html

To make this link, the user of the ES must have their own GitHub account and this account must be given contributor access to the remote PSP repository.

The remote repository is public repository (one that anyone with a GitHub account can read and copy) and is part of the GitHub PracticalSeries organisation. The organisation is available here:

https://github.com/practicalseries

The remote repository itself is available here:

https://github.com/practicalseries/PS2001-pal-software

Read access to the organisation and all of the repositories it contains, is available to anyone with a GitHub account.

Access for contributors requires permission from the organisation owner, applications for such access should be made to:

	GitHub Organisation:	https://github.com/practicalseries
	Repository Name:	PS2001-pal-software
	Organisation Owner:	Michael Gledhill
	Contact Details	mg@practicalseries.com
	Table 5.5   PracticalSeries GitHub organisation details

At the time of writing, the remote repository was in a preliminary state and had the following appearance: