Documenting Projects

Hi there. I have a simple question with a lengthy post. How do you document projects (HMI or PLC programming) so that you or your coworker can understand it after being away from the program?

When I'm tasked to work on upgrades to a previous project we did there is always a lack of documentation and it is frustrating. I want to fix this.

A little background of me; I didn't see an introduction forum). I've been working as an SI for almost 3 years doing AutoCAD electrical work, HMI, and AB PLC programming. Before this I was a .NET application developer but I this gig came to me that was too good of an opportunity to pass up. I've learned a lot here, but I'm no where near a master PLC programmer. It takes a certain mindset which I cannot seem to master.

At an absolute minimum I like to have:

1. Functional Spec - What is the program supposed to do?
2. I/O list in Excel - Shared by the HMI, PLC and drawings, for consistency
3. Judicious use of comments - Write them as you write the code and keep them updated if that code is changed.

welcome to the forum.
I worked for 2 integrators for 18 years and wore multiple hats at each place.
electrician, designer (electrical and mechanical), quotations manager, purchasing, programmer, installer, and so on.

here's the best advice I can give.

1. have a folder for each job quote and have a reference number.
2. when a po is received for a quote, make a copy of the quote information
and place it in the project folder.
3. put an 8 1/2 x 11" notepad in this folder - for the designers.
the mechanical designer may need a notepad also, but will usually give
you the design drawings.
4. all meeting notes goes on these notepads.
5. copies of all po's goes in the folder
6. any change orders is documented and signed by the customer and a copy of the change order goes in this folder (IN ORDER !!).
7. a drawing reference goes in this folder - list all drawings.
8. All electrical prints MUST go in this folder !! this is the master set !!
all changes goes on these drawings FIRST. cad the changes later.
keep these always. throw nothing away for 2 years.
9. WRITE A DETAILED USER MANUAL !
explain what the machine does in general terms.
then do a write up from turning on power, to manually homing the machine.
then do the automatic cycle step by step and include inputs and outputs.
YES, this is time consuming and a pain, but maintenance will love you for it.
10. rung comment your program every 3-5 rungs!
do not rely on instruction comments, you are limited to what you can type.

with this procedure in place, it should only take 1-2 days to become familiar with a project that 9 months to program.

by the way, this is the system I developed at a company that had no standards. took 18 months to put in place, but it works

regards,
james

Any rung comments would be an improvement of what is already in place.

James, that is a terrific list of what steps we need to take.

I wear every hat from quoting a job to commissioning and ongoing troubleshooting. Honestly I'm not sure this is what I want to be doing, but I hate to waste my PE and the money is good.

Excellent answer from James.
I will usually follow up with an email after any meetings indicating any process changes agreed upon.
The program should read like a book.

Regards,

a word of CAUTION !!!

ANY correspondence with the customer MUST go through the owner !!

if you chat with the customer, always state you must get with the boss before committing to that work.!

sent the email to him, let him read it, and then send it to the customer with his comments.

DO NOT, DO NOT commit to doing work without the boss's knowledge and permission. I can't stress that enough. Lesson from the past that my associate did. $10K of free work, the boss was not happy.

all emails in regards to the project go in the folder in order.
#1 - email to the boss, #2 - email from the boss to the customer, #3 - customer reply. if its a phone call, follow it up with an email.

Details are a royal pain at the start of any project, but they will save your butt at the end of the day if something goes wrong. especially if the customer had you make the changes and doesn't want to pay for them.

ALSO,
any fax transmissions from the customer has a copy in the folder.
any fax transmissions to the customer MUST have a printed out fax transmission page
showing when the fax was sent, to what #, and the number of pages.
a copy is also put in the folder. the masters stay in the administrative folder.

also
do an electrical and mechanical component inventory of the items used in the project. that let's you see how much you were off and where you need to improve your quotes.
the steel, nuts, bolts can be looked at, but not with a microscope.

james

+1 to the organizing projects bit. That is good stuff.
+1 to the commenting bit. If you have to do calculations, please label what each thing in the calculation is. I have had to go back and figure out what formula was used for something with a tape measure and guestimate to get a tank level sensor reading properly.

I had to go into a plant and document 20 years worth of machinery, trace out HMI's and PLC's that spoke with each other over a networked layered on top of a business network. Find out IP addresses, hows and whys. Not to mention a brand new amonia system that was being controlled with the manual switches on the IO cards because, and I quote, "We were never given a password." The list goes on. I did much, much, much more than this as far as documentation, but all in all it took about 2 months.

