Installing Mobian (Linux-first devices)

This guide covers installing Mobian on the PinePhone, Librem 5, or PineTab by flashing an image to an SD card or the device's eMMC. See the devices page for the full list of supported devices.

Install tow-boot bootloader

Starting April 3, 2022, Mobian images and installers do not contain device-specific a uboot bootloader anymore, so users are once required to install tow-boot on their device in case no bootloader is installed yet. These needs to be done before flashing Mobian. The upshot is that tow-boot integrates the jumpdrive functionality, so that is not needed anymore. Tow-boot is required for the PinePhone Pro (recommended to install to “SPI”) and the original PinePhone (recommended to install to the eMMC).

With tow-boot, the phone can be started in USB Mass Storage mode by holding the volume up button at startup before and during the second vibration. The LED will turn blue if done successfully. In this mode, the phone will work like a USB drive when connected to a host computer.

Booting an operating system from an SD card with tow-boot will require holding the volume down button before and during the second vibration. When done successfully, the LED will turn aqua.

Hint PP only: On the PP you must ensure that the u-boot sector on the SD card is deleted if you want to use that (volume down) tow-boot feature, otherwise the boot sector on the SD card will take control before tow-boot. It's because the PP takes the SD card as first device.

Hint PineTab only: There is no tow-boot distribution for the PineTab yet (help welcome). So the last image we recommend for the PineTab is the one including u-boot from March 27, 2022 (and upgrading from there).

Once tow-boot is installed, proceed with the next steps.

Obtain the Mobian Image

You can choose between downloading an installer or pre-built image or compiling the image yourself.

Installer Images (Alpha)

In order to flash with full disk encryption (FDE), use the installer images here:

To use these installer images, flash them to the device using the steps below, boot and follow the on screen prompts.

The installer uses Calamares, and our extensions to it can be found here.

Pre-built Images

We recommend downloading pre-built images for installation. The image file for your device will be named “mobian-<device>-phosh-YYYYMMDD.img.gz” and can be found here:

The root directory may contain the latest image that we consider stable. After installing and running a software upgrade, it should be rather close to the latest weekly image (assuming they are both recently updated). If no 'stable' image exists in the directory, see the weekly folder for weekly builds.

(Optional) verify the Download

If you simply want to make sure the download is not corrupted, the bmap method (Method 2 below) will automatically verify the checksum for you. Otherwise we publish the checksums of the images next to the images, e.g. as mobian-pinephone-phosh-YYYYMMDD.sha256sums.

If you have somewhat higher demands to verify the image actually came from us, you can also get the gpg signature of the checksum file, e.g. mobian-pinephone-phosh-20211107.sha256sums.sig. After you imported our public gpg key you can verify the checksums match with the our expectations:

gpg --verify ./mobian-pinephone-phosh-YYYYMMDD.sha256sums.sig

Building from Debos Recipes

You can build the image yourself using the debos recipes. If you build the image yourself, the produced image file will be not be zipped (i.e. named “mobian-<device>-phosh-YYYYMMDD.img”) and there is no need to unzip the archive.

Mounting the Target Storage Device

Option 1: Mounting an SD card

To mount an SD card, simply insert the SD card into a computer of your choice. Use lsblk to find the name of the sd card, which should be something like “sdb” or “sdc”.

Be advised that the first boot of Mobian (whether from micro SD card or eMMC) will take longer due to the automatic resizing of the filesystem. The boot screen will inform you while this is happening.

Option 2: Mounting the target device's eMMC using TowBoot

If you already have installed tow-boot (which you should have done), you have all that you need. You can access and mount your device through USB from a computer and flash from there.

You enter Tow-Boot's built-in “Jump Drive” mode and expose the phone's eMMC as USB storage by:

  1. Booting the device while holding the Volume Up button, and waiting for the LED to turn blue.
  2. Connecting the device to your computer using a USB cable.
  3. Mounting the PinePhone Pros eMMC storage (in the form of /dev/sdX block devices).

The device will be exposed as /dev/sdX. For instance, on my computer it assigned /dev/sdb1 to device'​s eMMC/boot partition, and /dev/sdb2 to eMMC/rootfs (/dev/sda was already used for the laptop's own disk). In this case you would want to flash to /dev/sdb. Your naming can differ!)

Note: Due to the boot order of the PinePhone Pro, there is no need to remove the uboot included with your Mobian Image (eMMC) as it will use the bootloader on the SPI flash first.

Option 3: Mounting the target device's eMMC using JumpDrive

Note: Somewhat obsolete, only do this if you are for some reasons not using tow-boot. You can install the image to eMMC using the latest release of JumpDrive. For additional ways to access the device's eMMC, seethese pine64 wiki instructions.

JumpDrive does not currently work with the PinePhone Pro.

You can either access your device through USB from a laptop and flash from there (recommended) or put the image file on the JumpDrive sdcard, log into the JumpDrive shell (using telnet) and flash from there (more difficult). If using the latter procedure, logging into the JumpDrive shell through telnet, the device should be exposed as /dev/mmcblk0 (for the JumpDrive SD card) or /dev/mmcblk2 (for eMMC, its size should be around 16GB or 32GB).

