1. About LibrePCB

Welcome to the documentation of LibrePCB! LibrePCB is a free EDA software to develop printed circuit boards. It runs on Linux, Windows and Mac.

This documentation is currently under construction. Contributions are welcome! Check out https://github.com/LibrePCB/librepcb-doc

screenshot

1.1. Features

  • Cross-platform (Unix/Linux, Mac OS X, Windows)

  • All-In-One: project management + library/schematic/board editors

  • Intuitive, modern and easy-to-use graphical user interface

  • Very powerful library design with some innovative concepts

  • Human-readable file formats for both libraries and projects

  • Multi-PCB feature (different PCB variants of the same schematic)

  • Automatic netlist synchronisation between schematic and board

1.2. Project Status

LibrePCB is still under development and many features are not implemented yet. So here’s an overview about the project status:

What’s working

  • Downloading, creating and modifying libraries

  • Drawing simple schematics with multiple sheets

  • Creating simple PCBs (incl. Gerber export)

What’s missing

  • All editors:

    • No clipboard functionality (cut/copy/paste) [#13]

  • Schematic editor:

  • Board editor:

    • No DRC (design rule check)

    • No 3D board viewer [wishlist]

2. Getting Started With LibrePCB

This chapter will give you a quick introduction into LibrePCB, starting from where to download it and ending with how to generate the production data for the PCB.

2.1. Installation

There are not yet any stable releases available, so at the moment you need to download the nightly builds instead.

Attention: Unstable file format!

The file format of LibrePCB is still under development, and breaking changes can occur at any time. This means that you may not be able to open your created libraries and projects with future versions of LibrePCB!

Or in other words: LibrePCB does not yet have an upgrade mechanism for the files created with older LibrePCB versions. We will start providing an upgrade mechanism as soon as we publish the first stable release of LibrePCB.

2.1.1. Method 1: Installer

The recommended way to install LibrePCB is to use the online installer. It provides the following features:

  • Downloads the latest version from the Internet (no offline installation possible).

  • Installs a maintenance tool to easily download and install updates.

  • Creates start menu entries for LibrePCB and the maintenance tool.

  • Optionally registers *.lpp files, so LibrePCB projects can be opened with a double-click in the file manager.

Windows
Linux

Download librepcb-installer-nightly-linux-x86_64.run, make it executable and run it:

wget "https://download.librepcb.org/nightly_builds/master/librepcb-installer-nightly-linux-x86_64.run"
chmod +x ./librepcb-installer-nightly-linux-x86_64.run
./librepcb-installer-nightly-linux-x86_64.run
Mac

Download and run librepcb-installer-nightly-mac-x86_64.dmg. "Unverified" packages may have to be opened via right-click.

Because Apple doesn’t provide the ability to run macOS without purchasing their hardware, we’re not able to automatically test LibrePCB for macOS. Feel free to open an issue if LibrePCB doesn’t work as expected.

2.1.2. Method 2: Portable Package

Alternatively you could run LibrePCB without installing it. But then you don’t get an update mechanism, no start menu entries are created, and *.lpp files will not be registered.

Windows

Download and extract librepcb-nightly-windows-x86.zip, then run the contained file bin\librepcb.exe.

Linux

Download librepcb-nightly-linux-x86_64.AppImage, make it executable and start it:

wget "https://download.librepcb.org/nightly_builds/master/librepcb-nightly-linux-x86_64.AppImage"
chmod +x ./librepcb-nightly-linux-x86_64.AppImage
./librepcb-nightly-linux-x86_64.AppImage
Mac

Download librepcb-nightly-mac-x86_64.dmg and double-click it. Then drag and drop the app onto the "Applications" icon of Finder.

Because Apple doesn’t provide the ability to run macOS without purchasing their hardware, we’re not able to automatically test LibrePCB for macOS. Feel free to open an issue if LibrePCB doesn’t work as expected.

2.2. Create a Workspace

When starting LibrePCB the first time, a wizard asks you to open or create a Workspace. The Workspace is just a directory where settings, libraries and (optionally) projects will be stored. Once created, it can be used from all supported operating systems (i.e. it is platform independent) and in future it will also be usable with different LibrePCB versions.

You can just accept the default Workspace location (you could still move it to another location afterwards, if desired):

choose workspace

After clicking Finish, the Control Panel shows up and you’re ready to start using LibrePCB!

2.3. Add Libraries

Before you can start with creating new projects, you need to add some libraries to your Workspace. Libraries contain various kinds of elements which can be added to schematics and boards (e.g. symbols and footprints).

To open the Library Manager, click on the corresponding button in the Control Panel (or on the link in the shown warning, but the warning will disappear after you add a library):

Library Manager

2.3.1. Download Remote Libraries

The Library Manager directly fetches the list of available libraries from the Internet. Most of these libraries are hosted at https://github.com/LibrePCB-Libraries.

The provided libraries currently contain only a few elements. You are welcome to contribute more elements by opening pull requests at https://github.com/LibrePCB-Libraries!

The most important library is the LibrePCB Base library because it contains the most commonly used library elements (like resistors or diodes). It is highly recommended to install this library. To do so, just select the checkboxes at the right and click on the Download and install/update all selected libraries button:

Download Libraries

By the way, the same way you can also update already installed libraries to the latest version. You should regularly update all libraries to get more elements and bugfixes/improvements of existing elements.

Dependencies between different libraries are automatically taken into account when changing the selection. So for example if you select LibrePCB Connectors, the LibrePCB Base Library will automatically be selected too because the Connectors library depends on it.

Downloaded (so-called remote-) libraries are always read-only because otherwise local modifications could cause conflicts when updating the library the next time. But this should not be an issue, just follow the guide below to create your own local library. In a local library you can extend, or even overwrite existing library elements (by using a higher version number to enforce higher priority).

If you are familiar with Version Control Systems (e.g. Git) and want to use them to manage your libraries (instead of the Library Manager), just clone the libraries into the subdirectory v0.1/libraries/local/ in your Workspace.

2.3.2. Create Local Libraries

Of course you can also create your own libraries. To do so, enter some metadata in the tab Create local library and click on Create Library:

Create Library

Now you can open the library editor to create some symbols and footprints in your new library. Select your library on the left and then click on the Open Library Editor button:

Open Library Editor

Now we need a crash course to understand the basics of LibrePCB’s library concept ;) A library consists of several different elements:

  • Component Category: These are basically "metadata-only" elements used to categorize the "real" library elements in a category tree. Every Symbol, Component and Device can be assigned to one or more categories so they will appear in the category tree. Examples: Resistors. LEDs, Microcontrollers

  • Symbol: A symbol is the graphical representation of a Component (or parts of it) in a schematic. It consists of electrical pins and graphical objects like lines. Examples: European Resistor, LED, 1x10 Connector

  • Component: A Component basically represents a "generic" kind of electrical part. It’s not a real part which you can buy, it’s just theoretical. The Component defines the electrical interface of a part and how it is represented in the schematic (by referencing one ore more Symbols). But it does not define how the part looks like in a board. Examples: Resistor, Bipolar Capacitor, 4-channel OpAmp

  • Package Category: Exactly the same as Component Categories, but for Packages instead of Components. Examples: Chip Resistors, Axial Capacitors, DIP

  • Package: As the name suggests, packages represent the mechanical part of a "real" electronic part. It contains the footprint with their electrical pads and graphical objects which is then added to boards. Later a package may also contain a 3D model for the 3D board viewer. Examples: TO220, DIP20, LQFP32

  • Device: The Device now represents a real electronic part which you can buy. It basically combines a Component with a Package to specify how a Component looks like on the board. Examples: 0805 Resistor, LM358D, STM32F103C

The order of this list is actually also the order to follow when creating new library elements. For example a Device always needs to be created after the corresponding Component. The other direction is not possible because of the dependencies.

Ready to create your first library elements? At the top left of the library editor there is the entry point for every new library element. There you can choose which of the six library element type you want to create:

New Library Element

Example: LMV321LILT

Let’s say you want to create the part LMV321LILT from A to Z. We will create now all the necessary library elements for the LMV321LILT, though in practice you only need to create the elements which do not already exist. You can even use elements from other libraries, for example the Symbol from library A, the Component from library B and the Package from library C.

Component Category

First you should create a Component Category for the LMV321LILT (if it doesn’t already exists). Choose a suitable (generic!) name and select a parent category. You may first need to create the required parent categories.

Create Component Category

After clicking on Finish, your first Component Category is ready to be used :)

Symbol

Now we need to create a Symbol for the OpAmp. So this time you click on the Symbol button in the New Library Element wizard. Then fill in some metadata and click on Finish. Now you can place the required pins (choose reasonable and unique names!), add the texts {{NAME}} and {{VALUE}} and draw the outline. The result could look like this:

Create Symbol

Yeah, the overlapping pin texts look ugly, but let’s ignore that for the moment ;)

Following are the most important rules to create reusable Symbols:
  • Create generic symbols, not specific ones. Generic symbols can be shared between many components, specific symbols not.

  • Don’t name pins according their location in the package. Just use incrementing numbers (i.e. 1, 2, 3, …​) or the electrical purpose (e.g. Source, Drain, Gate) where applicable.

  • Don’t add multiple pins with the same name. Even for a microcontroller which has multiple GND pins, the symbol should have only one GND pin. A symbol represents the electrical interface of a part, not the mechanical!

  • Add the texts {{NAME}} and {{VALUE}}. Most symbols should have exactly these two texts — no more, no less.

  • The origin (coordinate 0,0) should be in the center of the symbol (here the symbol can be grabbed with the mouse).

  • Place all pins on the 2.54mm grid.

