Enginursday - Open Source Documentation Tools
Discussion of the OS tools we are using, and a GitHub update.
My current job here at SparkFun includes organizing documentation for our products, as well as determining what parts need to be examined for possible revisions and acting as a liaison between customer feedback and the engineering team. When I first started this job a few months ago, we didn’t have a great system in place to track changes and product suggestions from customers, or even internal changes and updates. All of our board revisions were done on our internal share drive, which made it difficult to track down who was currently updating files. There was also no notification system if things did get modified in any way. Needless to say, navigating through that system for anyone looking for particular information could be overwhelming and panic-inducing.
Because of this, we started moving all of our Eagle files and code for boards and tutorials over to GitHub, which allows us to have a trackable history on product changes and to make this history accessible to the entire community. The other great thing about this is that it allows you, the customer, to become a part of the revision cycle. You can now take our board or code files, update them, and send us a pull request with your revisions. Have a great example sketch for a sensor you want to share, that you would prefer doesn’t get lost in the forums/comments? Can’t stand the fact that a board is missing mounting holes? Let’s add it to the repo for that board! You can find out more gritty details about how to contribute and use this to your advantage on our GitHub tutorial here.
While GitHub does have a lot of great features and is accessible to anyone, it certainly isn’t perfect for us. It was originally designed to work with code and isn’t optimal for version control in regards to board design files, 3D model files or part libraries. Because of this, we are still looking to the Open Source community to see what other tools we can find to help make the sharing and distribution of our documentation easier. We want something that helps us to stay organized and on top of changes currently being worked on, and something that allows the community to access the information as needed. While we are currently collaborating with several Open Source projects, including Fritzing and Circuits.io, we are still interested to find out what other options are out there. And while we are also using tools that are freely available to the general public, such as SketchUp for 3D models, this again isn’t the most ideal tool for us, and from a lot of your feedback, you aren’t all thrilled with it as well.
A few months back, I attended the Open Source Hardware Documentation Jam along with my fellow engineer Mike Hord, and we were able to interact with several different members in the community and hear about the different tools available.
Open Hardware Documentation Jam
(Image credits: Maximilian Becker, aLF, Daniel Heitz, Guilherme Arnon Schmitt)
Unfortunately, the general consensus was that there are still a lot of problems with the current toolset available for sharing OSHW projects. Mike and I will also be attending the Open Hardware Summit in a few weeks (come say hi if you end up there!) to see what other tools we might be able to learn about. In the meantime however, we want to poll you! What type of Open Source tools do you use for your personal designs? Is there something we could be using to make sharing our code, board files and documentation with you easier? What can we be doing differently to make it easier for you to access the information you need?
Keep in mind that while I will be taking a look at what feedback you give, there’s only a handful of us here at SparkFun in charge of updating links and file types to share with you, so any changes may take time and there’s no guarantee that we can feasibly switch to a new toolset. But in the spirit of Open Sourcing All the Things!, share your ideas with the community! We’ll compile all of the suggested tools into a resource page for you.
This stuff is King Cool. I am very interested in what has happened with the ancient prophecy that Sparkfun will release its eCommerce/inventory/fulfillment solution. There are people who have copied the look and feel nearly exactly (eeetech for example). But it is the back end that counts. Like you guys a few years ago, I have looked at dozens and dozens of other people's offerings and they are either too expensive, too eccentric, or just don't fit the business.
About the not so ideal tool chain, hook up with Blender3d !! Those guys are all about OS and whatnot. Maybe they'd do a summer of programming to add PCB, schematics, technical drawings and all that good stuff to it's already impressive capabilities. There might be scripts out there already that do some of these things.
It's definitely worth checking out. Thanks for the hints about the scripts though. I'm going to have to dig into it more.
So, my wish was that there is an easier to understand open source license; I barely understand the different implications of all the software licenses through all the legal mumbo-jumbo, let alone how to apply them to hardware. How does one go about releasing a hardware project open source? Can one just say something like: please go ahead, use it, and don't bother me or other people about it? Can the same license apply to both the hardware and software?
I agree that the current licensing definitions can be a little confusing. Sadly, as with anything that ends up with legal implications, I don't think they can simplify them down much more than they are currently. However, you might want to check out CreativeCommons.org and OpenSource.org if you haven't already. Seeing all of the definitions together helped it become a little clearer for me personally.
I am surprised that you guys use Eagle, as that is not open source. I am using KiCad for schematic capture and PCB design. For mechanical drawings I am using Sketchup.
The lack of Eagle being OS is bothersome, but at the time that we started moving our file documentation into Eagle (many, many years ago), Eagle was chosen as being one of the few PCB programs that had a useful free version. There are new OS pcb editors, but this again comes down to the issue of porting all of our current existing data from one system to another, and the logistics of that.
That is always a tough call, but I have always found it better to make moves sooner, rather than later. Having to support Legacy software is always a pain, but it is better to make the move on your own terms rather than waiting to be forced.
Agreed. Until I came into this position though, there wasn't really anyone here at SparkFun who had the time to dedicate to finding a new system or porting data over. There's also the tiny issue of having to retrain half of the company on a new system if we were to decide to do that, which can be a hard sell to some departments. Something about people getting stuck in their ways :)
Sparkfun should hire a software engineer dedicated to design an open source cad package that can read eagle libraries and eventually replace Eagle...
Someone has already started on that, and it's open source! https://github.com/Trump211/Eagle2Kicad
Awesome! Thanks for sharing that!
Current Eagle libraries are in XML - reading them is pretty easy. Writing a converter to any well-documented format should be straightforward.
Nice to see that I'm not the only one using KiCad. KiCad is great, and has absolutely nothing to envy to Eagle. I really hope some day Sparkfun will get things strait and migrate to an OS editor.
sketchup has some pretty severe limitations, but I have yet to find an alternative. I'd be curious if there's something a bit more robust.
Take a look at FreeCAD. It is in early stages of development, but moving ahead at a pretty steady pace. 0.14 will bring assemblies and a new historical modeling tree. http://www.freecadweb.org/
good to know, I might try it out. Ultimately, I'm looking for something with similar functionality to Solidworks, but that's open-source so the files can be shared.
I could personally recommend OpenSCAD for 3D modelling. But it is really for coders.
Huh. Never heard of it before, but it looks interesting from what I'm seeing on there now. Thanks for sharing!
I have been toying around with https://upverter.com/ and really like the pace of development along with the features. I originally tried out http://www.circuits.io/, but switched over due to what seemed like a better overall feel and features like simulation and now community review.
One thing that might be interesting to try is automatically generated image files (e.g. PNGs) each time you commit a hardware design file (e.g. Eagle file, SketchUp). GitHub has some reasonably good tools for comparing different versions of image files, so having an image for each version of, say, an Eagle schematic could go a long way towards being able to see the changes between versions. I think it might be possible with some combination of a Git commit hook and an Eagle script.
Hmm, that's a good idea. I don't know how well it would work with things like the Eagle parts library, but that's definitely something to check out for individual board files.
I'm pretty sure we talked to Tom Preston-Werner a few years back about rendering Gerbers on GitHub. That's probably a subject we should revisit.
We use Creo at school and the students find it easy to use - similar to solidworks but 'free for educational use'
I didn't realize they did a free-for-educational-use version. Thanks for sharing!
I am a SolidWorks user at work, but I've recently looked into using Creo Elements/Direct Modeling Express for home use. It's not technically open source, but more like freeware. I haven't used it much, but it seems more familiar to me than SketchUp.
good suggestion. I too am a solidworks user, and sketchup just doesn't get the job done. We can check into it.