If using the former (recommended) method of directly accessing your device from a computer, the device will be exposed as /dev/sdX devices. For instance, on my computer it assigned /dev/sdb1 to device'​s eMMC/boot partition, /dev/sdb2 to eMMC/rootfs and /dev/sdc1 to the SD card (JumpDrive itself) (/dev/sda was already used for the laptop's own disk). In this case you would want to flash to /dev/sdb. Your naming can differ!)

These are the steps to follow:

  1. Download the JumpDrive image and flash the JumpDrive image to a micro SD card from your computer. (using dd, a graphical app like Gnome Disks, balena etcher,…). Particularly with 'dd':
    1. Change to directory where the Jumpdrive image is stored, e.g.:
       cd ~/Downloads/ 
    2. Un-mount the SD card (replace X with the correct block, usually b):
       sudo umount /dev/sdX 
    3. Flash the image:
       sudo dd if=$IMAGE of=$BLOCKDEVICE bs=1M status=progress conv=fsync # e.g. for PinePhone sudo dd if=pine64-pinephone.img of=/dev/sdX bs=1M status=progress conv=fsync 
  2. Boot the device from the JumpDrive micro SD card.
  3. Connect the device to your computer using a USB cable.
  4. The sdcard and the eMMC will become available as block devices on your computer (in the form of /dev/sdX block devices).

Flashing the Image to the Target Storage Device

Be careful not to write to the wrong device! Identifying the right flashing target is the most difficult step and should be done with care, as you can easily wipe out the wrong disk by accident. You can also use device names by-id for increased safety, e.g. /dev/disk/by-id/mmc-SU16G_0x1d6654fd.

Method 1: A graphical flashing app

You can use any graphical app to burn/flash/etch the images to your target. For example, a popular app is balenaetcher; another app that comes pre-installed in many Linux distributions is Gnome Disks. In order to flash an image to the eMMC storage device with Gnome Disks:

  1. Launch the app after connecting the device. You should be able to see the eMMC on the left-panel list.
  2. Select the eMMC on that list.
  3. Press the Gear/Menu button (?icon depends on version?) on the top-right.
  4. Select “Restore Image”.
  5. On the menu that appears locate the downloaded Mobian image on your system.
  6. Confirm, and wait for the process to complete.

Method 2a: bmaptool using an URL

For faster flashing, bmaptool is a comfortable means to flash your image (available in Debian as package bmap-tools). It handles sparse files, so it can be considerably faster than plain dd. It also handles both .bmap and .gz files and can download them directly from an URL. Execute

sudo bmaptool copy https://images.mobian-project.org/pinephone/CHANGEME $BLOCKDEVICE

with $BLOCKDEVICE the blockdevice to flash, e.g. /dev/mmcblkX, /dev/sdX [in the case of JumpDrive], or /dev/disk/by-id/XXXXXX).

Example:

sudo bmaptool copy https://images.mobian-project.org/pinephone/weekly/mobian-pinephone-phosh-20211107.img.gz /dev/disk/by-id/mmc-SU16G_0x1d6654fd

Method 2b: bmaptool with a local image file

You can also use bmaptool to flash a local image. As it handles sparse files, it can flash considerably faster than plain dd. Be sure to also download the matching .bmap file for the image (“mobian-<device>-phosh-YYYYMMDD.img.bmap”).

sudo bmaptool copy $IMAGE $BLOCKDEVICE

with $IMAGE, the path to the compressed or uncompressed image file and $BLOCKDEVICE the blockdevice (/dev/mmcblkX or /dev/sdX - if you are using JumpDrive - or /dev/disk/by-id/).

Example:

sudo bmaptool copy mobian-pinephone-phosh-20211107.img.gz /dev/disk/by-id/mmc-SU16G_0x1d6654fd

Method 3: dd

Be very careful not to write to the wrong device! dd has earned the nickname “disk destroyer” for a reason! You can easily wipe out data on the wrong disk by picking the wrong device!

To use dd, you need to unzip the image using one of the following commands:

gunzip mobian-pinephone-phosh-YYYYMMDD.img.gz    
gzip -d mobian-pinephone-phosh-YYYYMMDD.img.gz

Then flash with the following command:

sudo dd bs=1M if=mobian-pinephone-phosh-YYYYMMDD.img of=/dev/TARGETSTORAGEDEVICE status=progress

where TARGETSTORAGEDEVICE is the name of the target storage device (e.g. “mmcblk0” or “sdb”).

Note: (the status= option will display some progress while flashing, as dd is awfully silent otherwise)

Post-installation

JumpDrive

If you flashed the image directly to the device's eMMC with JumpDrive, disconnect the PinePhone from your computer, turn off the device, and remove the JumpDrive SD card. Then, power up the device to boot Mobian from eMMC.

PinePhone Pro Specific

If flashed to the SD card the boot order starts with the internal eMMC, so it may not boot. You will need to either remove U-Boot from the internal eMMC dd if=/dev/zero of=/dev/mmcblk2 seek=64 count=400 conv=fsync or disable it for a single boot by holding the RE button underneath the cover for a few seconds, while powering on the device (holding it too long will cause the eMMC to not get initialized after the boot).