Component

The next element you need to create is the Component for a single OpAmp. Because it is still very generic (beside the LMV321LILT there are many other OpAmps with exactly the same functionality), so you should enter a generic name like Single OpAmp. In addition, it’s really important to choose a Category for the new Component, otherwise it’s hard to find it in the library when you want to add it to a schematic.

Create Component

Then you’re asked to specify some properties of the Component:

  • Schematic-Only: This should be checked if the Component must not appear on a board, but only in the schematics. This is typically used for schematic frames (yes, they are also Components).

  • Prefix: When adding the Component to a schematic, its name (designator) is automatically set to this value, followed by an incrementing number. So if you choose the prefix R, components added to a schematic will have the names R1, R2, R3 and so on. The prefix should be very short and uppercase.

  • Default Value: In addition to the name, Components also have a value assigned to it, which is typically also displayed in the schematic. For example a capacitor has its capacitance (e.g. 100nF) set in its value. When adding a Component to a schematic, its value is initially set to the value specified here. The value can also be a placeholder, for example {{PARTNUMBER}}, {{RESISTANCE}} or {{CAPACITANCE}}. If you are unsure, just leave it empty, you can still change it later.

Specify Component Properties

Now you need to choose the Symbols which represent the Component in schematics. Most Components have only one Symbol, but you can also add more than one, for example an OpAmp can have separate Symbols for power and amplifier.

Set Component Symbols

After adding the OpAmp Symbol, it should look like this:

Component Symbols

The next step is to define all so-called Signals of a Component. Signals represent the "electrical interface" of a Component. For example a transistor consists of the Signals base, collector and emitter. For a Component it’s irrelevant whether the "real" transistor has multiple emitter pads, or an additional thermal pad and so on, the Component only specifies the three Signals.

LibrePCB automatically extracts the Signals from the Pins of the specified Symbols, so often we don’t have to do this by hand. But sometimes you still should adjust the names or properties of these Signals. For the OpAmp, we check Required for all Signals, so the ERC will show a warning if these Signals are not connected to a net when the Component was added to a schematic:

