Peter Cai's Blog

This page contains links and documentation to PeterGSI, a Generic System Image (GSI) build that I use on all of my personal, unlockable Android devices. Although it is mainly intended for my personal use, I figured that it could be useful in general, and thus I decided to share my builds publicly.

What is a GSI?

GSI stands for Generic System Image. In a nutshell, with Android devices launched after Android 9, the entire system has been split into “system” and “vendor” partitions. The “vendor” partition contains vendor-specific code, mainly HALs. These HALs communicate with the “system” partition through a set of stablized interfaces. This allows a different system partition image to replace the stock one with no modification to vendor, while still working (mostly) as expected, even if the system image contains a newer version of Android than the original.

Can I use a GSI?

If your Android device is launched after Android version N (where N >= 9), you should expect to be able to at least boot a GSI of version at least N + 3, or, starting with chipsets released with Android 15, possibly N + 7. Any later version might be a hit or miss, depending on whether Google has decided to keep the HAL interfaces supported in that version. Third-party GSIs (such as this one) can also choose to revert some changes that remove compatibility with older interfaces, in which case you may be able to boot a GSI of an even higher version.

Your device manufacturer may also choose to upgrade the vendor partition at some point in the device's lifecycle, say, to version M, in which case you should be able to boot version M + 3. Note that this is different from an OS version upgrade — manufacturers often update the system image without updating the vendor partition, the same way as how a GSI can boot on an older vendor partition. Find out the version of your vendor partition by:

adb shell getprop ro.vndk.version

or (for devices launched after Android 15):

adb shell getprop ro.vendor.api_level

Why PeterGSI?

AOSP does publish official GSI builds, but these GSI builds are intended for compliance testing and development purposes. Usually your phone should be able to boot one of these GSIs, but it does not mean that all functionalities which matter for daily use are present. Most often, you might be seeing issues with in-call audio, bluetooth, etc, which are not what the tests are concerned with but are a non-starter for daily driving. The stock apps (phone, messaging, etc.) on AOSP are also largely unmaintained and less than useful.

This GSI is what I ended up with for daily driving my devices (see below for a list). Please note that this build is not based on TrebleDroid directly, and does not include fixes and hacks for all devices. This is intentional — this build is intended to be as close to AOSP as possible, and only includes fixes that I know are necessary for all the devices I have tested on. All device-specific hacks in this GSI are implemented using a C++ framework rather than a shell script, which hopefully makes it easier to manage in the future.

What this also means is that this GSI might be (currently) missing some features you might care about. One example is VoLTE support, because I am a jmp.chat user and do not rely on VoLTE from my carrier. This does not mean it will not work at all, just that someone else who can test and debug is needed to get it working. See below for a detailed explanation.

If you want to make this GSI work on your device OR for your use-case, contributions are welcome! Join our chat below to discuss your changes, or send a pull request on the source code repositories.

Contact

Join us on Matrix at #peter-gsi:neo.angry.im

Warning

By flashing GSIs, you are taking the risk of customizing your device outside of what your warranty likely covers. Remember that there is NO GUARANTEE that any of the features will work on this GSI. Your device might not even be able to boot. I am NOT RESPONSIBLE for any potential damage that might result from YOU attempting to customize YOUR device.

Download

Shared folders:

Android 17: https://share.typeblog.net/share/KvBXSEXP

Android 16 (archival): https://share.typeblog.net/share/NzaLT1XF

Android 15 (archival): https://share.typeblog.net/share/Ac2cLUJX

Android 14 (archival): https://share.typeblog.net/share/rhUs8MOA

All updates will be uploaded to the same shared folder. You can expect semi-monthly updates corresponding to Google's security patch releases.

Source code: https://gitea.angry.im/PeterGSI

Source code for OpenEUICC is available at https://gitea.angry.im/PeterCxy/OpenEUICC, and the prebuilt dependencies to use in AOSP is located at https://gitea.angry.im/PeterCxy/android_prebuilts_openeuicc-deps.

Installation

First download and extract the .img file, and the rest is the same as any other GSI:

• For devices with dynamic partitions (i.e. anything shipped after Android 12):
  • Boot into recovery then select enter fastboot (or adb reboot fastboot, DO NOT USE adb reboot bootloader, note the difference!!!), and then fastboot flash system <insert_name_of_the_img_file>
  • If it fails with something along the lines of not enough space, try fastboot delete-logical-partition product, and/or fastboot delete-logical-partition system_ext.
