The Problem

In KiCAD, a problem occurs when you try to create a new schematic symbol for a custom library and you happen to give it the same name as another part that exists in a different library.

For example, let’s say you decide to create a part called “MAX3232”, and there happens to be another part in a different library already called “MAX3232”.  This can happen for a number of reasons; you may not have noticed that this part already existed in the standard library set, or you may have seen it but decided that you’d rather make your own.  This happens to me quite often – for example, I have a bit of a personal standard for the way I like ICs to look on my schematic.  I like my ICs to have a thicker border than on normal components, and I like them to be filled in yellow.  Additionally, I often have preferences about the pin layouts.  It is unlikely that an existing part in a different library will satisfy all of my personal preferences, so usually I’ll cook my own.

When you first set up the custom part, KiCAD will create your part for you and add it to your custom library using the name you chose at the beginning.  If this name is the same as an existing part in another library, KiCAD doesn’t complain – it adds it to your custom library as requested and initially there is no obvious conflict.
The trouble starts when you come to add the component to your schematic.  You select the “Place a component” button, choose your custom library, and select the part you just created.  KiCAD highlights the part and shows a preview of it, which matches the custom symbol that you intend to place.  So all looks well.  However, when you actually try to place the part you’ve selected something unexpected can occur.  It places the part without complaint, but sometimes it will place the existing part from the standard library instead of the custom part you intended!

Clearly there is a conflict here that KiCAD hasn’t warned us about.  When you actually try to place the part, you’d think that KiCAD would dive straight into the appropriate library and pick out the part you actually selected.  But this is not what happens.  Instead, KiCAD searches through its entire set of libraries and picks the first part whose name matches the one you selected.  If your custom library is scanned first, it picks the part you intended.  If the other library is scanned first, it picks the existing part that you didn’t want!

Workarounds

I haven’t managed to find a completely satisfactory solution to this problem.  But it is possible to get close to a satisfactory solution using one of two optional workarounds that I will describe here.

#1 The nomenclature workaround

The first workaround, and the easiest (though neither are difficult), is to simply be careful when you’re choosing names for your custom parts.  For example, I could decide to append all of my custom parts with “_BJH” for the rest of eternity.  Then, when I want to create a custom MAX3232, I would create it with the name “MAX3232_BJH” instead.  It’s unlikely that another part in some different library is going to match this name, so I can feel pretty confident that no conflict will ever occur and the custom part I intend to use will be placed on my schematic every time.
An alternative that I’ve seen suggested on other websites is to append your library name to each of your parts.  So if your custom library was called “Devices_BJH”, then you’d call your part “MAX3232_DevicesBJH”.

A problem with the nomenclature workaround

This works fine, but when you place your part it ends up being titled “MAX3232_BJH”.  There are two problems with this.  One is that it’s just plain messy; who in their right mind would want all their component names appended with workaround text? The second problem is that somebody else, reading your schematic, may be fooled into thinking that the appended text has some other importance – for example, they might think the “BJH” is a specific variant of the part which they need to pay attention to.  So clearly we will want to do something about this.

Fortunately it’s quite easy to solve this problem, with one exception which I will talk about in a minute.  If the part you’ve created is a regular schematic part (resistor, IC, diode, custom component, etc) then you can select the component on your schematic, select “edit”, (or hover over the component and press e on your keyboard) and then you will be presented with the following dialogue box:

 

As you can see, all you have to do in order to change the way the title looks for your custom component is change the Value.  This allows you to call your part “MAX3232” while KiCAD still refers to it by the conflict-free name that you chose earlier.  The annoying thing with this workaround is that you have to repeat this process for each part you add to your schematic, and you leave yourself open to the possibility of accidentally naming multiples of the same part differently.  For example you might end up with two MAX3232 parts on your circuit, one with a Value of “MAX3232” and the other with a value of “max3232”.  A trivial issue, yes, but one that would annoy the heck out of me!

 An exception

There is at least one exception to this workaround which I have discovered.  The other day I decided that I wanted to create my own power symbols.  KiCAD already has a suite of power symbols to choose from, but I find that the supply rail symbols (the ones which are a pin with a circle on top like that shown to the left) are too small for my liking.  Power supply rails are quite important connections, and I think they should be displayed more prominently.  I also have issues with the legacy “VCC, VDD, VSS” power rail nomenclature, which is a rant for another day.

Having created my new power rails, and taken care to append them all with “_BJH”, I thought I would be able to use the edit dialogue box in the same way as for my other components to change the Value field so it was displayed, for example, as “+3V” instead of “+3V_BJH”.  Unfortunately, if you try this for yourself, you will discover that the Value field is greyed out for power pins.  You can’t change it! To solve this problem we must move on to workaround #2, which is now my preferred method which I am going to use for all my custom symbols from now on (or until the KiCAD team fix the naming conflict problem).

#2 The Custom Field Workaround

Since we can’t change the Value field on power pins, we need some other way of changing how KiCAD displays the name of our custom parts.  Thankfully, we can do it quite easily using custom fields.  You have two options here.  The first option is to apply a custom field manually to each custom part after placing it on your schematic.  The second option is to generate the custom field when you’re actually creating or editing the custom symbol in the library editor.  The second option makes the most sense by far, because this way you can set up exactly how you want your symbol’s title to be displayed, position it just-so, and then it will be automatically repeated in exactly the same way for every single part you lay down with no need to go about maintaining it retrospectively.  The second option also shields you from the horror of accidentally naming your parts in slightly different ways (capitals here, dashes there, etc).  For these reasons I am only going to talk about the second option, but the principle is exactly the same anyway so you can pick your poison for yourself.

Generating custom fields in the library editor

Assuming you know how to edit components in the library editor (if you don’t then I guess your problem starts at how to create symbols, not how to tweak their names), launch the library editor and open up your custom component.
Along the top toolbar you will find a T-shaped button  for editing custom fields.  Select this button and then you will be presented with the fields dialogue box shown below.

Now, at the moment KiCAD is using the Value field – which on power pins you can’t edit – to display a title for your component on the schematic.  So the first thing you want to do is select this field and change its visibility setting so that the “show” checkbox is no longer checked.  This will stop it displaying on your schematics.

The next thing you want to do is create your custom field.  Select the “Add Field” button, and then set the Field Value to something sensible that denotes your component in some pedantic way of your choosing.  Set the text size, its style, and set the position.  Once you’re happy, make certain that you set its visibility checkbox to “show” so that it’ll display on your schematic.  Then you can exit the dialogue box.

Done!

That’s it! You’re done.  Save your component back to the library, and update it.  You’ll probably also need to close the schematic editor and open it back up again.  From now on, you can place your custom component without any nasty surprises and it will display with a sensible name of your choosing.

Have a FAB old time with your PCBs! <groan>