Component Signals

These Signals now need to be assigned to the corresponding Symbol Pins, but as they were automatically generated from the Pins, you can just click on the button below to automatically assign all Pins to their Signals:

Component Pin-Signal-Map

That’s it, the Component is now ready to be used:

Component Editor

For this simple example, this procedure may feel a little bit complicated. This is basically caused by the high flexibility of the library concept. The Component which we created now actually uses only the very basic library features, but as soon as you understand the whole library concept, you will be able to easily create much more powerful library elements. We’re sure you will love the flexibility of the library concept ;)

Following are the most important rules to create reusable Components:
  • Create generic components whenever possible. Only create specific components for manufacturer-specific parts (like microcontrollers).

  • Name signals according their electrical purpose (e.g. Source, Drain, Gate).

  • Don’t add multiple signals with the same name. Even for a microcontroller which has multiple GND pins, the component should have only one GND signal. A component represents the electrical interface of a part, not the mechanical!

Package Category

Before creating a Package for the LMV321LILT, you should (optionally) create a category for it. This is basically done exactly the same way as you already created the Component Category, so we won’t explain it again. It could look like this:

Create Package Category

Package

Then you need to create the Package for the LMV321LILT, which is called SOT23-5. After specifying some metadata (like you already did for other library elements), you are asked to specify all pads of the Package. The SOT23-5 has 5 pads which we just name from 1 to 5:

Create Package Pads

After that, you can start drawing the footprint of the Package. It’s recommended to start with the pads:

Create Package

And then add other graphical items like the outline, name and value:

Create Package Graphics

That is already enough for a simple footprint.

Following are the most important rules to create reusable Packages:
  • Create generic packages, not specific ones. For example DIP08 is DIP08 — no matter whether it’s an OpAmp, an EEPROM or a microcontroller.

  • Don’t name pins according their location in the package. Just use incrementing numbers (i.e. 1, 2, 3, …​) or the electrical purpose (e.g. Source, Drain, Gate) where applicable.

  • Add all pads of a package, not only the one you currently need. For example if the package has a thermal pad, you should add it, even if you don’t need it.

  • Name pads according specifications (datasheet or IPC-7351), typically just 1, 2, 3 etc. Never name pads according their electrical purpose (e.g. Gate)!

  • Add the texts {{NAME}} and {{VALUE}}. Most footprints should have exactly these two texts — no more, no less.

  • The origin (coordinate 0,0) should be in the center of the footprint (here the footprint can be grabbed with the mouse).

Device

The last library element you need to create is the Device which combines the Component Single OpAmp with the Package SOT23-5. This is actually the only library element which is specifically for LMV321LILT — all previously created elements are generic!

Again, specify some metadata about the Device first. Then you need to choose the Component and Package you want to assign:

Create Device

Then you have to assign the Package pads to Component signals according to the datasheet of the LMV321LILT:

Device Pad-Signal-Map

And that’s it! In the library overview (the first tab in the Library Editor) you can see all the elements you have created:

Library Overview

The LMV321LILT is now ready to be added to schematics and boards. And because the Categories, Symbol, Component and Package are quite generic, they can also be used for many other library elements :)

2.4. Create a New Project

In LibrePCB, schematics and boards are always part of a Project, so to draw schematics and boards you first need to create a Project for every PCB you want to design. This is really easy, just follow the New Project wizard:

Create Project

Then fill in some metadata about the Project:

Create Project

For Open-Hardware projects it’s highly recommended to select the license CC0-1.0 as this allows everyone to use your project without restrictions.

Even if it is possible to create the Project outside the Workspace directory, it’s recommended to store all Projects inside the Workspace because these Projects are listed at the left side of the Control Panel. This allows to easily locate and open them. Projects outside the Workspace need to be opened by specifying their location in an open dialog.

