✏[HOWTO] Upgrade FPOOS without overwriting TWRP

1 Preface

This howto describes a method of upgrading an existing Fairphone Open OS (FPOOS) without overwriting a previously manually flashed TWRP recovery partition. This may be useful because as of FPOOS 17.09.3 the manual upgrade package includes an outdated version of TWRP which cannot decrypt and therefore mount an encrypted data partition. This makes backups or other maintenance work from TWRP impossible if your device is encrypted.

:warning: This tutorial involves command line work. If you’re uncomfortable with that, please move on. Additionally, this tutorial may make you brick your Fairphone. If you’re uncomfortable with that either, please move on.

If you want to know how to initially flash your Fairphone with Fairphone Open OS, please read this howto.

If you want to know how to initially flash your Fairphone with TWRP, please visit the official FP2 TWRP page.

2 Doing the upgrade

2.1 Preparations

Download the manual upgrade package from code.fairphone.com. Unzip the file and check its contents:

  • bin-darwin/
  • COPYING.txt
  • fastboot
  • bin-msys/
  • AdbWinApi.dll
  • AdbWinUsbApi.dll
  • apache-2.0.txt
  • COPYING.txt
  • fastboot.exe
  • gpl-2.0.txt
  • libiconv2.dll
  • libintl3.dll
  • libwinpthread-1.dll
  • md5sum.exe
  • images/
  • boot.img
  • emmc_appsboot.mbn
  • NON-HLOS.bin
  • recovery.img
  • rpm.mbn
  • sbl1.mbn
  • SHA256SUMS
  • splash.img
  • system.img
  • tz.mbn
  • flash-for-mac.command
  • flash-for-unix.sh
  • flash-for-windows.bat
  • README.txt

The interesting files are the checksum files images/MD5SUMS and images/SHA256SUMS, the *.img files, and the OS specific scripts flash-for-mac.command, flash-for-unix.sh and flash-for-windows.bat.

2.2 Some modifications

Delete the following file (optionally, but just for being sure…):

  • images/
  • recovery.img

Open the flashing script appropriate to your operating system and delete the following line:

  • In flash-for-mac.command line 166:
    flash_image_or_abort ${sn} recovery "${IMAGES_DIR}/recovery.img"
  • In flash-for-unix.sh line 166:
    flash_image_or_abort ${sn} recovery "${IMAGES_DIR}/recovery.img"
  • In flash-for-windows.bat line 22:
    call :flash_image_or_abort recovery "images\recovery.img"

These modifications alter the checksums of these scipt files which are stored in MD5SUMS and SHA256SUMS and have to be changed there for the flashing scripts to succeed.

  • On macOS issue
    sha256sum flash-for-mac.command && md5sum flash-for-mac.command
  • On Linux/Unix issue
    sha256sum flash-for-unix.sh && md5sum flash-for-unix.sh
  • On Windows issue from bin-msys
    md5sum.exe ..\flash-for-windows.bat

Replace the original checksums in images/SHA256SUMS and images/MD5SUMS with the new ones from the commands above.

The Windows script will only check the MD5 checksum, therefore you can ignore the SHA256 checksum. Both the macOS and the Linux/Unix script will only check the MD5 checksum if the SHA256 checksum generator is not found, therefore you could skip the replacement of the MD5 checksum.

2.3 Flashing

Reboot your phone into fastboot mode. Make sure you have fastboot connection with fastboot devices and execute the appropriate script as described in the manual installation guide. Your recovery partition should be spared from flashing.

3 Postface

Although this method may not be the most comfortable, it still spares you from flashing each image to its appropriate partition and validate data integrity of these images manually.

I hope that this guide will serve you well. If you have any additions or corrections please feel free to edit this wiki post. If you have any feedback please start a new thread and then link it here.