Use excel where possible, it makes manipulation of the data so much easier.

adding to what sparkie posted.

lets use a slc 500 program
ladder 2 the main program only
power up timers
display and camera power up timers.
auto / manual selection

for a multiple station machine,
put each station in its own subroutine - easier to keep track of.
use different bits, timers, counters, integer registers also

for a multi station machine that does the same thing at each station.
do the same thing.
station 1 - bit 13
station 2 - bit 23
station 3 - bit 33

the same for the timers, counters, and so on.
get station 1 working.
save that station to a library
import that library into station 2 logic and use the edit index function.
you will then do a LOCAL search and replace for the I/o.

james

James Mcquade said:

adding to what sparkie posted.

lets use a slc 500 program
ladder 2 the main program only
power up timers
display and camera power up timers.
auto / manual selection

for a multiple station machine,
put each station in its own subroutine - easier to keep track of.
use different bits, timers, counters, integer registers also

for a multi station machine that does the same thing at each station.
do the same thing.
station 1 - bit 13
station 2 - bit 23
station 3 - bit 33

the same for the timers, counters, and so on.
get station 1 working.
save that station to a library
import that library into station 2 logic and use the edit index function.
you will then do a LOCAL search and replace for the I/o.

james

Click to expand...

I have never used that function. I'm going to have to fire up Logix500 and play with it

I takes a while to get used to it, but once you learn it, your programming time will drop.

Less stress, less headaches, all the station logic is the same.
learn 1 station, you learned them all.

works great.
I have used this on a 2,4,12, and 24 station machine.

james

Hi theproee,

I think bjh hit the nail.

For sw documentation you have two folds. The overall organization of the program i.e. the big picture, being a developer think of this as a classes diagram. How everything interconnects, reusable blocks, etc. Then you can get in more detail for a specific block if you need to. For example in one of our big programs blocks 240-244 are used for speed functions, etc you get the point.

Siemens you can also document a change log inside the project under sources via a text file, it really depends up to you, you can also have a word document with all the change logs. I am sure Rockwell can do the same.

It is common practice in my company to keep an internal change log in every function block, well mainly if is a complex block. So for example V1.0.0 Initial commissioning, initials, programmer, V1.0.1 fix bug XXX. As a dev you already know variable names should be very descriptive, and that goes for everything rungs, blocks, rung comments, etc.

Also we have a guideline for documenting function blocks, you start with a description of the block what it is supposed to do, any other useful information for example commissioning help details, then you go and note what the block input and outputs. This helps the next developer big time when dealing with that block specially on a grand scale.

I know the pain of working on a project after so long, but if you do a good job documenting and keep a good structure you will be ok. No need to know ALL the project if you are only upgrading a portion of the project, just focus on the IN/OUT you need for the upgrade. Good luck!

Well-documented ladder logic is a huge part of simplifying maintenance. As an example, I recently updated a multi-site telemetry system where the designer did a great job documenting each line of logic. This setup was a pleasure to work with, and didn't take nearly as long or risk as many mistakes.

A few thoughts:

1. Document your ladder logic clearly and consistently! Pretend you're the maintenance guy (or maybe you *are* the maintenance guy). Don't assume you will remember how the program works next month/year.

2. Give the customer the documented ladder files! (PLEASE!!!!!)

3. Versioning is handy. This particular project used a very simple versioning system where each upgrade to the code was saved with a sequential version number.

4. Assume the written manuals will be misplaced. Nobody can keep up with printed documentation. Put everything on disk, keep copies yourself, and give the customer copies. Assume future maintenance men will only see your in-program comments, and possibly the schematics, if they can be found. Put a copy of the schematics with the PLC and update them when changes are made. Maybe even store a thumb drive with the PLC.

5. Some PLCs save comments and/or memory tag names or nicknames in the PLC's memory, and are retrieved with the program. USE THESE and make sure they get saved to the PLC.

I have spent hours studying and attempting to comment programs which the original creator didn't bother to provide the documented code (or worse, didn't provide the documented code *on purpose*). There are better ways to spend a week.

3. Versioning is handy. This particular project used a very simple versioning system where each upgrade to the code was saved with a sequential version number.

Click to expand...

Just to add on this, for versioning you can even create your own scheme. For example: XX.YY.ZZ

Initial development: 0.0.0
Beta testing: 1.0.0
Commissioning: 2.0.0

ZZ up the number for minor fixes
YY any function additions
XX major updates to the system

Depending on the complexity of your machines a simple one number version might suffice as noted by ryangriggs