Librem 5 Development Kit

Note

This page is incomplete and is being regularly updated.

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.

Updating the Software

There are three main software components that can be updated: the bootloader, the kernel and the distribution packages. The installed packages can be updated in the normal way using the``apt`` tool to update and upgrade them:

sudo apt update
sudo apt full-upgrade

Currently, the bootloader can only be updated by reflashing the eMMC on the board – see Flashing eMMC for instructions. This limitation will be fixed when the following issue is resolved:

The kernel can be upgraded from a package file using dpkg. In the future it will also be possible to upgrade the kernel using apt when these issues are resolved:

These instructions will be updated as developments occur.

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 -b 115200 /dev/ttyACM0

This should produce the output like this:

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. Later images will try to obtain an IP address using DHCP – see below for information.

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

$ ssh purism@192.168.42.202

If you update the image on the development board, it will try to obtain an IP address using DHCP. You will need to determine this address by accessing the DHCP client table for your local network. For example, if the board has been assigned the IP address 192.168.1.110 you can log in with the following command:

$ ssh purism@192.168.1.110

If you have difficulty determining the IP address of the board in the case where it uses DHCP, please contact your local network administrator for assistance.

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.

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

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. On Debian-based systems, issue the following commands as root to make the development board accessible to your user over USB whenever it’s 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

Users of non-Debian systems may need to add the plugdev group if it does not already exist. This group grants permission to its members to access the devices it owns:

groupadd plugdev

You will need to add your user to the plugdev group to access the development board:

sudo usermod -a -G plugdev $USER

You can log in to the new group without having to log out by running this command:

newgrp plugdev

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

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.

Reboot

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, and a new newtwork interface will appear, confirming a successful reflash.

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

HDMI

After flashing the latest image, connect to it using serial console in the same way as previously, and log in as root.

Copy the librem5-evk-hdmi.dtb file to the correct place:

root@pureos:~# cp /boot/dtbs/librem5-evk.dtb /boot/dtbs/librem5-evk.dtb.bak
root@pureos:~# cp /usr/lib/linux-image-`uname -r`/freescale/librem5-evk-hdmi.dtb /boot/dtbs/librem5-evk.dtb

Note: The LCD panel is disabled when using this dtb file.

Connect the HDMI monitor and reboot the system:

root@pureos:~# reboot

After the system exits u-boot, a row of penguins will appear in the top-left corner of the monitor. Afterwards, Phosh will occupy the display, showing a login screen on a gray background.

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 Wi-Fi

Before attempting to use Wi-Fi, ensure that the Wi-Fi/Bluetooth switch is set to the ON position on the board.

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

modprobe rsi_sdio

Then you can configure the network interface.

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

Configure Bluetooth

Before attempting to use Bluetooth, ensure that the Wi-Fi/Bluetooth switch is set to the ON position on the board.

To enable Bluetooth you must first make sure the relevant module is loaded:

modprobe rsi_sdio

It should then be possible to query the Bluetooth device:

hcitool dev

This should produce output like this:

Devices:
        hci0    88:DA:1A:9E:BA:95

The exact device address will be different for your board. See Bluetooth Connections for further ways to test and use the Bluetooth module.

Printable Case

A printable case model has been designed by MrPickleGG and is available on youmagine.com.