Eagle CAD Parts Search
11/02/09 06:07 Filed in: Eagle CAD
News: ESawdust is now offering a free Eagle CAD electronic parts search available on ESawdust.com.
Synopsis: The impetus for this came from a general frustration with not being able to easily find components in the sea of Eagle parts libraries.
There are two problems. One, a part you need may already exist in the Eagle libraries, but you can’t find it, so it might as well not exist. Two, the component you’re looking for may exist in a 3rd party Eagle library, but you don’t want to have to download every contributed library and search it to find out.
There’s no way to search the contents of contributed libraries from the Eagle site. You might get lucky and find what you’re looking for on the web page of contributed libraries based solely on the overall description of the library, but for actual parts, you would need to download each library candidate and search it locally.
Bottom line: Out of the thousands of parts available in the Eagle CAD libraries, it can be very difficult to find the part you’re looking for with the Eagle CAD search mechanism. There has to be a better way, so we made one.
How the ESawdust Eagle Parts Search Engine Works
First, we downloaded all Eagle contributed libraries. Next we developed an SCR script file to export all libraries, including the standard, builtin libraries of Eagle, to SCR text files that can be indexed and searched using more powerful search methods.
With the ESawdust Eagle electronic parts search engine, you can use regular expressions or simple literal strings to find many more parts types than you can with Eagle’s search.
You can search for device names, descriptions, even package types and the search algorithm will product a summary of the library names where the component can be found along with detailed discoveries of Eagle parts in the libraries.
Give it a try and let us know what you think.
Synopsis: The impetus for this came from a general frustration with not being able to easily find components in the sea of Eagle parts libraries.
There are two problems. One, a part you need may already exist in the Eagle libraries, but you can’t find it, so it might as well not exist. Two, the component you’re looking for may exist in a 3rd party Eagle library, but you don’t want to have to download every contributed library and search it to find out.
There’s no way to search the contents of contributed libraries from the Eagle site. You might get lucky and find what you’re looking for on the web page of contributed libraries based solely on the overall description of the library, but for actual parts, you would need to download each library candidate and search it locally.
Bottom line: Out of the thousands of parts available in the Eagle CAD libraries, it can be very difficult to find the part you’re looking for with the Eagle CAD search mechanism. There has to be a better way, so we made one.
How the ESawdust Eagle Parts Search Engine Works
First, we downloaded all Eagle contributed libraries. Next we developed an SCR script file to export all libraries, including the standard, builtin libraries of Eagle, to SCR text files that can be indexed and searched using more powerful search methods.
With the ESawdust Eagle electronic parts search engine, you can use regular expressions or simple literal strings to find many more parts types than you can with Eagle’s search.
You can search for device names, descriptions, even package types and the search algorithm will product a summary of the library names where the component can be found along with detailed discoveries of Eagle parts in the libraries.
Give it a try and let us know what you think.
Version Control for Embedded Engineers
08/31/09 09:14 Filed in: git
Synopsis - Embedded engineers often get in the mindset that they’re developing hardware. Hardware developers even think they’re developing hardware, too - imagine that. However, the processes by which commercial firmware and hardware are developed have a lot more in common with software development than digging out the breadboard and making blue smoke. Even in commercial environments, practices long established in software engineering are often lacking in firmware and hardware development. One of these practices includes good version control. Every asset of embedded product development including schematics, PCB layouts, firmware, test instrument configurations, simulations, test results, parts lists and sources, can and should be under version control. In many cases, there are more types of IP assets to track for a hardware / embedded project than for a pure software project.
This article shows how to deploy one of the best version control systems, git, for embedded hardware and software developers. The example I’ll use is to version control Eagle PCB CAD designs, but the example is generally applicable to any dimension of embedded development regardless of design tool.
Motivation
Even if you’re a lone-wolf developer, it can be extremely useful to be able to quickly tell when a bug was introduced or regenerate versions of PCBs you made months or years prior. Sure you could make pure directory snapshot backups and try to manage all your assets on the file system, but there are better ways that make collaborating on designs as well as backup, distribution, reversion, and testing processes a lot easier. And even if you’re a lone-wolf, it’s easy enough to set up that you’ll sleep better at night knowing you’ve got your hard work under version management.
If you’re on a hardware or firmware development team, you’ll have all the same problems as any pure software project has plus more. You have an even bigger need for the benefits a version control system like git can offer.
Anecdotally, there’s a local company with which I’m familiar that is involved in a substantial FPGA crypto project for the federal government. Recently, they lost days of time and effort because a developer made a change in the HDL that another developer wasn’t aware of. All this HDL lived on a common file share, so while it’s backed up and accessible by all, there was no notification and no process for change management around what is essentially software - FPGA HDL code. Even though the ultimate product is a hardware product, the real intellectual property is actually software, HDL in this case, and therefore, it should be treated like software.
Because so much hardware product development boils down to software in the form of HDL, firmware, schematics, PCB layouts, test instrument and test fixture scripts, for better or worse the overriding practice that governs hardware processes looks more like a software process. So, it makes sense to apply good software processes to managing the assets of hardware and embedded development.
Better management starts with ‘git’, the same version control system used to manage the 1000+ commits daily from the rollup of 100’s of developers for the Linux kernel. I’m assuming you’re reading this because you don’t have any version control established. If you do, it may not make sense to convert to ‘git’ if you’re already happy with your processes. However, if you’re starting a new project or have no process in place now, do yourself a favor, do a fast-forward - start with ‘git’.
Start with the Star Model
Git is capable of many different models of version management - the most advanced being completely distributed. In git, every repository can be a master - peer level with the original. However, I’m going to suggest the classic “Star” model to start with. The star model is a central source control server with many individual contributors all pulling from and pushing changes to the central system.
Git goes a step further in the Star model than other systems, however. Any developer is able to make local changes, keep those local changes versioned locally and only push changes when he or she’s ready to push to a wider group. No longer do you have to take a snapshot of the central tag, do a huge week-long or month-long binge of changes, then do a big-bang checkin at the end. You can be versioning your work locally, making changes, testing, throwing away things that don’t work, pulling current changes from others, reverting to a working version - all the things that make version management great. You can do these locally, without disrupting the work of others until your solution is fully baked and not lose the power of version control.
This local versioning and testing large number of changes locally before committing to a central server is often called micro-checkins. It simply a model for maintaining the benefits of version control without having to make every commit “official” and public until you’re ready to do so. Git supports the micro-checkin model superbly.
The Central Server
Git’s DNA is Linux - originally developed by Linus Torvalds. Git clients are available for all the popular platforms, but this article is about setting up a git server on Linux, specifically Ubuntu, so git clients of any common platform ilk can pull and push code .
Here’s the scenario:
We have an existing directory of embedded development assets that we want under version control. We want to access these items from any machine that has access to the server from any platform or client type (Windows, OS X, or Linux.) We want to be able to make a change, check it in locally, and when we’re ready, or even perhaps connected to the network again, push any changes to the central server.
In this example, I’ll show you how to put your Eagle PCB design files under management from a Mac OS X client where all version control transactions are safely done using secure shell.
On the Server
0) Install - The first thing you need to do, besides insuring you have an account and sudo access on the Linux server is install git. Fortunately, installing git on an Ubuntu linux server is trivial. Login to your Linux server, then type:
This gives you everything your Linux machine needs to be either a git client or server. There are ready-made binaries for many other platforms as well - I’ll leave it to you to follow the installation instructions relevant to your central server platform.
Other server assumptions:
0a) You have it on a network and can access it by secure shell.
0b) You have enough disk space with some headroom to store a code repository
1) Find ample space on the server to start the git repository. In this example, I’ve chosen: /var/git and made that directory. You will need to be root to create the directory in /var but you can change the permissions to be whatever you need. You can start with a single user and expand it to a git group later if you wish.
2) Copy the existing directory you want to manage to the server. This directory either already exists on the central Linux server or on your local machine. In either case, you need to start with your existing assets on the Linux server. You can put this directory anywhere you have permissions on the central server.
I have a directory called ‘eagle’ in which I keep all my Eagle CAD designs. Use scp to recursively copy the directory to the central server. As an example, if your remote server is called mybogusdomain.com and your user name is ‘joebob’ and your existing assets exist on a local machine, cd to the directory above the directory you want to copy to the central server and then secure copy it to the central server.
Wow that sounds like a sentence out of Dr. Suess, but it’s really this easy. On the Client machine where you have your original tree (ie: ~/Documents/eagle):
This will recursively copy the eagle sub-directory under the local ~/Documents directory, to your account on mybogusdomain.com.
At this point, that’s all you have: a copy of the directory you plan to put under management. You don’t have any version control going yet.
3) Back over on the server, you need to create a git repository and populate it with the initial directory structure. This is where it first got tricky for me when I was first getting to know git. It would be nice to just add all the files in the directory you uploaded into a git repo on the central server and just use that, but if you do this, you’ll only be able to clone the repository and a developer will not be able to push changes back to the central server.
You have to create what’s known as a Bare repository in order to allow remote developers to push changes to the central system.
In order to do that, follow these steps:
3a) Add all your files to a local git repository on the central server, then clone it as a bare repo.
After logging into the central server as your username, go to where you uploaded your asset directory in step 2), then create a git repo and add your files. Carrying the example through, login to the server as username: joebob and go to the directory: ~/eagle:
At this point you have a little localized git repo in your ~/eagle directory, but you still do not have a git repo you can both pull from and push changes to.
3b) Next, clone that local repository with the --bare option to create a centrally accessible git repository that you can pull from and push to. You do this from the space where you will permanently store the master tree: /var/git in this example:
This creates a bare repository in the /var/git directory called eagle.
The last parameter is optional but if you leave it off, it will create a directory named ‘eagle.git’ which I always find to be redundant and is something that will forever be required when you specify the URL to access the repo. So, I like to explicitly name the actual directory, usually after the project directory itself, in this case, just ‘eagle.’
Now you have a centrally accessible repository that you can both push and pull. This is considered the “Remote” repository. I’ve been calling it the central repository, but in git jargon, it’s the remote.
4) Add the remote repository location information to the git repo you made for yourself and from which the actual remote was cloned. This lets you try out some git using the tree you uploaded and effectively turns your uploaded tree into a full-fledged development workspace if you would like.
4a) Add the remote to the local development workspace git repo:
this tells your localized git repository that it can pull from a remote or push to a remote and where that remote is.
4b) Edit .git/config
Add these lines to your ~/eagle/.git/config file:
This tells git how the initial branches are set up both locally and remotely.
You’re done. Now you can both push and pull a centrally accessible git remote repository and you have a full-fledged push/pull workspace from which you can update or make changes.
5) Next: HOWOTO Pull a remote git repo to a local machine.
Install the appropriate git client for the client platform you’re planning to use. For Windows users, use the msysGit installer - You can download msysGit from here: http://code.google.com/p/msysgit/downloads/list
For Mac OS X users, pull git from: http://code.google.com/p/git-osx-installer/downloads/list?can=3 The full msysGit installer for Windows includes all the environmental things you need include a subset of cygwin and openssl.
Warning: if you use the msysGit client in GUI mode, make sure any SSH URLs, as in cli the examples below, you specify use the login name of the Linux server.
5a) Assume you have already installed a git client on your local machine, even for Windows, there’s a git client that uses a cli, so I’ll stick with the CLI since it covers all the client platforms:
5b) Clone a remote repository so you have a local version of it you can modify and push back if you want. Find a directory on your local machine where you want to populate the tree...lets say $HOME/git - from a bash shell (cygwin on Windows):
After a little bit of time where you can see some progress, git will bundle up the remote tree, securely transfer it, and make you one like it locally. Your new local repository is in ~/git/eagle.
From this point on, you can run Eagle CAD for PCB design locally, make changes in your designs, save them, commit them, and have them under version control. There’s one more step to go end-to-end with your designs so that others can see your changes - namely, you need to push your changes back to the central server.
6) Committing and Pushing
Lets say you modified your Eagle schematic and saved the file. Then you regenerated your PCB board layout and finally, regenerated all the Gerber files for your CAM jobs, possibly even using gerbmerge to create an entire panelized design you’ll submit to the board fab house. You’ve changed quite a bit of stuff that you want versioned so you can go back if you need.
Each time I get ready to submit a board design to BatchPCB or another board fab house, I commit and push my changes in order to make sure that if I need to resurrect the design later for debug or further production, I can go right to it. (Actually, there are ways to make an easy to remember tag or label for a specific version of all the files at a given point in time, but for git, it’s easy to pull designs based on dates if you want, too.)
I can put a date, version string, or even tag name on the silkscreen of my PCB and use that same date or tag name to retrieve the design later - but only if I commit and push first.
Here’s how to commit and push after your design changes and CAM file generations. On the client side:
The “git add .” (the dot is important) tells git to add any new files created to the repo and note any modifications made to existing files. You always have to add before you can commit any changes.
As you surmised in the example above, the -m option lets you supply a note about what changed to remind you later what you did. I’ll often write things like “moved the RJ45 and rotated the resistor net, regenerated board layout.” If you need to write a tome, don’t use the -m option and let git launch your default text editor instead. (set GIT_EDITOR environment variable in your shell to point to vim, emacs, or whatever programmer editor you like.)
At this point you have versioned your Eagle files locally and could revert to any date or time if you needed to. Every time you commit, you have the ability to exactly reconstruct your tree at that point in time any time in the future.
Now, when you’re ready to make sure the rest of the world also has your changes (other developers on your team) you still need to push them to the central server:
Push will conveniently wrap up all your changes, compress them and safely transfer them to the remote repository over ssh.
After this push has completed, your Eagle board changes are not only committed to your local repository (previous to the push) but they are also on the remote repository as well. Anyone else with access to that repository will be able to pull your changes assuming they’ve cloned the same repository and have credentials to access that server.
If someone else was working on the same Eagle project at the same time you were, you’ll have some conflicts, unfortunately. Git doesn’t use a locking mechanism like some SCM’s so there’s no way for it to know if two people have modified a binary file, for example, until both try to commit to the remote repository. If that happens, just like if two developers had tried to modify any binary, whether it’s a PNG file or a HEX firmware file, the two developers need to come to a conclusion about how to resolve it. Usually this involves lots of blood and large quantities of beer and other vices before everyone’s feeling right about the world again. It’s not really something the version control system can do to help merge a binary.
7) Pulling
If you’re working on a joint project and other developers are also making changes to other parts of the project - say someone’s working on a daughter card PCB and you’re working on the base board and the firmware, you may occasionally need to get their changes to review or at least keep current. Pin assignments can change, dimensions can change, power requirements might change - you need to stay up to date with what else is going on in the project. You need to pull the latest changes from the remote repository:
I will often need this even as a lone developer because I have multiple machines on which I develop - my desktop, my laptop, and the central server itself. I spend most of my time on my desktop, but if I’m going to go off-road, I’ll pull the latest onto my laptop so I can develop, even without a network connection. I can work, do my micro-checkins on my local laptop, and when I get back to a network connection, do a push to synchronize my changes to the central server.
I also want to share a design with my business partner, so to do that, after he’s cloned the Eagle repository, he can stay up with my changes on a daily or hourly basis if he wants by doing a ‘git pull’. Vica-versa, I can also get any of his progress and changes.
8) Backup
On the central server, if the /var directory isn’t already being backed up in its entirety, it would be a very good practice to put an rsync backup process on a cron job. I have a cron rsync of /var/git going every hour to copy changes in /var/git to an external backup drive so that the worst that can happen if I lose the disk for the remote repository is about an hour’s worth of work. Theoretically, I could have another cron job that does a git pull every hour to get the latest repo - that repo could then become a master in the event of a catastrophic failure of the original server (assuming the git pull was going to an external drive or other machine.) Finally, one could rsync the /var/git directory to another linux box entirely across the network or have it doing periodic git pulls also. It’s a very redundant architecture for backup purposes.
Summary
This has been a very quick introduction to using ‘git’ for embedded development. It’s very similar to using git for any type of software development and that’s pretty much the point of the article - hardware and firmware asset management can be easily accomplished with the same powerful tools and best practices used by software engineers.
I hope this has inspired you to build good software practices into your hardware development methodology. In future articles, I’ll try to cover what types of embedded development assets are appropriate for version control (not all are), how to tag, branch, and revert as needed.
Additional Resources
Here are some very good additional resources that will help you as you become accustomed to ‘git’:
http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html
A fairly lengthy, but quite high quality video tutorial on git can be found here: http://bit.ly/SABw7
One of the best books on git is Version Control with Git http://bit.ly/oriellygit
The latter book has one of the best explanations I’ve seen of why you need a --bare repository to implement a central server model and was the critical piece of info I was missing when I first tried to implement ‘git’.
Comments and Corrections
If you have ideas for future articles around the topic of git and version control for embedded developers feel free to tweet me at @esawdust. Same if you have any comments or corrections you see to make on this article - tweet me @esawdust.
Alternatively, you can contact me directly.
This article shows how to deploy one of the best version control systems, git, for embedded hardware and software developers. The example I’ll use is to version control Eagle PCB CAD designs, but the example is generally applicable to any dimension of embedded development regardless of design tool.
Motivation
Even if you’re a lone-wolf developer, it can be extremely useful to be able to quickly tell when a bug was introduced or regenerate versions of PCBs you made months or years prior. Sure you could make pure directory snapshot backups and try to manage all your assets on the file system, but there are better ways that make collaborating on designs as well as backup, distribution, reversion, and testing processes a lot easier. And even if you’re a lone-wolf, it’s easy enough to set up that you’ll sleep better at night knowing you’ve got your hard work under version management.
If you’re on a hardware or firmware development team, you’ll have all the same problems as any pure software project has plus more. You have an even bigger need for the benefits a version control system like git can offer.
Anecdotally, there’s a local company with which I’m familiar that is involved in a substantial FPGA crypto project for the federal government. Recently, they lost days of time and effort because a developer made a change in the HDL that another developer wasn’t aware of. All this HDL lived on a common file share, so while it’s backed up and accessible by all, there was no notification and no process for change management around what is essentially software - FPGA HDL code. Even though the ultimate product is a hardware product, the real intellectual property is actually software, HDL in this case, and therefore, it should be treated like software.
Because so much hardware product development boils down to software in the form of HDL, firmware, schematics, PCB layouts, test instrument and test fixture scripts, for better or worse the overriding practice that governs hardware processes looks more like a software process. So, it makes sense to apply good software processes to managing the assets of hardware and embedded development.
Better management starts with ‘git’, the same version control system used to manage the 1000+ commits daily from the rollup of 100’s of developers for the Linux kernel. I’m assuming you’re reading this because you don’t have any version control established. If you do, it may not make sense to convert to ‘git’ if you’re already happy with your processes. However, if you’re starting a new project or have no process in place now, do yourself a favor, do a fast-forward - start with ‘git’.
Start with the Star Model
Git is capable of many different models of version management - the most advanced being completely distributed. In git, every repository can be a master - peer level with the original. However, I’m going to suggest the classic “Star” model to start with. The star model is a central source control server with many individual contributors all pulling from and pushing changes to the central system.
Git goes a step further in the Star model than other systems, however. Any developer is able to make local changes, keep those local changes versioned locally and only push changes when he or she’s ready to push to a wider group. No longer do you have to take a snapshot of the central tag, do a huge week-long or month-long binge of changes, then do a big-bang checkin at the end. You can be versioning your work locally, making changes, testing, throwing away things that don’t work, pulling current changes from others, reverting to a working version - all the things that make version management great. You can do these locally, without disrupting the work of others until your solution is fully baked and not lose the power of version control.
This local versioning and testing large number of changes locally before committing to a central server is often called micro-checkins. It simply a model for maintaining the benefits of version control without having to make every commit “official” and public until you’re ready to do so. Git supports the micro-checkin model superbly.
The Central Server
Git’s DNA is Linux - originally developed by Linus Torvalds. Git clients are available for all the popular platforms, but this article is about setting up a git server on Linux, specifically Ubuntu, so git clients of any common platform ilk can pull and push code .
Here’s the scenario:
We have an existing directory of embedded development assets that we want under version control. We want to access these items from any machine that has access to the server from any platform or client type (Windows, OS X, or Linux.) We want to be able to make a change, check it in locally, and when we’re ready, or even perhaps connected to the network again, push any changes to the central server.
In this example, I’ll show you how to put your Eagle PCB design files under management from a Mac OS X client where all version control transactions are safely done using secure shell.
On the Server
0) Install - The first thing you need to do, besides insuring you have an account and sudo access on the Linux server is install git. Fortunately, installing git on an Ubuntu linux server is trivial. Login to your Linux server, then type:
sudo apt-get install git
This gives you everything your Linux machine needs to be either a git client or server. There are ready-made binaries for many other platforms as well - I’ll leave it to you to follow the installation instructions relevant to your central server platform.
Other server assumptions:
0a) You have it on a network and can access it by secure shell.
0b) You have enough disk space with some headroom to store a code repository
1) Find ample space on the server to start the git repository. In this example, I’ve chosen: /var/git and made that directory. You will need to be root to create the directory in /var but you can change the permissions to be whatever you need. You can start with a single user and expand it to a git group later if you wish.
sudo mkdir /var/git
2) Copy the existing directory you want to manage to the server. This directory either already exists on the central Linux server or on your local machine. In either case, you need to start with your existing assets on the Linux server. You can put this directory anywhere you have permissions on the central server.
I have a directory called ‘eagle’ in which I keep all my Eagle CAD designs. Use scp to recursively copy the directory to the central server. As an example, if your remote server is called mybogusdomain.com and your user name is ‘joebob’ and your existing assets exist on a local machine, cd to the directory above the directory you want to copy to the central server and then secure copy it to the central server.
Wow that sounds like a sentence out of Dr. Suess, but it’s really this easy. On the Client machine where you have your original tree (ie: ~/Documents/eagle):
cd ~/Documents scp -r eagle joebob@mybogusdomain.com:/home/joebob/
This will recursively copy the eagle sub-directory under the local ~/Documents directory, to your account on mybogusdomain.com.
At this point, that’s all you have: a copy of the directory you plan to put under management. You don’t have any version control going yet.
3) Back over on the server, you need to create a git repository and populate it with the initial directory structure. This is where it first got tricky for me when I was first getting to know git. It would be nice to just add all the files in the directory you uploaded into a git repo on the central server and just use that, but if you do this, you’ll only be able to clone the repository and a developer will not be able to push changes back to the central server.
You have to create what’s known as a Bare repository in order to allow remote developers to push changes to the central system.
In order to do that, follow these steps:
3a) Add all your files to a local git repository on the central server, then clone it as a bare repo.
After logging into the central server as your username, go to where you uploaded your asset directory in step 2), then create a git repo and add your files. Carrying the example through, login to the server as username: joebob and go to the directory: ~/eagle:
cd ~/eagle
git init
git add .
git commit -m"initial checkin"
At this point you have a little localized git repo in your ~/eagle directory, but you still do not have a git repo you can both pull from and push changes to.
3b) Next, clone that local repository with the --bare option to create a centrally accessible git repository that you can pull from and push to. You do this from the space where you will permanently store the master tree: /var/git in this example:
cd /var/git git clone --bare ~/eagle eagle
This creates a bare repository in the /var/git directory called eagle.
The last parameter is optional but if you leave it off, it will create a directory named ‘eagle.git’ which I always find to be redundant and is something that will forever be required when you specify the URL to access the repo. So, I like to explicitly name the actual directory, usually after the project directory itself, in this case, just ‘eagle.’
Now you have a centrally accessible repository that you can both push and pull. This is considered the “Remote” repository. I’ve been calling it the central repository, but in git jargon, it’s the remote.
4) Add the remote repository location information to the git repo you made for yourself and from which the actual remote was cloned. This lets you try out some git using the tree you uploaded and effectively turns your uploaded tree into a full-fledged development workspace if you would like.
4a) Add the remote to the local development workspace git repo:
cd ~/eagle git remote add origin /var/git/eagle
this tells your localized git repository that it can pull from a remote or push to a remote and where that remote is.
4b) Edit .git/config
Add these lines to your ~/eagle/.git/config file:
[branch "master"] remote = origin merge = refs/heads/master
This tells git how the initial branches are set up both locally and remotely.
You’re done. Now you can both push and pull a centrally accessible git remote repository and you have a full-fledged push/pull workspace from which you can update or make changes.
5) Next: HOWOTO Pull a remote git repo to a local machine.
Install the appropriate git client for the client platform you’re planning to use. For Windows users, use the msysGit installer - You can download msysGit from here: http://code.google.com/p/msysgit/downloads/list
For Mac OS X users, pull git from: http://code.google.com/p/git-osx-installer/downloads/list?can=3 The full msysGit installer for Windows includes all the environmental things you need include a subset of cygwin and openssl.
Warning: if you use the msysGit client in GUI mode, make sure any SSH URLs, as in cli the examples below, you specify use the login name of the Linux server.
5a) Assume you have already installed a git client on your local machine, even for Windows, there’s a git client that uses a cli, so I’ll stick with the CLI since it covers all the client platforms:
5b) Clone a remote repository so you have a local version of it you can modify and push back if you want. Find a directory on your local machine where you want to populate the tree...lets say $HOME/git - from a bash shell (cygwin on Windows):
mkdir ~/git cd ~/git git clone ssh://joebob@mybogusdomain.com/var/git/eagle
After a little bit of time where you can see some progress, git will bundle up the remote tree, securely transfer it, and make you one like it locally. Your new local repository is in ~/git/eagle.
From this point on, you can run Eagle CAD for PCB design locally, make changes in your designs, save them, commit them, and have them under version control. There’s one more step to go end-to-end with your designs so that others can see your changes - namely, you need to push your changes back to the central server.
6) Committing and Pushing
Lets say you modified your Eagle schematic and saved the file. Then you regenerated your PCB board layout and finally, regenerated all the Gerber files for your CAM jobs, possibly even using gerbmerge to create an entire panelized design you’ll submit to the board fab house. You’ve changed quite a bit of stuff that you want versioned so you can go back if you need.
Each time I get ready to submit a board design to BatchPCB or another board fab house, I commit and push my changes in order to make sure that if I need to resurrect the design later for debug or further production, I can go right to it. (Actually, there are ways to make an easy to remember tag or label for a specific version of all the files at a given point in time, but for git, it’s easy to pull designs based on dates if you want, too.)
I can put a date, version string, or even tag name on the silkscreen of my PCB and use that same date or tag name to retrieve the design later - but only if I commit and push first.
Here’s how to commit and push after your design changes and CAM file generations. On the client side:
cd ~/git/eagle git add . git commit -m"Made massive changes"
The “git add .” (the dot is important) tells git to add any new files created to the repo and note any modifications made to existing files. You always have to add before you can commit any changes.
As you surmised in the example above, the -m option lets you supply a note about what changed to remind you later what you did. I’ll often write things like “moved the RJ45 and rotated the resistor net, regenerated board layout.” If you need to write a tome, don’t use the -m option and let git launch your default text editor instead. (set GIT_EDITOR environment variable in your shell to point to vim, emacs, or whatever programmer editor you like.)
At this point you have versioned your Eagle files locally and could revert to any date or time if you needed to. Every time you commit, you have the ability to exactly reconstruct your tree at that point in time any time in the future.
Now, when you’re ready to make sure the rest of the world also has your changes (other developers on your team) you still need to push them to the central server:
git push
Push will conveniently wrap up all your changes, compress them and safely transfer them to the remote repository over ssh.
After this push has completed, your Eagle board changes are not only committed to your local repository (previous to the push) but they are also on the remote repository as well. Anyone else with access to that repository will be able to pull your changes assuming they’ve cloned the same repository and have credentials to access that server.
If someone else was working on the same Eagle project at the same time you were, you’ll have some conflicts, unfortunately. Git doesn’t use a locking mechanism like some SCM’s so there’s no way for it to know if two people have modified a binary file, for example, until both try to commit to the remote repository. If that happens, just like if two developers had tried to modify any binary, whether it’s a PNG file or a HEX firmware file, the two developers need to come to a conclusion about how to resolve it. Usually this involves lots of blood and large quantities of beer and other vices before everyone’s feeling right about the world again. It’s not really something the version control system can do to help merge a binary.
7) Pulling
If you’re working on a joint project and other developers are also making changes to other parts of the project - say someone’s working on a daughter card PCB and you’re working on the base board and the firmware, you may occasionally need to get their changes to review or at least keep current. Pin assignments can change, dimensions can change, power requirements might change - you need to stay up to date with what else is going on in the project. You need to pull the latest changes from the remote repository:
cd ~/git/eagle git pull
I will often need this even as a lone developer because I have multiple machines on which I develop - my desktop, my laptop, and the central server itself. I spend most of my time on my desktop, but if I’m going to go off-road, I’ll pull the latest onto my laptop so I can develop, even without a network connection. I can work, do my micro-checkins on my local laptop, and when I get back to a network connection, do a push to synchronize my changes to the central server.
I also want to share a design with my business partner, so to do that, after he’s cloned the Eagle repository, he can stay up with my changes on a daily or hourly basis if he wants by doing a ‘git pull’. Vica-versa, I can also get any of his progress and changes.
8) Backup
On the central server, if the /var directory isn’t already being backed up in its entirety, it would be a very good practice to put an rsync backup process on a cron job. I have a cron rsync of /var/git going every hour to copy changes in /var/git to an external backup drive so that the worst that can happen if I lose the disk for the remote repository is about an hour’s worth of work. Theoretically, I could have another cron job that does a git pull every hour to get the latest repo - that repo could then become a master in the event of a catastrophic failure of the original server (assuming the git pull was going to an external drive or other machine.) Finally, one could rsync the /var/git directory to another linux box entirely across the network or have it doing periodic git pulls also. It’s a very redundant architecture for backup purposes.
Summary
This has been a very quick introduction to using ‘git’ for embedded development. It’s very similar to using git for any type of software development and that’s pretty much the point of the article - hardware and firmware asset management can be easily accomplished with the same powerful tools and best practices used by software engineers.
I hope this has inspired you to build good software practices into your hardware development methodology. In future articles, I’ll try to cover what types of embedded development assets are appropriate for version control (not all are), how to tag, branch, and revert as needed.
Additional Resources
Here are some very good additional resources that will help you as you become accustomed to ‘git’:
http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html
A fairly lengthy, but quite high quality video tutorial on git can be found here: http://bit.ly/SABw7
One of the best books on git is Version Control with Git http://bit.ly/oriellygit
The latter book has one of the best explanations I’ve seen of why you need a --bare repository to implement a central server model and was the critical piece of info I was missing when I first tried to implement ‘git’.
Comments and Corrections
If you have ideas for future articles around the topic of git and version control for embedded developers feel free to tweet me at @esawdust. Same if you have any comments or corrections you see to make on this article - tweet me @esawdust.
Alternatively, you can contact me directly.
Eagle Tip #2 - Selection and Movement
03/12/09 22:55 Filed in: Eagle CAD | Eagle Tutorial
Synopsis: This is the second screencast in the Eagle CAD Tips and Tutorials for New Users and it focuses primarily on how selection and movement work. When you first start with Eagle it seems ridiculously hard to move a component or group of components around on a schematic. Until you first understand the Eagle selection model, it’s very difficult to get very far with your first schematic.
Tip #1 - Separating Label from Part
[Update: 11/2/09 - check out our new ESawdust Eagle Parts Search Engine ]
Tip #1 - Separating Label from Part
[Update: 11/2/09 - check out our new ESawdust Eagle Parts Search Engine ]
Eagle Tip #1 - Separating Label from Part
03/12/09 21:09 Filed in: Eagle CAD | Eagle Tutorial
Synopsis: This is the opening screencast of Eagle CAD Tips and Tutorials for New Users. I am (was?) a new user a few months ago and I found Eagle has an obtuse user interface if you’re used to fine digital graphic arts applications like Adobe Photoshop or Flash vector drawing applications. The objective of this series of screencasts is to help new users over the initial Eagle CAD bumps.
While Eagle is a very powerful schematic capture and PCB design package, there are many operations that are unintuitive in Eagle. I stumbled over most, if not all of them on my way to designing my first PCB. The problem with Eagle is you quickly hit walls and it’s difficult and time-consuming to guess your way around the Eagle user interface roadblocks.
As these sometimes painful lessons are still fresh in my mind, I am hoping to help others in the same boat learn the basics of Eagle more quickly. If I stumbled on it, I want to make a tutorial about the issue and how to get around it or make Eagle do what you want. If you have any requests for Eagle tutorials, send me an email perhaps I can figure out the issue you have or post something related to it.
Eagle Tip #1 - How to separate the label from the component and reposition the component’s label in an Eagle schematic
What’s the problem? If you rotate a part, the label rotates with it making it difficult to read or improperly positioned for a pleasing and easy to read schematc. This screencast demonstrates how to separate an Eagle component from its label and adjust its orientation and fine position.
Tip #2 - Selection and Movement
[Update: 11/2/09 - check out our new ESawdust Eagle Parts Search Engine ]
While Eagle is a very powerful schematic capture and PCB design package, there are many operations that are unintuitive in Eagle. I stumbled over most, if not all of them on my way to designing my first PCB. The problem with Eagle is you quickly hit walls and it’s difficult and time-consuming to guess your way around the Eagle user interface roadblocks.
As these sometimes painful lessons are still fresh in my mind, I am hoping to help others in the same boat learn the basics of Eagle more quickly. If I stumbled on it, I want to make a tutorial about the issue and how to get around it or make Eagle do what you want. If you have any requests for Eagle tutorials, send me an email perhaps I can figure out the issue you have or post something related to it.
Eagle Tip #1 - How to separate the label from the component and reposition the component’s label in an Eagle schematic
What’s the problem? If you rotate a part, the label rotates with it making it difficult to read or improperly positioned for a pleasing and easy to read schematc. This screencast demonstrates how to separate an Eagle component from its label and adjust its orientation and fine position.
Tip #2 - Selection and Movement
[Update: 11/2/09 - check out our new ESawdust Eagle Parts Search Engine ]
Sparkfun Stencil and Solder Paste Class
02/12/09 07:29 Filed in: PCB | Solder Paste
Synopsis - These are notes and pictures I took when I was at the Sparkfun stencil and solder paste class in Boulder Feb 11, 2009. This article includes pictures of parts of the process, Livescribe notes with audio, and a short movie showing the swipe technique used by Abe, the production floor manager at Sparkfun.
The class was broadcast over live streaming, but apparently the audio was poor, so I have uploaded my notes which include audio that is pretty decent. Perhaps some of the questions might be heard that weren’t heard on the broadcast. These notes use Livescribe, so you can click in the notes anywhere and jump to that section of the audio and presentation.
After the presentation was over, it was hands-on time and I stopped taking notes and recording audio but did manage to take some pictures and one little vignette/movie whose link is down below.
I didn’t count the total number of participants but it looked like maybe 14-15 people attended; most from the Colorado area but one gent was from Oregon.
Overall impression - I’m not sure how you could really learn this topic without doing it hands-on and therefore, this article and any like it that shows solder paste and stencil techniques will always be lacking that element. If the Sparkfun guys lack anything in their presentation polish (they’re engineers after all!), they way more than make up for it in hard-core experience and their willingness to share their knowledge and facility with us to learn. These classes are excellent and if you ever get a chance to take a class at Sparkfun, DO IT!. (This is my 3rd - SMD soldering, Eagle schematic capture, and now solder paste.) Their PCB Layout class is coming up on March 11.
Below are some pictures from the hands-on session and a link to a short video on swipe technique.
If you click the pictures you’ll get an enlarged image.
Here’s the Sparkfun production floor where the class was held:
This is one of 3 stencil and solder paste stations we used:
The project was to stencil and populate a few of these single axis gyro boards from Sparkfun
The “frame” is just some dents and dings circuit boards which work well because they’re the right height and are good and square. Abe (Sparkfun production manager), usually lays down a couple strips of masking tape to help keep the target board slightly higher than the frame. He says the stencil will tend to sit better this way:
Here’s the board after it’s in the frame. You should block the open end with another dinged board in order help keep the stencil flat as you swipe it with paste later.
Initial alignment of the stencil. The stencil looks gold in these pictures, but it really had a stainless steel color:
Initial spatula sizing - get a putty knife that’s clean and that’s slightly wider than the holes in the stencil you need to cover.
Use a narrow putty knife to ladle out a small glop of solder paste:
Spread the paste on the application putty knife right along the end - you want form a clean narrow bead on the end of the application putty knife.
You should end up with a bead of solder paste that looks like this:
Lay the putty knife over the edge of the station so it doesn’t smear on anything. Then start in on the initial fine alignment of the stencil.
Abe said to use a light touch to position it during this stage. The thing I noticed was that when you had perfect alignment, all the holes in the stencil will turn bright silver. If you have any dark colored holes or any holes are partially silver and partially dark, you’re not aligned yet.
Using your weak hand (Abe’s left hand in this picture), anchor one end of the stencil. Press hard, but not so hard that you could make the stencil slip:
Get ready to grab the putty knife with your strong hand. Do not move the stencil:
Make the initial swipe. Start at a steep angle and swipe towards a lower angle. You hardly need to press at all on the initial swipe:
Here’s a movie of the 2nd clean swipe with some narration by Sparkfun’s Abe. It should only take two swipes. The more you swipe it, the more likely you are to move the stencil and have to clean everything and start over.
In that movie above, you can see the proper technique for lifting the stencil. Lifting it off is where most of the mistakes will occur. Any slight rotation as you lift will smear the solder closest to your anchor hand. Peel it up and make sure it’s completely clear of the board before you remove the stencil.
Students populating the surface mount components of the gyro board after stenciling:
Sparkfun’s Nate Seidle reminiscing over the 1985 reflow oven Sparkfun uses for all reflow soldering:
A student project going into the oven for reflow:
The Sparkfun 1985 reflow oven:
It was a fantastic class and our thanks go out to Nathan, Abe, Matt, Bob and Heather for their excellent help and support teaching us this process.
Landon
The class was broadcast over live streaming, but apparently the audio was poor, so I have uploaded my notes which include audio that is pretty decent. Perhaps some of the questions might be heard that weren’t heard on the broadcast. These notes use Livescribe, so you can click in the notes anywhere and jump to that section of the audio and presentation.
After the presentation was over, it was hands-on time and I stopped taking notes and recording audio but did manage to take some pictures and one little vignette/movie whose link is down below.
I didn’t count the total number of participants but it looked like maybe 14-15 people attended; most from the Colorado area but one gent was from Oregon.
Overall impression - I’m not sure how you could really learn this topic without doing it hands-on and therefore, this article and any like it that shows solder paste and stencil techniques will always be lacking that element. If the Sparkfun guys lack anything in their presentation polish (they’re engineers after all!), they way more than make up for it in hard-core experience and their willingness to share their knowledge and facility with us to learn. These classes are excellent and if you ever get a chance to take a class at Sparkfun, DO IT!. (This is my 3rd - SMD soldering, Eagle schematic capture, and now solder paste.) Their PCB Layout class is coming up on March 11.
Below are some pictures from the hands-on session and a link to a short video on swipe technique.
If you click the pictures you’ll get an enlarged image.
Here’s the Sparkfun production floor where the class was held:
This is one of 3 stencil and solder paste stations we used:
The project was to stencil and populate a few of these single axis gyro boards from Sparkfun
The “frame” is just some dents and dings circuit boards which work well because they’re the right height and are good and square. Abe (Sparkfun production manager), usually lays down a couple strips of masking tape to help keep the target board slightly higher than the frame. He says the stencil will tend to sit better this way:
Here’s the board after it’s in the frame. You should block the open end with another dinged board in order help keep the stencil flat as you swipe it with paste later.
Initial alignment of the stencil. The stencil looks gold in these pictures, but it really had a stainless steel color:
Initial spatula sizing - get a putty knife that’s clean and that’s slightly wider than the holes in the stencil you need to cover.
Use a narrow putty knife to ladle out a small glop of solder paste:
Spread the paste on the application putty knife right along the end - you want form a clean narrow bead on the end of the application putty knife.
You should end up with a bead of solder paste that looks like this:
Lay the putty knife over the edge of the station so it doesn’t smear on anything. Then start in on the initial fine alignment of the stencil.
Abe said to use a light touch to position it during this stage. The thing I noticed was that when you had perfect alignment, all the holes in the stencil will turn bright silver. If you have any dark colored holes or any holes are partially silver and partially dark, you’re not aligned yet.
Using your weak hand (Abe’s left hand in this picture), anchor one end of the stencil. Press hard, but not so hard that you could make the stencil slip:
Get ready to grab the putty knife with your strong hand. Do not move the stencil:
Make the initial swipe. Start at a steep angle and swipe towards a lower angle. You hardly need to press at all on the initial swipe:
Here’s a movie of the 2nd clean swipe with some narration by Sparkfun’s Abe. It should only take two swipes. The more you swipe it, the more likely you are to move the stencil and have to clean everything and start over.
In that movie above, you can see the proper technique for lifting the stencil. Lifting it off is where most of the mistakes will occur. Any slight rotation as you lift will smear the solder closest to your anchor hand. Peel it up and make sure it’s completely clear of the board before you remove the stencil.
Students populating the surface mount components of the gyro board after stenciling:
Sparkfun’s Nate Seidle reminiscing over the 1985 reflow oven Sparkfun uses for all reflow soldering:
A student project going into the oven for reflow:
The Sparkfun 1985 reflow oven:
It was a fantastic class and our thanks go out to Nathan, Abe, Matt, Bob and Heather for their excellent help and support teaching us this process.
Landon
asdfasdf
