Collaborative PCB Design in Altium Designer

Parent page: Laying out Your PCB

As the saying goes, many hands make light work. One of the long-held dreams of board designers is to be able to have multiple people working on the same board, at the same time. While this task might not seem overly complex to the layman – just take Bob’s routing from that part of the board and bring it into my copy of the board – delivering it requires a mixture of certain key capabilities.

These include:

• A system that allows multiple designer access to the same board design, that they can work on and save their own changes without affecting the work of other designers.
• A mechanism to accurately compare and identify differences between multiple versions of the same board.
• Tools that can be used to resolve differences that are detected, allowing the designer to choose whose changes win.
• Tools that can automatically handle a large number of differences and resolve them without creating conflicts.

There’s another tremendous advantage to working with a design tool that is able to show you differences between different versions of the same board – you can also use this ability to check your own work. Forgotten exactly what you routed before the weekend?, no problems, the PCB Editor's Compare and Merge features can also be used to identify and examine the changes you've made, and even remove them if you want.

How It Works

Detecting and resolving differences between 2 documents, or diff’ing and merging as it is more often called, is a mature and well-proven process in the software development world. Because software is written and stored in ASCII documents, that can easily be read and compared by a human or a software application, numerous high-quality and robust 3rd party diff & merge tools are available.

To deliver that ability to board designers, diff & merge capabilities have been built into in Altium Designer’s PCB editor. The PCB editor has a sophisticated differencing engine that can detect the smallest physical difference between 2 boards. The physical difference engine works at a shape comparison level, comparing the shapes found on each layer.

The Compare and Merge features actually have 2 ways of working. The first is a 2-way comparison, used to detect differences between your current board and another version of the board.

The second way of working is a 3-way comparison, which you use if someone else is also working on the board. Imagine the scenario where both you and your colleague Bob check out a copy of the board from the Version Control repository. You both work on your own copy of the board, placing and routing components. Bob finishes the area of the board for which he is responsible, and checks it back into the repository. You would like to examine and incorporate Bob's work into your copy, so how does Altium Designer handle this situation?

To establish exactly what has been changed, and by whom, Altium Designer needs to compare your board to Bob's, and also compare it to the board as it was when you both checked it out of the repository (this version is called the Base). This requires a 3-way comparison - by doing this Altium Designer can understand the sequence of changes, and then gives you tools and commands to merge those changes into your version of the board. Whenever the Collaborate, Compare and Merge panel reports Version Control Status: Merge Required, it means that Altium Designer has detected that someone else has checked their work into the repository since you checked the board out, so you will need to perform a Merge to bring their changes into your version of the board.

   
The route as it was originally, then after it was modified by you (Designer1) and Bob (Designer 2).

When Designer 1 Clicks to show the merge resolution view, Altium Designer shows the route as done by each designer, as well as tagging the routes to show who has modified them.

The first designer’s merge resolution view.

How You Use the Collaborative PCB Design Features

Altium Designer’s collaborative PCB design features are accessed and operated through the Collaborate, Compare and Merge panel. It is command-central for performing a copper comparison between two versions of the same PCB design. It requires that the board is currently under version control and that the repository that it is stored in is configured in the Data Management - Design Repositories page of the Preferences dialog.

The Actions section of the panel is used for both control and status of the collaboration features. The panel checks if the board is the latest revision (known as the Head revision). If it is not, it indicates what must be done to bring it up to date.

Once a merge or comparison has been performed the differences are displayed in the Difference Map in the panel and in the design space, as shown in the image below. When you click on a cell the differences in that cell are detailed in the lower section of the panel, and also in the design space. The Difference Map also includes Layer tabs, use these to examine the differences on each layer.

Use the panel to get status information and run commands to display any differences.

The Settings region of the panel includes options and controls for the comparison configuration:

• Cell Size - displays the cell size when performing comparisons. Use the drop-down to select the desired size.
• Include Polygon Pours in Comparison - enable to include polygon pours when performing comparisons.
• Show Differences - enable to show differences.

To manage the display of differences, the board is temporarily divided up into cells. The cell reference is displayed when you hover the cursor over the cell in the Difference Map in the panel, and is also displayed in the bottom left corner of the cell in the main editing window. The color of the cell indicates who changed that cell, use the legend in the map for more details. The Difference Map will also include a layer tab for each PCB layer that includes a difference, select the layer and then click on a cell to zoom to that cell in the main editing window. Note that changed objects are highlighted using color or a ghosting effect, the meaning of these is explained below.

The Actions region of the panel is used to display, define and clear Progress Regions in the design space, indicate if the board is up-to-date with the repository, define what must be done if it is not, and initiate Compare and Merge actions. It includes a number of commands, divided into 3 sections:

• Live Collaboration - use these commands to configure, display and clear work regions.
• Version Control Status - will display commands when you are working with a version-controlled board.
• Comparison - use these commands to perform a difference comparison with another board either in version control (Click to show differences against any revision) or not (Click to show differences against any PCB document).

Use the Actions commands to launch comparisons and manage the Live Collaboration features.

When you click on a command in this region of the panel to initiate a Comparison, the software compares your file against the latest revision in the repository and displays the differences in the Difference Map region of the panel, as well as in the design space. Most commands are toggle-type commands, click once to enable them, click again to disable them. One command, Manually mark an intended work area, is different in that once it has been clicked the cursor moves into the design space, ready for you to define the region.

When the panel is opened, the software automatically checks the revision number of your board and compares it to the revision number of the Head revision. If they are not the same, the Version control status will indicate what needs to be done to make them the same.

Terminology and Status Messages

Performing a Difference Comparison

You’ll perform a difference comparison when you’re the only one working on the board, and you want to check your version against another existing version of the board. That existing version can be a version of the board in the version control repository, or a board on a hard drive.

