Project and libary setup for sharing and collaboration (KiCad version 5)

Rene_Poschl · January 23, 2020, 10:15pm

Introduction

This information is written with KiCad version 5 in mind.

There are at least two schools of thought how to best set up your project and libraries for sharing or collaboration regarding library management. One can either have mainly global libraries or exclusively local libraries. These are of course the extreme ends of the spectrum. Understanding both of them should allow you to find the best mix that best fits your needs.

For a detailed lecture about library management read Library management in KiCad version 5

General Rules for KiCad Projects

No matter which workflow you follow be aware that you need to share all project files listed below

All used .sch (schematic) files
The .pro (project definition) file
The .kicad_pcb (board layout) file
Both the sym-lib-table and fp-lib-table (project local library tables) if they exist
The -cache.lib (Symbol cache) library
The -rescue.lib and any other project local library

Index

Centralized (global) library setup

Why would you use a global setup?

The benefit of global libraries is that this type of setup scales very well with the number of managed projects and library assets. It is especially well suited for collaboration within a relatively stable team (example within a company). This includes sharing projects between different computers owned by you.

In this case the one time effort required by every user to set up the central (global) library pays of during the prolonged time of working together.

How to get Libraries to Everyone in the Team

This first time setup consists of ensuring that the libraries are available to the current computers file system (details depend on file sharing option) After that the library tables need to be set up and if used also path variables set. See Library management in KiCad version 5 for details.

The libraries themselves can live on a normal file server which is mounted in the usual way. Another option is to use cloud services for exchanging the libs. But possibly the best option is to have the libraries in some sort of version control (example git or svn). Be aware that merging library changes requires at least some basic understanding of the file format. So svn with locks is a good option or using a pull request based system for git (gitlab, bitbucket or similar).

Manage what can get into the Central Library

It is beneficial if there are clear rules about library organization and asset design. Maybe even a review process that reduces the chances of an error for library assets before they are used in a project.

Continuous integration tools can help with the review process. Especially to check some common rules are followed (like a specific set of symbol fields that need to be filled for consistent BOM creation.)
As an inspiration take a look at the tools used by the official library team: https://gitlab.com/kicad/libraries/kicad-library-utils (symbol check scripts are in the schlib subdirectory and footprint check assets in the pcb subfolder)

Guide to the First Time Setup

This guide is meant to be a template for your own personal guide that you share with your team (it is a shortened version of the above)

Get the central lib onto your computer (git clone, svn checkout, mount network drive)
Setup path variables (in KiCad) pointing to this storage location as required (at least for 3d models)
Use the library managers (footprint and symbol) to add these libraries to your setup (to the global library table)

Simplify First Time Setup by Providing Library Tables

One can include the library tables for the shared libraries in some way to ease first time setup. It is suggested to use path variables for best results (otherwise all team members must place the libraries at the exact same file system path).

Sadly KiCad has no way to import a library table into an existing one. So one option is to include a full library table containing all libraries that are allowed to be used (So possibly including the official libraries in addition to your libraries).
This allows users to copy these tables directly in their KiCad config directory or if they never opened KiCad before use the first time setup dialog to point to this library table.

Another option is the use a text editor to copy the team entries into their tables. A saver option would be to develop a simple script that handles this task. Make sure no entries are duplicated by this step.

Centralized Library Tables

There is the option to directly link the user library tables to a central location. This will give the library team even more control over what assets can be used in projects.

A way to achieve this is to have a script that copies the library tables at a regular interval (example at login via the operating systems startup applications or as part of a custom KiCad startup script)

Another option is to point KiCads config directory into a config directory within the library location by setting the environment variable KICAD_CONFIG_HOME as described in for example Running several KiCad versions on the same Windows machine. This really only works when using version control systems that allow excluding config files other than the lib tables.

Rene_Poschl · March 28, 2020, 12:43pm

Project local setup (atomic project)

Why would you want to go this route?

Using only project local assets all living within the project directory ensures that people you share this project with do not need to set up anything to use your project. This is a good option if you just want to put your project out there for anyone to use (example as an open hardware project shared publicly)

And why you might still want to use the central option?

The downside is that such a setup splits up your library over different projects. Making it hard to keep track on which assets you already have. The more projects you make the more likely it gets that you will start to duplicate assets. (And possibly even repeat errors you made in the past like again reading the drawing in the datasheet as top view instead of bottom view)

How does this workflow work?

Symbols, footprints and optionally 3d models used in a project are all placed in project specific libraries. These libraries are placed inside the project directory best in their own subdirectory. An example is shown in this picture.

Path Variable KIPRJMOD

KiCad automatically creates the path variable KIPRJMOD that points to the projects root directory (as indicated in the picture above).
This path variable is used inside the project library tables and for handling 3d models.

You still want a central library to source your assets.

You probably do not want to start fresh for every project. And you really do not want to copy assets around between projects either. Which means the best option is to still create a central library that you use as the source for your assets.

In this workflow you would add any new asset always to the centralized library first. But any asset that is used in a project is first copied to a project local library and this local copy is then used.

Another option is to design your projects fully with the central library and only convert it to an atomic setup at the end (just for sharing) There is the archive project plugin that automates this task.

Handling of 3d Models

Footprints sadly directly link to a file path for the 3d models. You will need to ensure that you use the path variable KIPRJMOD here.

One option here is to define a common folder structure within the project (the folder containing the 3d models of the project must always have the same name). With this restriction set up the footprint to point to the file location as expected in a project following this rule.

Rene_Poschl · March 28, 2020, 12:44pm

Special case: Read only access

Viewing the project without the option to make changes can use a modified version of the local setup.
There is no special need for viewing the layout as footprints are already included in the layout (pcbnew) file.

The schematic side however requires special care. If you include the cache library (-cache.lib) then the reader can just use the rescue process to convert the project into an atomic version for viewing. (The rescue process copies symbols from the cache library into a new rescue lib and points the schematic references to this new library)

For 3d model sharing the best option might be to export the board as a self-contained step or wrl (or vrml) file. Either directly from within KiCad or via the kicad-stepup extension of FreeCAD.