12

I am developing an electronic device which has two parts: hardware (Eagle schematics) and firmware (C++ source code). I would like to track changes in both source code and schematics, but there are some points where I am not sure how to organize my work:

  • For the source code I would definitely use Git. But are schematics worth versioning when they are in fact binary files (new Eagle versions use some XML format, but it is not so human readable...)?

  • Is it good idea to put sources and schematics into one Git repository? It would make sense, but on the other hand my log would contain both software and hardware changes. Also the software can have several branches, but hardware probably not...

  • How to deal with hardware revisions? Tag them or save them in separate directories?

  • Also there could be some dependencies between hardware revision and firmware version. How to deal with them?

Could you please share your best practices with me?

Null
  • 7,448
  • 17
  • 36
  • 48
Honza Vojtěch
  • 465
  • 6
  • 13
  • Would a commercial solution work? – Eugene Sh. Feb 15 '17 at 15:07
  • 5
    I wouldn't touch a commercial version control system ever again. My experience of them is terrible workflows that are far harder to use than svn or even git. – pjc50 Feb 15 '17 at 15:17
  • Whatever versioning software you use, make sure it is replacing the whole file when dealing with schematics and not looking at the text. I've had that be an issue in the past. You'd never want to do a diff on most schematic files. – Voltage Spike Feb 16 '17 at 17:09

2 Answers2

19

Most of it comes down to personal preferences.

I track everything I do for a project in Git. Especially since Git handles most types of files, even binary, sufficiently efficiently. (In stead of built-in Altium SVN nonsense)

One of my main reasons to do so is that my customers don't all feel Dropbox is safe enough and I need a back-up system that I can access across the world, with also some versioning context on most of what I do. So I set up a private Git server and encrypted backup system and it works a treat. Boards, Schematics, Code, Documentation, Reports, Manual Modifications, everything is tracked.

I would normally create a a Repository for Hardware, one for Software and one for Firmware if it is a large, potentially long-running project, but for small service projects, examples or little experiments I often put it all in one repository, since the resulting chaos won't be big.

In Git you can use sub-repositories as well to integrate the Firmware into the Hardware project or the other way around, even if they are separately managed repositories.

For the larger projects I also commonly use bug tracking systems to keep track of issues and resolutions, again for HW as well as SW, Mantis is a nice one that can be used for free.

For hardware revisions I generate Gerbers, or whatever have you, tagged with the Git Hash for that revision, those Gerbers then are the only discrete "old fashioned" versioned stuff in folders by R01, 02, etc. Since you don't want to regenerate them all the time, but they are resulting files so shouldn't be versioned in Git itself, really (because your design software should be deterministic with generating production content, or else ...).

If there's something interesting in R01 that isn't happening in R02 (or the other way around), you have two Git Hashes with which you can compare source files, no worries.

As a final note, one conceptual example of a project, would have a Hardware repository, which also hosts a "BoardPinout.h" file. This file is included as a remotely versioned file into the Firmware repository, which has a few interface definition files that get remotely included into the Software repository.

Meaning every time I change a few signals without modifying broad functionality the HW project "updates" the BoardPinout, which then can be updated and used in Firmware, and so on.

