Librem 5 Development Kit

Note

If you experience problems with the development kit, you may find it useful to consult the Known Issues page and Troubleshooting guide.

Development Kit Package

The package contains:

  • Receipts
  • An informational leaflet
  • A 5V @ 3A USB power supply with a USB-A (non-SS) socket
  • A cable with a USB-A (non-SS) plug on one side and a USB-C plug on the other
  • The dev board, composed of the following detachable parts:
    • The base board, AKA Librem 5 Dev Kit v1.0.0
    • The SIM7100E modem in the Europe version, SIM7100A in the US version, with an antenna cable attached – see Modems for details
    • The EmCraft SoM with a Quad iMX8M
    • A camera module marked TRULY-M (covered with a paper protector)
    • The RedPine Signals WiFi/BT module with 2 antenna cables attached

The development board accepts the following items, not included in the package:

  • a MicroSD card
  • a Micro/3FF SIM card (15×12mm)
  • a Mini/2FF GPG smart card (25x15mm)
  • a protected 18650 Li-ion battery that meets the specs on the silkscreen
    • Built-in over-voltage, under-voltage, over-current, and over/under-temperature protection
    • minimum cell voltage of 2.5V or less
    • maximum cell voltage of 4.2V or more
    • maximum discharge current of 8A or more
    • maximum charge current of 1.6A or more

Warning

If a battery is used with the board, it must be inserted in the battery holder instead of being connected indirectly via adaptors or jumper wires. Use of the battery holder ensures that thermal regulation can be used as an additional precaution against overheating.
The polarity marking must be followed when inserting the battery otherwise there is a risk of damaging the board and/or the 18650 cell.

Notably, the development board has an Ethernet port, a single USB-C port, and a Mini-HDMI port.

Ports, right hand side, top to bottom: 3.5mm audio socket, RJ45 Ethernet socket, mini HDMI socket, USB C socket, micro SD card socket. Kill switch side, left to right: reset button, boot mode switch, camera + microphone kill switch, cellular kill switch, Wi-Fi kill switch. Button side, right to left: smart card socket, volume down button, volume up button, power button, micro SIM card socket.

The positions and types of sockets, push buttons and switches (click to enlarge). Ports, right hand side, top to bottom: 3.5mm audio socket (see Audio), RJ45 Ethernet socket, mini HDMI socket (see Display), USB C socket (see USB), micro SD card socket (see Micro SD Card). Kill switch side, right to left: reset button, boot mode switch, camera + microphone kill switch, cellular kill switch, Wi-Fi kill switch. Button side, right to left: smart card socket (see Smart Card), volume down button, volume up button, power button (see Push Buttons), micro SIM card socket (see Micro SIM Card).

See Hardware Reference for information about the specific parts used for the sockets, buttons and switches.

Setting up the Board

In its original factory state, the board is lacking some essential features. We recommend that you consider Flashing the eMMC before using the board for development.

It may also be useful to consult the Known Issues page and Troubleshooting guide if problems occur.

Flashing the eMMC

The main purpose of the image included on the eMMC is factory testing, therefore it’s strongly recommended to flash an up-to-date one immediately.

The scripts mentioned in this section can be obtained from the librem5-devkit-tools repository.

Install uuu

The NXP mfgtool uuu is required to boot a board that has no bootloader or is otherwise “bricked”.

You can obtain a uuu package for Debian-based systems from the Purism CI server or build uuu from source.

To install the package, run the dpkg tool in the following way:

sudo dpkg -i uuu_1.2.91_amd64.deb

The precise .deb package file name may differ from the one given above. Version 1.2.91 or later is recommended.

Downloading Flashing Scripts

Files from the librem5-devkit-tools repository are responsible for the downloading of the image files, and for coordinating their transfers to the dev kit.

Check out the repository before proceeding.

Flash the Image

Note: If your workstation cannot provide the necessary power for this process you may need a USB 3 powered hub between the host and the development board.

Put the “Boot Mode” switch in the USB position. Attach the development board to a USB C or USB 3 port on the host that is capable of providing 900mA of current. The HID device should appear in the output of the lsusb command, like this:

Bus 001 Device 005: ID 1fc9:012b NXP Semiconductors

The librem5-devkit-flash-image script will download and flash the newest available rootfs and U-Boot images. You may need to install some Python modules before running the script. On Debian 9 (Stretch), Ubuntu 18.04 LTS (Bionic Beaver) and later, this command should install these modules:

sudo apt-get -y install python3-jenkins python3-tqdm python3-yaml

Now you can proceed with the flashing, using the script as shown below to download temporary copies of U-Boot, kernel and the base system, before flashing them on the board. Use the --skip-cleanup and --dir command line options to keep the downloaded files after flashing.

This will erase everything on the board’s eMMC:

cd librem5-devkit-tools
export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/
./scripts/librem5-devkit-flash-image

If you use the --dir option to download the files into a directory and --skip-cleanup to keep them after flashing, you can re-flash the eMMC using the same files by entering the download directory and running uuu. For example, this is how you would download the files to the /tmp/devkit directory and flash the eMMC, then re-flash it later as required.

This will erase everything on the board’s eMMC:

cd librem5-devkit-tools
export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/
./scripts/librem5-devkit-flash-image --dir /tmp/devkit --skip-cleanup

# Re-flash the eMMC later:
cd /tmp/devkit
uuu flash_devkit.lst

It can also be useful to use the --skip-flash if you only want to download the files without flashing the eMMC.

Booting for the First Time

Flip the boot switch back to eMMC position and press the reboot button. The output of the lsusb command should show a multifunction gadget, like this:

Bus 003 Device 068: ID 1d6b:0104 Linux Foundation Multifunction Composite Gadget

The serial console should appear at /dev/ttyACM0. You should be able to log in as the user purism with the password 123456.

The board should also be available as a USB network device – see the Ethernet over USB guide for setup instructions.

As usual, don’t hesitate to get in touch if you find yourself stuck.

Next Steps

See the How To Guides page for a collection of guides covering common tasks and use cases for the board.