Beruflich Dokumente
Kultur Dokumente
The ability to place components directly from a database using a Database Library (*.DBLib) already offers great flexibility and control. Extending this method of linking to allow source-controlled libraries housing the schematic symbols and footprint models lifts library and component management to a higher level still. The source libraries are created, added-to and maintained, within a Subversion-based repository. The link to the repository and to the external database is defined within an SVN Database Library file (*.SVNDBLib), an extension of the Database Library file (*.DBLib) and often referred to as a Version-Controlled Database Library.
Summary
This application note provides detailed information on placing components from a database using Altium Designer's SVN Database Library feature.
Before proceeding further in this document, you should familiarize yourself with the fundamentals of the database library feature by reading the Using Components Directly from Your Company Database application note. Indeed, many of the areas discussed later assume prior knowledge gained from reading this document.
Librarian or Designer?
There are essentially two modes in which you can work with a version-controlled database library as a Librarian, or as a Designer. The use of these roles will differ from company to company. A larger company may have a dedicated library center which will, in the role of Librarian, solely be involved with the setup and maintenance of the symbol and model libraries in the source control repository and the generation of the SVN Database Library file(s). The SVNDBLib file(s) will then be made available to the Designer(s) within that company, who will install and use the library files from which to place the components in their designs. In a smaller company, both roles may be filled by the same person. Not only will that person setup and maintain the repository of libraries, but will also use the defined SVNDBLib to carry out the design. The following sections consider the role of the Librarian and Designer in greater detail.
Altium Designer in no way prohibits a Designer from performing Librarian-based activities. Access rights/permissions defined for the source control repository will ultimately define how far the Designer can drive the Librarian 'car'. For example, the Designer may be able to checkout, open and modify a library, but is prevented from committing the change to the repository.
Working as a Librarian
As a Librarian, not only will you need to set up and maintain the external source control repository of symbol and model libraries, but you will also be responsible for setting up the SVN Database Library file. This entails: Connecting to the external component database. Defining database record to component parameter/model mapping. Specifying the link to the SVN repository in which the symbol and model libraries are stored.
The following sections discuss the repository, configuration of the SVNDBLib file, and also how changes to symbols and models in the repository-based libraries are made.
marked by the version control system as having been modified. Having one symbol/model per library file plays to the nature of version control, while allowing you to keep track of exactly what has been modified and what has not. For the purposes of this document, it is assumed that the repository has already been created. For more information on the use of the particular SVN client you are using, refer to the relevant documentation associated with that software. For more information on version control, refer to the Working with a Version Control System tutorial. When reading this document, remember that for a version-controlled database library, the source control system used must be Subversion.
In Altium Designer, ensure that the Provider, on the Version Control General page of the Preferences dialog, is set to SVN Subversion. Use the Auto Detect Subversion button to quickly fill the path fields to the required SVN executables.
The subsequent page of the Wizard allows you to specify the output directories into which the (split) individual symbol/model libraries will be placed.
By default, the output directory will be set to the same directory in which the source library is stored. As the split library files will be added to the SVN repository, it can be a good idea to setup the folder structure that you want in the repository in terms of the symbol/model files locally on your hard disk. Once the structure is defined, copy the source libraries to their respective folders within that structure. You can then just leave the output directory settings for each source library at their defaults. After the split, the generated single library files will already be in the correct locations. You can then simply delete the original source library from each folder and add the folders to the repository, using the SVN client you have decided to use.
Care should be taken if the original source libraries are stored in the same source directory folder. If the output directories are not specified and are left at their defaults pointing to the same source directory folder you can end up with a very large mixture of single symbol and model libraries. Sifting through these when creating the repository structure may prove very time consuming.
The Wizard provides additional options to control how the source libraries are split. For a schematic component library, two options are provided that allow you to strip the parameter and/or model information from each constituent component leaving just the bare symbol. An option is also provided to deal with the situation where an output directory already has libraries in it. You can set this option to: Overwrite Existing Files with this setting, existing libraries will be overwritten by newly split libraries of the same name. Append Incrementing Number To File Names with this setting, the Wizard will scan through the list of output directories to build a list of existing files to be protected. Each potential split library with the same name as an existing library will be appended with the suffix _n (where n is an integer, starting from 1).
Once the source libraries and options have been specified the Wizard will perform an analysis, the result of which is the set of single symbol/model libraries that will be created, listed for you to review. The name of each split library to be generated is shown, as well as the actual name of the schematic component/footprint model/PCB3D model within that library. The original source library is also listed. The name used for a library will be the same as that used for the constituent component/model. If any of the following characters have been used in the component/model name, they will be replaced by an underscore when creating the library name: .
Figure 3. Reviewing single libraries to be created.
! ' [ ]
Review the list of libraries to be created and then click Next to proceed with the splitting process and ultimately obtain the libraries to be added to the source control repository.
The SVNDatabaseLib Editor becomes active when the active document in the main design window is a *.SVNDBLib file. Create a new file of this type by using the File New Library SVN Database Library command.
The connection to the SVN repository is defined on the SVN Repository tab of the Database Library Options dialog (Tools Options). Figure 5 shows an example connection to a web-based server, where the parent repository folder has the following address: http://ares/svn/Altium
Use the dialog's 'What's This Help' feature to obtain detailed information about each of the options available. Simply click on the question mark button at the top right of the dialog and then click over a field or option to pop-up information specific to that field or option.
Matching Criteria
After successful connection to the external database, table and mapping data will be loaded. For each table in the database, you will need to define matching criteria the parameter field (or fields) used to create and maintain the post-placement link between the schematic component and its source database record. Once again, matching criteria is defined in exactly the same way as for a DBLib file.
When mapping symbols and models for an SVNDBLib file, path information in the external database is optional. If such path information does exist, it should be mapped to the respective Design Parameter entries ([Library Path] and [Footprint Path]). Linked PCB3D and simulation models are currently not supported for an SVNDBLib. All other database field names will be automatically mapped to design parameters using the same names. Change parameter naming on the design side, or specify database fields to not be mapped as required. For more information, including the definition of parameter update options, refer back to the Model and Parameter Mapping section of the Using Components Directly from Your Company Database application note.
It is important to stress that the symbols and footprints must reside within the base repository directories specified. They can of course be in sub-folders of those directories and the paths specified for both symbols and footprints can point to the same directory in the repository. The following methods can be used to locate the required symbol and footprint model within these nominated base directories:
Absolute Path the full path to the location of the library can be entered into the database. (e.g. http://ares/svn/Altium/SVNTest/SchematicSymbols/Capacitor_NonPolarized.SchLib). Relative Path a relative path (relative to the root of the repository) to the location of the library can be entered into the database. The URL for the repository specified on the SVN Repository tab of the Database Library Options dialog will be prefixed to the path you enter, to give the absolute address. Considering Figure 6 for example, if you specify /SVNTest/SchematicSymbols/Capacitor_NonPolarized.SchLib, the full path will be http://ares/svn/Altium/SVNTest/SchematicSymbols/Capacitor_NonPolarized.SchLib. Filename Only you can simply specify the name of the library in which to find the required symbol or footprint, again within the database record for the component. The first file found with this name will be used. (e.g. Capacitor_NonPolarized.SchLib). No Path Information you can opt not to enter any path information in the database record for the component. When locating the symbol/footprint, the system will initially look for the first library named like the symbol or footprint itself. For example, if the logical symbol name in the database (specified by the [Library Ref] mapping) is DIOSCHOTTKY-2S, the system will look for the first file named DIO-SCHOTTKY-2S.SchLib and look for the symbol within this file. If the symbol/footprint cannot be found in this way, the system will look for a match in all libraries.
When searching for a symbol/model match, the flattened folder paths in the base symbol or footprint directory are sorted and searched alphabetically. If the Library Splitter Wizard is used, there will always be a corresponding library with the name of the actual symbol/footprint.
If you have defined fields in your database for symbol and footprint path information, these fields need to be mapped to the appropriate design parameters [Library Path] and [Footprint Path] respectively.
Not specifying library path information in the database makes it much more robust. The repository location and/or its internal folder structure could be changed and the database would not need to be updated.
Figure 9. Verifying the edit in both Table Browser (SVNDBLib) and database table (MDB).
The folder nominated as the local working directory should only be used to contain a copy of the version-controlled files. Other files, such as SVNDBLib, MDB, XLS, should be located in a different directory, as these are not under version control.
To quickly check out all symbol and footprint model libraries from the repository into the nominated local working folder, simply run the Check Out All Working Folders command from the SVNDatabaseLib Editor's main Tools menu. Figure 12 illustrates the result of such a checkout, with all files and folders in the local workspace linked and up-to-date with the content of the repository.
The folders checked out will be those specified in the Models Location region, on the SVN Repository tab of the Database Library Options dialog.
Figure 12. Checkout of repository folders and files to the Librarian's local workspace.
Figure 13. The Storage Manager panel reflects the Librarian's local working folder.
To open a library file for editing, simply right-click on its entry in the All Files region of the panel, and choose Open from the context menu that appears. Make changes as required and save the file as normal using the associated Editor's standard Save command. A library can also be opened for editing using one of the following methods: With the SVNDBLib file active, right-click on a component's record entry, on the Table Browser tab, and choose to open either the schematic symbol or the footprint model.
With the SVNDBLib added to the Available Libraries, simply browse (using the Libraries panel) to the target component within the linked database, then right-click on its entry and choose to edit either the schematic symbol or the footprint model.
Use the library Editor's File Open command to browse to and open, the required library in the local work space. Drag-and-drop the library file from Window Explorer directly into Altium Designer.
10
Figure 14. Refreshing the status of the local working copy of the files.
Refreshing the status of the source libraries becomes even more important in a multi-librarian environment, where several people may be responsible for maintaining the repository of source symbol and model files. When the local copy of a library is identical in revision to that of the repository, the status will display as No modification. You are free to open the file and make modifications. If the status for a library is Out of date, you will need to get the latest version of the file from the repository updating your own local working copy before you can modify and commit your own changes. Use the Update command to do this (available from the same right-click menu for the region).
Within Altium Designer, the controls for committing to, and updating from, the repository are solely available through the Storage Manager panel. You can of course commit and update outside of Altium Designer, using your SVN Client software.
When you have made and saved changes to a library, the status will change to Locally modified by me. To push your local changes into the repository, simply right-click on the file's entry and choose the Commit command from the context menu. Once checked in to the repository, the status will return to No modification. For more detailed information on the Storage Manager panel, press F1 when the cursor is over the (focused) panel.
Once the Compare command is invoked, the two selected document revisions will be opened in the workspace, the graphical comparison is made, and any differences detected between the two will be listed in the Differences panel. It is a good idea to have the two documents open side-by-side in the workspace, to easily peruse the differences.
11
Browsing Differences
Figure 15 shows an example of differences detected between two revisions of the same library file (a schematic component library).
Differences are listed in a hierarchical fashion. The top-level entry lists the number of differences detected. For libraries, this is the number of matching parts that are found to be different between the two revisions. For source libraries associated with an SVNDBLib where there is only one symbol/model per file this entry will always be 1. The next level down lists the parts found to be different. The entry marked by a red cross icon shows the matching parts that are different. The sub-level entries correspond to that part on each separate document. Again, with a library associated with an SVNDBLib, there will only be one matching component. The next level down lists the actual graphical differences between the parts or, put another way, the objects causing the differences. Again, an entry with a red cross reflects the matching object found to be different. The sub-level entries correspond to that object on each separate document. Clicking on the top-level entry for a detected difference denoted by the red cross icon will highlight that difference on both documents simultaneously (Figure 16). Click on the subentry for an object to highlight it on its parent document separately.
12
Working as a Designer
As a Designer, you will take the SVNDBLib file generated by the Librarian and make it available in the Libraries panel by adding it to the Available Libraries list (Figure 17).
Figure 17. Making the SVN Database Library available for use.
The Libraries panel becomes a 'browsing window' into the linked external database. Browsing database components and searching for specific components is performed in the same way as for an installed DBLib. For more information, refer to the sections Browsing the Database Components and Searching for a Component, in the Using Components Directly from Your Company Database application note.
Localized Cache
When the SVNDBLib file is added to the Available Libraries list, the symbol and model libraries in the repository are cached in a temporary folder, local to the Designer's computer. When an action in the software calls for the use of a schematic symbol or model, that symbol/model is retrieved from the local cache.
Although the update is automatic, it Figure 18. Setting the local cache 'update timer'. can be controlled by the use of an option available on the Version Control SVN Libraries page of the Preferences dialog (Figure 18).
Version (v1.2) Apr 21, 2008
13
This option essentially provides an update timer for the local cache. If the specified time has elapsed since the last time the cache was updated, then the cache will be updated automatically when one of the listed actions is performed. If an action is performed within this time, the current content of the cache will be used, which may be out of date compared to the content in the repository.
Placement
Placement is performed as it is for any other library loaded and available in the Libraries panel. With the target schematic sheet open as the active document in the main design window, simply select the component you want to place from the Libraries panel and either click the Place button or drag-and-drop the component directly onto the sheet. The component is built on-thefly, with the following actions taking place: The schematic symbol is retrieved from the relevant schematic component library in the local cache. Any referenced footprint model is linked in. The design parameters specified in the SVNDBLib file are added (in accordance with the associated Add To Design update setting) to the component.
After placement, double-click on the component on the schematic to access its properties dialog (Figure 19). You will see the design parameters added to the Parameters region of the dialog, the linked models added to the Models region and this Library Link region.
This region provides the following information: The parent SVN Database Library file The specific database table in which the component resides The value for Design Item ID (Component Name / Part Number). This is the chosen key field defined in the Field Settings region of the SVNDBLib file, and is typically the part number.
You can change the placed component to another from the same table by clicking the Choose button. This will open the Browse Libraries dialog, initially listing all components in the same table. In fact, you can change to a component in a different table of the same SVNDBLib file, or browse to one in a different SVNDBLib file altogether. The region will update accordingly with the new information for the chosen database component.
Post-Placement Maintenance
After placement, the chosen key parameter in the SVNDBLib file is used to ensure that the placed component on the schematic retains its link to the corresponding record for that component in the external database. This means that at any stage in the future, changes to parameter and model information in the database can be easily passed back to the placed component, synchronizing the two.
In the PCB Editor, use the Tools Update From PCB Libraries command to update placed footprints with the latest information stored in the source libraries.
If you simply want to update parameter information, use the Update Parameters From Database command, available from the Schematic Editors main Tools menu.
14
To perform a full update, including parameters, model and graphical attributes of schematic symbols, use the Update From Libraries command (also available from the Schematic Editor's main Tools menu). For further information on using the various update tools, refer to the Keeping Components Up-To-Date application note.
15
Revision History
Date 20-Jun-2006 14-Jun-2007 21-April-2008 16-Mar-2011 Version No. 1.0 1.1 1.2 Revision Initial release Updated for Altium Designer 6.8 Updated Pagesize to A4. Updated template.
Software, hardware, documentation and related materials: Copyright 2011 Altium Limited. All rights reserved. You are permitted to print this document provided that (1) the use of such is for personal use only and will not be copied or posted on any network computer or broadcast in any media, and (2) no modifications of the document is made. Unauthorized duplication, in whole or part, of this document by any means, mechanical or electronic, including translation into another language, except for brief excerpts in published reviews, is prohibited without the express written permission of Altium Limited. Unauthorized duplication of this work may also be prohibited by local statute. Violators may be subject to both criminal and civil penalties, including fines and/or imprisonment. Altium, Altium Designer, Board Insight, DXP, Innovation Station, LiveDesign, NanoBoard, NanoTalk, OpenBus, P-CAD, SimCode, Situs, TASKING, and Topological Autorouting and their respective logos are trademarks or registered trademarks of Altium Limited or its subsidiaries. All other registered or unregistered trademarks referenced herein are the property of their respective owners and no trademark rights to the same are claimed.
16