Now you can choose whether the Project should be initialized with a first schematic page and board, and how they are named. If you are unsure, just accept the default values:

Initialize Project

After clicking on Finish, the schematic and board editors show up and you’re ready to draw the schematics:

Project Editor

2.5. Create Schematics

First, you may want to add a frame to the schematic. Is is done by choosing a schematic frame in the Component Chooser:

Add Schematic Frame

Then let’s add the OpAmp we have created in our own library, again with the Component Chooser:

Add OpAmp

Here you can choose whether you want to add the Component Single OpAmp or the Device LMV321LILT. Yes, you can add either a Component or a Device to a schematic ;) Actually the schematic always contains Components (not Devices), but you can still (optionally) choose the Device which will be used later when adding the Component to the board (boards always contain Devices).

The most commonly used Components are also available in the toolbar on the left side:

Standard Components

Just place some Components and draw the net lines with the corresponding tool in the toolbar at the left side.

2.6. Create Boards

Once the schematic is (more or less) complete, you can start adding Devices to the board. For every Component in the schematic, you need to place a Device in the board (except schematic-only Components, like the schematic frame). In the Place Devices dock on the right side of the board editor you can see all unplaced Components. For every Component you can choose its corresponding Device now and add them to the board:

Add Devices to Board

By the way, it’s even possible to replace the Devices after adding them to the board. So for example you can replace a C-1210 capacitor by a C-0805 capacitor just in the context menu of the Device:

Change Device

Then you can start adding vias and traces to connect the pads together.

The functionality of the board editor is still very limited. Some very important features (like airwires) are currently under development.

2.7. Generate Production Data

Once the board is finished, you can generate the production data for the PCB manufacturer:

Generate Production Data

Here you can adjust some settings of the Gerber export. Generally you should determine what format your PCB manufacturer accepts. Many manufacturers accept Protel-style Gerber files, so if you’re unsure, click on the Protel naming button:

Production Data Generator

Then just click on the Generate Gerber & Excellon Files button and LibrePCB places the generated files in your project’s output subdirectory. Send these files (and some money) to your PCB manufacturer and wait for the PCBs :)

The production data generator is not very mature yet. It’s highly recommended to cross-check the generated files with 3rd-party tools like gerbv or the reference gerber viewer.

LibrePCB is not responsible for any implications caused by wrong production data.

3. LibrePCB Command Line Interface

LibrePCB also provides a command line interface (CLI). With that tool, you can automate some tasks, for example on Continuous Integration (CI) systems.

3.1. Installation

Method 1: Installer

If you have installed LibrePCB with the installer (as described here), you should already have the librepcb-cli tool available in the installation directory.

Method 2: Portable Package

Alternatively you could run librepcb-cli without installing it.

Windows

Download and extract librepcb-nightly-windows-x86.zip, then run the contained file bin\librepcb-cli.exe.

Linux

Download librepcb-cli-nightly-linux-x86_64.AppImage, make it executable and start it:

wget "https://download.librepcb.org/nightly_builds/master/librepcb-cli-nightly-linux-x86_64.AppImage"
chmod +x ./librepcb-cli-nightly-linux-x86_64.AppImage
./librepcb-cli-nightly-linux-x86_64.AppImage
Mac

Download librepcb-cli-nightly-mac-x86_64.dmg and double-click it. Then drag and drop the app onto the "Applications" icon of Finder.

3.2. Running on Headless Linux

Please note that (at this time) librepcb-cli requires a running X-server even if it doesn’t open any windows. If your system doesn’t have an X-server running, you can use xvfb instead:

$ xvfb-run -a librepcb-cli [args]

You may also need to install the OpenGL library (e.g. libglu1-mesa).

Running in Docker Container

In addition to xvfb, running the LibrePCB CLI AppImage in a Docker container needs a workaround because FUSE is missing. See details here: https://github.com/AppImage/AppImageKit/wiki/FUSE#docker

