UUID References

In every EDA tool, libraries and projects are full of cross-references between different objects. For example, when attaching a wire to a pin in the schematic, the wire has to store a reference to that particular pin to successfully restore that connection when you open the schematic the next time.

Many EDA tools use the object’s name as reference. For example when you connect a wire of the GND net to the pin named IN+ of the component with the designator U3, the schematic editor stores a reference like U3:IN+ for the attached wire in the schematic file. When opening the schematic the next time, the editor searches for a component with the designator U3 in the project library, and then for a pin named IN+ within this component to restore the wire connection.

This system works, but it comes with a big disadvantage. Whenever you rename any referenced object (e.g. renaming pin IN+ to +), all the references to this object will break, causing broken library elements or projects. So in fact it is not allowed to ever rename or move things, or you will run into troubles. A typical symptom is that the editor throws errors like "Component XYZ not found", for example after updating libraries and then opening an older project.

LibrePCB follows a different approach. Instead of referencing objects by their name, it assigns a random identifier to every newly created object, and uses this for all the references. In particular, it uses universally unique identifiers (UUIDs) which consist of 36 characters and look like 3da6ef2c-03ff-4ed1-a8b8-c8acf2ed0291.

For example, when you add a pin to a symbol, the editor automatically generates and assigns a random UUID to the pin. You may give the pin a human-readable name like IN+, but the editor gives it a UUID like cc3af4a4-cc26-4548-a026-468e1d689ab3. This UUID is typically not user-facing, so usually you won’t ever see it. But behind the scenes, LibrePCB uses this UUID for any references. So a wire in the schematic which is attached to a pin won’t reference the pin like U3:IN+ in other tools, but like 7b8fef14-64f9-4502-8094-7e2c1c0b6e9a:cc3af4a4-cc26-4548-a026-468e1d689ab3 where the first UUID refers to the component (U3) and the second UUID refers to a pin of it (IN+).

Now whenever you rename objects like a symbol pin, it will only affect the human-readable name, but not its UUID. The UUID of an existing object will never change, so all the references to it will stay intact.

This system comes with the advantage of keeping references intact even when renaming objects, thus avoiding broken library elements or projects after renaming or moving things. However, it also comes with some drawbacks you should be aware of.

As you may understand by now, the data structures of libraries and projects are full of references. A project consists of hundreds or thousands of wires, traces, nets, pins and pads which are all linked together by referencing each other. This is true for every EDA tool, no matter if references are made by names, UUIDs or anything else. References are everywhere.

Given this fact, it is also clear that there is always the risk of broken references. Imagine you add a symbol to a schematic and connect wires to its pins. Now you realize the symbol is not exactly correct as it has a pin which the real part doesn’t have. So you open the symbol in the library editor, delete that pin, and save the symbol. Then you update the project’s library (with the Project Library Manager in LibrePCB) to update the symbol in your schematic with the new one. But you have already attached a wire to the pin which no longer exists. This means that the wire holds a reference to a pin that doesn’t exist (anymore), a case which we call broken reference.

Some tools may silently ignore such broken references and try to revert to a valid state. In this particular case, they might silently disconnect the wire from the pin, leaving behind a "dead end" wire.

Other tools, like LibrePCB, are more strict about broken references. Instead of silently ignoring such (potentially unintended, dangerous) invalid situations, the tool throws an error to inform you about the problem. This may lead to a situation where you cannot open the project anymore until the problem is fixed (e.g. the deletion of the pin is reverted).

To avoid headaches and wasted time, such situation should be avoided to happen at all. In other words, it is highly recommended to never make so-called breaking changes to existing library elements. If you have a situation like the described superfluous symbol pin, it is better to create a new library element (using the Duplicate operation) and make the breaking changes there. Then just replace the wrong symbol in the schematics with the new one. Using this workflow, there will never be any broken references, causing no errors or other troubles.

LibrePCB tries to prevent you from (accidentally) making breaking changes. Generally you don’t need to worry about breaking changes in library elements — whenever you made a breaking change to an existing library element, LibrePCB will warn you with this banner:

As soon as this red banner shows up, the editor is put into read-only mode and saving is not possible anymore. Now you have three options:

Here are some simple recommendations which help to avoid running into troubles due to broken references: