A few tips to help prevent head-scratching.
“Refactoring” is a word well known in software development circles, and it’s often one that invokes either boredom or spine shudders in those blessed few coders that have had to do a bit of it. Nevertheless it is an important concept – refactoring essentially means re-writing the insides of a module of code or at least a few functions in order to improve performance without compromising functionality or critical specifications. It is often carried out by original authors who’ve got some “breathing space” after a release to go back and tidy up code that they know was rushed through development, or perhaps for extensibility reasons its dependencies may need to change. If you consider what refactoring is at a basic conceptual level, you could say it’s a common activity across all design disciplines – in the mechanical world for example, an engineer may completely re-design a transmission on the inside without changing the housing, gear ratio, connections or base loading, perhaps redesigning for reduced noise and wear. You get the picture.
It’s also an activity often undertaken in the electronics department of many organisations – I am tempted to say all, though I can’t prove it. It’s the most fundamental form of design re-use – to take an existing design or portion thereof, make a copy of it, rename it, and start editing out the bits you don’t need and editing in the bits you do. You may have a more disciplined process than that, but this is very common practice in industry.
But there are flies in the ointment. Unless you are very careful and rigid in the way you make copies of design data for refactoring (or to begin a new revision of the product), you expose yourself to confusion about which version or copy of a document you are really working on. Everything can be fine until something you notice on the page pricks your conscience; that you may not be working on the file you first thought you were.
Another common problem is that when working with design documents that originated from a different author, you may not have a history of the changes they (or other authors) have made before you got a hold of those documents. What if you’re trying to do a modification for revision 3 when the source files you have obtained were only at revision 2, and you don’t necessarily have a way of knowing that unless the documents clearly contain that revision name or number – even then, you have to track down the right version.
Refactoring and design revisions need not be this uncertain or painful. With a little discipline and the right use of the right tools, you can be confident that you are doing the right edits to the right files. It is a two-pronged approach that uses refactoring features of Altium Designer along with proper version control of the design documents.
Refactoring in Altium Designer
Refactoring is actually very smooth when using the refactoring commands in Altium Designer. Assuming you already have a good baseline set of design files (i.e. a PCB Project, all its schematics, the PCB etc.), then you can get started by using the Refactor commands on the schematic right-click menu. There are several refactoring commands and all are context sensitive – the commands displayed will depend on what object type you are hovering over when you right-click. These commands cover the following scenarios:
- A part has become obsolete and is to be replaced by a functionally equivalent sub-circuit.
- The current schematic design is to become a sub-circuit used within a larger design.
- You wish to make an existing sub-sheet a device sheet (a re-use element).
- An existing device sheet needs to be localized and customized for the current design.
- You need to split a schematic into multiple pages.
In scenario 1 above, right-clicking on the part and choosing Refactor»Convert Part To Sheet Symbol replaces the component symbol on the schematic with a sheet symbol that retains the connections – where each pin of the part has become a sheet entry of the same name and (as closely as possible) the same electrical type for connection into a new lower-level schematic page (see Figure 1).
Figure 1
The lower level schematic page needs to be created, and is easily done using the right-click command on the newly created sheet symbol Sheet Symbol Actions»Create Sheet From Sheet Symbol (Figure 2). Note that you may wish to create a VHDL or Verilog file instead – useful when working with FPGA designs.
Figure 2
Now you are in a fresh new schematic sheet with all the necessary port connections for creating the replacement sub-circuit. Figure 3 shows a quick way to perform these steps while retaining the original component in a new lower level sheet – Push Part To Sheet. In this case you would then simply delete the component and begin work on the replacement equivalent circuit.
Figure 3
Scenario 2 is similar to scenario 1, but it’s a move in the opposite direction of hierarchy. For example, rather than replacing a component with a lower-level sub-circuit, you are “plugging it in” to a higher-level design – effectively replacing a component with a “socket” to connect up in the hierarchy. For example, let’s say you have a separate power supply design, previously produced as a separate PCB and connected to the main board with a cable harness and headers. Now, you wish to combine the PCB with the main board to reduce manufacturing costs – in this case you would make the power supply design a child of the main design, and you need to replace the connector symbols with ports, so you can add the power supply schematics to your main board project as sub-sheets. To do that, right click on the connectors within the power supply schematic and choose Refactor»Convert Part To Ports (see Figure 4).
Figure 4
In scenario 3, the assumption is that you would like to re-use a sub-sheet in multiple other designs, because it’s proven its usefulness and manufacturability. In this case, you can simply right-click on the sheet symbol of the said sub-circuit, and choose Refactor»Convert Schematic Sheet To Device Sheet (see Figure 5). In performing this action, you are then prompted to choose the target location of the device sheet (see Figure 6), and whether or not you wish to replace the current sheet symbol with the device sheet, or all sheet symbols in the current design or workspace – particularly useful if this is a multi-channel design where this sub-circuit exists in several instances.
Figure 5
Figure 6
That circuit has now become a re-useable element for all your designs.
The opposite – scenario 4 – is when you have an existing device sheet, but need to tweak it just a little bit for the current design. In this case, simply right click, choose Refactor»Convert Device Sheet To Schematic Sheet, and the device sheet is copied to a local unprotected schematic page in the project, with the sheet symbol updated to be linked to the new local copy rather than the centrally stored read-only device sheet. Now you can edit the local copy with confidence that you are not breaking the original source.
Finally, in scenario 4, sometimes you just run out of space and need to move things around a bit – to the point where you want to create new schematic pages and move parts of the schematic over to the new pages. This is a lot easier to do cleanly with the right click command Refactor»Move Selected Subcircuit to Different Sheet. Again this is a context sensitive command – it is available only when you have one or more objects in the design selected. Once you run this command, you are prompted to choose which page in the project you wish to deposit the sub-circuit onto. Once that has been selected that page it opened and you simply click to place the sub-circuit where you want it.
A Single Line of Development
As mentioned earlier, a lot of problems and uncertainty can arise from refactoring tasks carried out on the design. These can be mitigated with good data management habits, and eliminated with a rigorous data management methodology.
The most important place to begin rigorous data management is to have a single line of development for each project. Rather than copying files to different places to create new versions of the given design, keep everything as a single project, in one place, and only edit the one project. Altium Designer’s refactoring tools have been developed with this fundamental concept in mind.
Figure 7
By not making copies of the design, but rather revising the existing design, you achieve some important things:
- Traceability – within Altium Designer, every time you save, the history of that file is updated and at any time if you need to go back you can. You can also compare different revisions in the history of development to see in detail what has been changed. Better still, if you are using a version control system such as Subversion (a.k.a. SVN) you can see a complete history with user names and comments about changes that have been checked in (see Figure 7).
- Single source of truth – if you maintain a single location and file set for a given project, regardless of where you are or what day it is, you know that the design files you are working with a the only ones for that project. There are no other half-baked copies lurking in other folders or on your home computer. If you work from different places, or need to collaborate with others on a design, then using a version control system allows each user to have a local working copy but they are all reconciled and checked back into the main source (the repository) with traceability, and you can therefore know when someone has modified something and see when that occurred and why.
- History – the all-important ability to be able to go back in time and see why certain design decisions or refactoring were made, and better still the ability to revert back to a previous version if something was tried but didn’t work.
- Collaboration – the ability to spread design and refactoring tasks across members of a team and, if using a version control system in the cloud, the team can be geographically dispersed.
Using the refactoring tools, along with version control integration in Altium Designer, is a great way to keep innovating and evolving your products without headaches and uncertainty. Even without a version control system, keep a single line of development for each project and make use of the history in the Storage Manager (as shown in Figure 7), and you are well on your way to alleviating common confusion.
