CAD –  Examples

Using CAD with Eagle, BOM, Digikey and Mouser

This example will show you how to use CAD with circuit schematics made with Eagle, the CAD Bill-of-Materials (BOM) IO module, and the CAD Digikey and Mouser Fetch modules. Specifically, it covers:

• Generating a BOM from Eagle for the first time.
• Automatically filling description, manufacturer as well as pricing information from Digikey and Mouser, with a configurable preference.
• Generating order sheets with a user-defined quantity multiplier that can be uploaded directly to Digikey and Mouser.
• Filtering Eagle footprint names.
• Resolving the conflicts generated when the Eagle schematic and the BOM disagree.

Step 1: Download the example files

Make a directory for this example. lt3434 is a good name for it.

$ mkdir lt3434

Download the following files to that directory:

• lt3434.sch - Eagle Schematic for the LT3434 power converter.
• cad.xml - a slightly modified version of the stock digimouser-descs.xml definition file; changed to have prettier BOM header, notes section and Newark references.
• lt3434.xml - Bare-bones root file.

$ cd lt3434
$ wget http://cad.devl.org/examples/eaglebom/lt3434.sch
$ wget http://cad.devl.org/examples/eaglebom/cad.xml
$ wget http://cad.devl.org/examples/eaglebom/lt3434.xml

Step 2: Create a basic .cadrc

Create a file named .cadrc with the following inside:

scan cad.xml
scan lt3434.xml

CAD executes any commands in .cadrc on startup. The first command, scan cad.xml, loads CAD with your definitions. The second command, scan lt3434.xml, loads the root file lt3434.xml into the CAD repository.

Step 3: Run CAD

$ cad

After expanding the "lt3434" element your screen should look something like this:

This is the result of scanning our initial bare-bones project file. In that file, we specified that we have a pcb named "lt3434". CAD used the definitions in cad.xml to determine that all pcb's have four documents associated with them: a bom, schematic, digikey-ordersheet, and mouser-ordersheet. Each of these documents has a filename field that we have to set in order for CAD to make use of them. Use the fill command to have CAD fill in your root files with the required tags:

> fill

which will cause lt3434.xml to look like the following:

<part class="pcb" name="lt3434">
  <doc class="digikey-ordersheet" name="digikey-ordersheet">
    <data class="number" name="order-qty"></data>
    <data class="string" name="filename"></data>
  </doc>
  <doc class="mouser-ordersheet" name="mouser-ordersheet">
    <data class="number" name="order-qty"></data>
    <data class="string" name="filename"></data>
  </doc>
  <doc class="eagle-sch" name="schematic">
    <data class="string" name="filename"></data>
  </doc>
  <doc class="bom" name="bom">
    <data class="string" name="filename"></data>
  </doc>
</part>

edit lt3434.xml to add filenames for the documents:

• schematic: lt3434.sch
• bom: bom.csv
• digikey-ordersheet: digikey.csv
• mouser-ordersheet: mouser.csv

<part class="pcb" name="lt3434">
  <doc class="digikey-ordersheet" name="digikey-ordersheet">
    <data class="number" name="order-qty"></data>
    <data class="string" name="filename">digikey.csv</data>
  </doc>
  <doc class="mouser-ordersheet" name="mouser-ordersheet">
    <data class="number" name="order-qty"></data>
    <data class="string" name="filename">mouser.csv</data>
  </doc>
  <doc class="eagle-sch" name="schematic">
    <data class="string" name="filename">lt3434.sch</data>
  </doc>
  <doc class="bom" name="bom">
    <data class="string" name="filename">bom.csv</data>
  </doc>
</part>

When you save this change to the root file, CAD will have enough information to do "stuff". The first thing that will happen is that these four files will now be "watched" by CAD. As the bom and ordersheets don't exist yet, the only thing that will happen is CAD will spawn Eagle to extract information from your schematic and insert it into the repository. After this occurs, your screen with update and look like the following:

