Copy of A Walk Through...the Board Design Release Process Language Japanese Contents
Design Project - Initial Preparation Create a New Design Repository Add Your Project to the Design Repository Connect to an Altium Vault Define Structure and Create Items PCB Project Configurations and Output Job Files Define Output Job Files Specify Output Locations Define PCB Project Configurations Release a Configuration of the Design Access Released Data
Parent article: Vault-Driven Electronics Design Altium's Design Data Management system includes a range of technologies that combine together to allow you to pass data from the design domain to the production domain in a pain-free, streamlined, and automated fashion - generating data output of the highest integrity. A key element of this system is a powerful board design release process. This process is automated, enabling you to release your design projects or, more specifically, defined configurations of those projects, without the risks associated with manual release procedures. When a particular configuration for a project is released, a snapshot of the design source is taken and archived along with any generated output. Release data is stored as a revision of a specific Item in a target Altium Vault. The Item is the entity within the vault to which the configuration is mapped, and which represents the physical object that will be 'realized' by the supply chain. In this article, we will take a look at how you prepare the system for release of your board design, how you initiate a release, and how you can 'get at' your generated release data upon successful completion of a release. Tutorial-like, but not rigidly so, think of this article as more of a conversational 'walk through' of the system - providing an overview of the system's key elements and how they are defined, with links out to more in-depth articles as and when appropriate. Although not strictly a pre-requisite, it may be a good idea to have a cursory read through the various sub-articles of the main Vault-Driven Electronics Design article which provides information on not only the key concepts and terminology of the system, but also the benefits to using it, over and above your traditional board design release methods. Before getting started, you should install TortoiseSVN or a similar Subversion browser interface, if you intend to create folders in your Design Repository as described in the section Add Your Project to the Design Repository. If you have not installed Tortoise you will still be able to continue, however you will not be able to create subfolders in your Design Repository as outlined in Step 1 and referenced in Steps 4 & 5 of that section. TortoiseSVN can be downloaded from http://tortoisesvn.net/downloads. Design Project - Initial Preparation The first thing is to ensure that your design project is added to a version control repository, or Design Repository. Of course, you can still release a design project that is not under version control, but by using a version-controlled Design Repository, you have the integral assurance that no revision of a design is ever lost, allowing for safe collaboration on the same design between members of a team that can be geographically diverse in their locations. The very nature of the version control system provides an audit trail for the design. Full accountability arises through transparency of who changed what, in which source document, and when. If your project is under version control, then the system requires all files to be checked in and up to date before releasing. This ensures that no "private copy" of an essential design document is ever allowed to sit on an engineer's hard drive - with the potential of becoming lost. This simple rule can save hours down the track in costly searching for the right set of design documents that were used to generate a released product. Create a New Design Repository Altium Designer supports version-controlled Design Repositories using either Subversion (SVN) or Concurrent Versions System (CVS) as the service provider. Subversion is the preferred provider and Altium Designer, true to its unified nature, comes with Subversion capabilities built-in. To quickly create a new folder-based SVN Design
Repository: 1. Open the Preferences dialog 2. On the Data Management Version Control page, you will see that SVN - Subversion is an enabled version control provider, and that the built-in Subversion is enabled for use by default. 3. On the Data Management Design Repositories page, click the Create New button and choose the SVN e ntry on the associated drop-down menu. Use the Create SVN Design Repository dialog that appears to give the vault a meaningful name and specify the location for the repository. If a folder is specified that does not currently exist, it will be created for you. Example newly created SVN Design Repository, appearing within Altium Designer as Main Design Repository. By creating a repository in this way you are, in effect, registering that repository with the system telling Altium Designer of its existence as it were. Furthermore, there is no manual specification of paths to unofficial or 'rogue' repositories. Through Altium Designer, you can only interact with those VCS-based Design Repositories you have purposefully connected to the system. Add Your Project to the Design Repository Related articles: Understanding Version Control - an Introduction, Using Version Control in Altium Designer With your centralized storage repository your Design Repository created, you now need to add your design project and any dependencies (e.g. device sheets, harness definition files, annotation file) to the vault. This can be performed using version control commands from within Altium Designer from the Storage Manager panel or Projec ts panel or externally, from within the repository itself.
For this walk-through, let's add the reference design project for the PB02: 1. Open the \Examples\Reference Designs\Peripheral Boards\PB02 Mass Storage\PB02.PrjPcb example project 2. Right-click on the project in the Projects panel and choose Version Control»Add Project Folder To Version Control 3. The Add to Version Control dialog that appears presents a drop-down listing of all connected and activated Design Repositories. Select the repository we just created Main Design Repository. Click the butto n at the right of the field to quickly access the Data Management Design Repositories page of the Prefere nces dialog if you need to connect a different repository or create a new one. The folder hierarchy within the chosen Design Repository is presented to you in the Folders region of the dialog. Either specify an existing folder into which to add the design files, or create a new folder using the New Folder button. In the latter case, a folder will be added at the specified position within the repository's folder hierarchy, named using the project name. Specify the folder within the repository to store the project. 4. With the target folder specified, click OK you will be presented with a second Add to Version Control dialog. Simply select the files to add to the repository and click OK. The Projects panel will now show that the
project and files are Scheduled for addition, denoted by a blue cross icon ( ). The project files are now in a state to be committed to the Design Repository. 5. Now right-click on the project in the Projects panel and choose Version Control»Commit Whole Project. You will be presented with the Commit to Version Control dialog. Simply select the files you wish to commit to the Design Repository and click OK. Once added, the Projects panel will reflect the fully synchronized state
that exists between the files in the repository and the local working copy. Example project added to the created Design Repository, in this case the PB02 reference design. Connect to an Altium Vault Related article: Altium Vaults With the project added to the Design Repository, we can go ahead and connect to an Altium Vault. An Altium Vault is simply a centralized storage system into which all release data for each target Item is stored. In the vault, each Item is stored as a series of revisions. Each revision contains documentation, generated at release time, that is inclusive of detailed instructions needed to build that specific Item. Each time a new release of the design data for a particular Item is required, a new revision of that Item is created in the vault, ready to accept (store) the generated data. To connect to an Altium Vault: 1. On the Data Management Vaults page of the Preferences dialog, click the Add Vault button the Connec t To Vault dialog will appear. Enter the URL for the vault you wish to connect to in the Vault Server Address field. A vault that has been installed on your Local Area Network can be quickly discovered by clicking the Fin d Vaults on LAN link. As well as the address of the vault server you must also enter a username and password. These will be checked by the authentication server (providing the Identity Service), to ensure you have rights to access that vault. Your standard AltiumLive credentials will be pre-filled and used. Should you wish to access the vault using alternate valid credentials, you can do so by enabling the Use Alternative Credentials option and entering those credentials accordingly. 2. You can test whether a connection is successful prior to adding it, by using the Test Connection button. With a successful connection, you can go ahead and click OK. A connection to the vault from Altium Designer is made, provided you have access rights and your login details are authenticated as being valid. An entry will appear for it in the listing of vaults back on the Data Management Vaults page of the Preferences dialog. The vault will be enabled by default ready for use.
The name of the vault listed in the the Data Management Vaults page of the Preferences dialog is initially provided by the vault. This name can be changed by right-clicking on the vault entry and selecting Edit Vault Properties from the context menu. In the dialog that appears, simply change the name as required. Example of a connected Altium Vault, appearing within Altium Designer as Company Vault. Should you wish to quickly add connections to vaults that are part of the AltiumLive ecosystem, and to which you have authenticated access to, you can do so by clicking the Add Content Services button. This will give you access to the Available Vault Services dialog. The dialog presents vaults running within AltiumLive. To connect to one of these vaults, simply enable the Click to Connect option beneath the vault's icon, which will change to Connect. Clicking OK will add that vault to the list of vaults back on the Data Management Vaults page. Define Structure and Create Items Related article: Vaults Panel Having connected to an Altium Vault you now need to define it, in terms of its internal structure and the various Items it is to contain the data for. In terms of releasing a board design, these will be Items representing the Blank Boards and Assembled Boards that you will ultimately manufacture. Interaction with a vault is performed through the dedicated Vaults panel. This is a system panel (accessed from the System panel-access button at the bottom-right of the main design window) that enables you to browse and manage your connected vault(s). You can also create folders and/or Items in a vault at the time of defining the configurations for your board when choosing which Item to map a configuration to.
Interact with a connected Altium Vault through the that reside within. Vaults panel. The panel allows you to define the structure of the vault, and Items In the Vault Folders region of the panel, use commands on the right-click menu to define a series of folders and sub-folders in which to organize Items bringing a sense of logical order to the world. Items themselves are created using the Create Item command, on the right-click menu for the Items region of the panel. Before you can create a new Item within a vault, you need to create a folder into which that Item can reside. You must therefore have at least one folder defined in the vault. For our PB02 design project, we will create two Items one to represent a blank board and one to represent an assembled board. Let's go ahead and define a folder structure: 1. Right-click inside the Vault Folders region of the Vaults panel and choose the Add Top Level Folder» altium-production-release-zone command to define a top-level category in the overall structure. The Add Top Level Folder dialog will appear, from where you can enter a meaningful name for the category. As this folder will ultimately hold the data for all board designs that are released, let's call it Production. 2. To add depth to the structure, simply right-click on an existing folder and choose the Add Subfolder» generic-folder command. Use the Add Subfolder For FolderName dialog to name this new folder, perhaps an umbrella term that reflects the relationship of the Items that will be stored beneath. Let's call it Periphera l Boards. 3. 4. As we might want to release data from different peripheral board designs, it can be a good idea to have a distinct sub-folder per peripheral board. So let's add a sub-folder called PB02 - Mass Storage. As each product will consist of at least one fabricated bare board Item and at least one assembled board Item, it can also be a good idea to create further sub-folders for these types of board. It will be these lowest level folders into which the required Items will be created. Let's add further sub-folders called Blank Boards
and Assembled Boards respectively. Folders defined ready within the vault. By using the concept of top-level 'zones' of content within a vault, you can have separate areas for component management, design content management and production release data. Having defined folders within the vault as required, you can proceed to create Items in the vault. To create an Item, simply click on the folder into which you wish to effectively store the Item, right-click in the Items region of the panel and choose the Create Item command. A further sub-menu will allow you to choose the particular type of Item, based on the type of data content it is to hold. The Create Item dialog will appear, providing all controls necessary to fully define the Item.
Create and define an Item using the Create Item dialog. The key property for an Item that we are interested in at this stage is the Item ID the unique ID for the Item. It is through this ID that a configuration of a project on the design side is able to be mapped to the target Item in the Altium Vault. The ID itself is typically a code, in accordance with established naming conventions. For example D-81 0-XXXX is used at Altium to reflect a fabricated Blank Board Item, while D-820-XXXX reflects an Assembled Board Item. The Item ID can not be changed after the Item is created. Let's go ahead and create the two Items for the PB02 design: 1. Click on the Blank Boards folder in the Vaults panel, then right-click in the Items region and choose Creat e Item» altium-pcb-blank. For the Item ID, enter D-810-2000. Change the Revision Naming Scheme an d Lifecycle Definition as required. For this walk-through, let's change the Revision Scheme to be 3-Level Revision Scheme and the Lifecycle Definition to be Structure Lifecycle With Approvals. Let's also add a description Blank Board for the PB02. Leave all other fields at their default settings. 2. Click on the Assembled Boards folder, then right-click in the Items region and choose Create Item» altium-pcb-assembly. Repeat the process above, but this time enter an Item ID of D-820-2001 and a description of Assembled Board for the PB02. We now have our Items defined ready in the vault, each with an initial revision, sitting in the Planned state ready
to accommodate release data! Items created, defined and with initial planned revisions to accept data. PCB Project Configurations and Output Job Files With the project in the Design Repository, it s now time to prepare it for the release management system but before doing so it s important to understand just how the data in the design maps to the outputs required to manufacture the items you want to produce. This is managed through a concept known as the PCB Project Configuration. Put simply, a PCB Project Configuration, or simply a Configuration, is used to map the data in the Design Area to the Item we want to produce. Each of these Items is uniquely identified by an Item ID, and each Item corresponds to the sort of thing one might expect to find on a product-level bill of materials such as a bare board, assembly, and different assembly variants. Each are examples of different Items and each would have its own unique Item ID.
The PCB Configuration serves as a blueprint to map the data in the Design Area to the files required to produce some specific item. The Configuration allows us to define the blueprint by which the source data in our project is converted to the outputs required to manufacture each unique Item. Each project therefore will generally have at least 2 configurations, one for the bare board and one for the assembled board. Different assembly variants would also each have their own configurations and thus map to their own unique Items. The use of configurations requires a change in the way Output Job files are managed in a project. Where historically Output Job files might contain all of the outputs you want to produce, defined in a single *.OutJob file, for the release management system it s best practice to separate assembly and bare board outputs into at least 2 (or more) output job files (with each file containing only the outputs specific to the type of finished goods whether bare board or assembly that you want to produce). Also, because the release management system supports validation of the design, as a part of the release process, it s recommended you have at least one Output Job file that specifically defines the validations you d like performed on the design while running the release flow. Define Output Job Files Related article: Content and Use of the Output Job Editor Taking the PB02 reference design project, which has a single Output Job file defined ( PB02_Panel.OutJob), let's instead define the following three distinct Output Job files: Assembly.OutJob to cater for assembly-based output Fabrication.OutJob to cater for fabrication-based output Validation.OutJob which we will use to generate ERC, DRC and a Differences report. Simply save the existing file with one of these new names, then add two additional Output Job files to the project once the output generators are defined as required in each, ensure to commit the changes from the local working folder back into the master fileset in the Design Repository!
Separate and distinct Output Job files, including one that defines validation reports that will be run during the release process. Specify Output Locations Related article: Enhanced Output Path Definition in Output Job Files The outputs defined in an Output Job file can be published into various types of output container, depending on the type of media being published. When publishing to PDF, generating files, or generating video, you have advanced control over where the outputs generated in these containers are located.
Accessing output location controls, in this case for a PDF output container. To have the Design Data Management system control the base path of the output container location for you, ensure that the base path is set to [Release Managed]. This is especially required if you want to make use of validation report generation as part of the release process. Define PCB Project Configurations Related article: PCB Project Configurations So where are we up to. We have our PB02 design project resident in a version-controlled Design Repository. We have our target Items defined and sitting ready in our Altium Vault. We need some way of mapping our design project to those Items. Remember, a PCB project is parametric in nature, enabling a single design project to be the source of multiple real-world production Items the tangible products that are made and sold. Providing a formal configuration structure, to map from source PCB project to these Items in the vault, Altium Designer employs the concept of PCB Project Configurations. Configurations are part of the actual design project and provide the link from the design world to the manufacturing world. Each configuration represents an Item that we want to build in the real world, defining the data that will be required by the supply chain to actually build that Item. When we release a design project, we are in fact releasing a configuration of that project. The generated 'release data' is stored in a revision of the target Item specified as part of that configuration. All definition and management of configurations for a PCB project is performed from within the Configuration Manager dialog ( Project»Configuration Manager). Initially, there are two default configurations defined, one for a blank board and another for an assembly, as shown below. Initial appearance of the Configuration Manager for the PB02 reference design. First things first, we need to specify a target Altium Vault release data could be stored in any vault, and if we had multiple vaults defined, we need to make sure that the design references the correct vault. Simply use the drop-down at the top-right of the dialog to select your Altium Vault. In this example, the name of the vault as seen by Altium Designer is called Company Vault. Select the name that you have given your particular vault.
If you have not connected to a vault, or need to connect to a different one, simply click the button to access the Data Management Vaults page of the Preferences dialog, from where you can manage connections to vaults as required. Targeting the required vault. Now we need to define the configurations that we need for our project, and specify the target Items that they are to map to in the vault. The Configuration Manager dialog is divided into configurations on the left, that map to target Items on the right. Each unique configuration must map to a unique Item in the target vault. We require two configurations one that will be used to generate data to make a target Blank Board Item, and one that will be used to generate data to make a target Assembled Board Item. Let's consider the configuration needed for the blank board: 1. On the left side (Configuration), rename the existing default configuration to Blank Board and leave the option to Ignore Variants enabled. For the blank board configuration, we need to assign the Fabrication a nd Validation Output Job files, and so simply check their corresponding check boxes. Defined configuration needed to generate the data to build the fabricated bare-board. 2. On the right side (Target Item), we need to specify which Item in the vault is to be "built" using the data generated from the configuration at release time. Click on the button at the right of the field. This will give you access to the Choose Item dialog. This dialog essentially presents a view of the target vault, and allows you to drill down within the folder structure you have defined to the particular Item you want to map the configuration to. Choose the Item D-810-2000 in the Production» Peripheral Boards» PB02 - Mass Storage» Blank Boards folder. Note that if you hadn't created an Item already in the vault, you
can do so through this dialog, on-the-fly as it were. Mapping the Blank Board configuration to the blank board Item ( D-810-2000) defined in the vault. 3. In order to release a configuration, the revision of the Item into which the release data is to be stored must be in the Planned state. That is, it must be ready to accommodate that release data. Use the drop-down list associated to the Target Planned Revision for Next Release field to choose a planned revision to use. As our Item only has a single planned revision, it will be chosen automatically 01.A.1. Now we need to define a configuration (and the Item to which it maps) for the assembled board: 1. On the left side (Configuration), rename the configuration to Assembled Board and leave the option to Igno re Variants enabled so we use the full complement of components in the design, and not a subset. In terms of Output Job files for this configuration, we need to assign the Assembly and Validation files, and so simply check their corresponding check boxes. 2. On the right side (Target Item), we simply repeat the previous process of specifying the target Item to map the configuration to, and a planned revision of that Item to use for the release. Specify the Item to be D-820-2001 the revision field will automatically be filled with the initial planned revision, 01.A.1. Our two configurations for the PB02 design project are now fully defined, and mapped to planned revisions of the unique Items we have created in the vault.
Our configurations for the PB02 design fully defined! One final thing to do before we proceed to the PCB Release view and ultimately to the release process itself, and that is to SAVE AND COMMIT LOCAL CHANGES TO THE DESIGN REPOSITORY. The importance of this cannot be stressed enough, and this is why the system requires all files to be checked in and up to date before releasing. Of course, you can synchronize at any stage and the PCB Release view will chase you about it, but it is good to get into the habit of committing changes at the time you make them. Release a Configuration of the Design Related article: PCB Release View The PCB Release view ( View»PCB Release View) is the graphical interface to Altium Designer's PCB Process Manager used to perform the board design release process and presents a high-level 'Dashboard' that operates in two modes: Design Mode and Release Mode.
Initial appearance of the PCB Release view showing our PB02 design project. The view shows a single tab for our project ( PB02) and two sub-tabs for each of the configurations we have defined for that project ( Blank Board and Assembled Board). Let's look at releasing the Assembled Board configurati on click the tab for this configuration to make it the active configuration. We have already synchronized our local working copy of the project with that in the Design Repository, and specified the target Item in the vault that the Assembled Board configuration is to map to including a specific planned revision of that Item. The PCB Release view, initially in Design Mode, reflects that our project is synchronized with version control in the Design Repository region, and in the Vault region, the revision of the Item referenced in the active configuration is indeed ready to release. Everything is in a 'green state' ready to release. Green on both Design Repository and Vault sides - good to go! Each configuration has an associated Process Flow. In its entirety, this flow represents the board design release process getting the design from the Design Repository, processing the chosen configuration of it, and committing generated release data into the referenced Item (and revision) in the nominated vault. Notice that only stages 2 and 3 of the flow are active and enabled in Design Mode Validate Design and Generate Outputs. These two stages are the 'meat' of the flow and their successful running is crucial to the board design release process. If either of these stages fails, the release fails simple as that. So within Design Mode, access to these stages gives you arguably the most valuable pre-release checking aid possible.
The Validate Design stage is optional in the release process it is included only if you have defined validation outputs as part of an Output Job file assigned to the configuration being released. You have the option to trial run the validation and output generation stages while in will pass muster with checks such as ERC and DRC, and that those generated files are all as they should be to get the Item built as you designed it! 1. Click the Generate Outputs stage of the flow. This will run the Validate Design stage, followed by the Gener ate Outputs stage. The state in each output's Status field will reflect when that output is running and then the result once generation is complete. 2. Design Mode - one last check that the design If any failures occur, simply return to the source design document(s) and fix the cause of the problem accordingly. For our PB02 design, both stages pass with flying colors. All outputs are generated successfully validations all Pas sed and other outputs are Up To Date. Success is therefore guaranteed with respect to these stages when running the flow in Release Mode. Successful trial run in Design Mode! So let's go ahead and perform the actual release. 1. Click to select Release Mode, in the center of the PCB Release view. Once in this mode, everything becomes locked down. Only the chosen configuration of the selected design project remains enabled, with all other projects and configurations disabled (dimmed). You cannot select a different configuration or jump to another project in this mode. At this point, all attention is fixed on releasing the chosen configuration with the
highest integrity. Once in Release Mode, only the chosen configuration is available to interact with. 2. To initiate the release of the Assembled Board configuration of our PB02 design project, simply click the C ommit Release button. Initiate the actual release literally at the 'click of a button'. Each stage of the process flow is run in sequence a snapshot of the design source is taken, validated, and the outputs defined in Output Job files assigned to that configuration are generated. The resulting generated data, as well as the snapshot, are then committed to the target vault. Upon committal, the Release Summary dialog will appear, providing a listing of the data that has been stored in the specified revision of the target Item in the vault.
Successful release of the Assembled Board configuration of the PB02 design! As the process is fully automated, the risk of errors associated with a manual release process are no longer a consideration. Full validation, full checking. The data sent to manufacturing is exactly what it needs to be, to produce the product exactly as you designed it. As our PB02 design project is stored in a version-controlled Design Repository, during the release process Altium Designer records the version control repository address and revision of the project and commits this information to the target vault. This method means that at any point in the future it is possible to retrieve an identical snapshot of all files in the design project from version control. Access Released Data Related articles: Managing the Item's Revision and Lifecycle State - the Item View, Item Lifecycle Management Once released, you can preview the generated data for the specific Item Revision from within the Vaults panel. The Preview tab presents a list of released documents, the snapshot of the design project used to generate the release and the generated Bill of Materials (BOM) that will be used to physically manufacture that board.
Preview the generated data for the newly released revision of the target Item in the vault, courtesy of the Vaults panel. Controls available from the right-click menu enable you to quickly download or publish data, as well as compare two revisions of the same parent Item. A more detailed, structured view of the lifecycle of an Item is presented in a dedicated view for that Item known simply as the Item view. This view is accessed by: Right-clicking on an Item entry in the Vaults panel and choosing Full Item Details from the context menu. Clicking on the header text in the Vault region ( Revision <Revision ID> of <Item ID> ) of the PCB Release view, to quickly access the detailed Item view for that Item, with the indicated revision focused. Item view for our target assembled board Item D-820-2001. The Item view provides an intuitive user interface by which to visually assess the state of the Item and its revisions.
Controls are provided that allow you to: Browse dynamically through the timeline of the Item, from initial release of data into the first revision, to the latest revision, and all revisions and state changes in-between. Establish a new 'Planned' revision/prototype/model of the Item. Manage the lifecycle state for a particular revision of the Item, in accordance with the lifecycle definition employed for revisions of that Item. Compare a selected revision with a second, ancestor or descendant revision. Retrieve documents associated with each revision of the Item (generated release data and/or design snapshot). Publish release data directly to a nominated publishing destination. For any revision of the Item, the view presents a preview listing of released documents, identical to that presented in the Vaults panel. Altium Designer supports the ability to publish released documents generated output from Output Job files assigned to the released project configuration for any Item Revision, to a storage space, such as Amazon S3, FTP servers and Box.net. Before you can publish data, ensure you have defined a connection to the required publishing destination. This is performed from the Data Management Publishing Destinations page of the Preferences dialog ( DXP»Preferences). For more detailed information, see Publishing Destinations.