EMCS and ENC_LIC Software Management
- Gary Foster
- Karl Newman
Intent
Machine control programs are very complicated, expensive and fragile. Prototype (single instance) and new control systems are quite often continuously improved and upgraded.
Multiple people will modify these PLC programs. Multiple changes might be done concurrently. Communication might be imperfect. Procedures might not be perfectly followed. Copies of the program can be mishandled and become different from the program running in the machine.
To avoid catastrophic loss of our PLC programs we save the program in the controller in a well defined manner. If the worst happens: we always have a valid and accessible fallback.
PLC allows inspection, modification and upload of the control software while online.
Except in rare specific circumstances, the program in the PLC is known to be working code. If this is not the case, then a plan should be made to replace the defective program with known working code.
Downloading a program to the PLC adds a risk of making unknown changes to the current program. Avoid downloading to the PLC except when absolutely required.
Controlled PLC Programs
Controlled Program | Repository location |
EMCS.ACD | |
ENCLIC_GLX.ACD | |
EMCS_HMI_PENDANT.prx |
Definitions
Device | PLC that uses programmable logic. Devices referenced in this document are PLC processors and HMI handheld pendant. |
Program | AKA code, application, source code The control logic, memory and parameters running in a Device. |
Master | The running code in the Device that you make changes.
Software definition for published software is that the Master is the controlled source code from which all copies are made. It is the program we start with when making changes. PLC prototype world (the one we live in) is different from other software environments. We have, and will only ever have, one installation of each program. It is our running code. There is one instance. It exists on the Target Device. |
Controlled Copy | For PLC programs: The Controlled Program uploaded and saved in the appropriate git folder. It is our preferred Backup.
For HMI program: The source code that was downloaded into the HMI and saved in the appropriate git folder. It is our preferred Backup. |
Uncontrolled Copy | All other copies of the program. These are usually For Reference Only. |
Working Copy | Any copy of the program that has been modified while not online with the Device. Working copies should be uniquely named to avoid misidentification as a Controlled Copy or git-copy Uncontrolled Copy. |
git folder | The folder containing the Controlled Copy. It is created on your computer during installation of git. Do not save working programs in git. |
git_copy folder | The DropBox folder for uncontrolled copies that have been directly uploaded from the Device. This folder is available for use by anyone. It is not required to use this folder. It is a history of the running code on the date saved. This is useful when the Controlled Copy is not updated during the course of a code change. Do not modify programs in git_copy. Do not save working programs in git-copy. |
upload | Transfer a program from the device to the editor. |
download | Transfer a program from the editor to the Device |
Verify | Confirm that the code change is according to the specification. |
Validate | Confirm that the code change operates according to the specification. |
Safety Signature |
|
Prerequisites
Required
git program installed
git folder on your computer
RS Logix 5000, V20.xx
Recommended
git_copy folder on your computer
git extensions or other git GUI
Hardware using Controlled Software
EMCS and ECS PLC hardware
ControlLogix PLC hardware is a quasi-real-time automation controller. It includes control logic and memory. It is intended for 24 / 7 operation and modification while running in continuous operation.
A quirk of RS Studio 20.xx and earlier
Source code (executable code) is downloaded and uploaded to the processor. This is Controlled Software.
Rung and Tag comments are stored and saved only in the file that is open on the editor. This is very convenient and desirable to the programmer, but is not necessary for execution and is not controlled software.
Starting with a Controlled Copy will include all current comments…
Comments can be exported from one program and imported into another program.
HMI Pendant
HMI Pendant is a handheld graphic HMI used for basic enclosure display and functions.
Program logic can be uploaded from the device. However, this HMI is not critical. Updates can be done by modifying a known working copy and downloading to the device.
File copy locations
git
git_copy ttps://www.dropbox.com/sh/cysdn1s3utzbu2x/AAA7foFluN3qBq2pBa5U9hiwa?dl=0
Design & specification for program changes
Justification, specification, review, progress for code changes is typically done via Jira.
The specification should be suitable for use as a basis for Verification and Validation.
Small changes and emergency fixes are managed as required by the circumstance..
Changing code in the processor
Except in unusual cases, make changes to the PLC online.
Small changes
Change code in the PLC while online
Larger changes
Upload or copy the Controlled Copy. Rename it as a Working Copy.
Make changes to the Working Copy.
Transcribe or copy/paste changes from the Working Copy to the Device while online.
Connecting to a Rockwell PLC:
(Recommended) Copy the Controlled Program from the git folder to a new filename and location of your choosing. Starting with the Controlled Copy helps ensure that all comments (not stored in the processor) are current and are carried forward.
Open the uncontrolled copy of the Controlled Program.
Click to go Online
If you see a popup asking to upload or download or a popup that indicates “Program is changed” this indicates that the processor does not match the Controlled Copy.
DO NOT DOWNLOAD TO THE PROCESSOR
Upload will load the processor (Master) into your current uncontrolled copy.
While online, save the program to a new unique filename.
Make your code changes while connected with this file.
DO NOT MODIFY THE FILE IN THE GIT FOLDER. This is your ultimate Undo option.
Modifying the Program
Except in very rare cases, the proper source code to begin modification of the Controlled Programs is the Master code running in the processor.
Modifying the Program offline:
If you plan to work offline:
Begin with a copy of the running program.
Connect to the processor (The Master).
Save the upload with a unique filename (other than the git filename).
Feel free to modify the existing PLC code.
This is an uncontrolled copy, For Reference.
Recommended: A filename distinctive to you and the modification purpose
DO NOT DOWNLOAD THIS FILE TO THE PROCESSOR.
Use your Reference Copy as a guide to Modify PLC code online.
Modifying the Program online
Rockwell makes it easy to avoid stepping on existing code while modifying the program online.
(Option) Create a new PLC routine. Copy code to the new routine and run it instead of the original. You can easily switch between modified code and original code
(Option) For minor changes, add parallels around code changes, enabled by a temporary ‘test bit’
Enter your code changes by editing online or,
To enter code that you modified off-line:
Open the Reference Only copy of the program that you modified earlier.
Transcribe or copy / paste modified code from offline copy to online copy (Master).
Save the Program during code change
DO NOT SAVE TO THE CONTROLLED FILE IN THE GIT FOLDER N OR TO AN EXISTING TIMESTAMPED UNCONTROLLED FILE.
Save your intermediate code to a unique filename and location,
The git backup should remain intact. The program can be recovered from the git file.
Your work is at risk. Do not put an existing backup at risk.
There is no penalty for too many backups. These are Uncontrolled Copies. If changes are extensive, feel free to save the program as your comfort level indicates.
Unique filenames are a good idea. You can serially undo rabbit holes, or recover an earlier iteration.
git_copy is a good place to save intermediate code at end of day (The Daily Save).
Managing Safety Signature
Inform and coordinate with Technical Management prior to breaking or setting a Safety Signature
…..
Installation and Testing
Install code only after review.
Test changes sequentially. Do not make multiple changes to the Controlled Application
Validation
Test to specification / design intent defined elsewhere
Closeout, cleanup
Check for
Unused tags
Dead code
Test code / tags deleted
Set a Safety Signature - if required.
When all work is complete
Save the program to the git folder with the original filename (Controlled Copy).
Notify the Gatekeeper.
Download Program to the processor
Download to the processor should be a very rare event.
Before downloading to the processor:
Confirm that the source is a Controlled Copy.
If it is necessary to download an Uncontrolled Copy, make everyone aware of the situation and the risk.
Open the source program file
Connect to the processor.
Ensure that it is safe to stop the processor.
Inform everyone that the PLC will stop.
Click to download to the processor.
Processor will Halt.
Program will download.
Processor will Run. If not, then change processor mode to Run
Update the Controlled Copy
Clear the ‘Read Only’ file attribute on the Controlled Copy.
Open the Controlled Copy.
Go online with the processor
Upload the Controlled Program into the Controlled Copy.
Save the Controlled Copy to the git folder.
Exit RSLogix.
Set the ‘Read Only’ file attribute on the Controlled Copy.
Update git_copy
Avoid saving known buggy or untested code into git_copy.
At end of day, or other suitable breakpoint,
Program Source Code Control
Normally, the Gatekeeper will monitor the controlled programs and update as changes occur.
You are welcome to participate. Otherwise inform the Gatekeeper when changes are made.
Whenever the Controlled Copy is updated:
Commit and push the Controlled Copy to bitbucket using the git program.
Set the ‘Read Only’ file attribute on the Controlled Copy and the git-copy file
If the Controlled Copy becomes unavailable or unusable
Locate the most recent or most applicable Uncontrolled Copy.
Upload the Controlled Program into the Uncontrolled Copy.
Verify Device operation.
If the running program operates properly
While on-line with the Device, save the Program to the git folder with the filename of the Controlled Copy.
Set the ‘Read Only’ file attribute on the Controlled Copy.
If the Controlled Program becomes unavailable or unusable
If possible, upload the program and save with a unique filename. This will help in diagnosing the problem.
Download the Controlled Program to the Device.
Adding comments to PLC source code
Rung and tag comments are stored in the source code file and not in the processor.
There are two ways to add comments to a PLC program so that they can saved with the Controlled Copy:
Confirm that the Controlled Copy matches the code in the PLC processor
Create an Uncontrolled Copy of the program. This copy will contain all rung and tag comments.
Add your comments to the Uncontrolled Copy.
In RSLogix, click Tools > Export > Tags and Logic Comments …
Clear the Read Only property on the Controlled Copy.
Open the Controlled Copy.
In RSLogix, click Tools > Import > Tags and Logic Comments …
Save the Controlled Copy
Set the Read Only property of the Controlled Copy.
Commit and Push the Controlled Copy to git.
Clear the Read Only property on the Controlled Copy.
Open the Controlled Copy.
Go online with the PLC processor.
Add your comments to the Controlled Copy.
Save the Controlled Copy.
Set the Read Only property of the Controlled Copy.
Commit and Push the Controlled Copy to git.
=============================================
Code Review Guidelines
Compare the code to the specification
Identify Obvious Bugs. ...
Look for Possible Security Issues. ...
Look for "Clever" Code. ...
Check for Code Duplication. ...
Check Whether Names Are Descriptive Enough. ...
Look for Possible Performance Improvements. ...
Check the Presence and Quality of Tests. ...
Explain Your Changes.
Guidelines
Respect Running Software. Save frequently.
Always start from the Controlled Copy (git).
When you make changes to an Uncontrolled Copy remember that your copy is different from the Controlled Copy. Other people might change the online version and / or the Controlled Copy.
Never use the Controlled Copy as a working file.
Never use the Controlled Copy filename as a working filename.
Personalize and timedate stamp your work in progress.
If you modify an Uncontrolled Copy of a program, change the filename so that it does not appear to be a Controlled Copy or a git-copy Copy.
Do not put unknown code in either git or git-copy folder.
Make incremental changes.
Ensure the integrity and accessibility of Controlled Programs.
Ensure that the program can be quickly restored to a known running configuration.
For convenience, troubleshooting and problem solving a history of previous copies of the Controlled Program is desirable.
*** Set the ‘Read Only’ attribute of Controlled Copies
Guidelines for code changes
Design for testability / validation / visibility.
Conform to existing code style and format.
Consider the engineer or tech who will support the program.
Anticipate fault or failure scenarios.
Include appropriate warnings, Alarms, Fault, Fault handling, Fault Recovery.
Assign tag names consistent with the program.
Be consistent in tag naming format.;
Avoid hard coded constants. Better is to create a tag with a descriptive name and set its ‘constant’ attribute.
Include comments, headers, descriptions.
Consider how you will test the new code.
Consider your fellow programmers. Make the code readable to your coworkers.
Consider the user: Include tags and signals to include in the HMI
Don’t change existing tag names. Don’t reuse existing tags.. Don’t change the purpose of an existing tag.
Verification recommendations
Except for small changes:
Present data flow, state diagrams or any other useful descriptive information along with the code for review. This information should be updated, based on review and should be provided as documentation for future users.
The first concept is sometimes not the best. Additional input into usually improves the outcome
Begin review prior to coding. Evaluate alternatives.
The most effective review is done via the eyeballs of a qualified third party.
Compare the code to specification / design intent
Update the specification when required.
Anticipate and evaluate failure scenarios
Warning
If we download code rather than modifying code running in the controller: let's recognize that there is an increased risk of losing data or code.
If a processor dumps its memory for any reason then we have good solid backups to recover the program... But we should not depend on those copies to be the Master.
This is not true for Beckhoff or B&R controllers, and all compiled programs. There is no upload function to retrieve running code.
Beckhoff code can be modified online, but not uploaded.
Changes to Beckhoff (and similar environments) must be done by modifying the source code, then compiling and downloading to the target hardware.
It is necessary to maintain source code for these programs in a manner similar to how published software is managed.
Source Code Control philosophy
When we change code on a Rockwell PLC program:
We modify and debug our code online.
We upload and save the modified code.
PLC backup includes all logic and state of all memory at the time of save.
Controlled Copy copies are for backup purposes in case the Master becomes unavailable.