Difference between revisions of "How to Install and Configure Altium"

From Stanford SSI Wiki
Jump to navigation Jump to search
Line 13: Line 13:
  
 
* All new projects are stored on Github. An example of this is [https://github.com/stanford-ssi/ThunderGuppy-EE ThunderGuppy-EE]. All SSI projects should be public on the [https://github.com/stanford-ssi SSI Github], but in order to commit changes, you're going to need to [https://github.com/join create a Github Account] and have someone add you as a member of the SSI Github organization. Ask in {{slack-channel|git}} to be added.
 
* All new projects are stored on Github. An example of this is [https://github.com/stanford-ssi/ThunderGuppy-EE ThunderGuppy-EE]. All SSI projects should be public on the [https://github.com/stanford-ssi SSI Github], but in order to commit changes, you're going to need to [https://github.com/join create a Github Account] and have someone add you as a member of the SSI Github organization. Ask in {{slack-channel|git}} to be added.
* All components and parts live on the [https://stanford-university-student-space-initiative.365.altium.com/ Altium 365 workspace]. To access this you will need an Altium account connected to your Stanford email, and you will need to be added to the workspace. You should ask for these things in {{slack-channel|altium}}, and tag the {{slack-user|altium-admin}}.
+
* All components and parts live on the [https://stanford-university-student-space-initiative.365.altium.com/ Altium 365 workspace]. To access this you will need an Altium account connected to your Stanford email, and you will need to be added to the workspace. You should ask for these things in {{slack-channel|altium}}, and tag the {{slack-user|sunet-id=altium-admin|display-name=altium-admin}}.
 
* Templates, Logos, Fonts, and oddball SSI-wide data lives in the [https://ssi-svn.stanford.edu/svn/altium-core/ Altium SVN]. SVN ([https://subversion.apache.org/ Subversion]) is the grandfather to Git and Google Drive. To access the SVN you need credentials which you can get from https://ssi-svn.stanford.edu/ and an SVN client, like [https://tortoisesvn.net/ TortoiseSVN].
 
* Templates, Logos, Fonts, and oddball SSI-wide data lives in the [https://ssi-svn.stanford.edu/svn/altium-core/ Altium SVN]. SVN ([https://subversion.apache.org/ Subversion]) is the grandfather to Git and Google Drive. To access the SVN you need credentials which you can get from https://ssi-svn.stanford.edu/ and an SVN client, like [https://tortoisesvn.net/ TortoiseSVN].
  
Line 28: Line 28:
 
[[File:TortoiseSVNMenu.png|thumb|200px|right|A screenshot showing all of the SVN functions available when right-clicking after installing TortoiseSVN. You will never use most of these.]]
 
[[File:TortoiseSVNMenu.png|thumb|200px|right|A screenshot showing all of the SVN functions available when right-clicking after installing TortoiseSVN. You will never use most of these.]]
 
Within the {{slack-channel|altium}} channel, request an account for Altium itself, the Altium365 workspace, and the SVN. Messaging {{slack-user|sunet-id=altium-admin|display-name=altium-admin}} will summon the relevant person.
 
Within the {{slack-channel|altium}} channel, request an account for Altium itself, the Altium365 workspace, and the SVN. Messaging {{slack-user|sunet-id=altium-admin|display-name=altium-admin}} will summon the relevant person.
 
===Installing SVN===
 
You will need SVN software to use the SSI Altium repository. The recommended choice is to install [http://tortoisesvn.net/ Tortoise SVN] (Windows-only). There are solutions for Mac and Linux users as well, though none quite as streamlined as TortoiseSVN; many Linux and Max users use the command line (Terminal) to handle SVN.
 
 
TortoiseSVN will run persistently on your computer and allow you to work with files synchronized with the SVN. As shown at right, TortoiseSVN will appear as a menu available when right clicking on files or folders. We will introduce the most useful of these commands in this article; several more are discussed [[Using TortoiseSVN|here]] (recommended reading ''after'' completing this guide).
 
 
===Downloading SSI Altium SVN===
 
[[File:SVNCheckout.png|thumb|200px|right|Make sure you're right clicking on the folder you just created.]]
 
[[File:SVNCheckout2.png|thumb|200px|right|Your checkout window should look very similar to this.]]
 
Find a convenient location on your computer (i.e. your desktop) to create a folder that will host all of the shared SSI Altium files. Create a new folder there (my folder is called "SVN-SSI-Altium," though "altium-core" is what the folder is called on the server). Right click on the folder, and select "SVN Checkout" (see right). A window should pop up (see right) showing a URL to download files from and a location on your computer where the files will be downloaded. Verify that the target on your computer is where you intend and set the URL of the repository to {{altium-repo}}, and click OK. You will then likely be prompted for your SVN login - this will be your '''username''' and password Slacked to you after you requested them. You do not need credentials to download the libraries on campus, but you do need credentials to push changes to the libraries (regardless of where you are). Enter credentials if you have them, click OK, and your computer should begin to download the Altium libraries. These should take less than a minute to download on campus.
 
  
 
===Installing Altium===
 
===Installing Altium===
Line 64: Line 54:
 
If you do not have a schematic open already, open one by clicking "File → New → Schematic." Next, open up the Customize panel by either clicking on a blank space of the toolbar (the space to the right of the "Help" drop-down menu works) or by right-clicking in that same spot and selecting "Customize..." In the window that comes up (see right), click "Edit" from the "Categories" column on the left, then double click on "Delete" in the "Commands" column on the right. This is the command used to delete components from a schematic, which is by default mapped to the delete key, which, if you're completing this step, you do not have. Click the "Primary" field, and then hit your backspace key to remap the command to that key. This only changes the delete key for schematics, so repeat this process with a PCB document open.
 
If you do not have a schematic open already, open one by clicking "File → New → Schematic." Next, open up the Customize panel by either clicking on a blank space of the toolbar (the space to the right of the "Help" drop-down menu works) or by right-clicking in that same spot and selecting "Customize..." In the window that comes up (see right), click "Edit" from the "Categories" column on the left, then double click on "Delete" in the "Commands" column on the right. This is the command used to delete components from a schematic, which is by default mapped to the delete key, which, if you're completing this step, you do not have. Click the "Primary" field, and then hit your backspace key to remap the command to that key. This only changes the delete key for schematics, so repeat this process with a PCB document open.
  
==A Brief Introduction to SVN==
 
This is the last part of this guide! You have actually already completed the installation and configuration of Altium; this step is intended to give you a quick introduction to SVN and how to use it. You will not need Altium for this last step; if you're completing this tutorial at a time when others are likely to also be working through it, close Altium, as that will free up licenses for others to use. If you're already familiar with SVN, skip to the [[#Your First Commit|last task]].
 
  
===Background===
+
 
 +
'''You're done!''' Welcome to Altium!
 +
 
 +
==Next Steps==
 +
 
 +
;A First Project :[[Your First Altium Project|This (currently in-development) guide]] offers you a walkthrough of a fun introductory Altium project, which ends with making a circuit board that allows you to play StrEEt Fighter with your fellow SSI members.
 +
;Creating Parts for Altium Libraries : [[Making Parts for PCB Libraries|This guide]] walks you through the process of adding new parts to the SSI Altium library, teaching both the process involved and quality standards for the library that we and the Stanford Solar Car Project have long worked to maintain.
 +
 
 +
==Addendum: SVN==
 +
 
 +
===Installing SVN===
 +
You will need SVN software to use the SSI Altium repository. The recommended choice is to install [http://tortoisesvn.net/ Tortoise SVN] (Windows-only). There are solutions for Mac and Linux users as well, though none quite as streamlined as TortoiseSVN; many Linux and Max users use the command line (Terminal) to handle SVN.
 +
 
 +
TortoiseSVN will run persistently on your computer and allow you to work with files synchronized with the SVN. As shown at right, TortoiseSVN will appear as a menu available when right clicking on files or folders. We will introduce the most useful of these commands in this article; several more are discussed [[Using TortoiseSVN|here]] (recommended reading ''after'' completing this guide).
 +
 
 +
===Downloading SSI Altium SVN===
 +
[[File:SVNCheckout.png|thumb|200px|right|Make sure you're right clicking on the folder you just created.]]
 +
[[File:SVNCheckout2.png|thumb|200px|right|Your checkout window should look very similar to this.]]
 +
Find a convenient location on your computer (i.e. your desktop) to create a folder that will host all of the shared SSI Altium files. Create a new folder there (my folder is called "SVN-SSI-Altium," though "altium-core" is what the folder is called on the server). Right click on the folder, and select "SVN Checkout" (see right). A window should pop up (see right) showing a URL to download files from and a location on your computer where the files will be downloaded. Verify that the target on your computer is where you intend and set the URL of the repository to {{altium-repo}}, and click OK. You will then likely be prompted for your SVN login - this will be your '''username''' and password Slacked to you after you requested them. You do not need credentials to download the libraries on campus, but you do need credentials to push changes to the libraries (regardless of where you are). Enter credentials if you have them, click OK, and your computer should begin to download the Altium libraries. These should take less than a minute to download on campus.
 +
 
 +
===A Brief Introduction to SVN===
 
An SVN repository is a series of "snapshots" of a folder over time. Each snapshot is called a '''commit''', and represents the state of the folder and some or all of its contents at a moment in time. Commits are created by users (aka you) when they want to preserve a version of the files they are working on - this typically happens after making a group of changes to files stored in the SVN repository (ie. after adding a part to a library or making progress on a circuit schematic or circuit board).
 
An SVN repository is a series of "snapshots" of a folder over time. Each snapshot is called a '''commit''', and represents the state of the folder and some or all of its contents at a moment in time. Commits are created by users (aka you) when they want to preserve a version of the files they are working on - this typically happens after making a group of changes to files stored in the SVN repository (ie. after adding a part to a library or making progress on a circuit schematic or circuit board).
  
Line 87: Line 95:
  
 
To finish, go back to your Altium SVN folder, right click while ''not'' on any file or folder, and mouse down to "SVN Commit..." and click it. A dialog box will come up (see right), at the bottom of which should be a list of files. This shows files you have changed since the last time you ran SVN update, and ''should'' just have iwuzhere.txt listed. Make sure you have it checked. In the text box at the top of the window, you will need to write a '''commit message''', a brief description of what changes you're committing. This message will appear in Slack and must be at least 20 characters (but shouldn't be longer than a single sentence). Once you've written it, click okay, and wait for a message to appear in Slack.
 
To finish, go back to your Altium SVN folder, right click while ''not'' on any file or folder, and mouse down to "SVN Commit..." and click it. A dialog box will come up (see right), at the bottom of which should be a list of files. This shows files you have changed since the last time you ran SVN update, and ''should'' just have iwuzhere.txt listed. Make sure you have it checked. In the text box at the top of the window, you will need to write a '''commit message''', a brief description of what changes you're committing. This message will appear in Slack and must be at least 20 characters (but shouldn't be longer than a single sentence). Once you've written it, click okay, and wait for a message to appear in Slack.
 
'''You're done!''' Welcome to Altium!
 
 
==Next Steps==
 
 
;A First Project :[[Your First Altium Project|This (currently in-development) guide]] offers you a walkthrough of a fun introductory Altium project, which ends with making a circuit board that allows you to play StrEEt Fighter with your fellow SSI members.
 
;Creating Parts for Altium Libraries : [[Making Parts for PCB Libraries|This guide]] walks you through the process of adding new parts to the SSI Altium library, teaching both the process involved and quality standards for the library that we and the Stanford Solar Car Project have long worked to maintain.
 
  
 
[[Category: Altium]]
 
[[Category: Altium]]

Revision as of 05:03, 23 August 2022

Journey.jpg

This is a guide

Welcome! This article is intended to guide you through an SSI process. While its authors have made efforts to make it useful, if you have questions, please ask the authors on Slack. They will be able to both help you and improve this resource for future SSI-ers.

This article was written by (SlackLogo.png@Sasha Maldonado ) and updated by (SlackLogo.png@Tim Vrakas ).

Background

Altium Designer is SSI's preferred circuit board design program. The program runs exclusively on Windows; Mac and Linux users have successfully run Altium through both dedicated Windows partitions and Windows virtual machines. Though debated amongst SSI members, a USB mouse is also a useful tool when designing circuit boards.

Altium Ltd. sponsors SSI with a number of shared licenses to use their software. These licenses are managed over the internet - after signing in for the first time, your computer will automatically download a license file every time you open Altium and release your license when you close the program.

Altium allows users to draw circuit schematics and then design the physical layout of the components represented in the schematic. This requires libraries of symbols to represent components, the physical dimensions of those components in real life, and links so that they can be purchased from suppliers. SSI and Stanford Solar Car Project members have designed parts for these libraries over the course of several years, and as an Altium user, you will almost certainly add parts to the SSI PCB libraries.

Where do things live?

There are three places Altium data lives:

  • All new projects are stored on Github. An example of this is ThunderGuppy-EE. All SSI projects should be public on the SSI Github, but in order to commit changes, you're going to need to create a Github Account and have someone add you as a member of the SSI Github organization. Ask in SlackLogo.png#git  to be added.
  • All components and parts live on the Altium 365 workspace. To access this you will need an Altium account connected to your Stanford email, and you will need to be added to the workspace. You should ask for these things in SlackLogo.png#altium , and tag the SlackLogo.png@altium-admin .
  • Templates, Logos, Fonts, and oddball SSI-wide data lives in the Altium SVN. SVN (Subversion) is the grandfather to Git and Google Drive. To access the SVN you need credentials which you can get from https://ssi-svn.stanford.edu/ and an SVN client, like TortoiseSVN.

A Brief Motivational Note

At the time of this guide's original writing, only two people in SSI had used Altium for more than a year (neither of whom wrote this article - I began using Altium 8 months prior to originally writing it). As with any worthwhile skill, Altium takes time to gain familiarity with, and doing projects in Altium - though initially somewhat tedious and frustrating at times - is the best way of learning to use it.

Furthermore, as with all good technical software, Altium has many features, with many buttons and options. This is understandably anxiety-inducing. This guide (and the SSI wiki at large) is written to try and point you to the buttons you will need to complete setup and common tasks, which are a small subset of all of the buttons available to you. People who have worked in Altium for 20 years have commented that they still have never used most of the features of the program. In reality, doing a couple of projects is enough for you to learn what the core functions are and how to use them, and SSI has a robust community of able and willing engineers eager to help you get started.

With that in mind, let's get underway!

Installation and Setup

Account Setup

A screenshot showing all of the SVN functions available when right-clicking after installing TortoiseSVN. You will never use most of these.

Within the SlackLogo.png#altium  channel, request an account for Altium itself, the Altium365 workspace, and the SVN. Messaging SlackLogo.png@altium-admin  will summon the relevant person.

Installing Altium

Once you have an Altium account, Altium Designer can be downloaded here after logging in on the Altium website. Be aware that the software will only install on Windows operating systems. After downloading, install with the default settings.

Connecting Altium to the License System

Protip: Don't publish sensitive information on the internet.

After Altium finishes installing, open it. Under "My Account," click "Sign in" and log in with your Altium account. Check "Sign me in when I open Altium Designer," as this will automatically grant you license access when you start the program. Next, under "Available Licenses," select Altium Designer from the list of products (you may or may not have other options listed; you can safely ignore all other ones) and click "Use" underneath (see right). This will now happen automatically every time you open the program.

Configuring Altium Preferences

You will end up with something like this.

Altium's default preferences are quite workable, but a couple of settings relating to the default locations of files need to be configured on each new computer. To change Altium preferences, from the top bar, click "DXP → Preferences..."

Templates Location

You will end up with something like this, unless you're attempting to steal my identity, in which case you will end up with exactly this.

An unjustifiable length of time was spent creating formatting templates for SSI circuit schematics, which make for a clean, professional project and add a bit of information to each schematic. To use, in Preferences, go to "Data Management → Templates," and set the "Template location" field to point to the "libraries\templates" folder in your Altium SVN. See the image at right for an example of the result.

Install the SSI PCB Logos Font

Adding logos to PCBs is an important aspect of professionalism, part of SSI's agreements with its sponsors, and a nice way to add some creativity to a technical process. For logos that SSI commonly uses, we've created a font with scalable versions of each. This font is stored in "libraries\logos\SSI" - there, you can double click on "SSI_logos.ttf" to install it.

Remap Delete Key

You should end up with this.

This step is only required of computers which do not have distinct "backspace" and "delete" keys. Desktops and most non-Apple laptops can skip this step. Apple laptops which have a "delete" key that functions as a backspace key need to complete this step.

If you do not have a schematic open already, open one by clicking "File → New → Schematic." Next, open up the Customize panel by either clicking on a blank space of the toolbar (the space to the right of the "Help" drop-down menu works) or by right-clicking in that same spot and selecting "Customize..." In the window that comes up (see right), click "Edit" from the "Categories" column on the left, then double click on "Delete" in the "Commands" column on the right. This is the command used to delete components from a schematic, which is by default mapped to the delete key, which, if you're completing this step, you do not have. Click the "Primary" field, and then hit your backspace key to remap the command to that key. This only changes the delete key for schematics, so repeat this process with a PCB document open.


You're done! Welcome to Altium!

Next Steps

A First Project
This (currently in-development) guide offers you a walkthrough of a fun introductory Altium project, which ends with making a circuit board that allows you to play StrEEt Fighter with your fellow SSI members.
Creating Parts for Altium Libraries
This guide walks you through the process of adding new parts to the SSI Altium library, teaching both the process involved and quality standards for the library that we and the Stanford Solar Car Project have long worked to maintain.

Addendum: SVN

Installing SVN

You will need SVN software to use the SSI Altium repository. The recommended choice is to install Tortoise SVN (Windows-only). There are solutions for Mac and Linux users as well, though none quite as streamlined as TortoiseSVN; many Linux and Max users use the command line (Terminal) to handle SVN.

TortoiseSVN will run persistently on your computer and allow you to work with files synchronized with the SVN. As shown at right, TortoiseSVN will appear as a menu available when right clicking on files or folders. We will introduce the most useful of these commands in this article; several more are discussed here (recommended reading after completing this guide).

Downloading SSI Altium SVN

Make sure you're right clicking on the folder you just created.
Your checkout window should look very similar to this.

Find a convenient location on your computer (i.e. your desktop) to create a folder that will host all of the shared SSI Altium files. Create a new folder there (my folder is called "SVN-SSI-Altium," though "altium-core" is what the folder is called on the server). Right click on the folder, and select "SVN Checkout" (see right). A window should pop up (see right) showing a URL to download files from and a location on your computer where the files will be downloaded. Verify that the target on your computer is where you intend and set the URL of the repository to TortoiseLogo.gif altium-core, and click OK. You will then likely be prompted for your SVN login - this will be your username and password Slacked to you after you requested them. You do not need credentials to download the libraries on campus, but you do need credentials to push changes to the libraries (regardless of where you are). Enter credentials if you have them, click OK, and your computer should begin to download the Altium libraries. These should take less than a minute to download on campus.

A Brief Introduction to SVN

An SVN repository is a series of "snapshots" of a folder over time. Each snapshot is called a commit, and represents the state of the folder and some or all of its contents at a moment in time. Commits are created by users (aka you) when they want to preserve a version of the files they are working on - this typically happens after making a group of changes to files stored in the SVN repository (ie. after adding a part to a library or making progress on a circuit schematic or circuit board).

Any file can be stored in an SVN repository, and the repository can detect any change to any file. With TortoiseSVN installed, tracked files in an SVN repository which have been edited since the last commit will have a small red exclamation point displayed on their icon when viewed in a folder. New files created in your Altium SVN folder will not automatically be tracked - this is intentional, and a good thing.

Unlike other version control systems, "branches" do not work in SVN. All commits in an SVN repository contain changes that directly follow the commit before them, and can have only a single commit that follows after them. Because of this, SVN users can lock files and folders, becoming the only person allowed to commit changes to that file or folder. Other users can still edit the files, but their changes cannot be committed, making those edits futile. TortoiseSVN shows when a file has been locked by someone else, to help keep you from trying to edit something that somebody else is working on. Locking exists so that two users cannot try to commit different versions of the same file - someone who opens a file and knows they will commit changes to it soon can lock the file, marking the fact that they started editing the file first and so should be allowed to complete and commit their changes before anyone else. Locks can be taken away from someone who locks a file for an extended period of time, preventing abuse of this feature.

Changes other people make to files stored in the SVN must be downloaded manually, through the SVN update command. Updating replaces any files in your SVN folder that have been changed since the last time you ran SVN update with their most recently committed versions. You can see if there are new SVN commits to download in the SlackLogo.png#altium  channel, where notices of new commits are automatically posted.

Future tutorials will discuss when and how to add files and how to use Altium's SVN commands; below, we will briefly discuss how to generally commit file changes to the SVN repository.

Your First Commit

You will likely only have iwuzhere.txt in your list of files to commit, but if you have others, leave them unchecked.

In your SSI Altium SVN folder, right click while not on any file or folder, and mouse down to "SVN Update" and click it. This will quickly bring all of your files up to date. Next, in your Altium SVN folder, find "iwuzhere.txt." This file is tracked by the SVN repository, and should have a small green check mark on it. Right click on the file, mouse down to "TortoiseSVN," and then click "Get lock..." Click OK on any windows that appear. A small lock icon should appear on the file - you now have the lock on this file.

If the file was already locked by someone else, you will not be able to lock it, and should message the SlackLogo.png#altium  to ask to lock it. If you do not receive a response within 10 minutes, lock the file as described above, and check "Steal the locks" to take the lock from whomever had it previously. Slack is how locking conflicts like this (which are rare) are resolved, and 10 minutes is a short period of time to wait for a response, but this file is simple and very little work is lost from stealing the lock on it. If someone else commits a new version of the file, run another SVN update, and then you should be able to lock it.

Open the file, and add your name and the current date, matching the format of the names already there. You're now a part of SSI's corps of electrical engineers!

To finish, go back to your Altium SVN folder, right click while not on any file or folder, and mouse down to "SVN Commit..." and click it. A dialog box will come up (see right), at the bottom of which should be a list of files. This shows files you have changed since the last time you ran SVN update, and should just have iwuzhere.txt listed. Make sure you have it checked. In the text box at the top of the window, you will need to write a commit message, a brief description of what changes you're committing. This message will appear in Slack and must be at least 20 characters (but shouldn't be longer than a single sentence). Once you've written it, click okay, and wait for a message to appear in Slack.