What is the difference between REF** and ${REFERENCE}?

REF** is historical.

Each footprint must have one primary reference designator. It’s the Reference field of the footprint, and by convention it has text REF** by default. When you create a new footprint it will be in the silkscreen layer and can’t be deleted (deleting it is impossible, even pressing Del only sets it invisible), but you can set it invisible or change its layer. According to the KiCad Library Conventions for the official footprints it should be in the Silk.F layer.

You can of course add several reference designator texts. The KLC says there should be one copy of the reference designator in the Fab layer. In older versions of KiCad this was achieved with text “%R”. But later, for version 6.0, the idea of more generic text variables was added. Symbol fields can be used in the footprints. It didn’t make much sense to stick with the old style %R (or the corresponding %V for the Value). It was changed to ${REFERENCE}.

Actually it looks like REF** is just an arbitrary string which could be anything. You can’t do anything special with it. You can’t use it as a variable. It’s just a placeholder for actual reference designator and shows with one glance that this footprint doesn’t have a reference designator yet. What is important is the field. The Reference field is the link between the symbol and the footprint: it’s updated when you update the PCB from the schematic, or vice versa: the symbol reference is updated according to this field if you update the schematic from the PCB. You can change the text of the field to anything and it still works, or set it invisible, but you can’t delete the field or change the field’s name.

Unless someone finds a case where REF** actually does anything special, I would say that it’s just a string. Only ${REFERENCE} has a special meaning: it carries the reference designator text. It automatically follows the content of the Reference field.

We must understand the difference between conventions or defaults on one hand and how KiCad works on the other. The Reference field, which is always there and can’t be deleted, is how KiCad works. The text REF** there is only a convention and the default text, but otherwise it doesn’t have any special meaning and as far as I can see is not relied on anywhere in KiCad.

The variable name REFERENCE is part of how KiCad works, but its existence in the footprint F.Fab layer text item in the official footprints or in newly created footprints is only a convention and it is added by default. These non-mandatory text items and/or property fields can be deleted and added at will.


So, I bet you didn’t know what REF** and ${REFERENCE} and those fields actually do, but I’m not sure if others understood this, either.

No, because the Reference field is special. When the text replacement variables were developed (by Jeff) I pondered on this and justified why the reference designators (I thought about the schematic, but it goes for the PCB, too) shouldn’t do text substitution at all. KiCad uses references in certain ways and it would be far too brittle to allow for the user “creative” ways to use that field.

You can test this by replacing a Reference field text in a PCB with ${REFERENCE}. It is seen there verbatim. The fab layer copy also reads ${REFERENCE}, verbatim, but not because that fab layer field says ${REFERENCE} verbatim. Actually that ${REFERENCE} is substituted with the reference designator, which now happens to be ${REFERENCE}, verbatim.

Further reading for KiCad history enthusiasts (about text replacement variables in general, about replacement in the Reference field and about the old %R): New string replacement options for kicad assets.

I have no proof for this, but I think that the primary reference designator text is in the Silk layer only because that’s the most natural place for the refdes if there’s only one. As I said, the Reference property field is mandatory, and properties are embodied as text items which must have a layer. Silk is the default layer for the Reference in KiCad, but can be changed. Notice that the secondary reference in the Fab layer is just a normal text item, not a property field. It’s totally optional but by default is added to the Fab layer because that layer in KiCad contains other similar information about the footprints/components.

Anyone who creates their own libraries can change the layer of the primary reference text and can leave out the secondary, or put it in a different layer. Even the REF** text can be changed to something else in the library, it’s just the default text when the footprint is put to the PCB without a link to the schematic.

5 Likes