An introduction to Version Control Systems for engineers

Every project an engineer works on creates a host of files that

1. must not be lost or corrupted
2. must be able to be modified in a restorable manner

Files such as PCB schematics and layouts, electrical wiring diagrams, PLC project files, CAD files, source code and many others fall into this category. The files will have required a lot of time, money and effort to create. They will need to be maintained over a long period of time, generally by multiple engineers. So if these files are so important how should we look after them.

The most common method I have seen could be summed up as 'Manual Backups and Version Numbers'. This system, or something like it, is the logical end point for an engineer that has been bitten by a file corruption or accidental file over-write. It tends to appeal to engineers for a few reasons,

1. they thought of it themselves
2. it only requires tools that they already use (the file browser, copy and paste) and
3. it requires a disciplined operator (engineers are used to being rewarded for disciplined behaviour).

The system works like this

1. Once a file has been developed to the point that it is considered important a version number gets added to its name
2. If a big change is planned the file gets copied and the version number gets incremented
3. whenever it is thought about the file gets backed up to another computer

This system appears to be pretty good. It is simple to understand and easy enough to follow (though a little arduous). It is easy to see some simple improvements such as using a file server to share the files with other engineers or an automatic backup script to garrauntee multiple copies. However there are problems with this system that can best be explained by introducing another solution to the problem.

The other solution to this problem is to use a Version Control System.

Version control systems are very common within the software development industry. Unfortunetly in my experience their use hasn't really caught on amongst the hard engineering disciplines. If the 'Manual Backups and Version Numbers' method is the logical conclusion for an engineer then a Version control system would have to be described as the logical conclusion for a software developer. The major goals that we were tackling with the method above still apply however they have been extended and automated within the Version Control System software. The goals that most VCSs strive to achieve are

1. files, including all previous versions, must not be lost or corrupted
2. every modification to a file should be stored in a restorable manner
3. the history of modifications should be well documented including the time and date, the author, the files modified and a description of the modification
4. any locally modified files should be easy to identify
5. the modifications within files should be easy to identify
6. the files should be editable by as many people as are required
7. If the same file is edited by two people at the same time neither persons changes will be lost
   

The version control system that I have the most experience with is Subversion and it does a good job of meeting the the goals listed above. The areas in which Subversion excels compared with a manual system are in garraunteeing the validity of previous versions, managing the file history and the sharing of files between multiple engineers.

With any project, whether it is a single source code file or a directory full of documentation, there will be a large number of modifications to the important files. With a manual versioning system each new version is surprisingly taxing. On the surface it would appear as though this is untrue. To create a new version all you need to do is copy and rename the files, right. The taxing parts though are before and after this step. Prior to copying your files you need to identify which files have changed. This is particularly difficult if the change was accidental or made by another person. Worse though is the fact that once you have a few versions it becomes very difficult to identify which changes were made in which version. As a result people that use manual version control tend to limit the number of version they make.

On the other hand with subversion creating a new version is very cheap. At a glance you can see if your files have been modified, whether the same files have been modified by other people and if you are using text files you can see exactly which characters have been changed. Performing a commit is usually a two mouse button and one paragraph action. For this effort we also get to record the author of the changes, the exact time the modification was made, which files were affected and a brief description of the modifications. This extra detail is extremely useful when you need to track back through your changes. With Subversion the ease of creating a new version means that there is no fear about making a change to your files. You should commit a new version everytime you make a change that could cause a problem. You then can always track back to the exact point in which your troubles started.

Another important concept that a VCS like subversion enforces is that you are always working with a copy of the files, not the files themselves. This greatly reduces the risk of accidental modification and it is a virtue that is hard to bring to a manual system. The problem becomes particularly aparent when you look at a situation that involves the investigation of an error with a previous version of a file. Because you are able to gain access to the master copy of the old version of the file there is a risk that it will be modified during the investigation. You may well want to fix the error in the old version however unless you have made a copy first the state of that file when it originally was versioned becomes lost. What do you do then if the modification you made isn't correct after all? With Subversion that will never happen. When a version is commited you will always be able to return to that point in time. This is another reason why it is a good idea to commit regularly.

The extra information attached to each commit and the enforcement of always working with a copy of the files also makes the task of working with multiple engineers much more reliable. For a start it is a lot easier to know what changes other people have made when you can see who changed which file, when with an explanation about what they did. This also helps with project management as the improvements and fixes are documented as they are made. The conflict avoidance features, the cornerstone of which is that you are always working on a copy, remove the risk of multiple people overwriting each others changes.

All in all I think that engineers of all walks of life can benefit by making use of a version control system such as Subversion. It will greatly reduce the risk of losing important information, ease the process of tracking back through versions and help to manage files used by teams. In the future I will dive into some more specific information related to setting up and using Subversion. I'll also be looking into some of the specific problems associated with keeping engineering files in subversion.

For further information about Version control systems and Subversion

Windows client - http://tortoisesvn.tigris.org/

Manual - http://svnbook.red-bean.com/

Gumstix as a network gateway

Ross and I have been doing a fair bit of work at a sand mine recently. In particular looking at control improvements on the Dozer trap that is being used at a mineral sands mine down near Mildura. For a variety of reasons the trap hasn't been running too well and due to the remoteness of the site there have been difficulties getting the suitable people enough access to the machine to make significant improvements. Because of this and also to aid with remote monitoring of the operation of the dozer trap it was decided to get the dozer trap network connected up for remote access.

Fortunately the Momentum PLC and the Citect HMI interface were originally setup to communicate via an ethernet network. This decision allowed for a wide range of options when setting up remote connections. So a radio was fitted to the trap with a repeater within site at the top of the pit. Everyone who needs access has a VPN login to the site wide business network. At this point we could have connected the business network and the dozer trap network directly and changed each of the dozer trap ip addresses to fall within the business network range. This would have a few risks associated with it though. Whilst the two networks were connected together anyone on the business network would have had direct access to the PLC and other network enabled items within the dozer trap. If the operation of the PLC was compromised either through a direct interaction from someone on the business network or by an accidental ip conflict the operation of the dozer trap could be affected. To solve this problem we decided to place an ssh server in between the two networks.

For those that have not come into contact with ssh before have a read of the wikipedia page . In our setup we have installed a computer that has two ethernet ports in between the business network and the dozer trap network. One ethernet connection goes to each separate network. In this way the two networks aren't actually connected so the dozer trap devices don't need to change their ip addresses and they aren't directly accessible from the business network. We can then create tunnels between the two networks using the secure connections made using ssh.

The computer that we chose for this task had to be small, energy efficient and reliable. It needed multiple ethernet ports and an ssh server. As it turns out there is a computer that fits this bill exactly. We chose a Connex 400 with a net-DUO expansion board from Gumstix. These tiny computers run linux in flash on a 400MHz Intel (ARM licensed) processor. The net-DUO expansion board provides the two ethernet ports and the default linux installation includes an ssh server.



With the gumstix in place we have setup PuTTY sessions to tunnel VNC (port 5900) for viewing the HMI panel, Subversion (port 3690) for handling the program changes, Serial (port 10001) for communicating with the EDM via a lantronix XPort and Modbus (port 502) for programming the Momentum PLC via Concept. The connection has been fast, reliable and most importantly secure. Overall a resounding success.