All comparisons are initiated in the Collaborate, Compare and Merge panel. To perform a difference comparison select one of the following commands to access the reference document, your choices are:

1. Click to show differences against the head revision - to compare your board to the last version that was checked into the repository.
2. Click to show differences against any revision - to compare your board to an older revision in the repository.
3. Click to show differences against any PCB document - to compare your board to a board on the hard drive or network.

How Difference Comparison Results are Displayed

Once a comparison command has been selected, all differences are displayed in the Difference Map, where the board is divided into cells (the cell size is defined at the top of the panel in the Settings region) presented in a checkerboard fashion. As you hover the cursor over a cell, its cell reference is displayed, such as G4.

Click on a cell that has differences to jump to that region of the board in the design space. Note that you can change the zoom level used to jump via the Zoom Level button at the bottom of the panel. The lower region of the panel will detail the individual differences in the currently selected cell.

In the Difference Map, cells that contain differences are shaded in color, the choice of color reflecting ownership of those changes as defined in the color key just below the map of the board. Clicking on a colored cell details all the differences in the Differences section at the bottom of the panel.

• Layer tabs - select the desired layer to examine the differences on a specific layer.
• Previous Unchecked / Next Unchecked - use to move backward or forward through the cells in a logical pattern, layer by layer.
• Set Checked / Clear Checked - use to set or clear the checked differences.

In the design space, cells that contain no differences are shaded in translucent white, indicating that there is nothing of interest in this area. If a cell contains differences, then it is not shaded. Switch to single layer mode (Shift+S) to more easily see the differences.

Differences are highlighted using a variety of techniques, including color, shading in white, and ghosting (the object of interest is displayed in a dull, hollow-looking way). The meaning of each is detailed below.

Performing a Merge Resolution Comparison

You perform a merge resolution comparison when there are 2 or more people working on the same board. For this to work all designers must have checked out a copy of the board from the same repository. Each designer should also configure the feature, to ensure that they all have maximum awareness of what the other designers are doing.

If the Actions region of the panel reports a Version Control Status:Merge required, then a merge resolution comparison is required. To do this, use the Click to show merge resolution view command in the Actions list.

How Merge Resolution Comparison Differences are Displayed

Resolving Differences

Differences are resolved by merging in differences detected in the reference document, into the current board. Merging can either be performed in the PCB editor window or in the Collaborate, Compare and Merge panel. The Automatically merge in non-conflicting changes from the head revision command in the panel is displayed when the Show Merge Resolution View is active. It will bring into your working all the non-conflicting modifications made in the head (depicted in the Difference Map by green cells).

To merge from the panel, right-clicking on a modified cell in the panel’s Difference Map to display the Add/Remove to match [ReferenceDocument] command. Selecting the command will modify the primitives in that cell to match the reference document. Note that the name of the reference document will be displayed in the square brackets. Multiple cells can be highlighted at the same time (Shift+Click or Drag+Click to multi-select) allowing as many or as few changes from the reference to be brought across to the current board.

If a cell includes some changes that you want to keep and others that you want to bring in, then you can selectively merge the changes in the main PCB editor. To do that you use the right-click Merge menu.

Right-Click Merge Menu

To resolve differences in the main editing window, right-click on an object that is flagged as a difference. The popup context menu will include a Merge submenu, in that will be merge actions tailored to the primitive that was clicked on, as well as the status of the changes in the cell.

Right-click on a marked track and select a command from the Merge sub-menu.

There are 3 possible levels the commands in the Merge submenu can operate on:

• Primitive - only the actual track segment/via/component that you right-clicked on will be modified by this action.
• Route - for the connection you clicked on, all track segments that are different will be modified by this action.
• Cell - all track segments passing through the cell that are part of this difference, are modified by this action.

The commands available in the right-click Merge sub-menu support the following types of actions:

• Add - Displayed when clicking on a primitive that exist in the reference document, but not in your document. Adds the primitives from the reference document into the current document, but does not remove primitives. When the Add Component action is performed, it will attempt to remove an existing component that would cause an UniqueID conflict.
• Remove - Modifies primitives so the changes made to the current document are removed.
• Replace - Adds and removes primitives so the end result matches the reference document used for comparison.

Supported Objects

Some objects/features are not supported by the merge process. Supported/not supported objects are detailed below.

Supported:

• Tracks
• Arcs
• Fills
• Solid Regions
• Pads
• Vias (also Blind & Buried)
• Dimensions
• Coordinates
• Components

Not supported:

• Polygon + cutout + board cutout
• Embedded board array
• Rooms
• Origin
• Grid
• Free 3D Bodies
• Guides
• Rules

Live Collaboration

The backbone of Altium Designer's PCB collaboration feature is the version control system and the repository. The VCS keeps track of which revision each designer has checked out, and if it is different from the Head revision.

To make it easier for individual designers to keep track of who else is working on the board you can also use Altium Designer's Live Collaboration and Work Regions features.

The Live Collaboration feature details which other designers are currently working on the same board. The log-in and computer name of each designer that currently has the same board file open (their own local copy) is detailed in the Difference Map region of the Collaborate, Compare and Merge panel.

For the Live Collaboration feature to work, you must be connected to a Workspace.

Work Regions

Each designer can define Work Regions - areas that define where they are design space. Work regions are defined in the main workspace, enable the Click to show work regions in the main editor option in the panel to display them in the design space before you attempt to define one.

To create a work region, click the Manually mark an area as work region command in the panel, position the cursor where one of the corners is to be located, and click to start. Work regions are polygonal objects, click to define each corner of the polygonal shape, Shift+Spacebar to cycle corner modes, Spacebar to toggle the corner direction, right-click to close the shape and end placement.