> **Warning**: This application is currently in beta state, so use at your own risk! While many people tested the application so far and we heard of no bricked devices, things might still go wrong.
> **Note**: Unlocking the bootloader will erase all data on your device!
This also includes your DRM keys, which are stored in the Trim Area partition (also called TA) in case your device is fairly recent and supports DRM L1. Those devices will be downgraded to DRM L3. Devices on DRM L3 by default will not be affected.
Before proceeding, ensure the data you would like to retain is backed up to your PC and/or your Google account, or equivalent. Please note that OEM backup solutions like Samsung and Motorola backup may not be accessible from LineageOS once installed.
If you wish to backup the TA partition first, you can find tutorials related to your device on the internet.
> [!WARNING]
> This application is currently in beta state, so use at your own risk! While many people tested the application so far and we heard of no bricked devices, things might still go wrong.
> [!IMPORTANT]
> Unlocking the bootloader will erase all data on your device!
> This also includes your DRM keys, which are stored in the Trim Area partition (also called TA) in case your device is fairly recent and supports DRM L1. Those devices will be downgraded to DRM L3. Devices on DRM L3 by default will not be affected.
> Before proceeding, ensure the data you would like to retain is backed up to your PC and/or your Google account, or equivalent. Please note that OEM backup solutions like Samsung and Motorola backup may not be accessible from LineageOS once installed.
> If you wish to backup the TA partition first, you can find tutorials related to your device on the internet.
## Usage
Linux is currently the best supported platform (tested with Ubuntu 20.04/22.04 LTS). Windows and MacOS are also supported but you might experience more issues. So far there is no support for ARM-based systems.
1. Download the [.exe or appropriate executable file for your OS](https://github.com/openandroidinstaller-dev/openandroidinstaller/releases) from the releases or get the [official flatpak from flathub](https://flathub.org/apps/org.openandroidinstaller.OpenAndroidInstaller). You might need to change permissions to run the executable.
- On Windows also [install the Universal USB Drivers](https://adb.clockworkmod.com/) and other potentially drivers needed for your device.
- On Windows also [install the Universal USB Drivers](https://adb.clockworkmod.com) and other potentially drivers needed for your device.
2. Download the custom ROM image and the TWRP recovery image for your device and optionally some addons. A source for files can be found on the following websites:
- some custom ROMs:
-[LineageOS](https://wiki.lineageos.org/devices)
...
...
@@ -82,11 +83,12 @@ Samsung | Galaxy Grand Prime VE | grandprimevelte | SM-G531F | tested
Samsung | Galaxy S III Neo | s3ve3g | GT-I9301I | tested
Currently development is only supported on Ubuntu Linux. MacOS and Windows should also work fine. You might need to install additional USB-drivers on Windows.
1. Clone the main branch of this repository
2. Run `make poetry` and `make install` to install poetry to manage python and install the required dependencies like adb, fastboot and heimdall.
3. Run `make app` to start the desktop app from the source.
## Contributing
All kinds of contributions are welcome. These include:
...
...
@@ -199,62 +195,17 @@ All kinds of contributions are welcome. These include:
- Add features and/or improve the code base.
- Report bugs.
More details on how to contribute can be found [here](https://github.com/openandroidinstaller-dev/openandroidinstaller/blob/main/CONTRIBUTING.md).
Please have a look before opening an issue or starting to contribute.
A detailed list can be found [here](https://openandroidinstaller.org/#contribute).
### How to contribute your own installation configurations
If you want to use the tool for a non-supported smartphone, the fastest way is to adapt an [existing config file](https://github.com/openandroidinstaller-dev/openandroidinstaller/tree/main/openandroidinstaller/assets/configs). The file should be named after the official `device code` of the device. Add the code output by `adb shell getprop | grep ro.product.device` (when the devices is connected to the computer) as well as the official device code to the `supported_device_codes` list in the config. You can also get the device code by connecting the device to the computer and run OpenAndroidInstaller to detect the device.
[How to contribute your own installation configurations](https://github.com/openandroidinstaller-dev/openandroidinstaller/blob/main/docs/how_to_contribute_your_own_installation_configurations.md)
**To test your config file with the executable** without using the developer setup, place it in the same directory as the executable. There it will be detected by name. After you created a config file and it works fine, you can open a pull request to make the file available to other users. Please also add the device to the supported devices table above.
[How to build the application for your platform](https://github.com/openandroidinstaller-dev/openandroidinstaller/blob/main/docs/building_the_application_for_your_platform.md)
#### Content of a config file
[On unlocking the bootloader](https://github.com/openandroidinstaller-dev/openandroidinstaller/blob/main/docs/unlocking_the_bootloader.md)
A config file consists of two parts. The first part are some metadata about the device and the second parts are the steps to unlock the bootloader, boot a recovery and install the ROMs.
##### How to write Metadata
Every config file should have `metadata` with the following fields:
-`maintainer`: str; Maintainer and author of the config file.
-`device_name`: str; Name of the device.
-`is_ab_device`: bool; A boolean to determine if the device is a/b-partitioned or not.
-`device_code`: str; The official device code.
-`supported_device_codes`: List[str]; A list of supported device codes for the config. The config will be loaded based on this field.
-`twrp-link`: [OPTIONAL] str; name of the corresponding twrp page.
In addition to these metadata, every config can have optional `requirements`. If these are set, the user is asked to check if they are meet.
-`android`: [OPTIONAL] int|str; Android version to install prior to installing a custom ROM.
-`firmware`: [OPTIONAL] str; specific firmware version to install before installing a custom ROM.
##### How to write steps:
Every step in the config file corresponds to one view in the application. These steps should contain the following fields:
-`type`: str; Corresponds to the type of view to generate. There are the following options:
-`text`: Just display the text given in content.
-`confirm_button`: Display the content, as well as a button to allow the user to go to the next step.
-`call_button`: Display the content text and a button that runs a given command. After the command is run, a confirm button is displayed to allow the user to move to the next step.
-`call_button_with_input`: Display the content text, an input field and a button that runs a given command. The inputtext, can be used in the command by using the `<inputtext>` placeholder in the command field. After the command is run, a confirm button is displayed to allow the user to move to the next step.
-`link_button_with_confirm`: Display a button that opens a browser with a given link, confirm afterwards. Link is given in `link`.
-`img`: [OPTIONAL] Display an image on the left pane of the step view. Images are loaded from `openandroidinstaller/assets/imgs/`.
-`content`: str; The content text displayed alongside the action of the step. Used to inform the user about what's going on. For consistency and better readability the text should be moved into the next line using `>`.
-`link`: [OPTIONAL] Link to use for the link button if type is `link_button_with_confirm`.
-`command`: [ONLY for call_button* steps] str; The command to run. One of `adb_reboot`, `adb_reboot_bootloader`, `adb_reboot_download`, `adb_sideload`, `adb_twrp_wipe_and_install`, `adb_twrp_copy_partitions`, `fastboot_boot_recovery`, `fastboot_unlock_with_code`, `fastboot_unlock`, `fastboot_oem_unlock`, `fastboot_get_unlock_data`, `fastboot_reboot`, `heimdall_flash_recovery`.
-`allow_skip`: [OPTIONAL] boolean; If a skip button should be displayed to allow skipping this step. Can be useful when the bootloader is already unlocked.
**Please try to retain this order of these fields in your config to ensure consistency.**
## How to build the application for your platform
The executables for the OpenAndroidInstaller are build with [pyinstaller](https://pyinstaller.org/en/stable/index.html). You can create builds for MacOS or Linux with `make build-app`. For Windows the paths need to be modified. For now, you can have a look [here](https://github.com/openandroidinstaller-dev/openandroidinstaller/blob/v0.1.2-alpha/.github/workflows/manual-build-windows.yml#L22) on how it's done.
If you build the application for your platform and want to contribute the build, please reach out to me.
#### On unlocking the bootloader
Devices by *Samsung*, *Google* and *Fairphone* make it fairly easy to unlock the bootloader and receive good support in the installer.
More details on how to contribute can be found [here](https://github.com/openandroidinstaller-dev/openandroidinstaller/blob/main/CONTRIBUTING.md).
Please have a look before opening an issue or starting to contribute.
Some devices with require manual steps to unlock the bootloader. In general you will need to create an account at a vendor website and receive some code from there. OpenAndroidInstaller will try to guide you as far as possible. These vendors include *Sony, Motorola, Xiaomi* and *OnePlus* among others.
A detailed list can be found [here](https://openandroidinstaller.org/#contribute).
Other phone vendors stops allowing to unlock the bootloader all together. There is nothing to be done if you didn't unlock your device in time. These vendors include *Huawei and LG* among others. Support for these vendors will always be very limited.
The executables for the OpenAndroidInstaller are build with [pyinstaller](https://pyinstaller.org/en/stable/index.html). You can create builds for MacOS or Linux with `make build-app`. For Windows the paths need to be modified. For now, you can have a look [here](https://github.com/openandroidinstaller-dev/openandroidinstaller/blob/v0.1.2-alpha/.github/workflows/manual-build-windows.yml#L22) on how it's done.
If you build the application for your platform and want to contribute the build, please reach out to me.
## Run OpenAndroidInstaller for development
Currently development is only supported on Ubuntu Linux. MacOS and Windows should also work fine. You might need to install additional USB-drivers on Windows.
1. Clone the main branch of this repository
2. Run `make poetry` and `make install` to install poetry to manage python and install the required dependencies like adb, fastboot and heimdall.
3. Run `make app` to start the desktop app from the source.
### How to contribute your own installation configurations
If you want to use the tool for a non-supported smartphone, the fastest way is to adapt an [existing config file](https://github.com/openandroidinstaller-dev/openandroidinstaller/tree/main/openandroidinstaller/assets/configs). The file should be named after the official `device code` of the device. Add the code output by `adb shell getprop | grep ro.product.device` (when the devices is connected to the computer) as well as the official device code to the `supported_device_codes` list in the config. You can also get the device code by connecting the device to the computer and run OpenAndroidInstaller to detect the device.
**To test your config file with the executable** without using the developer setup, place it in the same directory as the executable. There it will be detected by name. After you created a config file and it works fine, you can open a pull request to make the file available to other users. Please also add the device to the supported devices table above.
#### Content of a config file
A config file consists of two parts. The first part are some metadata about the device and the second parts are the steps to unlock the bootloader, boot a recovery and install the ROMs.
##### How to write Metadata
Every config file should have `metadata` with the following fields:
-`maintainer`: str; Maintainer and author of the config file.
-`device_name`: str; Name of the device.
-`brand`: [OPTIONAL] str; Name of the brand. Can be used to make brand specific actions.
-`is_ab_device`: bool; A boolean to determine if the device is a/b-partitioned or not.
-`device_code`: str; The official device code.
-`supported_device_codes`: List[str]; A list of supported device codes for the config. The config will be loaded based on this field.
-`twrp-link`: [OPTIONAL] str; name of the corresponding twrp page.
-`additional_steps` : [OPTIONAL] List[str]; A list of additional steps. Can be `dtbo`, `vbmeta`, `vendor_boot` or `super_empty`.
-`notes`: [OPTIONAL] List[str]; specific phone information, showed before choosing ROM / recovery
-`untested`: [OPTIONAL] bool; If `true`, a warning message is showed during installation process.
In addition to these metadata, every config can have optional `requirements`. If these are set, the user is asked to check if they are meet.
-`android`: [OPTIONAL] int|str; Android version to install prior to installing a custom ROM.
-`firmware`: [OPTIONAL] str; specific firmware version to install before installing a custom ROM.
##### How to write steps:
Every step in the config file corresponds to one view in the application. These steps should contain the following fields:
-`type`: str; Corresponds to the type of view to generate. There are the following options:
-`text`: Just display the text given in content.
-`confirm_button`: Display the content, as well as a button to allow the user to go to the next step.
-`call_button`: Display the content text and a button that runs a given command. After the command is run, a confirm button is displayed to allow the user to move to the next step.
-`call_button_with_input`: Display the content text, an input field and a button that runs a given command. The inputtext, can be used in the command by using the `<inputtext>` placeholder in the command field. After the command is run, a confirm button is displayed to allow the user to move to the next step.
-`link_button_with_confirm`: Display a button that opens a browser with a given link, confirm afterwards. Link is given in `link`.
-`img`: [OPTIONAL] Display an image on the left pane of the step view. Images are loaded from `openandroidinstaller/assets/imgs/`.
-`content`: str; The content text displayed alongside the action of the step. Used to inform the user about what's going on. For consistency and better readability the text should be moved into the next line using `>`.
-`link`: [OPTIONAL] Link to use for the link button if type is `link_button_with_confirm`.
-`command`: [ONLY for call_button* steps] str; The command to run. One of `adb_reboot`, `adb_reboot_bootloader`, `adb_reboot_download`, `adb_sideload`, `adb_twrp_wipe_and_install`, `adb_twrp_copy_partitions`, `fastboot_boot_recovery`, `fastboot_flash_recovery`, `fastboot_reboot_recovery`, `fastboot_flash_additional_partitions`, `fastboot_unlock_with_code`, `fastboot_unlock`, `fastboot_unlock_critical`, `fastboot_oem_unlock`, `fastboot_get_unlock_data`, `fastboot_reboot`, `heimdall_flash_recovery`.
-`allow_skip`: [OPTIONAL] boolean; If a skip button should be displayed to allow skipping this step. Can be useful when the bootloader is already unlocked.
**Please try to retain this order of these fields in your config to ensure consistency.**
First of all, this tool will not help you bypass any vender locked bootloaders in non-official ways.
Devices by *Samsung, Google, OnePlus, Fairphone* and others make it relatively easy to unlock the bootloader and get good support in the installer.
For some devices, it is necessary to unlock the bootloader manually. You usually need to create an account on the manufacturer's website, wait for a certain time and obtain a code from there. OpenAndroidInstaller will try to guide you as far as possible. These vendors include *Sony, Motorola and Xiaomi* amongst others.
Other phone manufacturers no longer allow you to unlock the bootloader. Nothing can be done if you have not unlocked your device in time. These manufacturers include *Huawei, Honor, LG and ASUS*. Support for these manufacturers will always be very limited.
<details>
<summary>
<b>Here is a brief overview of the bootloader policies of some of the most popular brands (may be incomplete/inaccurate)</b>
</summary>
| Brand | Flashing tool | Unlocking Method | Loss of guarantee\* | Supported models |
|---|---|---|---|---|
| Google | Fastboot | OEM/Flashing unlock | No | Pixel and Nexus |
| Samsung | ODIN or Heimdall | Download mode | **Yes** | Galaxy S and A series<br>(Increasing complexity **on and after S10**) |
| OnePlus | Fastboot | OEM/Flashing unlock | No | All |
| Fairphone | Fastboot | [Code from manufacturer](https://support.fairphone.com/hc/en-us/articles/10492476238865-Manage-the-Bootloader)<br>(**Already unlocked until FP2**) | No | All |
| Xiaomi | Fastboot | [Mi Unlock Tool](https://new.c.mi.com/global/post/101245) | **Yes** | Mi 4c, Redmi Note 3, Mi Note Pro, Redmi 3, Mi 4S, Mi 5 and all devices from 2016 onwards |
| Motorola | Fastboot | [Code from manufacturer](https://en-us.support.motorola.com/app/standalone/bootloader/unlock-your-device-a) | **Yes** | Almost all **except** carrier specific models (e.g. Verizon, AT&T, Tracfone) and certain other models |
| Sony | Fastboot | [Code from manufacturer](https://developer.sony.com/open-source/aosp-on-xperia-open-devices/get-started/unlock-bootloader) | **Yes** | All **except** XQ-CT62 (1Ⅳ US) & XQ-CQ62 (5Ⅳ US) |
| Huawei | Fastboot | No official codes since 2017/2018<br>(**Unofficial methods available**) | **Yes** | Mate 9/9Pro, P10/P10Plus |
| Honor | Fastboot | No official codes since 2017/2018<br>(**Unofficial methods available**) | **Yes** | Honor 8 |
| LG | Fastboot | Impossible since December 2021 | **Yes** | |
| ASUS | Fastboot | Impossible since May 2023 (ASUS unlocking App) | **Yes** | |
**\*** In the EU you won't loose your standard 2 years of the warranty when you unlock your bootloader, flash your device or root it. ([source](https://forum.xda-developers.com/t/info-eu-rooting-and-flashing-dont-void-the-warranty.1998801/))
</details>
<br>
You can find more information about the brands and their bootloader policies [here](https://wikilibriste.fr/fr/tutoriels-android/bootloader-unlock)(in French).
content="If you already flashed TWRP, boot into it by pressing 'Confirm and run'. Otherwise restart the process. Once your phone screen looks like the picture on the left, continue.",
content="If you already flashed TWRP, boot into it by pressing 'Confirm and run'. Otherwise restart the process. Once your phone screen looks like the picture on the left, continue.",
-Be careful when choosing OrangeFox version, Android 12 & 13 ROM needs OrangeFox version code with `A12`, for example `R11.1_5_A12`. Android 10 & 11 ROM needs OrangeFox version code without `A12` (bellow on the page)
requirements:
firmware:MiUI 12.5 (Q)
steps:
unlock_bootloader:
-type:confirm_button
content:>
As a first step, you need to unlock the bootloader. A bootloader is the piece of software, that tells your phone
how to start and run an operating system (like Android). Your device should be turned on. This will reset your phone.
-type:link_button_with_confirm
content:>
- Create a Mi account on Xiaomi’s website. Beware that one account is only allowed to unlock one unique device every 30 days.
- Add a phone number to your Mi account, insert a SIM into your phone.
- Enable developer options in `Settings` > `About Phone` by repeatedly tapping MIUI Version.
- Link the device to your Mi account in `Settings` > `Additional settings` > `Developer options` > `Mi Unlock status`.
- Download the Mi Unlock app with the link bellow (Windows is required to run the app), and follow the instructions provided by the app. It may tell you that you have to wait, usually 7 days. If it does so, please wait the quoted amount of time before continuing to the next step!
- After device and Mi account are successfully verified, the bootloader should be unlocked.
- Since the device resets completely, you will need to re-enable USB debugging to continue : `Settings` > `Additional settings` > `Developer options` > `USB debugging`
link:https://en.miui.com/unlock/download_en.html
boot_recovery:
-type:call_button
content:>
Now you need to install a custom recovery system on the phone. A recovery is a small subsystem on your phone,
that manages updating, adapting and repairing of the operating system.
Once the device is fully booted, you need to reboot into the bootloader again by pressing 'Confirm and run' here. Then continue.
command:adb_reboot_bootloader
-type:call_button
content:>
Install additional partitions selected before by pressing 'Confirm and run'. Once it's done continue.
Note : If you have not selected this partition, it will do nothing.
command:fastboot_flash_additional_partitions
-type:call_button
content:>
Install the recovery you chosen before by pressing 'Confirm and run'. Once it's done continue.
command:fastboot_flash_recovery
-type:call_button
img:ofox.png
content:>
Reboot to recovery by pressing 'Confirm and run', and hold the Vol+ button of your phone UNTIL you see the recovery.
If MiUI starts, you have to start the process again, since MiUI delete the recovery you just flashed.
As a first step, you need to unlock the bootloader. A bootloader is the piece of software, that tells your phone
how to start and run an operating system (like Android). Your device should be turned on. This will reset your phone.
-type:link_button_with_confirm
content:>
- Create a Mi account on Xiaomi’s website. Beware that one account is only allowed to unlock one unique device every 30 days.
- Add a phone number to your Mi account, insert a SIM into your phone.
- Enable developer options in `Settings` > `About Phone` by repeatedly tapping MIUI Version.
- Link the device to your Mi account in `Settings` > `Additional settings` > `Developer options` > `Mi Unlock status`.
- Download the Mi Unlock app with the link bellow (Windows is required to run the app), and follow the instructions provided by the app. It may tell you that you have to wait, usually 7 days. If it does so, please wait the quoted amount of time before continuing to the next step!
- After device and Mi account are successfully verified, the bootloader should be unlocked.
- Since the device resets completely, you will need to re-enable USB debugging to continue : `Settings` > `Additional settings` > `Developer options` > `USB debugging`
link:https://en.miui.com/unlock/download_en.html
boot_recovery:
-type:confirm_button
content:>
Now you need to boot a custom recovery system on the phone. A recovery is a small subsystem on your phone, that manages updating,
adapting and repairing of the operating system.
-type:call_button
content:>
Once the device is fully booted, you need to reboot into the bootloader again by pressing 'Confirm and run' here. Then continue.
command:adb_reboot_bootloader
-type:call_button
content:>
Install the recovery you chosen before by pressing 'Confirm and run'. Once it's done continue.
command:fastboot_flash_recovery
-type:call_button
img:ofox.png
content:>
Reboot to recovery by pressing 'Confirm and run', and hold the Vol+ button of your phone UNTIL you see the recovery.
If MiUI starts, you have to start the process again, since MiUI delete the recovery you just flashed.
