Disclaimer: This guide and the tools included are provided as-is. Testing has been limited and nothing is guaranteed to work. I take no responsibility for lost data, bricked devices, etc. Continue at your own risk, and please read carefully. THIS GUIDE WAS WRITTEN FOR PHONES ON ANDROID 8.1 - MAY NOT WORK ON DEVICES WITH THE PIE UPDATE.
Note that Magisk and TWRP can interfere with downloading and installing OTA updates. At this time the only updates are security patches, so it would be best to make sure all OTAs are installed before starting.
Mounting and decrypting the data partition is still hit-or-miss. If you haven't set up a passcode or password, TWRP should be able to mount it, and you still might be able to even if you have. Magisk will corrupt encrypted partitions and force a factory reset, and TWRP will not be able to help you back things up if Magisk has been installed before disabling encryption. You've been warned.
Guide: Installing TWRP and Magisk on the Visible R2
Tools:
prog_emmc_firehose_8917.mbn - firehose for flashing system partitions
Latest available TWRP zip - contains TWRP recovery image and the necessary files for flashing
fstab.qcom - for removing forced encryption
Patched boot image - for installing versions of Magisk newer than v16.7
Stock firmware - optional, but handy to have in case something goes wrong.
Windows users: QPST/QFIL and the QDLoad drivers (possibly the first set of ZTE drivers as well, but likely not necessary). Installing drivers in compatibility mode for XP or Windows 7 might help resolve issues.
Install adb if you don't already have it set up.
Linux users: qdl source code; the guide will cover compiling and installing it. You'll also want to install adb from your distro's repositories. There is a snap package for qdl, but it doesn't work for the purposes of this guide, so please don't use it.
Part 1: Installing TWRP
TWRP is an easy-to-use, touch-based custom recovery for Android devices, designed to make backups and installs simple and painless. Unfortunately, the installation of TWRP on the R2 is going to be a little less simple and painless; the device's bootloader isn't locked down, but it doesn't support fastboot commands, meaning we'll need to get our hands dirty to flash partitions.
Before starting, it's also worth noting that the current TWRP build cannot always decrypt encrypted data partitions, and the device is encrypted by default. This means that TWRP may not be able to mount or back up your data partition unless it's formatted and forced encryption is removed (see part 2).
To flash TWRP, we need to put the device into EDL mode and forcibly overwrite the existing partitions using an EDL tool and the firehose linked above, which unfortunately requires a PC of some sort. Enable USB debugging on your phone, then follow the steps for your operating system below.
For Windows:
For Linux:
That's it! Verify that TWRP is working as expected by doing some test backups and restores, etc. Note that TWRP builds for this device are still sort of experimental; decrypting the data partition may not work for some users, and keeping data encrypted while trying to flash Magisk will not work - you will need to wipe and decrypt the device. If you're satisfied just with TWRP, there's not much else you need to do. If you want to run Magisk or decrypt your device for other reasons, keep reading.
Part 2: Removing Forced Encryption
By default, the device encrypts the data partition without input from the user. This is not ideal, and even if TWRP can decrypt and mount your data partition, from my experience Magisk's init process apparently gets things wrong and tries to write to data before its decrypted - whether that's actually the case or not, the fact of the matter is that Magisk has corrupted my data partition every time I've tried to install it while data was encrypted.
DO NOT flash any zip that removes dm-verity and force encryption - these modify the boot and recovery partitions, and the stock kernel doesn't like the way they do it. If you've flashed the patched boot.img first then you'll at least be able to boot to your system partition afterwards, but it'll still nuke recovery even with a custom kernel installed on it. If you're still using the stock boot.img, you'll get boot loops and won't be able to access recovery; your only choice is to enter diagnostic mode, and reflashing anything from that point is a gigantic pain in the ass, so please, just don't. If you feel the need to do it regardless, please please please reflash your boot and recovery images before rebooting.
Counter-intuitively, the quickest and most painless way to stop the device from force-encrypting itself is to modify the fstab on the vendor partition - the boot partition has no fstab files, and the ones in the TWRP recovery image are already set to make encryption optional. Place the fstab.qcom on the phone's microSD card (internal storage will work if you don't have one, as long as TWRP can access your internal storage; if not, use adb push/pull rather than the below commands), boot into TWRP, and adb shell into your device by USB; if done while in TWRP, you should have root permissions. If your PC doesn't see your phone as an ADB-ready device, go to Mount settings in TWRP and tap on the option to disable MTP; after confirming that ADB works, feel free to re-enable MTP. Once ADB is working, run the following commands:
.
That's the simple part - you've replaced the fstab on the vendor partition with one that tells the device that encryption is optional, and backed up the original to your microSD as fstab.qcom.bak, just in case. Now you need to actually remove the existing encryption, which will wipe all the user data from the device. If that hasn't scared you out of continuing, read on.
While we're still in TWRP, we need to go to the Wipe menu. From there, we need to Format Data. It'll give you warnings in a scarier color than I did, but you'll have to type yes and continue regardless. Once that's done, hit the back button a couple times before rebooting. Do a standard factory reset, then reboot.
From there, it may take a couple tries for the device to boot normally as it reformats and repopulates the data partition. If you find yourself stuck on a black screen, reboot again, and if it keeps happening, boot into TWRP and then reboot to System from the reboot menu. Eventually, you should be able to get back to the device setup screen, and depending on your security settings beforehand, you may be prompted to enter your PIN, password, or Google account information.
From here, you should be able to mount, backup, and restore your data partition in TWRP without any issues. If you want to go further and root your device, keep reading for the Magisk guide.
Part 3: Any Magisk You'd Like
Note: Magisk and encrypted data partitions do not play nicely together. Follow through Part 2 first, or you'll have headaches.
ZTE's kernel has a custom SELinux plugin called policyproc, which in short doesn't play nice with a lot of things that modify what happens during the kernel's startup sequence. Unfortunately, modifying the startup sequence is what Magisk does best, and versions of Magisk past v16.7 don't play well with the stock kernel.
If you're fine with v16.7, you can download the zip from its Github release page and flash it through TWRP. However, it doesn't support current versions of Magisk Manager or the uninstaller zip, and naturally it doesn't have all the features of newer versions.
This is where the patched boot image comes in. Basically, it's the stock kernel, rebuilt with policyproc disabled, stuffed into the stock boot.img and replacing the original kernel. It's not entirely perfect as ZTE deliberately left out bits of the source, but even working around that, the kernel seems to run fine after nearly a week of testing on my own device. Still, if you run into any issues that don't show up with the stock kernel, please let me know.
So. you can take that patched boot image and install newer versions of Magisk whichever way you'd like. The default method would be to use TWRP to flash the patched boot image, then flash the latest Magisk zip (v20.1 at the time of writing). Alternatively, you could put the patched boot.img on your microSD or internal storage, install the Magisk Manager app, use it to patch Magisk into the patched boot image, then use TWRP to flash the patched-patched-image to the boot partition. Either way should work fine, and honestly I'm hoping if you've made it this far you don't need further instruction on how to get Magisk installed.
Note that on the first reboot after installing Magisk, the phone may reboot again before loading the system normally. I assume this is standard practice for initializing Magisk, but honestly I have no idea.
With that, you've done just about everything you came here to do. If you still feel like tweaking and possibly bricking your phone, however, scroll on down to Part 4.
Part 3.5: Updating Your Magisk Install
When a Magisk update is available, the Magisk Manager app will generally push a notification to you. Letting the manager handle the upgrade is a good way to get bootloops, unfortunately; upgrading requires re-patching and re-flashing the boot image, and most apps running in system mode seem to handle the task poorly on the R2. If you want to update to a newer version of Magisk, it'd be best to reboot into TWRP, flash the 'clean' Magisk-ready boot image, then install the zip for the version of Magisk you want to update to. You don't need to uninstall previous versions of Magisk to do this, and it should be doable even if a previous Magisk upgrade left you stuck in a boot loop. Note that if you previously told the Manager to 'hide' itself, you may end up with two Manager apps after the update; it should be safe to remove either of them, although the one with the Magisk Manager name will need to be re-hidden if you choose to keep it.
Part 4: Going Even Further Beyond - Project Treble and You
Google requires that all Android phones releasing with Android Oreo or newer must support the Treble framework: generally speaking, anything that's 'stock' Android lives on the system partition, and anything manufacturer or carrier specific exists on the vendor partition. This has allowed for developers to create generic system images, or GSI, consisting of particular Android system partitions that should run on a variety of Treble-enabled devices. And wouldn't you know it, the R2 launched with Oreo, and you've got a couple handy methods of writing system images to your device, through TWRP and EDL flashers.
So, does that mean the R2 supports these GSIs? Not really! Honestly, it's more that it's up to curious people to find out. I've been able to get phhussons's Oreo image working, but that's a bit boring on a device that supports Oreo out of the box. A couple more highly modified Pie builds failed to boot properly, either hanging on their splash screen or crashing the display manager before getting through setup.
There's also the fact that they're generally only distributed as sparse system.img files, something I had trouble flashing with QFIL, and up until about 18 hours before this guide went live, the only TWRP build I had for the R2 could only write images to the boot and recovery partitions, not system, so writing them meant I had to decompress them to a standard EXT4 image and then flash them with QFIL, which wasn't a lot of fun to mess with. In short, testing's been pretty limited, but this build of TWRP should make it much easier for anyone to flash whatever image they'd like. If you feel like being a guinea pig, we'd all love to hear the results! If you want to test, you should look for A-only, ARM64 images.
Questions and Issues
My phone is bootlooping after leaving recovery!
If you haven't messed with system partitions in a way that might cause a bootloop, reboot to recovery and try to boot to system from there. If it continues, reflash your boot image (and Magisk afterwards, if necessary, removing the extra Manager app that might pop up in your app tray if you've got Manager disguised in its settings).
I can't access ADB or MTP from recovery.
It happens sometimes, especially in Windows; just toggle MTP on/off from inside TWRP, or unplug and replug your USB cable.
My phone says I need a factory reset, but TWRP just reboots.
This generally happens if something messed with the encrypted data partition. Do not tap the factory reset button on your phone; instead, power off entirely and manually reboot into TWRP by hilding Vol Up while booting. Perform a factory reset (and format data if necessary) from there, then reboot.
(to be populated)
Credits
@deadman96385 - for uploading the tools that made this possible and the stock ROMs that saved my ass more than a few times
@famewolf - for feedback on what did/didn't work in the last guide
@asderdd - for his Axon 7 kernel work which I shamelessly copied to get Magisk working
Anyone who's contributed to Magisk or TWRP over the years, and the maintainers of the moto e5+ device tree for TWRP since I used most of their branch.
Sources
Kernel source, specifically the tree used for the Magisk patch
TWRP device tree
Note that Magisk and TWRP can interfere with downloading and installing OTA updates. At this time the only updates are security patches, so it would be best to make sure all OTAs are installed before starting.
Mounting and decrypting the data partition is still hit-or-miss. If you haven't set up a passcode or password, TWRP should be able to mount it, and you still might be able to even if you have. Magisk will corrupt encrypted partitions and force a factory reset, and TWRP will not be able to help you back things up if Magisk has been installed before disabling encryption. You've been warned.
Guide: Installing TWRP and Magisk on the Visible R2
Tools:
prog_emmc_firehose_8917.mbn - firehose for flashing system partitions
Latest available TWRP zip - contains TWRP recovery image and the necessary files for flashing
fstab.qcom - for removing forced encryption
Patched boot image - for installing versions of Magisk newer than v16.7
Stock firmware - optional, but handy to have in case something goes wrong.
Windows users: QPST/QFIL and the QDLoad drivers (possibly the first set of ZTE drivers as well, but likely not necessary). Installing drivers in compatibility mode for XP or Windows 7 might help resolve issues.
Install adb if you don't already have it set up.
Linux users: qdl source code; the guide will cover compiling and installing it. You'll also want to install adb from your distro's repositories. There is a snap package for qdl, but it doesn't work for the purposes of this guide, so please don't use it.
Part 1: Installing TWRP
TWRP is an easy-to-use, touch-based custom recovery for Android devices, designed to make backups and installs simple and painless. Unfortunately, the installation of TWRP on the R2 is going to be a little less simple and painless; the device's bootloader isn't locked down, but it doesn't support fastboot commands, meaning we'll need to get our hands dirty to flash partitions.
Before starting, it's also worth noting that the current TWRP build cannot always decrypt encrypted data partitions, and the device is encrypted by default. This means that TWRP may not be able to mount or back up your data partition unless it's formatted and forced encryption is removed (see part 2).
To flash TWRP, we need to put the device into EDL mode and forcibly overwrite the existing partitions using an EDL tool and the firehose linked above, which unfortunately requires a PC of some sort. Enable USB debugging on your phone, then follow the steps for your operating system below.
For Windows:
For Linux:
That's it! Verify that TWRP is working as expected by doing some test backups and restores, etc. Note that TWRP builds for this device are still sort of experimental; decrypting the data partition may not work for some users, and keeping data encrypted while trying to flash Magisk will not work - you will need to wipe and decrypt the device. If you're satisfied just with TWRP, there's not much else you need to do. If you want to run Magisk or decrypt your device for other reasons, keep reading.
Part 2: Removing Forced Encryption
By default, the device encrypts the data partition without input from the user. This is not ideal, and even if TWRP can decrypt and mount your data partition, from my experience Magisk's init process apparently gets things wrong and tries to write to data before its decrypted - whether that's actually the case or not, the fact of the matter is that Magisk has corrupted my data partition every time I've tried to install it while data was encrypted.
DO NOT flash any zip that removes dm-verity and force encryption - these modify the boot and recovery partitions, and the stock kernel doesn't like the way they do it. If you've flashed the patched boot.img first then you'll at least be able to boot to your system partition afterwards, but it'll still nuke recovery even with a custom kernel installed on it. If you're still using the stock boot.img, you'll get boot loops and won't be able to access recovery; your only choice is to enter diagnostic mode, and reflashing anything from that point is a gigantic pain in the ass, so please, just don't. If you feel the need to do it regardless, please please please reflash your boot and recovery images before rebooting.
Counter-intuitively, the quickest and most painless way to stop the device from force-encrypting itself is to modify the fstab on the vendor partition - the boot partition has no fstab files, and the ones in the TWRP recovery image are already set to make encryption optional. Place the fstab.qcom on the phone's microSD card (internal storage will work if you don't have one, as long as TWRP can access your internal storage; if not, use adb push/pull rather than the below commands), boot into TWRP, and adb shell into your device by USB; if done while in TWRP, you should have root permissions. If your PC doesn't see your phone as an ADB-ready device, go to Mount settings in TWRP and tap on the option to disable MTP; after confirming that ADB works, feel free to re-enable MTP. Once ADB is working, run the following commands:
Code:
mount /vendor
cp /vendor/etc/fstab.qcom /external_sd/fstab.qcom.bak
cp /external_sd/fstab.qcom /vendor/etc/fstab.qcom
chmod 644 /vendor/etc/fstab.qcom
umount vendorThat's the simple part - you've replaced the fstab on the vendor partition with one that tells the device that encryption is optional, and backed up the original to your microSD as fstab.qcom.bak, just in case. Now you need to actually remove the existing encryption, which will wipe all the user data from the device. If that hasn't scared you out of continuing, read on.
While we're still in TWRP, we need to go to the Wipe menu. From there, we need to Format Data. It'll give you warnings in a scarier color than I did, but you'll have to type yes and continue regardless. Once that's done, hit the back button a couple times before rebooting. Do a standard factory reset, then reboot.
From there, it may take a couple tries for the device to boot normally as it reformats and repopulates the data partition. If you find yourself stuck on a black screen, reboot again, and if it keeps happening, boot into TWRP and then reboot to System from the reboot menu. Eventually, you should be able to get back to the device setup screen, and depending on your security settings beforehand, you may be prompted to enter your PIN, password, or Google account information.
From here, you should be able to mount, backup, and restore your data partition in TWRP without any issues. If you want to go further and root your device, keep reading for the Magisk guide.
Part 3: Any Magisk You'd Like
Note: Magisk and encrypted data partitions do not play nicely together. Follow through Part 2 first, or you'll have headaches.
ZTE's kernel has a custom SELinux plugin called policyproc, which in short doesn't play nice with a lot of things that modify what happens during the kernel's startup sequence. Unfortunately, modifying the startup sequence is what Magisk does best, and versions of Magisk past v16.7 don't play well with the stock kernel.
If you're fine with v16.7, you can download the zip from its Github release page and flash it through TWRP. However, it doesn't support current versions of Magisk Manager or the uninstaller zip, and naturally it doesn't have all the features of newer versions.
This is where the patched boot image comes in. Basically, it's the stock kernel, rebuilt with policyproc disabled, stuffed into the stock boot.img and replacing the original kernel. It's not entirely perfect as ZTE deliberately left out bits of the source, but even working around that, the kernel seems to run fine after nearly a week of testing on my own device. Still, if you run into any issues that don't show up with the stock kernel, please let me know.
So. you can take that patched boot image and install newer versions of Magisk whichever way you'd like. The default method would be to use TWRP to flash the patched boot image, then flash the latest Magisk zip (v20.1 at the time of writing). Alternatively, you could put the patched boot.img on your microSD or internal storage, install the Magisk Manager app, use it to patch Magisk into the patched boot image, then use TWRP to flash the patched-patched-image to the boot partition. Either way should work fine, and honestly I'm hoping if you've made it this far you don't need further instruction on how to get Magisk installed.
Note that on the first reboot after installing Magisk, the phone may reboot again before loading the system normally. I assume this is standard practice for initializing Magisk, but honestly I have no idea.
With that, you've done just about everything you came here to do. If you still feel like tweaking and possibly bricking your phone, however, scroll on down to Part 4.
Part 3.5: Updating Your Magisk Install
When a Magisk update is available, the Magisk Manager app will generally push a notification to you. Letting the manager handle the upgrade is a good way to get bootloops, unfortunately; upgrading requires re-patching and re-flashing the boot image, and most apps running in system mode seem to handle the task poorly on the R2. If you want to update to a newer version of Magisk, it'd be best to reboot into TWRP, flash the 'clean' Magisk-ready boot image, then install the zip for the version of Magisk you want to update to. You don't need to uninstall previous versions of Magisk to do this, and it should be doable even if a previous Magisk upgrade left you stuck in a boot loop. Note that if you previously told the Manager to 'hide' itself, you may end up with two Manager apps after the update; it should be safe to remove either of them, although the one with the Magisk Manager name will need to be re-hidden if you choose to keep it.
Part 4: Going Even Further Beyond - Project Treble and You
Google requires that all Android phones releasing with Android Oreo or newer must support the Treble framework: generally speaking, anything that's 'stock' Android lives on the system partition, and anything manufacturer or carrier specific exists on the vendor partition. This has allowed for developers to create generic system images, or GSI, consisting of particular Android system partitions that should run on a variety of Treble-enabled devices. And wouldn't you know it, the R2 launched with Oreo, and you've got a couple handy methods of writing system images to your device, through TWRP and EDL flashers.
So, does that mean the R2 supports these GSIs? Not really! Honestly, it's more that it's up to curious people to find out. I've been able to get phhussons's Oreo image working, but that's a bit boring on a device that supports Oreo out of the box. A couple more highly modified Pie builds failed to boot properly, either hanging on their splash screen or crashing the display manager before getting through setup.
There's also the fact that they're generally only distributed as sparse system.img files, something I had trouble flashing with QFIL, and up until about 18 hours before this guide went live, the only TWRP build I had for the R2 could only write images to the boot and recovery partitions, not system, so writing them meant I had to decompress them to a standard EXT4 image and then flash them with QFIL, which wasn't a lot of fun to mess with. In short, testing's been pretty limited, but this build of TWRP should make it much easier for anyone to flash whatever image they'd like. If you feel like being a guinea pig, we'd all love to hear the results! If you want to test, you should look for A-only, ARM64 images.
Questions and Issues
My phone is bootlooping after leaving recovery!
If you haven't messed with system partitions in a way that might cause a bootloop, reboot to recovery and try to boot to system from there. If it continues, reflash your boot image (and Magisk afterwards, if necessary, removing the extra Manager app that might pop up in your app tray if you've got Manager disguised in its settings).
I can't access ADB or MTP from recovery.
It happens sometimes, especially in Windows; just toggle MTP on/off from inside TWRP, or unplug and replug your USB cable.
My phone says I need a factory reset, but TWRP just reboots.
This generally happens if something messed with the encrypted data partition. Do not tap the factory reset button on your phone; instead, power off entirely and manually reboot into TWRP by hilding Vol Up while booting. Perform a factory reset (and format data if necessary) from there, then reboot.
(to be populated)
Credits
@deadman96385 - for uploading the tools that made this possible and the stock ROMs that saved my ass more than a few times
@famewolf - for feedback on what did/didn't work in the last guide
@asderdd - for his Axon 7 kernel work which I shamelessly copied to get Magisk working
Anyone who's contributed to Magisk or TWRP over the years, and the maintainers of the moto e5+ device tree for TWRP since I used most of their branch.
Sources
Kernel source, specifically the tree used for the Magisk patch
TWRP device tree
Last edited:
