Machine commissioning: A programmer’s checklist

Inside Machines tips and tricks: Control engineers need to practice these programming tips to ensure project timeline pressure doesn’t harm the machine project.

By Nishant Unnikrishnan October 31, 2012

A lot of emphasis is placed upon the importance of specification gathering and project planning before starting a machine project. Once projects are underway, control engineers are typically under pressure from project managers to complete programming on time even though they may be waiting for the mechanical and electrical teams to finish their parts of the projects. The control engineers working on programming the machine face a time crunch as the deadline nears. Due to commercial reasons, in many situations, final programming is done after the machine ships to the customer, leaving testing incomplete.

In the race to deliver the project on time, programmers may be tempted to skip the “wrap-up” steps after programming is complete. Below are eight essential wrap-up steps that make the project easy to maintain, easy to troubleshoot, and easy to build upon, if needed.


1. Map the various areas in control algorithm (from the basic design document) to drawings in the project: A basic design document is the first step in project design. The design document translates customer requirements to a plan of action that contains designs of algorithms required for machine operation. Programmers use the control algorithms laid out in the basic design document to write code for motion control and other logic required for machine operation. Multiple drawings or program organizational units (POUs) may be required to complete one control algorithm. In such situations, once the coding is complete, a map that links specific parts of the algorithm to POUs is essential to understand the project’s flow of code. Such a mapping gives the user a better understanding of the layout of the program and the sequences used in machine control. This map can help understand sequence issues on machine controllers that have multitasking capabilities.

Documentation like this will be a good starting point to someone who will be taking ownership of the machine code after the initial programmer hands it off. It may not be possible to include such documentation in the project itself. A separate document may be necessary for this purpose. A simple example of how an algorithm can be converted to a color-coded flowchart with the roles of individual drawings/POUs is shown in Figure 1. 

2. Document inputs to each POU and outputs from each POU: Documenting inputs flowing into a drawing and outputs flowing out of a drawing will help a user understand the data flow within a project. Such documentation will help in understanding the process and in troubleshooting the application. This way the project is modular and each POU or drawing can be checked for functionality independently. For example, Figure 2 below details data flow in a part of a project. To troubleshoot an issue related to H10.03, one can look at the inputs and outputs of H10.03. Only if the inputs to H10.03 are as expected should the user go into H10.03 to troubleshoot the code there. If the inputs to H10.03 are not as expected, the user should not delve into the code in H10.03. 

3. Define variables (status variables/ parameters) at key points in the code to help troubleshoot: Modularity and transparency are important properties of good code that is easy to troubleshoot. To be modular and transparent, the programmer must make an effort to break down complicated sequences to smaller sequences such that variables can be monitored closely for accuracy. This also paves the way for easy maintenance. Such programming practices may affect the programmer’s time while programming, but they will save a lot of time during start-up and later during troubleshooting. 

A screenshot of Structured Text (ST) code broken down for making the code modular is shown in Figure 4. If the code were not made modular with the introduction of the additional variable, the total number of lines of code would be small, but complex and unmanageable.


Placing functionality at critical locations to monitor motion parameters in motion applications during program development will help immensely in the long run. This will prevent an unnecessary waste of time during the debug stage of application start-up. This is very important in applications that involve synchronized motion like electronic camming or electronic gearing. The above-mentioned motion functions involve various internal parameters whose understanding will help in application troubleshooting. 

4. Plan for part replacement strategies in the code: Over the lifetime of a machine, various components of the machine will have to be replaced. When a machine component controlled by the motion controller is replaced, the motion controller should have the capability to extract the same functionality from the new component as it did from the old component prior to it becoming worn out or faulty. This involves keeping a copy of the working component’s parameters as part of the project. The programmer will have to foresee such a scenario and design code with this capability. Most motion controllers have the capability to retain parameters and compare parameters. If needed, the retained parameters can be sent to the new component that is installed in the machine. It is beneficial to incorporate these aspects into the code before machine commissioning and not wait for a component to become faulty before thinking of replacement strategies.


Finalizing project and documenting start-up 

1. Save parameter files as part of the project (after final machine setup): One of the last steps before commissioning a machine is parameter optimization and turning on motion components to optimize performance. This will involve editing parameters on various components that are part of the control system. After the parameters are finalized, the programmer should make the extra effort to save a copy of these parameters as part of the project.

2. Review project access rights: Many times, OEMs use custom algorithms to control motion. If the OEM wishes to protect certain algorithm implementations from end users, such code should be password protected. Most programming software products have selections for read/write protection. Selected portions of the code that are not for public viewing or editing should be placed under password protection. 


3. Review deliverables at project hand-over: At the time the customer receives the project, the programmer should make arrangements such that all required files are handed over. The OEM and user should agree on whether the code and project can be reused on other machines if the user wishes to replicate the machine. The programmer should understand how the software allows a user to create a project image. The various checks that can be performed are:

a. Save source files on the controller if the programmer wants to allow the user to upload the project from the controller into the user’s PC at a later date. This is one form of backup. This allows the user to extract the project that is currently running on the machine.

b. Lock the project before hand-over. If the user does not want to make any edits to the project and wants to use the project for monitoring only, the programmer should lock the project. Locking a project helps in version control. A user will not be able to make edits to a locked project. Another good practice for version control is using the date as part of the project name.

c. Make sure all firmware and user libraries are compiled and included with the main project. If the project is built with the help of add-on user/firmware libraries that are not part of the standard software install, the programmer should take the extra step to include these libraries with the main project. The programmer should also check to make sure that the libraries and the paths are linked with the main project appropriately.

d. Lay out detailed steps that will help a user clone machines if the OEM wants to allow the user to do so. 

4. Document performance analysis (plots and numbers): Documenting machine performance in plots of motion parameters and in numbers of parts processed is essential at start-up. This will serve as a template for troubleshooting, commissioning other machines, analysis for improvements, and more. Start-up performance documentation should be reviewed and approved by the customer.

Often when a user complains about a machine not performing as per specifications, documentation made at machine start-up will come in handy to compare and verify. This will help explain any differences in performance over time. On motion applications, performance analysis must be done at the machine controller level and also at the drive level. The controller side analysis will help in evaluating the machine performance as a whole. Drive analysis will help in detailed evaluation of the axis in question. Various performance factors like tuning and filtering can be gleaned out of such performance plots. 

A programmer who does not address these steps appropriately can be compared to a car manufacturer who does not add a spare tire and the user’s manual as part of the new car that rolls out of the assembly line.

– Nishant Unnikrishnan is application engineer, Yaskawa America Inc. Edited by Mark T. Hoske, content manager, CFE Media, Control Engineering and Plant Engineering,

Key concepts

Control programming tips:

-Draw a map

-Document inputs

-Define variables

-Plan for part replacement strategies 

Consider this

With automation programming projects, is three out of four not bad…when you’re talking about compiling and including firmware and user libraries in time? 

Go Online – See links below for the follow articles

UML use cases, sequence diagrams: Easily converted into executable code 

Seven habits of unsuccessful projects