Librem 5 Development Kit

Note

This page is incomplete and is being revised.

The scripts mentioned on this page can be obtained from the librem5-devkit-tools repository.

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

Dev 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 dev kit accepts the following items, not included in the package:

  • 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
    • VBAT(min)≤2.5V
    • VBAT(max)≥4.2V
    • Icharge(max)≥1.6A
    • Idischarge(max)≥8A
  • a MicroSD card
  • a Micro/3FF SIM card (15×12mm)
  • a Mini/2FF GPG smart card (25x15mm)

Notably, the development board has an Ethernet port, a single USB-C port, and a Mini-HDMI port. The attached display does not function correctly at the time of writing (2018-12-09), so an external display is highly recommended.

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.

Test Run

There are two simple ways to verify that the development board is functioning. It is useful to try both of these to ensure that you can access the board via serial and Ethernet connections.

If neither of these procedures work for you, please get in touch.

First of all, make sure that the boot mode switch is set to eMMC – see the labelled photo above.

USB Console

Connect the board to a workstation using the USB A to USB C cable provided. The haptic motor will sound briefly and the board should appear shortly after as a USB serial device to the workstation.

Bus 003 Device 025: ID 0525:a4a7 Netchip Technology, Inc. Linux-USB Serial Gadget (CDC ACM mode)

It will appear in the /dev/ directory as a serial port, such as /dev/ttyACM0, which you can use to access the board’s serial console if you have permission to read and write to that device:

$ picocom --quiet -b 115200 /dev/ttyACM0

Debian GNU/Linux buster/sid pureos-test ttyGS0

pureos-test login:

It should be possible to log in using root as both the user name and password, or purism as the user name and 123456 as the password.

Note: You may have trouble accessing the serial device if your user is not a member of the dialout group on your workstation. For example, you may get an error like this:

FATAL: cannot open /dev/ttyACM0: Permission denied

In this case, you can either add your user to the dialout group or, as a workaround, run picocom using the sudo command.

Ethernet Connection

Connect the board to a network using the Ethernet socket and a suitable cable. Connect the board to the provided power supply using the provided cable. Two green LEDs will immediately light up between the SoM and the battery holder. After a moment, the orange Ethernet light should start blinking and the haptic motor will sound briefly. The board should be accessible over the network via SSH. The image shipped with the boards will claim the IP address 192.168.42.202 with the /24 netmask.

It should be possible to log in using purism as the user name and 123456 as the password:

$ ssh purism@192.168.42.202

Flashing 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.

Install uuu

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

Build by Hand

If you are not using uuu included in your favorite distribution, you can build it manually instead. On a Debian-based system, you will need to install some dependencies before building:

sudo apt-get -y install libusb-1.0-0-dev libzip-dev libbz2-dev

Then you can proceed with the build:

git clone https://source.puri.sm/Librem5/mfgtools
mkdir mfgtools-build
cd mfgtools-build
cmake ../mfgtools
make

The uuu binary will find itself in mfgtools-build/uuu/uuu.

Udev Rules

We recommend running uuu as an unprivileged user. Issue the following commands as root to make the dev kit accessible to your user over USB whenever it is connected:

cat <<EOF > /etc/udev/rules.d/99_librem5_devkit.rules
SUBSYSTEM!="usb", GOTO="librem5_devkit_rules_end"
# Devkit USB flash
ATTR{idVendor}=="1fc9", ATTR{idProduct}=="012b", GROUP+="plugdev", TAG+="uaccess"
ATTR{idVendor}=="0525", ATTR{idProduct}=="a4a5", GROUP+="plugdev", TAG+="uaccess"
ATTR{idVendor}=="0525", ATTR{idProduct}=="b4a4", GROUP+="plugdev", TAG+="uaccess"
LABEL="librem5_devkit_rules_end"
EOF
udevadm control -R
adduser <youruser> plugdev

and then, to log in to the new group:

newgrp plugdev

The next time you plug in the USB cable, the development board’s USB interface will be accessible by your user.

Note: You may need to create the plugdev group with groupadd if you are not using a Debian-based distribution.

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

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:

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

Now you can proceed with the flashing.

This will erase everything on your eMMC:

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

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

Reboot

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

Bus 001 Device 010: ID 0525:a4a7 Netchip Technology, Inc. Linux-USB Serial Gadget (CDC ACM mode)

The serial console should appear at /dev/ttyACM0, confirming a successful reflash.

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

Power on/off

On a development kit with an operating system installed, if the user holds the power button for ~2 seconds then a power down/reboot dialog should pop up; a quick press and release should turn the display on/off.

If the button is held for ~5 seconds the SoC triggers an event to shut down; pressing it again for ~2 seconds will turn it back on.

The button is also attached to the charge controller’s QON# pin, which when held for ~15 seconds is able to put the dev kit into a “shipping mode” where the charge controller is completely off, or holding it for ~18 seconds will cause it to perform a complete power cycle.

Flash u-boot

Using SDP

The uboot that gets flashed is files/u-boot-devkit-recovery.imx. Put the “Boot Mode” switch in the USB position:

cd librem5-devkit-tools
export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/
uuu uuu_scripts/u-boot_flash_librem5-devkit.lst

You can also just boot to u-boot without flashing anything:

cd librem5-devkit-tools
export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/
uuu uuu_scripts/u-boot_librem5-devkit.lst

Configure WiFi

For either method below you must first make sure the module is loaded:

modprobe rsi_sdio

Configure with nmtui

In a console, run nmtui to access the textual user interface to Network Manager. Choose the option to activate a connection then choose your WiFi network. The list may initially be empty because it sometimes takes 15 seconds after loading the module to populate it with available networks.

Configure with nmcli

If you know which network you want to connect to, you can just use nmcli directly:

nmcli device wifi rescan
nmcli device wifi list
nmcli device wifi connect SSID-Name password wireless-password