Case study · Low-level Android
Porting TWRP to a phone no one had before
The Motorola Edge 2025 is a fast, cheap, encrypted-by-default phone, and when it came out there was no custom recovery for it. This is the story of what that means, why it's hard, and the handful of unusual problems I had to solve to get a working one.
What's a recovery, in plain English?
Every modern Android phone ships with a tiny second operating system called the recovery. You don't normally see it. It lives on its own, next to the normal Android, and it's what the phone boots into when something has gone wrong, or when it needs to install an update.
The stock recovery that comes with the phone is deliberately boring. It can install an official update that the manufacturer signed, or wipe the whole phone back to factory. That's about it. It can't look at your files, back them up, restore them, or fix a broken phone that stock Android won't boot into. That's by design.
A custom recovery replaces that boring one with a much more capable version. TWRP (Team Win Recovery Project) is the most popular. With it you can back up every bit of the phone (apps, settings, photos, texts, everything), restore from one of those backups later, install modifications, and dig your way out of problems that would otherwise brick the device. For anyone who tinkers with Android, it's one of the most useful tools there is.
The problem: it only works if someone builds it for your exact phone
TWRP isn't one program you can install on any Android. It has to be ported to each phone model, by somebody who owns one and is willing to do the work. The port depends on the exact chipset, display, touch panel, storage layout, security chips and dozens of other things that vary between phones. For popular enthusiast phones (OnePlus, Pixel) a port exists within weeks. For most other phones, it just never happens.
The Motorola Edge 2025 is one of the "never happens" ones. When I bought mine, there was no TWRP for it, there was no device tree anybody had put online, and there wasn't a community poking at it. If I wanted one, I was going to have to build it myself. So I did.
Why this phone was unusually hard
Phones from 2015 are easy. Phones from 2025 are not. Every year, Android picks up another layer of security that recovery has to work around, because recovery runs before most of Android is awake. On this phone, four of those layers all collided at once.
1. Everything on the phone is encrypted, and the keys live in a chip you can't reach
Your pattern or PIN doesn't just unlock the screen. It also unlocks the actual data on the storage. All of it is encrypted, and the encryption keys are kept inside a separate little computer on the phone (the "Trusted Execution Environment", or TEE), running software from the chip vendor that your Android has no way to inspect. When you type your pattern, Android asks that little computer "please hand me the keys", and it does, briefly, so your files can be read.
In a stock recovery, that little computer isn't running. Which means your files are there on the disk, but they're scrambled nonsense and nothing in recovery can read them. Most custom recoveries just give up at this point and say "sorry, your /data is encrypted, you'll have to wipe it first." That's a terrible experience, because you lose everything.
Getting the TEE to come up inside the recovery, so it could hand over the keys, so the recovery could actually see your personal files to back them up, was the hardest single thing in this port. It took weeks. On any other phone, this would have been one line of configuration. On this one, it was five separate conditions that all had to be right, and if any one of them was off the little chip responded with the same opaque error no matter which part was wrong.
2. One number has to match, exactly, forever
Phones are constantly getting security updates. Each one bumps a little date on the phone saying "I'm patched up to this date." The TEE uses that date to decide whether the recovery is trustworthy enough to be given the keys.
If the date in the recovery and the date on the phone don't match, the TEE just refuses, and your data stays locked. So after every Motorola security update I now have to pop open the recovery, update that date in one specific place, and rebuild. Miss it and backups silently stop working.
3. TWRP itself had a quiet off-by-one bug nobody had hit yet
While trying to decrypt the storage, I kept getting errors that didn't quite line up with reality. After a lot of staring at logs I found that TWRP was handing one of its own helper functions the wrong argument in the wrong slot. The helper takes seven things in a specific order; TWRP was passing one of them in the sixth position instead of the seventh. That one-off caused two unrelated-looking failures at once, which is why it hadn't been noticed before. One line of code.
4. TWRP's data backup had been crashing for years and nobody knew
Here's a strange one. After I finally got the storage unlocked and tried to make my first full backup, the backup process immediately crashed. The error was that the program was trying to shove five characters into a four-character box. Easy enough to spot once you look.
What's weird is that this bug has probably been in TWRP's code for a long time. It only shows up at the moment the recovery is doing a real backup of real decrypted data — and on a modern phone, that's exactly what nobody had managed to do yet. The bug wasn't findable until the preceding problem (getting the storage unlocked) had been solved. Once you crossed that bridge, you hit this one three seconds later. I'm fairly sure it's a bug a lot of people would hit now, if they knew to look.
5. The recovery was talking to the wrong version of the fingerprint checker
When you type in your pattern, something in the system has to check it. Phones used to use one way of asking that question; newer phones use a different one. The code in TWRP was still asking the old way, and this phone only answers the new way. Rewriting that one piece to speak the modern version was the last thing standing between the recovery and actually unlocking files when you type a pattern in. The first time it worked and the thumbnails of my photos appeared on screen, that was a good day.
The result
The recovery boots on the phone, decrypts the storage when you enter your pattern, and takes a full backup of all 58 gigabytes of a phone in about twelve minutes with no crashes. It's been through many build iterations, and the device tree, patches and prebuilt images are all public on GitHub, so somebody else can skip all of this.
I don't normally expect to be reporting bugs into TWRP's upstream codebase while I'm using it. On this one I ended up with a short list for them, which is a nice side effect of pushing through a port on a phone the project hadn't really been pointed at yet.
Why spend a month on this
Three reasons. One, I wanted a real backup on a phone that otherwise would have no safety net. Two, this kind of work — where you have to understand why a system behaves the way it does rather than just how to call its API — is the muscle that lets me rescue an app someone else wrote, or build one that has to do something unusual on the hardware. And three, I'd be lying if I said I didn't enjoy it.