Notice the green numbers next to the bom and the schematic. These are the number of missing elements. Since the structure of what you are making has been defined by cad.xml, CAD understands, for instance, that electrical components have a "value" that is specified in both the schematic and the BOM. If you highlight the schematic, the details section will show that R2 and R3 have an empty value. The BOM is missing 180 elements (because the BOM doesn't exist).

Step 4: Generate an initial BOM from an Eagle schematic

To use CAD to generate an initial BOM from your Eagle Schematic, we will use the push command. Push updates the target file with all of the data in the repository. Since in this case, the only data in the repository is from the schematic, we are essentially generating the BOM directly from the schematic. This, however, isn't the best way to look at what is going on though, as we'll see later.

For now, run the following push, and think to your self, "CAD has pulled information out of the schematic, stuffed it into a data structure defined by cad.xml, and now I'm generating a BOM from that repository" --- even though it's a lie.

> push bom.csv

Not much in CAD will change. You'll notice that the number of missing elements in the BOM has been reduced to 142 (implying that something has been added to bom.csv). And if you look at any of the data elements for the components you might see that they are now pulled from both the schematic and the bom, when before the push they were only pulled from the schematic. However, there is now a file named bom.csv which has everything the repository has so far:

Step 5: Automatically fetch data from Digikey and Mouser

cad.xml has a Digikey and a Mouser fetches defined to automatically retrieve part information from these websites. To see this in action, edit bom.csv to include the following Digikey and Mouser references:

When you save these changes, CAD will notice that bom.csv has changed and pull the Digikey and Mouser partnumbers into the repository. Since this data has fetches associated with them, CAD will also perform those fetches and insert the resulting data into the repository. Note that most of this behavior is defined in cad.xml and is not a function of CAD. If you'd like CAD to behave differently, or if what it is doing now doesn't quite suit your needs, chances are you can create a definition file that will. If you can't then please email cad@devl.org and we'll do our best to help.

After CAD performs the fetches, take a look at one of the components we added the new part numbers to, such as L1:

And then push the data out to the bom:

> push bom.csv

Which will result in bom.csv to look like the following:

Step 6: Conflicts

Let's say that you've ordered an initial set of parts to test this circuit out. And then you spend three days debugging a problem --- it turns out that the values for C2 and C3 should be swapped. It's the end of the day, on Friday, and you want to go home to play video games all weekend, and the last thing you want to do is run eagle. So you edit the BOM instead, because that's quick and easy.

Now, with most programs this is a one-way street. Typically the schematic (and layout) are considered the authority from which the BOM should be generated; at least this is the approach that Eagle (and many others) take. If you were to edit the schematic (in a way that doesn't involve C2, C3) and regenerate the BOM you would lose the changes you made at the end of that long day from the last paragraph. Furthermore, if you make a new revision to the board, and say one-third of the schematic changes, you need to regenerate the BOM and merge by hand the relevant information from the old BOM --- leading to consistency errors, a headache, and general misery. Clearly, in the age of computers, this is nonsense.

CAD approaches the problem differently. First you define the structure of what you are making (e.g. cad.xml), including what documents have the information about what you are making. In this example, we are making a printed-circuit board and PCB's have an eagle schematic and a BOM. Then, since we've defined what information is in which documents where, CAD grabs all of that data and lets you know where there are problems. Instead of treating one document arbitrarily as the authority, CAD makes your definitions the authority.

Continuing with our example, edit the BOM reflect the changes we'd like to make. Set C2 = 4700p, C3 = 470p. After editing you can "push bom.csv" to recompute all of the quantities. CAD now displays that there are conflicts. If drill down the tree to select the elements that are conflicting you'll see that they are due to the discrepancy we created by changing the values in the BOM. Now it's up to you to resolve this conflict as you wish.

Appendix: Fancy stuff

The definitions used in the example have a few more tricks. They can: generate ordersheets for both mouser and digikey (to use directly in their upload order interfaces); preferentially push either digikey or mouser data to the BOM; and can override the footprints set in Eagle.

A: Order sheets

Both Mouser and Digikey allow you to upload .csv files to quickly add parts to an order. The definition file in this example can generate those files for you.

You must specify the order quantity for each sheet in your root file, lt3434.xml. We will set both of these to 10, meaning we'd like to order enough parts for 10 pcbs.

Both of these files are defined to be "push-only" which means they are always regenerated completely on a push and their data is never pulled into the repository. To generate the files:

> push digikey.csv
> push mouser.csv

which will produce the following files:

cad.xml has a hard-coded preference for ordering from Mouser. That is, parts that have both a Digikey Reference and a Mouser Reference (e.g. C8) will only appear on the mouser ordersheet. It also computes a minimum quantity for each part based on the pricebreak information pulled from the website and will adjust the quantity in the order sheet to always be at least that amount.

B: Vendor precedence

The default behavior, for this definition file, is to first use the data in the BOM, then the data fetched from Mouser, then the data fetched from Digikey. (You may have noticed that the data filled in from the website fetches for C8 came from Mouser). You can change this fetch preference by creating a file named mfgpn-map.csv. This is a flat csv file which contains a manufacture partnumber as a key followed by the preferred data source to use. For example, to use the data fetched from Digikey for C8 you could create a mfgpn-map.csv like the following:

You'll notice that this will set the fetch-pref for C8 to be digikey and the description and manufacturer, will first come from Digikey then Mouser unless you have values for these in the BOM. It that case, the BOM has precedence. This does not apply to the manufacture part number which must agree among all sources or else a conflict will be generated.

C: Footprint filters

It is often the case that the names of the footprints in eagle are not what you want in the BOM. There are a few examples of this in this project. Specifically the footprint for D2 is "0603-D" while for the other 0603 packages the name is "SMD0603". In Eagle they have to be different if we want to indicate orientation of the diodes in the silkscreen. A similar problem exists for capacitors --- or any device that has the same form-factor in polarized and unpolarized versions. Some names are just not what we may want, like "TSSOP-16-X". cad.xml filters all the footprints through filter.csv. To replace 0603-D with SMD0603, we'd make a filter.csv such as:

then to get the filtered values into the BOM we'd want delete all of footprints and push the BOM again.