Parent page: Getting Familiar with the Altium Design Environment
The starting point for every design created in Altium Designer is a project. An Altium Designer project is a set of design documents whose output defines a specific implementation.
In a nutshell, Project Management is focused on securely storing and tracking changes throughout the design process, and ultimately, channeling the resulting design through to the creation of a physical item – such as an assembled PCB to be used in the final product. To meet these needs, Altium Designer provides a range of project management approaches that offer increasing levels of sophistication and capabilities, yet simplify the process from a designer's perspective. These range from local file-based storage and management, to local/remote Version Control System (VCS) storage approaches, and through to its advanced and recommended form where the management of design data is centered on the capabilities of a Workspace.
A connected Workspace and its internal VCS service hosts and manages Altium Designer projects, and also provides simplified VCS operations, inherent design collaboration capabilities, advanced design data sharing, history tracking, Lifecycle management, and much more. Projects that are integrated with a Workspace are accessed directly from Altium Designer, such as from the Projects panel, or from the Workspace itself through its browser-based interface.
Thanks to the intelligence built into the services provided by a Workspace, tasks such as VCS operations are simplified and automated, and additional design collaboration features such as user access control (sharing), commenting and history are available directly from within Altium Designer. The end result is a robust and secure project storage format and location that can become the central point for collaborative project design.
For a Workspace project, the following actions are supported:
- Creating a Project – directly, by making an existing local project available in the Workspace, or by cloning an existing Workspace project.
- Opening a Project – to be able to work on it.
- Viewing Project History – browsing a progressive timeline of major events relating to the project – its creation, commits, releases, clones and MCAD exchanges – with various actions supported where applicable.
- Commenting a Project – placing tagged notes on a document that are stored in the Workspace and available to all users that have access to that project document.
- Sharing a Project – changing the access permissions for a project so that users that need to see and work with it have the ability to do so.
- 'Soft' Deleting a Project – removing an entire project to the Workspace Trash location, which has options to permanently delete the project or restore it to its previous location.
Types of Projects
Altium Designer supports a number of different kinds of projects. Below is a brief description of each.
In a Printed Circuit Board (PCB) project, the electronic circuit is captured as a schematic, which is built up from libraries of component symbols that are placed and wired together.
The design is then transferred to the PCB editor where each component is instantiated as a footprint (pattern) and the circuit wiring becomes point-to-point connection lines. A shape for the final PCB is defined, along with the physical layers the board will include. Design rules specify the layout requirements, such as routing widths and clearance. The components are positioned within the board shape, and the connection lines are then replaced by routing, either manually or automatically.
When the design is complete, standard format output files are generated which can be used to fabricate the blank board, configure an assembly machine, and so on.
In a Multi-board project, the logical design is captured using a schematic document that connects together sub-project modules, which in turn represent existing PCB projects. The Multi-board schematic data is then transferred to a Multi-board assembly document where the physical board assemblies, as defined by the sub-projects, are positioned together and within an added enclosure.
A Multi-board project (
*.PrjMbd) effectively defines the electrical and physical connectivity between existing PCB design projects through the application of a logical schematic document (
*.MbsDoc) and synchronized assembly document (
► Read more about Multi-board Projects.
The Harness Design functionality allows engineers of various types (involved in the Product Design process) to work in Altium Designer. It brings comprehensive harness design support into the same environment as PCB and system design, removing the previous heavy reliance on third-party software.
The Harness Design functionality allows you to create a full wiring harness design, from the individual pin-to-pin connections right through to manufacturing documentation. A harness design can be created as a standalone project, or as part of a Multi-board project. In the latter case, the logical connections between PCBs in the Multi-board project are used to define the connectivity within the harness.
► Read more about Harness Design.
An Integrated Library is created in a library package project (
*.LibPkg), where schematic symbols are created in a Schematic Library (
*.SchLib), and reference links defined to matching models in other domains. Referenced models can include PCB footprints, circuit simulation models, signal integrity models, and three-dimensional mechanical models.
Files that contain the models (PCBLibs, etc) are added to the Integrated Library Package (
*.LibPkg), or search paths are defined to identify their location. The source schematic symbol libraries and required models are then compiled into a single file (
*.IntLib), referred to as an Integrated Library.
► Read more about Working with Integrated Libraries.
A Script (
*.pas) contains a set of instructions (automated commands) that are interpreted when it is executed in Altium Designer. The scripts are written and debugged in the same editor environment.
There are two types of Scripts – script units and script forms. A script Unit can use the X2 Application Programming Interface (API) to modify or manipulate design objects on a design document. A script Form hosts controls as a user interface and harnesses the X2 API to provide script dialogs that act on active design documents.
Script Units, Forms and Data Models are contained in a Script project (
► Read more about Automating Design Tasks with Scripting.
The Projects panel displays all projects that are currently open and their constituent documents and structure.
The Projects panel
When connected to a Workspace, the Workspace icon (/) is shown next to the uppermost entry of this Workspace. When the local working copy of a project is opened but the Workspace where the project resides is not connected, a grayed-out Workspace icon (/) will appear, and the project icon will change (e.g. it appears as for a PCB project).
A Workspace project can also be shared with you without inviting you to the team of the Workspace where this project resides. A project that has been opened from shared access is indicated by an associated Shared with me label with the icon next to it.
If a project was shared with you so you can only view it, the View Only label will be shown next to the project entry in the panel to indicate this.
An indication of a project shared with you to view only.
Local projects are listed under the entry of the project group (
*.DsnWrk) – either the default one (
Project Group 1.DsnWrk), or one you have created or opened.
To access the context menu regarding your currently connected Workspace, right-click on your Workspace name or click the control at its far right. These commands include:
- Open Project – opens the Open Project dialog.
- Create Project – opens the Create Project dialog.
- Show in Explorer – opens the Explorer panel.
- Show in Web Browser – opens the Projects page of the Workspace's browser interface in your default browser.
- Sign out – signs you out of the Workspace.
- Sign in – signs you in to the Workspace. This command is available provided that you have at least one Workspace item (e.g., project) opened in the Projects panel and you are currently disconnected from the Workspace where this item resides.
You must be connected to a Workspace to access these commands. When signed out of a Workspace, right-click the Workspace you want to connect to, and click the Sign In command.
Project Documents Tree
When you open an existing project or create a new one, its entry will appear in the Projects panel. Any existing documents that are part of a project (and any new ones that have been added) will appear under sub-folders according to their purpose and/or type. For example, the following common folders and content document types can appear under a project:
- Source Documents – core design documents such as schematics, PCBs, etc.
- Settings – provides various files used within the project, including Output Job Files, Harness Definitions Files, and Annotation Documents, among other pertinent files.
- Libraries – local source library documents. Documents are further subdivided based on library type (e.g., schematic libraries, PCB libraries, etc.).
- Documentation – additional documents that have been added to the project, of a type that is known by Altium Designer (e.g., text, PDF, etc.).
- Other Documents – additional documents that have been added to the project, of a type that is not known by Altium Designer. These can be opened by Altium Designer if the owner application is known by Windows (eg, Word documents, Excel spreadsheets, etc).
- Generated – documents generated as output. Documents are further subdivided based on type (e.g., BOM documents, text documents, etc.). As project output is generated, the corresponding sub-folders in the main tree will be created and become populated.
- Components – this folder lists each component and the number of components in each group. Validate the project if this folder does not appear (Project » Validate). Components are grouped by the first letter in the designator by default - right-click on the entry for a component (or component grouping folder) and choose the Component Grouping command from the context menu to quickly access the Components Grouping controls for the Projects panel and change the style of grouping, or disable grouping, as required.
- Nets – this folder lists each net used in the project. Validate the project if this folder does not appear (Project » Validate).
Notes on working in the documents tree:
- Any documents that are independent of a project will appear as Free Documents and will appear under corresponding sub-folders. By right-clicking on a free document and choosing the Add to Project <ActiveProjectName> command from the context menu, you can add a currently open free document to the active project. Alternatively, you can drag and drop it onto the required project name, in the Projects panel.
- Along with allowing multiple documents to be open for editing, the environment also supports multiple projects being open at the same time. These could be related or unrelated projects.
- Documents in the Projects panel are automatically arranged in logical groups or 'folders', such as Source Documents (Schematic, PCB, etc.), Settings documents (Harness, Outjob, etc.,) and, in the case of a hierarchical design, top-level schematic documents. The documents within each folder group are displayed by default in the order they were added but can be dragged and dropped to a new order position within the group.
- In the case of a new hierarchical design, the parent-child relationship between documents will be displayed in the panel. Note that the connectivity relationships cannot be defined by dragging and dropping schematic documents since the inter-sheet connections and design hierarchy are in fact defined by Sheet Symbols and Port definitions.
- To close the currently focused project in the Projects panel, right-click on its entry and choose the Close Project command, from the context menu. The active project can be closed by choosing the Project » Close Project command, from the main menus.
- To close all currently open documents, select Window » Close Documents from the main menus.
- To close all currently open projects and their documents, select Window » Close All from the main menus.
- Right-click a project document sub-folder, whether expanded or closed, to access additional document management commands, such as opening, closing, or saving all documents within the focused project document sub-folder.
- Documents can be transferred between projects in the panel by clicking and dragging. The document does not have to be dragged into the correct sub-folder; it will be placed correctly within the project structure automatically.
- The keyboard shortcuts Up Arrow, Home, End, and Down Arrow can be used to display the previous, first, last, and next entry in the panel, respectively. Use the Right Arrow and Left Arrow keys to expand and collapse a top-level entry or its sub-folder, respectively.
- To cross-probe from the selected component or net entry in the Projects panel, to that entity on the schematic or PCB document of the parent PCB design project, right-click on the entry and choose the Cross Probe to Schematic or Cross Probe to PCB command from the context menu.
In the Projects panel's main tree, the active project is highlighted. When there are no documents open in the design editor window, a project is made active by selecting it from a list of all currently open (loaded) projects in the panel. As soon as a project document is opened (in an editor/viewer), the parent project of that document automatically becomes the active project. The active document in the design editor window will also be highlighted in the panel.
The highlighting of an open active document and its active parent project.
With numerous documents open in the design editor window, changing the active document using the editor's document tabs will cause the Projects panel to update accordingly, i.e. to reflect both the active document and the active project (if the document made active does not reside in the same project as the previously active document). Conversely, clicking on the entry for a document that is already open (and that belongs to a non-active project) will make the parent project of that document the active project.
Only one project and document may be active at any given time, however, the panel allows you to focus and perform actions on any project or document. Right-clicking on the entry for a non-active project or a non-active document will bring up an associated menu with commands targeting the focused project or focused document, respectively.
In the case of focusing a document, the document will only become focused if it is closed, otherwise, it will become the active document and its parent project will become the active project. For example, in the image below, the active project is
MiniPC.PrjPcb and the active document
DDR4.SchDoc. The focused document is
Ethernet-HPS.SchDoc (distinguished in the panel by a dotted outline box).
An opened active document (blue) and a selected focused document are indicated by the dotted outline.
In Altium Designer, you can open and edit multiple projects, and if desired, save the collective set of projects as a Project Group (
*.DsnWrk). In the Projects panel, the entry of the current Project Group – either the default one (
Project Group 1.DsnWrk), or one you have created or opened – is shown with the icon.
This can be of particular advantage when the set of projects is related or linked, such as a product design that is composed of multiple PCBs. Creating a Project Group that includes all the relevant projects allows you to open, manipulate, and save multiple projects as a single entity.
Notes on using project groups:
- The current Project Group is listed along with open projects in the Projects panel – either the default one (
Project Group 1.DsnWrk), or one you have created or opened.
- To save the currently opened set of projects as a group select File » Save Project Group As from the main menu.
To open an existing group, select File » Open Project Group from the main menu, or right-click in the panel and select Open Project Group from the context menu. Use the same access for the Save Project Group command.
- To save a project group, right-click on its entry in the Projects panel and choose the Save Project Group command, from the context menu.
- To save a copy of the currently active design Project Group in the Projects panel, with a new name (if required), and to a specified location on the hard disk, choose the File » Save Project Group As command from the main menus or right-click on its entry in the Projects panel and choose the Save Project Group As command from the context menu.
- To create a new Project Group, select File » New » Design Project Group from the main menu – this will load the default (blank) Project Group (
Project Group 1.DsnWrk). The same method can be used to close the current Project Group file.
- Only one Project Group can be open at a time, so when opening a different Project Group the current group will close. You will be prompted to save any unsaved documents, projects or changes to the current group first.
- To add another project to a Project Group, open or create a project and then save the current Project Group. Alternatively, right-click in the panel and select the Add Existing Project option.
A set of related local projects as a Project Group
An existing or newly created Project is associated with a range of Option settings that are specific to that project. These are stored in the project file (
*.PrjPcb, for example) and will vary depending on the type of project. Note that Server Parameters are stored with the project in its Workspace.
The option settings are configured in the Project Options dialog, which can be accessed from Project » Project Options on the main menu, or by right-clicking on the project name in the Projects panel and then selecting Project Options from the context menu. For the project focused in the Projects panel, the dialog can be accessed by clicking the control at the top of the panel.
Other project settings that are defined in other dialogs and then stored in the project file include:
- Schematic annotation settings.
- Output settings such as; reports, print, Gerber, and so on. Note that these are the output settings accessed via the schematic or PCB editor menus, rather than the output settings defined in an OutJob document.
When you perform a change on an open project's structure or options, it becomes modified. A modified project is distinguished by an asterisk next to its entry and the status icon in the Projects panel. To save the changes of a project document file, right-click the project entry in the Projects panel and select the Save command. For the focused project in the panel, it can be saved by clicking the control at the top of the panel.
For a Workspace project, the Save command will save the changes locally, i.e. only your local working copy of the project document file will be saved. To make the changes available in the connected Workspace, the projects must be saved to this Workspace. Save the selected files by right-clicking on a project and selecting Save to Server or by selecting the Save to Server link next to the project file.
Clicking the link and selecting the command saves any source design documents that have been modified but not yet saved locally and opens the Save to Server dialog in which you can select the documents to be saved to the Workspace. After clicking OK, the documents are saved to the Workspace and the Save to Server link disappears from the Projects panel.
This upper pane lists all files in the selected project and lists whether or not they are in VCS. Additional relevant information is also listed, including whether a file is marked for addition or deletion. You can select files to commit to version control. The Path column shows the path of each file, the Status column shows the file's current status. This part of the dialog also features a right-click menu with the following options:
- Select All – click to select all files listed in the dialog. Selected files will be added to VCS.
- Select None – click to deselect all files listed in the dialog. These files will not be added to VCS.
- Select Project Documents – click to select only project files.
The application of fully managed, version-controlled PCB projects relies on tight synchronization between the project's local working folder contents and the Workspace's versioned storage. If this relationship is disrupted by changes made outside of the normal processes, the managed project structure can become corrupted.
Possible changes that break the local-remote storage synchronization include manual actions such as renaming, moving, or copying/cloning a working project folder. These issues are detected and addressed through a choice dialog that highlights a recommended action based on the situation. In general, its options are to resynchronize the folder project as the current managed project or to remove the project's relationship with the server (make the project unmanaged).
Options to get you back into sync if you have manually changed the location of your local working copy of a project.
Other more complex synchronization disruptions may be caused by changes in the server identity, such as when the server itself has been renamed or moved when a local project file has been overwritten with one that contains different server identity parameters, or the project's target repository has changed. Such issues create a disparity between the server and the local project repositories and are reported by warning dialogs or dialogs that provide a resolution choice.
Options to get you back on track if the repository targeted by the local working copy of your design project has changed.
Saving when Closing a Project
If you close a project and that project has two or more modified documents that have not yet been saved, the Confirm Save for Modified Documents dialog will open. Use this dialog to decide what to do with those documents.
Use the Confirm Save for Modified Documents dialog to decide how to handle unsaved documents when closing one or more projects or Altium Designer itself.
The main area of the dialog lists all open and modified documents (by name and path to the local copy) for which you need to make a decision about whether or not to save. Documents are grouped by type (e.g., PCB Documents, PCB Projects, Schematic Documents, BOM Documents and so on).
The possible decisions are listed below. Which decisions are actually presented for a document will depend on whether that document is local or Workspace-based and, if the latter, whether or not that document has also been saved locally already.
- this decision is available for a local document or for a Workspace document that has not already been saved locally. In the case of the latter, it allows you to save the document locally without committing changes to the connected Workspace.
- this decision is available for a local document or for a Workspace document that has not already been saved locally. Any changes to the document will be discarded.
- this decision is available for a Workspace document, irrespective of whether it has already been saved locally or not. Changes to the document will be saved locally (where applicable) and to the connected Workspace.
- this decision is available for a Workspace document when it has already been saved locally. Since there is nothing to save locally, nothing will be done with this document.
The following buttons are available at the bottom of the dialog to quickly make decisions en-masse:
- use this button to quickly set decisions for each document in a 'save locally' way. For a local document or Workspace document that has not already been save locally, its decision will be set to Save. For a Workspace document that has already been save locally, its decision will be set to Do nothing.
- use this button to quickly set decisions for each document in a 'save none' way. For a local document or Workspace document that has not already been save locally, its decision will be set to Don't Save. For a Workspace document that has already been save locally, its decision will be set to Do nothing.
- use this button to quickly set decisions for each document in a 'save fully' way. For a local document its decision will be set to Save. For a Workspace document its decision will be set to Save to Server.
Opening Recent Documents, Projects and Project Groups
Recently closed documents, projects and project groups can be opened from any editor by using indexed commands of the File » Recent Documents, File » Recent Projects, or File » Recent Project Groups sub-menu, respectively. A list shows the most recently closed entities (up to a maximum of nine entities). Position 1 (at the top) reflects the last entity closed.
You can also choose the All Recent Documents and Projects command from any of these menus to open the Recent Documents, Projects and Project Groups dialog. The dialog lists all recently closed documents, projects, and design project groups conveniently within one location. Information listed includes:
- Document Name - name of the opened document.
- Document Type - type of opened document (PCB, schematic, etc.).
- Location - location path of the opened document.
- Modified - date and time document was last modified.
Select what you want to open then either click OK to close the dialog and open your selection or Open Selected Documents to open your selection - keeping the dialog open for further selection. Use the standard Windows shortcuts (Ctrl+click and Shift+click) to select multiple items from the list.
The Recent Documents, Projects and Project Groups dialog
Flexible functionality is available for removing managed design items such as Projects, Components and Released data directly from within Altium Designer, from the Explorer panel. Operating as a 'soft delete', the removal process provides increased options and information as you proceed, including relevant links to source items for review purposes. In the Workspace, deleted items are moved to a dedicated Trash location, where they can be retrieved (Restore) or completely removed (Permanently Delete) from the Trash page of the Workspace's browser interface.
Soft delete in action. Here, a project is being deleted, along with its related release (if manufacturing packages had been created from any releases, those would also be deleted).