Skip to content

Commit

Permalink
Merge branch 'main' into dev
Browse files Browse the repository at this point in the history
  • Loading branch information
@tsterbak
tsterbak committed Aug 6, 2023
2 parents 18faaf6 + 8f3ac85 commit 439eec1
Show file tree
Hide file tree
Showing 8 changed files with 78 additions and 70 deletions.
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/bug_report.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: Bug report
about: Create a report to help us improve
title: ''
labels: ''
labels: 'bug'
assignees: ''

---
Expand Down
18 changes: 10 additions & 8 deletions .github/ISSUE_TEMPLATE/device-support-request.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,22 @@
name: Device support request
about: Request support for a new device
title: ''
labels: ''
labels: 'device'
assignees: ''

---

**Device name**
Please enter the name of the device you would like to request support for.
If you know the device code, please also add it here.
**Device informations**
- Brand:
- Phone name:
- Device code (if unknown, leave blank):
- Model (if several models exist):

**Device images**
Please provide links to any available images of the device, such as official stock firmware or custom ROMs you would like to install.
**Device images**
Please provide links to any available images of the device, such as official stock firmware or custom ROMs you would like to install.

**Do you own the device and would be willing to test the installer?**
- [ ]

**Additional context**
Please provide any additional context or information that may be helpful in adding support for this device.
**Additional context**
Please provide any additional context or information that may be helpful in adding support for this device.
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/feature-request.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: Feature request
about: Suggest an idea for this project
title: ''
labels: ''
labels: 'enhancement'
assignees: ''

---
Expand Down
65 changes: 6 additions & 59 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -172,15 +172,6 @@ OnePlus | 9 | lemonade | | under development
And more to come!


## 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.


## Contributing

All kinds of contributions are welcome. These include:
Expand All @@ -192,62 +183,18 @@ 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/doc/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/doc/building_the_application_for_your_platform.md)

#### Content of a config file
[On unlocking the bootloader](https://github.com/openandroidinstaller-dev/openandroidinstaller/blob/main/doc/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.
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.

#### 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.
A detailed list can be found [here](https://openandroidinstaller.org/#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.

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.

## Tools

Expand Down
14 changes: 14 additions & 0 deletions doc/building_the_application_for_your_platform.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
## 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.

## 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.

39 changes: 39 additions & 0 deletions doc/how_to_contribute_your_own_installation_configurations.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
### 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.
- `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.**

6 changes: 6 additions & 0 deletions doc/unlocking_the_bootloader.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
#### 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.

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.

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.
2 changes: 1 addition & 1 deletion openandroidinstaller/installer_config.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ def validate_config(config: str) -> bool:
),
"content": str,
schema.Optional("command"): Regex(
r"adb_reboot|adb_reboot_bootloader|adb_reboot_download|adb_sideload|adb_twrp_wipe_and_install|adb_twrp_copy_partitions|fastboot_boot_recovery|fastboot_flash_boot|fastboot_unlock|fastboot_unlock_critical|fastboot_unlock_with_code|fastboot_get_unlock_data|fastboot_unlock|fastboot_oem_unlock|fastboot_reboot|heimdall_flash_recovery"
r"adb_reboot|adb_reboot_bootloader|adb_reboot_download|adb_sideload|adb_twrp_wipe_and_install|adb_twrp_copy_partitions|fastboot_boot_recovery|fastboot_flash_boot|fastboot_unlock_critical|fastboot_unlock_with_code|fastboot_get_unlock_data|fastboot_unlock|fastboot_oem_unlock|fastboot_reboot|heimdall_flash_recovery"
),
schema.Optional("allow_skip"): bool,
schema.Optional("img"): str,
Expand Down

0 comments on commit 439eec1

Please sign in to comment.