Disclaimers
Remapping a project will mean that it can no longer be opened with version 4!
No matter what you do always make a backup first. (One should always do that before doing major changes. It also makes it easy to restart should the result be different from what one expects.)
5.1.2 has a bug where it sometimes shows question marks for symbols even with them being ok. Restarting eeschema will fix it if the bug is to blame for having question marks. Remember to save before restarting (You had a bacup anyways did you?)
Remap a project
Why do i need to do this?
KiCad now includes information which library a symbol comes from. This information is added to the schemaitc by the so called remap dialog that appears when opening a version 4 project. (More details in appendix)
Tutorial files
To get a common starting point here the example project used to create this tutorial. It is designed in version 4.0.6 using the symbol libraries of that version. v4_to_v5_demo.zip (18.7 KB)
The default option (Easy to use, no additional knowledge required)
TlDr: Assuming you had a valid project (one with an intact cache lib) you can simply click through all dialogs with their default option. Worst thing that can happen is that your project gets rescued and you end up with a new local library. (See rescue section below.)
The process
Make a manual backup of the project before starting. (Always do that before doing something major.)
Open the project and start the schematic editor (eeschema) from KiCads main window. You will be presented with the remap dialog. Press the remap button to continue. (If you get a message about missing libs instead then read the rescue section below.)
If there are no warnings or errors in the output window then you are done. Click close (yes i know counter intuitive but this simply means closing the report dialog that happens to be included in the same dialog as the tool).
EEschema will open. Save the project and inspect it to ensure everything is ok .
For exampel run ERC to make sure nothing bad happened. (This assumes you had an error free ERC before remapping. This process does not magically fix them for you.)
Project “rescue”
More details regarding this topic: What are the cache and rescue libs and how does the schematic rescue dialog work? (KiCad version 5.x and earlier)
If there are errors or warnings then you will be presented with the rescue dialog that relies on having a valid cache library. (The file called project_name-cache.lib that should be in your project directory.)
In this case you will have gotten an error message regarding missing symbol library files as soon as you opened eeschema. (This will happen if you used official libraries from version 4 to create the project like is done in the example project.)
After that you will be presented with the remap dialog. When clicking remap the rescue dialog will appear. In it accept the rescue of all symbols. (This is the default.)
The auto generated library table
The local library table will be left quite empty in this case. KiCad will however wrongly identify two libraries. It assumes that the power lib and 74xx lib of the new library setup are the ones setup in the old project. It adds them to the local lib table for this reason.
In addition the rescue lib is added to the lib table.
Setup KiCad to use the original libraries that where used to create the project. (Advanced)
This is the safest option for converting a project. (It does not rely on the cache lib.) But it is also the one that requires the most work.
Downloading the correct library version
This part is tailored for the example project. The required library version might be different for your project. (Using a slightly wrong library release would not be the end of the world. It might however mean that some symbols need rescuing.)
We downlaod the same version of the library that was used to create the project. For the example given above this means you need to download the library version 4.0.6 from github.
You can place the lib anywhere on your filesystem. We will tell kicad in the next step where the libs are found.
Alternatively you could also clone the repo of the version 4 symbol library. Checkout the version you require (in this case 4.0.6) for the project you work on right now. (This option allows easy switching between different versions but requires knowledge about git.)
git clone https://github.com/KiCad/kicad-library.git
cd kicad-library
git checkout 4.0.6
Preparing the old project files
We need to point the original project files to the current location of the library. (Adding the libraries to the KiCad 5 setup does not help us.)
Open the .pro file in your favorite text editor as this is the only real option for doing this (besides using KiCad version 4).
The path must be added to the LibDir variable inside the pro file. If you had a custom search path configured then this variable is already present. If not then we need to create it.
- If the LibDir option already exists then add your path at the end. Separated from existing paths via a semicolon “;”
- If the LibDir option does not yet exist then add it as a new line before [eeschema/libraries]
In my example i added “/media/sf_kicad/07-version4/kicad-library/library” at the end of the example project files setting. You will need to add the path to your copy of the libraries. (Use the absolute path to the library directory you downloaded using the description given in the previous section.)
The remap process (with the project prepared for reusing old libs)
Now we can finally open the project with KiCad 5. Open the schematic editor (eeschema) from KiCads main window. You will be presented with the remap dialog. Press the remap button to continue.
After remapping you get a lot of messages in the output messages field. There should not be any errors or warnings. If you have any then something went wrong during the preparation phase. (Try again from the original files.)
Clicking close will finally get you to eeschema.
Save the schematic to really finish the process.
Testing the result
Run ERC to make sure nothing bad happened. (This assumes you had an error free ERC before remapping. This process does not magically fix them for you.)
You might additionally try to run “update pcb from schematic” from within pcb_new. This should not report any changes! (Assumes your pcb was up to date with eeschema before the remap step.)
The local library table is automatically generated
For the purpose of this tutorial we investigate the library table that was automatically created.
Note that there now is a power1 lib. This is because we already have a power lib in the global library table. The same happens with the 74xx lib.
Checking library references
Take a look at the library references (tools -> edit symbol library references). Again note that all symbols point to libraries that have just been automatically added to the local library table. (easiest to see for the power1 and 74xx1 libs.)
We could use this tool to change which symbols are used in the schematic. (Example: transfer the project to use symbols from the v5 library) More on that in the next section.
Transfer the project over to use version 5 libs (very advanced)
This will result in a project that will look to anyone in the futurer as if it was always created with v5. If your will need to maintain your project for quite some time then this might be the workflow to use.
Follow the original simple option and let kicad rescue all your symbols.
The power symbols will point to a library with the wrong nickname. (KiCad created a power1 lib in the local library table) Lets point them to the power lib you should have in your global library table. (Assuming you setup kicad to use the official library)
For editing the reference simply double click on the row you want to change (or select it and press the browse libraries button)
A symbol browser will open in which you can select the new symbol by double clicking on it.
After pointing all power symbols to new libs you should be left with something similar to what is shown in the screenshot. Accept the changes by pressing ok. After this is done you can delete the power1 lib entry from the local library table.
Appendix
What changed between version 4 and 5 to make this necessary?
KiCad version 4 did not store the library a symbol has been taken from inside the schematic. This meant that the same symbol name could not be used in different libraries.
Users either needed to ensure that all symbol names are unique over all libs or they needed to take care of symbol library priorities as kicad took the symbol from the lib with higher priority if there was a conflict.
This restriction is now lifted in version 5. KiCad now includes the information about the source library by including the library nickname in the symbol reference.
The official library has been reorganized for the v5 release. This means we can not simply use the version 5 lib for the old project and expect everything to work automatically. (More on that below)
What does remap do and how does it work?
The remap process adds this missing information to your schematic. For this it checks if it can find the symbols in any lib that was originally setup in version 4. (The libs really need to be at the same file system location)
If it can not find a symbol or if a symbol changed then it starts the rescue process. That process relies on a valid cache lib to work.
The libraries that are found by this process will be automatically added to the project local sym-lib-table. They are assigned a unique nickname. (If you have a lib in your global library table with the same name as one that was used in your old project then that libs nickname will get a number added at the end to make it unique.)
What can go wrong
If you do not prepare the project and have no valid cache lib then your project will break. In that case you will first get the message about missing symbol libraries.
You are presented with warnings (or errors) in the output messages window of the remap process. You are only presented with the rescue dialog if at least some of the symbols are still present in the cache library.
I forced this error by deleting the cache lib file from the example project. (To better show the errors i also disabled all other outputs of the remap dialog)
When i then check the schematic i am presented with this wonderful sight.
If this happens then the best course of action is to go back to the backup.
If this is not an option then you can manually add the libraries to the project and use the symbol library references editor (found in the tool menu) to point the project to the correct symbols. This can be a lot of work and is also error prone. (So not really the best option.)