Asmyldof
  • 18,299
  • 2
  • 33
  • 53
  • 1
    Does it really _ever_ make sense to put hardware and firmware in different repos? How would it be a problem to have them in one? I'd rather expect it to be a problem if you need to keep track of changes in the components that belong together (e.g. swapped IO pins need to be reflected in different firmware assignments, and checking out incomptable versions would lead to mayhem). – leftaroundabout Feb 15 '17 at 21:59
  • @leftaroundabout First of all, inflating your fast changing FW repo with the bulk of a complex CAD design isn't always what you want, but you might also want to re-read the bits about sub-repos and linkage between them. Not at all hard to do with Git and that fixes exactly that problem without causing all kinds of inappropriate intimacy between design tracts. – Asmyldof Feb 15 '17 at 22:31
  • 1
    "my customers don't all feel Dropbox is safe enough" For versioning files, they are 100% right. It's especially dangerous if multiple users can modify files at the same time, and even more so if you have several files that really comprise a single resource. I have seen binary "sets of files" get corrupted this way (ESRI file geodatabases, if you're curious). – jpmc26 Feb 15 '17 at 22:53
  • 1
    @jpmc26 That was a rushed comment, the versioning everything started initially more as a safety aspect. With a few clever GitIgnore templates versioning now easily envelops everything without hassle, with all the advantages it brings. I actually fully agree with you on shared Dropbox. At one customer site it causes endless issues. Files under development spawning endless conflicted copies on computers turned off during parts of dev being one of the most annoying ones. – Asmyldof Feb 15 '17 at 23:58
  • @leftaroundabout: It depends on the relationship between the hardware and firmware. Let's take an analogy with normal software projects. Would you commit gif and jpg files along with your website? In this case both the binary and source change with each other even if the pictures don't change as often. But.. would you commit Apache or Nginx source code with your project. For that matter, would you commit the source code of the Linux kernel? In this case Apache or Nginx and the Linux kernel is more analogous to hardware - they change but independently from the code you write that run on them – slebetman Feb 16 '17 at 03:39
  • +1 I really love the BoardPinout.h file belonging to the hardware repo. Great idea! – jwsc Feb 16 '17 at 08:00
  • I love SVN inside Altium. Not sure what you don't like about it. You can use external binaries like TortoiseSVN. Works great. Even some sort of "diff viewer" for binary files, which I've never used but looks nice in theory. – Joel Wigton Feb 16 '17 at 22:37
  • @JoelWigton For one SVN is a clunky and old system that creates a lot of bulk, which is inconvenient when you don't just use it locally. Adding to that the internal SVN adds a lot of clicks to documented commits, rather than random ones, not to mention the overhead in versioning external files like calculations in the same revision repo. If that's not bad enough I don't trust a company like Altium to keep the system consistent over 5 versions. My own system will stay compatible for the next few decades if I can help it at all. – Asmyldof Feb 17 '17 at 08:28
5

1) Its definitely worth versioning schematic/board files. Even if you can't track differences so easily, you have a clean way to revert to a specific hardware release if you have to work with an old device revision.

2) We have the following structure in our SVN.
/tag
/branch
/trunk/hardware
/trunk/software/firmware

If applicable with more sub-folders like maybe /Firmware and /ConfigTool for software and /mainboard and /daughterboard or something like that for hardware.

2) Tags are created from sub-folders not from the whole trunk, like Tag/Mainboard-v1.2.345. The hardware (namely the PCB) always contains the SVN revision in the silk screen print or in copper to have a direct reference.

4) Dependencies between hardware and firmware can be complex. IMO it doesn't make that much sense to deal with it on the repository level except leaving useful comments on commits.
Consider encoding hardware changes using spare I/O pins. Something like using 4 pins to encode 16 different hardware versions. We also used a single ADC input with different resistance values to encode versions. This way the software can "know" on what hardware it runs and change/disable/enable specific features.

Neil_UK
  • 158,152
  • 3
  • 173
  • 387
Rev
  • 10,017
  • 7
  • 40
  • 77
  • I agree. I've also seen a good practice of building a "release bundle" - schematics, BOM, gerbers, the whole lot - on the occasion of every release to production. You call these A, B, C etc and then archive them somewhere where the team can refer to them. Also, don't forget some means of tracking what wire mods you've done on which prototype boards. – pjc50 Feb 15 '17 at 15:19
  • @pjc50: Actually we do "build" release bundles as well, but out of source control (but with a revision reference). Essentially it will be an exact copy of everything that the manufacturer got. If you do hardware development professionally with high volume production it is very important to have all the information readily available in case something goes wrong. If you don't remember if you send the board house "this one important document" that maybe specifies custom PCB copper thickness you can be in trouble. – Rev Feb 15 '17 at 15:26