Chapter 6: Documenting the Application

Introduction

Documenting the application is an important step to ensure the way the application works can be understood in the future. This applies to any engineers who are unfamiliar with the application and sometimes the engineer who wrote it if they are coming back to it after a long period of time.

SoMachine Basic provides many ways to document the application which will be explored in this chapter.

This Chapter Covers These Topics:

i. Object Documentation
ii. Section Documentation
iii. Comments
iv. Application Information

Object Documentation

Symbols
If the symbol names are chosen carefully, they will help to document the application. Consider the following rung of ladder:

i13-1

What does this rung actually do?

Without some other information it is impossible to work out the function of this rung. Now consider the following rung of ladder.

i29

It immediately becomes much more obvious what the rung is doing simply by reading the object labels. This self-documentation is used by many engineers as an aid to programming and to understanding the program in the future.

The program created in Chapter 3 - Programming a Simple Application uses many meaningful symbol names making the program easy to understand without any additional comments.

Section Documentation

Naming POUs and Rungs
Similarly, choosing meaningful names for POUs and Rungs can help anyone understand what the program is doing and where to find parts of the program.

i30

The names in the above image are not very helpful but the ones below are much more descriptive.

i31

The program created in Chapter 3 - Programming a Simple Application uses meaningful POU and Rung names to make the program easy to navigate without additional cross referencing.

Comments
Comments can be added to each rung to describe the action of the rung.

While symbols can help to document the application, often the logic of the rung must be inspected to understand the function of the entire rung. A comment attached to the rung can immediately explain the purpose of that rung.

i32

How to Add a Comment
At the top of each rung there is a grey box.

i33

Click the grey box to add a comment.

Exercise - Add Comments to the Application

1. View the Conveyor Control Application
i. If SoMachine Basic is not running, start it.
ii. Open the Conveyor Control application.

If in doubt, refer to the Exercise - Managing Applications which shows how to do this.

2. Add comments to the control POU.
i. Go to the programming tab and select the Control POU.
ii. Select the Start Control rung and click the grey box at the top of the rung. Enter the text Energised to start the conveyor run sequence.

i34

iii. For the remaining rungs of the Control POU enter the following comments:

Conv 1 Conveyor 1 control
Conv 2 Conveyor 2 control
Conv 3 Conveyor 3 control
Running Run indicator
Stop Control Stop request - Initiate phased shutdown
Stop 1 Stop signal for conveyor 1
Stop 2 Stop signal for conveyor 2
Stop 3 Stop signal for conveyor 3

3. Optionally, for completeness enter the following comments for the Fault Handling and Speed Monitoring POUs:

Conv 1 Flt Conveyor 1 fault
Conv 2 Flt Conveyor 2 fault
Conv 3 Flt Conveyor 3 fault
Reset Reset conveyor faults when start button is pressed
Fault Light Fault light
VS High Compares with high setpoint - energised if speed is high
VS Low Compares with low setpoint - energised if speed is low
VS OK Speed OK
Setpoints Initialise speed voltage setpoints on startup (voltage is x10 speed)

Application Information

Application
There is some information that will apply to the entire application. This includes who wrote it, where the application is being used and what the application does. The properties section in SoMachine Basic allows this information to be recorded as part of the application.

i35

Front Page
The Front Page is used to store information about the engineer and company that produced the application

i36

This is of particular use to OEMs and integrators as it gives a point of contact if the application requires updating and the customer does not have the ability to do it themselves. It can also be used internally to identify the actual engineer who wrote the application and provide contact details.

Company
This can store information about the company using the application.
i37
This is of particular use OEMs and integrators who have many customers as it documents where the application is being used.

In the Company section there is also space for the company logo.

i38

Project Information
The Project Information section is where information about the project itself can be stored.

i39

This can be the name of the project, a description and a photo. The photo can be useful to show where the application is being used.

i40

Exercise - Enter Application Information

1. View the Conveyor Control application.
i. If SoMachine Basic is not running, start it.
ii. Open the Conveyor Control application.

If in doubt, refer to the Exercise - Managing Applications which shows how to do this.

2. Enter the programmer information.
i. Go to the properties tab and ensure that Front Page is selected in the Properties tree.

ii. Enter your details into the form and click the Apply button.

3. Enter the company information.
i. Select Company from the Properties tree.

i37-1

ii. Enter the information for the local Schneider Electric office and click the Apply button to apply the changes.

4. Change the company logo.
i. Under Company Logo, click the Change Button.
i41

ii. There is a Schneider Electric logo on the DVD located in the same folder as this document. Navigate to the folder and select Schneider Electric.jpg. Click the Open button.
iii. Click the Apply button to apply the changes.

5. Enter the project information
i. Select Project Information from the Properties tree.

i42

ii. Enter the name Conveyor Control Application into the Name field. Give the application an appropriate description. Click the Apply button to apply the changes.

6 Change the photo.
i. Under Photo, click the Change Button.
i43

ii. There is a picture of a conveyor system on the DVD located in the same folder as this document. Navigate to the folder and select Conveyor.png. Click the Open button.
iii. Click the Apply button to apply the changes.

7. Save the application.