Example Dockerfile
FROM ubuntu:18.04
RUN apt-get update && apt-get -yy install wget ca-certificates libglu1-mesa qt5-default xvfb
RUN wget https://download.librepcb.org/nightly_builds/master/librepcb-cli-nightly-linux-x86_64.AppImage
RUN chmod a+x ./librepcb-cli-nightly-linux-x86_64.AppImage
RUN ./librepcb-cli-nightly-linux-x86_64.AppImage --appimage-extract
ENTRYPOINT ["sh", "-c", "xvfb-run -a ./squashfs-root/AppRun"]

3.3. Usage

Usage instructions and available options can be shown with --help:

Command
$ ./librepcb-cli --help
Output
Usage: ./librepcb-cli [options] command
LibrePCB Command Line Interface

Options:
  -h, --help     Displays this help.
  -v, --version  Displays version information.
  --verbose      Verbose output.

Arguments:
  command        The command to execute.

Commands:
  open-project   Open a project to execute project-related tasks.

3.3.1. Command open-project

This command opens a LibrePCB project and lets you execute some tasks with it.

Command
$ ./librepcb-cli open-project --help
Output
Usage: ./librepcb-cli [options] open-project [command_options] project
LibrePCB Command Line Interface

Options:
  -h, --help                     Displays this help.
  -v, --version                  Displays version information.
  --verbose                      Verbose output.
  --erc                          Run the electrical rule check, print all
                                 non-approved warnings/errors and report failure
                                 (exit code = 1) if there are non-approved
                                 messages.
  --export-schematics <file>     Export schematics to given file(s). Existing
                                 files will be overwritten. Supported file
                                 extensions: pdf
  --export-pcb-fabrication-data  Export PCB fabrication data (Gerber/Excellon)
                                 according the fabrication output settings of
                                 boards. Existing files will be overwritten.
  --board <name>                 The name of the board(s) to export. Can be
                                 given multiple times. If not set, all boards
                                 are exported.
  --save                         Save project before closing it (useful to
                                 upgrade file format).

Arguments:
  open-project                   Open a project to execute project-related
                                 tasks.
  project                        Path to project file (*.lpp).
Example: Check ERC Messages and Export Schematics & Boards

This command is useful for Continuous Integration of LibrePCB projects because it reports failure if you check in projects with non-approved ERC messages. In addition, it generates all production data so you don’t have to do it manually.

Command
$ ./librepcb-cli open-project \
    --erc \
    --export-schematics="output/{{VERSION}}/{{PROJECT}}_Schematics.pdf" \
    --export-pcb-fabrication-data \
    MyProject.lpp
Output
Open project 'MyProject.lpp'...
Run ERC...
  Approved messages: 7
  Non-approved messages: 2
    - [WARNING] Net signal connected to less than two pins: "CAN_RX"
    - [WARNING] Net signal connected to less than two pins: "JTCK"
Export schematics to 'output/{{VERSION}}/{{PROJECT}}_Schematics.pdf'...
  => 'output/v1/MyProject_Schematics.pdf'
Export PCB fabrication data...
  Board 'default':
    => 'output/v1/gerber/MyProject_DRILLS-PTH.drl'
    => 'output/v1/gerber/MyProject_OUTLINES.gbr'
    => 'output/v1/gerber/MyProject_COPPER-TOP.gbr'
    => 'output/v1/gerber/MyProject_COPPER-BOTTOM.gbr'
    => 'output/v1/gerber/MyProject_SOLDERMASK-TOP.gbr'
    => 'output/v1/gerber/MyProject_SOLDERMASK-BOTTOM.gbr'
    => 'output/v1/gerber/MyProject_SILKSCREEN-TOP.gbr'
    => 'output/v1/gerber/MyProject_SILKSCREEN-BOTTOM.gbr'
Finished with errors!

In this example, the application reported errors and exited with code 1 because there are non-approved ERC messages.