Connecting via USB

A convenient way to connect the phone to a workstation is via a USB-A to USB-C cable. This guide describes how to configure the phone and a connected workstation to allow serial and network communication between the two devices.

This guide assumes that the phone is switched on and running the system software. Ensure that the phone is already in this state before trying to connect to it.

Notes about Cables

Some USB-A to USB-C cables may need to be plugged into the phone with a particular orientation. If the instructions above do not appear to work, try flipping the USB-C end of the cable over and replugging it into the phone.

USB Serial Console

Connect the phone to a workstation using a USB-A to USB-C cable. The phone should appear shortly after as a USB serial device to the workstation.

Check to see that the following appears in the output of the lsusb command:

Bus 002 Device 007: ID 316d:4c05 Purism, SPC Librem 5

The bus and device numbers may differ from those shown.

The device will also appear in the /dev/ directory as a serial port, such as /dev/ttyACM0, which you can use to access the phone’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:

pureos login:

You may need to press Return to see the prompt.

You should be able to log in using 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.

Enabling Networking

In this section, we briefly describe how to get a simple IPv4 interface set up and enable network routing from the phone via the workstation to the Internet. The procedure is similar to that described in the Ethernet over USB guide for the Librem 5 development board, which provides much more detail.

Workstation

On your workstation, check the output of the ip link command to see which network interfaces are available:

ip link

Connect the workstation and the phone using the USB cable, then run ip link again to see which new ones have appeared. You should see a new entry like this one in the output from the command:

7: enp0s18f2u1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN mode DEFAULT group default qlen 1000
    link/ether 2a:71:82:e2:63:84 brd ff:ff:ff:ff:ff:ff

The interface on your workstation may be different to this.

Obtain the librem5-usbnet script from the librem5-devkit-tools repository. It can be found in the scripts directory.

This script accepts an IPv4 address and the new network interface. Make sure that it is executable and on the run path, then run it in the following way, substituting the new interface on your workstation for the one given:

sudo librem5-usbnet 192.168.42.1 enp0s18f2u1

You should be able to run ip addr and ip route to see that the interface has an address and route associated with it.

Phone

Use the USB serial console described above to log in to the phone.

Obtain the usbnet script from the librem5-devkit-tools repository. It can be found in the test_scripts directory.

Running sudo usbnet should set up an IPv4 address for the phone and a default route for network traffic that goes via the workstation.

Next Steps

Once USB networking is enabled, it becomes possible to access the network via the workstation and install development tools. This is also possible via a cellular network or Wi-Fi.