postmarketOS preparation guide for oneplus 6

PLEASE NOTE: THIS IS A WORK IN PROGRESS AND BEING ITERATIVELY UPDATED AS I LEARN MORE ON HOW POSTMARKETOS CAN BE INSTALLED AND HANGS TOGETHER WITH THE TOOLING AND PARTITIONS FOR DUAL BOOTING ON ONEPLUS6 (22 MAY 2023)

I am writing this tutorial up as someone who is comfortable in Linux, but too old to have been playing with jailbreaking phones in the last couple of decades. To that end, being a little uncomfortable with the tooling around jailbreaking (and assuming others might be too), I decided to focus a tutorial on the preliminary process before handing over to the postmarketOS wiki for the excellent documentation they have.

This post covers areas where I had problems or questions that you may also have along the process of getting a working oneplus6 phone in phosh or gnome-mobile-shell

Decision - do I install phosh or gnome-shell on mobile?
- Start with phosh
Do I allow dual boot with Android (128GB storage, 8GB ram device) - currently defaulting to 'yes for dual boot'
- My understanding is that this will allow recovery to happen more easily
- research what this means from a trade-offs perspective

Gnome shell related

https://gitlab.com/postmarketOS/pmaports/-/merge_requests/3404

Preparing your computer for the process

1. Install the following packages (the below list are specific pkg names for nixos - your package names might be different if you are not using the nix package manager or NixOS)

android-tools # this will include fastboot and adb utilities
pmbootstrap # this is the postmarketOS utility for bootstrapping installs to your device using your computer and a usb cable
xz # compression tool for unzipping images used by postmarketOS      
python311Packages.adb-homeassistant # this seems to be a newer implementation of adb
element-desktop # client for matrix. Good for support on postmarketOS
e2fsprogs # `resize2fs` command if we need to resize a partition of the image

Preparing your Oneplus 6 device

If you are like me, you have bought this phone specificically for this experiment. I expect the device will arrive to you with the factory reset which takes it down to Android 9.

Pre-requisite 1. Update your Oneplus 6 to the latest version of Oxygen/Android

I had assumed the normally update process in Android OS would allow me to eventually have everything upgraded, this isn't the case. It will just respond that it is the latest version. By googling, you will think the next best action is to do a 'local update' after downloading the latest image. This is also not the right approach. We need to incrementally do some updates to give it a good upgrade path through to the latest version of Oxygen/Android that Oneplus 6 supports.

To do this we use a community built app called oxygen updater

2. Install oxygen updater on to your device
3. Go through a series of downloads via the installed app, then system update using the local install option

Just follow through the oxygen updater directions to make a series of image downloads and 'local updates' It is work mentioning that being community led, a small donation is always appreciated for projects like this

For me this took 3 image downloads and local updates and took the OygenOS system to 11.1.2.2. With the Oneplus 6 now end of life for support updates, I suspect this is as far it will ever go for updates.
Make sure you let the device do it's reboot to finish off the install process on each install cycle

Pre-requisite 2: Backup your device

4. Enable Developer Options: Go to "Settings" on your OnePlus 6 and scroll down to "About phone." Tap on it and find the "Build number" entry. Tap on it repeatedly (around 7 times) until you see a message saying, "You are now a developer."
5. Enable USB Debugging: Now, go back to the main "Settings" menu and scroll down to find "Developer options." Tap on it, and within the developer options, enable "USB debugging." This will allow your device to communicate with your computer.
6. Unlock the Bootloader: Unlocking the bootloader is necessary to install a custom recovery. However, note that unlocking the bootloader will wipe all data on your device. Proceed with caution and ensure that you have backed up all your important data.

By default, the OxygenOS firmware on your OnePlus 6 already includes the necessary bootloader drivers and supports fastboot commands. You don't need to separately install fastboot on your phone. The fastboot commands are executed on your computer while your phone is in fastboot mode, allowing you to interact with the bootloader.

Remember to exercise caution when using fastboot commands, as they can modify critical system components and potentially void your device's warranty if used incorrectly. It's important to carefully follow instructions and backup your data before proceeding with any modifications.

Pre-requisite 3: Backup for device

At this stage, let's be a little paranoid and create full backup images of our device.

There are a number of ways to create image backups of your OnePlus 6 device once it has the latest OxygenOS build installed. Here are two common approaches:

TWRP Recovery (Custom Recovery)
TODO: TWRP cannot restore from adb created backups. Therefore, I should have both backup types (storage is cheap)
- install TWRP
- create a TWRP backup
ADB (Android Debug Bridge): Another method to create an image backup is by using the ADB command-line tool on your computer.

I am personally more comfortable with the linux terminals than I am with tooling around twrp tools. I decided to use the second approach. Some notes are at the end of this post on TWRP if you decide to use that approach.

Keep in mind that both methods will create a complete backup of your device, including apps, system settings, and user data. These backups can be restored in case of any issues or when you want to revert to a previous state. Make sure to store the backup files in a safe location to avoid accidental loss.

ADB (Android Debug Bridge): create an image backup is by using the ADB command-line tool on your computer. Follow these steps:

Overview of what we will do

Make sure ADB is properly set up on your computer. You can verify this by running the command adb devices in the command prompt. If your device is listed, you're ready to proceed.

