QEMU

An experimental QEMU image is available that includes:

  • Phosh: the phone graphical shell
  • Common apps: Geary, Epiphany, Contacts, Calls, etc.
  • Phone/network services: NetworkManager, ModemManager, etc.

Linux Environments

First, obtain a disk image for your workstation. The most recent qcow2 image for x86_64 should be suitable for most users. If that is not available, follow these steps:

  1. Go to the Image Build page on the CI server.

  2. Find the most recent successful (green colored) qemu-x86_64 build in the Build History column on the left-hand side of the page (use the “find” field to filter the list in the column with “x86_64” as keyword for instance to match your target hardware architecture). Clicking on the link for that build will take you to a page containing a suitable qemu-x86_64.qcow2 image file.

    (The qcow2 image can also be built locally using Librem5 image building scripts.)

You need software to run the image. You can use any virtualization application that will create a VM from a qcow2 file to run this image.

GNOME Boxes

On PureOS, gnome-boxes is already installed and can be used right away. Create a new Box from archive selecting qemu-x86_64.qcow2

Virt-manager

On PureOS, you would need to install virt-manager:

$ sudo apt install virt-manager

Create a new virtual machine from your archive by selecting qemu-x86_64.qcow2

Using QEMU on the Command Line

You can also run the qcow2 image from the command line:

$ sudo qemu-system-x86_64 -boot menu=on -drive file=qemu-x86_64.qcow2,format=qcow2 -vga virtio -display gtk -m 2G -enable-kvm

It may be necessary to pass the -smp option (for example with -smp 6) to improve performance. The -display option accepts different display types as its parameter – experimenting with these may prove useful.

If you would like to allow ssh connections from the host into the guest system, you may add -device e1000,netdev=net0 -netdev user,id=net0,hostfwd=tcp::5555-:22 to the qemu-system-x86_64 command above. Then, from another terminal window in the host, you can log in with this command:

$ ssh -p 5555 purism@localhost

See the QEMU documentation for more information.

Microsoft Windows

First, obtain a disk image for your workstation. The most recent img.xz image for x86_64 should be suitable for most users. If that is not available, follow these steps:

  1. Go to the Image Build page on the CI server.
  2. Find the most recent successful (green colored) qemu-x86_64 build in the Build History column on the left-hand side of the page. Clicking on the link for that build will take you to a page containing a suitable qemu-x86_64.img.xz image file.

Download the image to a suitable place:

  1. Download the build artifact by right-clicking on the file called qemu-x86_64.img.xz and choosing “Save As”.

  2. Choose a folder on your computer with 4GB of free space.

  3. After the download is complete, extract the file with 7zip or other untar program.

  4. Open an instance of PowerShell and navigate to the extracted file’s folder.

  5. The following command can be executed in PowerShell after modifying the path to the qemu executable and the path to the downloaded qemu-x86-64.img file.:

    C:\Program Files\qemu\qemu-system-x86_64.exe -drive file=c:\downloads\qemu-x86_64.img,index=0,media=disk,format=raw -vga virtio -display sdl,gl=off -m 2G -L Bios -boot menu=on -rtc base=localtime,clock=host -parallel none -serial none -name PureOS -no-reboot

  6. Note: You may also download and modify the following PowerShell script for your environment. The file can executed on the command line, or by right-clicking launch-librem5.ps1 file from file explorer. The script is fully commented to explain the command line variables that are used.

PowerShell script: launch-librem5.ps1

Expanding the Filesystem

The qcow2 image is built such that, by running a simple command from within the VM environment, you can resize the root filesystem to fill the partitioned space.

Note

In this example, the filesystem to be resized is /dev/vda2 but it will depend on the drives that are available in the VM image – it could be /dev/sda2 or something similar.

Before the rootfs is resized, running df -h from within the VM environment will show you that /dev/vda2 has a size of 3.1G. To grow the partition, resize the /dev/vda2 partition and then check df -h again to see that it is now 31G:

purism@pureos:~$ sudo resize2fs /dev/vda2
resize2fs 1.44.4 (18-Aug-2018)
Filesystem at /dev/vda2 is mounted on /; on-line resizing required
old_desc_blocks = 1, new_desc_blocks = 4
The filesystem on /dev/vda2 is now 8172342 (4k) blocks long.

purism@pureos:~$ df -h /
Filesystem      Size  Used Avail Use% Mounted on
/dev/vda2        31G  2.2G   28G   8% /

Now your additional space on /dev/vda2 is immediately ready for use without any need to reboot.

Using workstation devices inside the VM

You might want to use your workstation’s devices to test hardware-specific features within the VM, such as:

  • testing the camera API or a camera app using your webcam
  • testing cellular network-related features (like calls/SMS/data) using your laptop’s modem

In such case, you need to redirect the devices of the host machine (i.e. your workstation) so that the guest VM can use them.

As an example, let’s take a USB webcam. Once you have redirection properly configured, you can test it out by installing and running cheese within the VM.

Virtual Machine Manager

  1. Run virt-manager and open the entry for your librem5 VM

  2. Click the “i” icon to show the virtual hardware details

    ../../_images/virt-manager-vm-info-button.png

  3. Click ‘Add Hardware’ (bottom-left corner)

    ../../_images/virt-manager-add-hardware-button.png

  4. Select ‘USB Host Device’

  5. From the list of available Host Devices available, select the webcam and click ‘Finish’

    ../../_images/virt-manager-host-usb-devices.png

  6. You should now see the newly added device listed as ‘USB <vendor ID>:<product ID>’

Command Line

If you’re running the VM manually via the command line instead, you will need to pass the following additional arguments to qemu:

  1. An emulated host controller of your choice (e.g. qemu-xhci)
  2. The product ID and vendor ID of the USB device you want to redirect

For example: a Logitech USB HD Webcam C910 has vendor ID 046d and product ID 0821. You would need to pass these as values to vendorid and productid respectively (with 0x prepended):

-device qemu-xhci,id=xhci -device usb-host,bus=xhci.0,vendorid=0x046d,productid=0x0821

To find the the information needed to redirect your device, run lsusb. It will print a list of USB devices present, in the following format:

Bus <USB bus> Device <address>: ID  <vendor ID>:<product ID> <human-readable device name>

Then you can get the vendor ID and product ID from the line corresponding to your device.

Webcam Example

The following script can be used to run qemu with the Librem 5 system image for the x86_64 architecture. Update the DEVICE environment variable to use the vendor and product IDs for your desktop webcam. This should allow you to take a picture with the Cheese application using your webcam:

#!/bin/bash
#On debian buster
#Use the Librem5 image (password is 123456)
#aptitude install qemu-system qemu-user qemu-utils
IMAGE=qemu-x86_64.qcow2
DEVICE="-device qemu-xhci,id=xhci -device usb-host,bus=xhci.0,vendorid=0x05ac,productid=0x8508"
#user must have usb writing access
qemu-system-x86_64 -boot menu=on -drive file=${IMAGE},format=qcow2 -display gtk -vga virtio -m 2G -enable-kvm ${DEVICE}

To demonstrate this, the picture below was stored in the user’s Documents directory, then sent by e-mail to the workstation hosting the emulator:

Qemu emulator (x86_64) Librem 5 image takes picture with Cheese application using desktop webcam

Using the Image

The emulator should boot up to a lock screen. Swipe up to show the passcode entry screen, then log in using the passcode 123456.

The initial lock screen Enter the passcode in the passcode entry screen

You can now start exploring the phone software.