Collaborative PCB Design in Altium NEXUS

Created: July 12, 2022 | Updated: July 12, 2022

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 NEXUS’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 NEXUS handle this situation?

To establish exactly what has been changed, and by whom, Altium NEXUS 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 NEXUS 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 NEXUS 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). The route as it was originally, then after it was modified by you (Designer1) and Bob (Designer 2). The route as it was originally, then after it was modified by you (Designer1) and Bob (Designer 2).
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 NEXUS 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.
The first designer’s merge resolution view.

How You Use the Collaborative PCB Design Features

Altium NEXUS’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, 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.
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.
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

Term

Definition

Head

The latest revision committed to the version control system.

Base

The revision in the repository that you checked out to be your local Working Copy. Also called the checked out revision.

Working Copy

Local copy of the version-controlled document on which editing is performed.

Local changes

Changes made on the Working Copy that have not been committed to version control.

Status : File up to Date

The Base revision is the Head revision and no Local Changes have been made.

Status : Modified

The Base revision is the Head revision and changes have been made the Working Copy. This Status indicates that you were the last one to check-in to the repository, so all differences are local and are a result of your own work.

Status : File Out of Date

The Base revision is older than the Head revision and no changes have been made to the Working Copy. This Status indicates that someone else has checked-in their work since you checked out your copy, but you have not made any changes to your copy. Click on the Bring this document up to date with the head revision action to replace your older copy with the latest copy of the document.

Status : Merge required

The Base revision is older than the Head revision and Local Changes have been made. In other words the document is both Modified and Out of Date. This Status indicates that someone else has checked-in their work since you checked out your copy, and you have also made Local Changes to your copy. This can only be resolved by merging your changes with the other designer's changes.

Resolve

The act of updating the Base revision number to the Head revision number. You must perform a Resolve when the Base is older than the Head, and you want your copy to become the Head. This transforms the Status from Merge Required to Modified.

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 contains 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.

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.

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.
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
Multi-channel design is also not supported by the Collaborative PCB feature.

Live Collaboration

The backbone of Altium NEXUS'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 NEXUS'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.

Collaboration Server Path

For the Live Collaboration feature to work, Altium NEXUS uses a central file to log collaborator and work region information (WIP.xml). The file is stored in the location defined by the Shared File option (PCB Editor - General page of the Preferences dialog). To use this feature each designer must define the same path in their installation of Altium NEXUS.

Collaboration can also be configured to work through the connected Workspace by selecting the Altium Vault option.

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.

Note that you must have common Collaboration settings (on the PCB Editor - General page of the Preferences dialog) defined to see the work regions that other designers have defined in the same board file.

The Role of Version Control

The challenge of collaborative design has long been solved in the software development domain. Best-practice software development demands that code is developed in a structured and ordered way, with the code broken down into individual files that reflect the overall structure of the project. That means that software development teams produce a large numbers of code files, containing large amounts of code.

To effectively and efficiently work collaboratively across that fileset, software developers typically use a Version Control System. A Version Control System, or VCS, allows them to:

  • Easily store all project files in a single, central location, or repository (making it easier to back up).
  • Undo changes, including across multiple files.
  • Store and retrieve any file from any point in the history of the project's development.
  • Work independently, yet collaboratively. Each team member has their own local copy of the files they need, when their development reaches a point of maturity they can check-in their work to the repository.

If you have not worked with a Version Control System then you might be inclined to think, it’s just too much mucking around. In reality, working without a VCS actually leads to far more mucking around, with everyone crafting their own system for saving revisions of files with strange filenames, in special locations, that soon become forgotten. In fact pretty much any business that makes its money developing content in electronic files is well served by storing those files in a Version Control System.

And the overhead of the VCS? Working with a VCS is not hard, once you understand the basics of interfacing to the repository. Whenever you check-in your work you have the opportunity to include a comment, use it well as it is ideal for keeping track of your changes. You can easily review the history of check-ins, examine the comments, or Revert to any version of any file. Once you have checked out a copy of the project into your own local working area you simply work as you always did, just check-in your updates when they are ready to be shared with others. Altium NEXUS interfaces directly to the repository too, making repository tasks, such as checking in your work, as simple as right-clicking on the file in the Projects panel.

What happens if my Project is not Under Version Control?

Altium NEXUS’s collaborative PCB design capabilities use a Version Control System at its core, providing the mechanism needed for individual designers to be able to work independently, yet bring their independent efforts together when needed. To fully utilize Altium NEXUS’s Collaborate, Compare and Merge features each designer must be working on their own copy of the same project, checked-out from the same repository. The reason for this is that the repository is the central pivot point - by communicating with the repository, Altium NEXUS is able to establish the status of each revision of the board that each designer has checked out, and then offer commands that can be used to compare to detect differences, and then merge those differences if required.

If you are working on a board that is not under version control, you can still use the compare and merge features. In the Actions section of the Collaborate, Compare and Merge panel, use the Click to show differences against any PCB Document command to find differences between the current board and any other board. Note that you will not have access to the Live Collaboration features if the board is not under version control.

Found an issue with this document? Highlight the area, then use Ctrl+Enter to report it.

Contact Us

Contact our corporate or local offices directly.

We're sorry to hear the article wasn't helpful to you.
Could you take a moment to tell us why?
200 characters remaining
You are reporting an issue with the following selected text
and/or image within the active document: