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. 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 15: 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:
    • Boot into recovery, select enter fastboot, 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:
    • 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 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
    • This is not impossible but system-side ims.apk and overlays are needed.
    • I have already included the overlays required for IMS to work. However, there is not any signed ims.apk published by me yet, so without building the system image from source yourself, you will not be able to use them even if you acquired a supposedly working ims.apk for your chipset.
    • I am willing to start publishing signed ims.apk if someone can 1) make a working port; 2) test and confirm to me that they work.

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)
  • To test Qualcomm IMS, set persist.sys.phh.ims.caf to true. To test MTK IMS, set persist.sys.phh.ims.mtk to true. These are the same as in phh GSI's overlays. You'll have to install the correct ims.apk signed with the platform signing key (this means you'll need to either build the GSI yourself or ask me to sign it for you).

Tested Devices

I regularly use the following devices:

  • Unihertz Jelly Max
  • Unihertz Jelly Star
  • Unihertz / 8849 Tank Mini
  • Unihertz Luna
  • Google Pixel 7 Pro

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

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.