TWRP-device-porting

KO | EN

gitlite — search

#react #ai #typescript #llm #golang #machine-learning #linux #macos #java #kubernetes #vue #ios #mcp #openai

TWRP-device-porting

(★ 9)

A guide on how to port TWRP recovery to any device

TWRP-device-porting Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Porting TWRP Recovery to Any Device Using Kernel Source

## Table of Contents
1. [Introduction](#introduction)  
2. [Prerequisites](#prerequisites)  
3. [Setting Up the Environment](#setting-up-the-environment)  
4. [Downloading and Preparing the Kernel Source](#downloading-and-preparing-the-kernel-source)  
5. [Extracting Recovery Files](#extracting-recovery-files)  
6. [Building the TWRP Recovery Image](#building-the-twrp-recovery-image)  
7. [Testing the TWRP Recovery](#testing-the-twrp-recovery)  
8. [Debugging and Troubleshooting](#debugging-and-troubleshooting)  
9. [Submitting Your Build](#submitting-your-build)  
10. [Additional Resources](#additional-resources)  
11. [Windows / WSL2 Setup](#️-windows--wsl2-setup)

---

## 📖 Introduction
This guide provides a detailed walkthrough on how to port **Team Win Recovery Project (TWRP)** to any Android device using the device’s kernel source.

TWRP is a feature-rich custom recovery that allows:  
- Flashing custom ROMs, kernels, and mods.  
- Backing up and restoring partitions.  
- File management, sideloading, and ADB access.

Learning this process helps unlock the full potential of your Android device.

> 💡 **Windows Users:** You don’t need to switch to Linux!  
> You can use **WSL2 (Windows Subsystem for Linux 2)** or a VM to follow this guide.  
> [Click here to jump to the WSL2 setup guide](#️-windows--wsl2-setup).

---

## ✅ Prerequisites

### Basic Knowledge
- Linux command-line usage.  
- Android recovery/boot image structure.  
- Basics of kernel compilation and troubleshooting.

### Hardware Requirements
- PC with at least **8GB RAM** (16GB+ recommended).  
- **50GB+ free storage**.

### Software Requirements
- **Operating System:** Ubuntu 20.04+ (or equivalent Linux distro).  
- **Essential tools:**  
  - [Android SDK Platform Tools](https://developer.android.com/studio/releases/platform-tools) (adb + fastboot).  
  - [Repo Tool](https://source.android.com/docs/setup/download).  
  - Build packages (install with):  
    ```bash
    sudo apt update
    sudo apt install build-essential git ccache python3 python3-pip openjdk-8-jdk adb fastboot wget curl unzip
    ```
  - Java Development Kit (**JDK 8** or **JDK 11**).  
  - Python 3.

### Device-Specific Requirements
- **Kernel source** from manufacturer open-source portals:  
  - Samsung: [opensource.samsung.com](https://opensource.samsung.com)  
  - Xiaomi: [github.com/MiCode](https://github.com/MiCode)  
  - OnePlus: [github.com/OnePlusOSS](https://github.com/OnePlusOSS)  
  - Motorola: [motorola.github.io](https://motorola.github.io/)  
  - Sony: [developer.sony.com](https://developer.sony.com/develop/open-devices/)  
  - Asus: [asus.com/zentalk](https://zentalk.asus.com/en/categories/developer-corner)  
  - Realme/OPPO: [github.com/realme-kernel-opensource](https://github.com/realme-kernel-opensource)

- **Stock firmware** (to extract recovery.img and proprietary blobs).  
- Recovery partition size (important so your build doesn’t exceed it).

---

## 🖥️ Setting Up the Environment

### 1. Install Packages
```bash
sudo apt update
sudo apt install git wget curl unzip tar build-essential gcc g++ ccache python3 python3-pip openjdk-8-jdk adb fastboot
```

### 2. Configure Git
```bash
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```

### 3. Set Up Repo Tool
```bash
mkdir ~/bin
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo
export PATH=~/bin:$PATH
```
*(Add the PATH line to `~/.bashrc` or `~/.zshrc` for persistence.)*

---

## 📥 Downloading and Preparing the Kernel Source

1. Download the correct kernel source for your firmware version.  
2. Clone it:
   ```bash
   git clone <kernel-source-url> kernel_source
   cd kernel_source
   ```
3. Ensure compatibility with your SoC/arch (ARMv7/ARM64, Snapdragon, MediaTek).  
4. Apply TWRP-specific patches if available:  
   ```bash
   git am <patch-file.patch>
   ```

---

## 📂 Extracting Recovery Files

1. **Download stock firmware** from:  
   - [Firmware.mobi](https://www.firmware.mobi/)  
   - [SamMobile](https://www.sammobile.com/firmwares/)  
   - [Xiaomi Firmware Updater](https://xiaomifirmwareupdater.com/)

2. **Extract firmware:**
   ```bash
   mkdir stock_firmware
   unzip firmware.zip -d stock_firmware
   ```

3. **Extract recovery.img** from the package.

4. **Unpack recovery.img** with [Android Image Kitchen](https://github.com/osm0sis/Android-Image-Kitchen):  
   ```bash
   ./unpackimg.sh recovery.img
   ```
   - Check `ramdisk/` for fstab files, init scripts, and configs.

---

## 🛠️ Building the TWRP Recovery Image

### 1. Download TWRP Source
```bash
mkdir ~/twrp
cd ~/twrp
repo init -u https://github.com/minimal-manifest-twrp/platform_manifest_twrp_aosp.git -b twrp-12.1
repo sync
```

### 2. Create Device Tree
```bash
mkdir -p device/<manufacturer>/<codename>
cd device/<manufacturer>/<codename>
```
- Add `BoardConfig.mk`, `recovery.fstab`, proprietary blobs, etc.  
- Reference working [device tree examples](https://github.com/minimal-manifest-twrp/platform_manifest_twrp_aosp).

### 3. Configure Build
```bash
export ALLOW_MISSING_DEPENDENCIES=true
source build/envsetup.sh
lunch omni_<codename>-eng
```

### 4. Compile Recovery
```bash
mka recoveryimage
```
Output is located at:
```
out/target/product/<codename>/recovery.img
```

---

## 📱 Testing the TWRP Recovery

1. Boot device into fastboot mode:
   ```bash
   adb reboot bootloader
   ```

2. Flash recovery:
   ```bash
   fastboot flash recovery out/target/product/<codename>/recovery.img
   ```

3. Boot directly into recovery:
   ```bash
   fastboot reboot recovery
   ```

---

## 🐞 Debugging and Troubleshooting

### Capture Logs
```bash
adb logcat > recovery_log.txt
```

### Common Issues
- **Bootloop:**  
  - Check kernel configs.  
  - Ensure `BOARD_RECOVERYIMAGE_PARTITION_SIZE` matches your device.

- **Touchscreen not working:**  
  - Verify touch panel drivers are enabled in kernel.  
  - Update device tree.

- **Black screen / no boot:**  
  - Wrong display drivers.  
  - Check framebuffer configs.

- **Recovery too large:**  
  - Remove unnecessary binaries.  
  - Use compression flags in BoardConfig.

---

## 🌍 Submitting Your Build

1. Test **ALL TWRP functions** (backup, restore, flashing, MTP, ADB).  
2. Contribute upstream:  
   - Fork [TWRP GitHub](https://github.com/TeamWin/Team-Win-Recovery-Project).  
   - Submit PR with clean commits.  
3. Share on:  
   - [XDA Developers](https://forum.xda-developers.com/)  
   - Telegram / Reddit communities.

---

## 📚 Additional Resources
- [Official TWRP Build Guide](https://twrp.me/faq/howtobuild.html)  
- [AOSP Build Docs](https://source.android.com/docs)  
- [Device Tree Examples](https://github.com/minimal-manifest-twrp/platform_manifest_twrp_aosp)  
- [Payload Dumper Go](https://github.com/ssut/payload-dumper-go) – for extracting `payload.bin` firmware.  
- [Android Image Kitchen](https://forum.xda-developers.com/t/tool-windows-linux-android-image-kitchen-unpack-repack-img.2073775/)

---

## 🖥️ Windows / WSL2 Setup

Most of this guide assumes you are using **Linux (Ubuntu recommended)**.  
If you are on **Windows**, you have three main options:

### 1. WSL2 (Windows Subsystem for Linux 2) – easiest method
- Open **PowerShell as Administrator** and run:  
  ```powershell
  wsl --install -d Ubuntu-20.04
  ```
  *(replace `20.04` with `22.04` if you want the newer version)*

- Restart your PC.  
- Open **Ubuntu** from Start Menu → set up a username and password.  
- Update packages inside Ubuntu:  
  ```bash
  sudo apt update && sudo apt upgrade -y
  ```

- Now you can follow this guide exactly as if you were on Linux.

⚠️ **Limitation:** adb/fastboot does not work directly inside WSL2.  
- Easiest fix: install [platform-tools](https://developer.android.com/studio/releases/platform-tools) on Windows and run adb/fastboot from **Windows Command Prompt** instead of WSL.  
- Advanced fix: use [`usbipd-win`](https://github.com/dorssel/usbipd-win) to forward USB devices into WSL2.

---

### 2. Virtual Machine (VM)
- Install Ubuntu inside VirtualBox or VMware.  
- Allocate **8GB RAM + 60GB storage** minimum.  
- USB passthrough lets adb/fastboot work normally.  
- Slower than WSL2 or dual boot.

---

### 3. Dual-Boot Linux
- Best option if you plan to build often.  
- Full performance, no USB issues.

---

### Quick Tip for Windows Users
If you only need to **unpack/repack recovery.img** (not compile TWRP from source), you can stay on Windows and use:  
- [Android Image Kitchen](https://forum.xda-developers.com/t/tool-windows-linux-android-image-kitchen-unpack-repack-img.2073775/)  
- [payload-dumper-go](https://github.com/ssut/payload-dumper-go)

TWRP-device-porting

TWRP-device-porting Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

TWRP-device-porting

TWRP-device-porting Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README