• For devices without dynamic partitions: (these devices probably don't work anymore)
  • Boot into fastboot mode, and then fastboot flash system <insert_name_of_the_img_file>
• You might need to do fastboot flash --disable-verity --disable-verification vbmeta vbmeta.img in order to disable dm-verity, otherwise your device might not be able to boot
  • Obtain a vbmeta.img from an official factory image for your device.
  • Note that on some devices doing this step will break boot, but on others this step is required to boot. Try both ways and see which works.
    

After flashing, remember to wipe all data from recovery before rebooting.

What Works

If your device is truly Treble-compliant (released after Android 9), then all features covered by CTS and VTS should work as expected. This includes booting (of course), audio, telephony, camera, WLAN, bluetooth, etc. However, some features are never expected to work on vanilla GSIs:

• In-display fingerprint scanners (except for devices after Android 13 with standardized HALs, such as Pixels)
  • These require injections into the framework to make the icon appear and to use the correct color and brightness for scanning (in the case of optical ones).
  • Making these work will require a lot of conditional hacks on the framework side, and it is unlikely that I will add them in the near future.
• VoLTE (IMS)
  • This technically can work with the correct ims.apk installed, however this is untested on my GSI builds because I do not use IMS personally and rely exclusively on Voice-over-XMPP through jmp.chat.
  • As a courtesy here're some ims.apk builds signed with the platform key of my GSI builds: https://share.typeblog.net/share/F9nTFMqo. They're not guaranteed to work, and I have only confirmed that they can be installed without crashing. These are simply apks downloaded from https://treble.phh.me resigned with my keys.
  • After installing the correct ims.apk, you'll also need to activate the corresponding resource overlays by setting some properties (setprop) over adb. To test Qualcomm IMS, set persist.sys.phh.ims.caf to true. To test MTK IMS, set persist.sys.phh.ims.mtk to true.
    

Modifications

The following incomplete list of modifications on top of AOSP has been made:

• Forward-port of the fix for in-call audio on older MTK devices
• SEPolicy compatibility fixes for old devices, especially MTK ones
• GPU frequency scaling fixes for MTK devices
• Bluetooth fixes for devices released before Android 13
  • A system-side generic bluetooth audio HAL, sysbta, has been included for generic bluetooth audio support.
  • This should work better than previous solutions from GSIs, but hardware offloading is likely unavailable even if turned on.
• Some changes from LineageOS:
  • A new suite of icons (including monochrome) for builtin apps
  • Launcher3 fixes and ThemePicker
• Fix for calling account selection automatically resetting when a third-party calling app is in use, such as jmp.chat
• microG signature spoofing support
• Replacement of unmaintained AOSP apps with FOSS apps (Fossify, LineageOS, etc.)

The full list of patches can be viewed here.

Preinstalled Apps

Peter's AOSP GSI strives to be as much FOSS as possible. A set of FOSS apps are included by default:

• microG Services Core
• Firefox (Fennec F-Droid)
• Bromite
• Fossify Gallery
• K-9 Mail
• MuPDF
• Aurora Store
• Neo Store
• Etar
• Fossify Messaging
• Fossify Contacts
• Open Camera

In addition, the following FOSS apps made by me are included because they have to be system apps:

• OpenEUICC
  • A generic eSIM manager application for FOSS ROMs. It supports downloading new eSIM profiles via QR codes or SM-DP+ addresses, switching between profiles, and, of course, profile deletion.
    

Tips and Tricks

• On Qualcomm devices, if your device audio does not work as expected, try the following:
  • Run adb shell, and input the command su (to gain temporary root via adb)
  • Run setprop persist.sys.gsi.alternate_audio_policy true
  • Reboot
  • This instructs the GSI to use /vendor/etc/audio/audio_policy_configuration.xml instead of /vendor/etc/audio_policy_configuration.xml, which is needed on some Qualcomm devices (but breaks on others)

Tested Devices

I regularly use the following devices:

• Unihertz Jelly Max
• Unihertz Titan 2 (Since Android 16 image peter_gsi_arm64_20251106)
• Google Pixel 7 Pro

This GSI will most likely work on these devices (except features that are never expected to work, of course).

• In the case of Unihertz Titan 2, the GSI uses a key layout somewhat different from official: the Fn key activates the symbol layer instead of the Sym key, because AOSP uses Sym for input method selection. Also, it includes and runs https://gitea.angry.im/PeterGSI/titan2-touchpadd by default, which uses Titan 2's keyboard touch input as a trackpad, among a couple of keyboard quality-of-life improvements.

FAQs

• Q: Does it work on my device?

• A: Maybe, or maybe not. But if your device is released after Android 11, then it is more likely to at least boot than not. Keep in mid that THERE IS NO GUARANTEE.

• Q: It does not boot on my device X.

• A: Unfortunate, but in this case there is not a lot I could do to help. If you have access to console-ramoops, you can try to extract that after a failed boot and send that to me. Otherwise, if I do not own the device myself, it would be extremely hard to debug. In addition, I have never intended to support devices released before Android 9 (i.e. vndklite), or any device that is not currently supported by the latest Treble standards (N + 3, i.e. if a device is released on Android N, then the last officially supported version would be N + 3). They may or may not work, but there is no guarantee.

• Q: Will you fix bug X on my device Y?

• A: Maybe, or maybe not. If you can fix it yourself, however, you are always welcome to make a contribution by contacting me via the Matrix group.