Run the following command to create a backup of your device: adb backup -apk -shared -all -f backup.ab. This command will create a backup file called "backup.ab" containing the apps, shared storage, and all other data.

On your device's screen, you will be prompted to confirm the backup. Unlock your device and follow the on-screen instructions to grant backup permissions.

Wait for the backup process to complete. The backup file will be saved in the directory where the command prompt or terminal is currently located.

7. Connect your OnePlus 6 to your computer using a USB cable.
8. Open a shell on your computer.
9. and run adb devices

If you have this no permissions problem show as below do the following

stuart@T14:~/adb-backups-device/onePlus6-v11.1.2.2/ > adb devices
* daemon not running; starting now at tcp:5037
* daemon started successfully
List of devices attached
d539f102	no permissions; see [http://developer.android.com/tools/device.html]

10. sudo adb kill-server
11. sudo adb start-server

stuart@T14:~/adb-backups-device/onePlus6-v11.1.2.2/ > sudo adb kill-server

stuart@T14:~/adb-backups-device/onePlus6-v11.1.2.2/ > sudo adb start-server

* daemon not running; starting now at tcp:5037
* daemon started successfully
stuart@T14:~/adb-backups-device/onePlus6-v11.1.2.2/ > adb devices
List of devices attached
d539f102	device

12. adb backup -apk -shared -all -f backup.ab

stuart@T14:~/adb-backups-device/onePlus6-v11.1.2.2/ > adb backup -apk -shared -all -f backup.ab
WARNING: adb backup is deprecated and may be removed in a future release
Now unlock your device and confirm the backup operation...
stuart@T14:~/adb-backups-device/onePlus6-v11.1.2.2/ > ls -alh         
total 120M
drwxr-xr-x 2 stuart users 4.0K May 21 12:11 .
drwxr-xr-x 3 stuart users 4.0K May 21 11:55 ..
-rw-r----- 1 stuart users 120M May 21 12:12 backup.ab

Pre-requisite 4. OEM unlock your phone

13. Boot your phone into fastmode
14. Run from your computer sudo fastboot oem unlock and follow the on screen instructions to OEM unlock your phone

Note: Once you have done this you will have to do these steps again

15. Enable Developer Options: Go to "Settings" on your OnePlus 6 and scroll down to "About phone." Tap on it and find the "Build number" entry. Tap on it repeatedly (around 7 times) until you see a message saying, "You are now a developer."
16. Enable USB Debugging: Now, go back to the main "Settings" menu and scroll down to find "Developer options." Tap on it, and within the developer options, enable "USB debugging." This will allow your device to communicate with your computer.
17. Not needed, but I like to go the Display setting and have the sleep set to 30 minutes

Pre-requisites are now completed

Now the pre-requisites are completed we can download images we want to use for the install that will orchestrated by the pmbootstrap utility

Postmarketos install

There are two parts to the install process. You have to

18. Install the postmarketOS pmbootstrap utility on to your linux machine; and then go through the process of using the tool to download the images and install using the pmbootstrap tool
19. Download the images for the Desktop environment/environment you want to use. From this point on you are best to follow the [instructions from the postmarketOS wiki for the Oneplust6](https://wiki.postmarketOS.org/wiki/OnePlus_6_(oneplus-enchilada)
20. Once downloaded, decompress the files with unxz.

> xz -d 20230517-0303-postmarketOS-edge-gnome-mobile-1-oneplus-enchilada.img.xz 
> xz -d 20230517-0303-postmarketOS-edge-gnome-mobile-1-oneplus-enchilada-boot.img.xz 
> ls
20230517-0303-postmarketOS-edge-gnome-mobile-1-oneplus-enchilada-boot.img
20230517-0303-postmarketOS-edge-gnome-mobile-1-oneplus-enchilada.img

Get you image ready

Decide whether to dualboot

For this area I am not sure what is best at this stage. I am going to have to do some trial-and-error

I decided to go for dual boot with Android. Therefore, I need to change my simultaneously It might be worth noting that fastboot did not work for me this time - until I did a reboot of my computer You can also see that I needed to use sudo to have it recognise the device

Usbility Notes

Once you have a working dual boot phone. You can install apps on the Android while the postmarketOS side has qbootctl to switch between OSes (setting slot A or slot B active)
It is also possible to switch by using a computer and usb connected phone with sudo fastboot set_active a or sudo fastboot set_active b
Anecdotally someone on the forum noted they had dual boot working with about 50GB used of the circa 128GB available

# check what slot is currently used
stuart@T14:~/ > sudo fastboot getvar current-slot
Place your right index finger on the fingerprint reader
current-slot: a
Finished. Total time: 0.002s
stuart@T14:~/ > sudo fastboot set_active b       
Setting current slot to 'b'                        OKAY [  0.033s]
Finished. Total time: 0.034s
stuart@T14:~/ > sudo fastboot getvar current-slot
current-slot: b
Finished. Total time: 0.002s

pmbootstrap install --split && pmbootstrap export

flash to userdata (root) and vendor (boot)

sudo was required for me

sudo fastboot flash userdata /tmp/postmarketOS-export/oneplus-enchilada-root.img
sudo fastboot flash vendor /tmp/postmarketOS-export/oneplus-enchilada-boot.img

#####################################

TODO: All TBD from here!!!!