Skip to content

Instantly share code, notes, and snippets.

@pcurz

pcurz/GSI_Nokia23.md

Last active May 31, 2025 18:06
Show Gist options
  • Save pcurz/72e85d296ce37d401b265d6391ca162c to your computer and use it in GitHub Desktop.
Save pcurz/72e85d296ce37d401b265d6391ca162c to your computer and use it in GitHub Desktop.
Download ZIP
GSI installation on Nokia 2.3
Raw
GSI_Nokia23.md

GSI installation on Nokia 2.3

This guide provides detailed instructions for installing a GSI (Generic System Image) on the Nokia 2.3 (model TA-1214 and similar, equipped with a MediaTek MT6761 SoC) using mtkclient under Windows. This includes preparing the environment, installing necessary drivers, unlocking the bootloader, bypassing FBE (File-Based Encryption) issues specific to this device by flashing a modified vendor image, and finally flashing the GSI and optionally Magisk.

Disclaimer

Modifying your device's software, such as unlocking the bootloader and flashing custom images, carries inherent risks. These actions can void your warranty, and if not performed correctly, could potentially brick your device (render it unusable). Precompiled binaries from unverified sources should be treated with caution. Only proceed if you understand the implications and have backed up any important data. You are solely responsible for any damage to your device.

Environment setup (Windows)

A correct environment setup is crucial for the procedures below.

1. Install Python

  • Download and install Python 3.9.22. Avoid versions 3.10+ as they might have compatibility issues with some mtkclient dependencies.
  • Do not use the Microsoft Store version of Python.

2. Install WinFsp (for FUSE support - needed by mtkclient)

3. Install Necessary Drivers

This is a critical step. Without the correct drivers, your computer will not be able to communicate properly with your Nokia 2.3 in different modes.

  • UsbDk (USB Development Kit): Required by mtkclient for low-level USB communication.

  • ADB & Fastboot Drivers: These are needed for fastboot commands once the bootloader is unlocked and you boot into fastboot mode.

    • The easiest way is to install "15 seconds ADB Installer": Search for it on XDA Forums or other reputable Android development sites. This will install ADB, Fastboot, and the necessary Google USB drivers.
    • Verify by booting your phone into fastboot mode and connecting it to your PC. Open a command prompt and type fastboot devices. Your device should be listed.

Troubleshooting Drivers:

  • Open Device Manager in Windows (search for it in the Start Menu).
  • Connect your phone in the respective mode (powered off for BROM/Preloader, or in fastboot mode).
  • Look for any devices with a yellow exclamation mark, especially under "Ports (COM & LPT)" or "Universal Serial Bus devices". This indicates a driver issue.
  • You might need to manually install drivers by right-clicking the problematic device, selecting "Update driver," and pointing to the location where you downloaded the drivers.
  • Sometimes, disabling Windows Driver Signature Enforcement temporarily might be needed to install unsigned drivers, but this should be done with caution.

4. Clone and install mtkclient

  • Open a Command Prompt (cmd.exe) or PowerShell.
  • Install Git for Windows if you haven't already: https://git-scm.com/download/win
  • Clone the mtkclient repository: 
    git clone https://github.com/bkerler/mtkclient
  • Navigate into the mtkclient directory: 
    cd mtkclient
  • Install Python dependencies: 
    pip install -r requirements.txt

If scrypt fails to build and you don't want to install Microsoft Visual C++ Build Tools, you can try using a precompiled wheel:

  • Download: scrypt-0.8.27-cp39-cp39-win_amd64.zip (This is for Python 3.9)
  • Rename the downloaded .zip file to .whl (e.g., scrypt-0.8.27-cp39-cp39-win_amd64.whl).
  • Install it manually using pip (navigate to the directory where you saved the .whl file or provide the full path): 
    pip install path/to/scrypt-0.8.27-cp39-cp39-win_amd64.whl

Nokia 2.3: Step-by-step GSI installation

Important Preliminary Notes:

  • Backup Your Data: Unlocking the bootloader will wipe all data on your phone. Operations like dumping firmware or erasing partitions also carry risks. Backup everything important (photos, contacts, etc.) before you begin.
  • Charge Your Phone: Ensure your phone has at least 50% battery charge to prevent it from shutting down during any flashing process.
  • Use a Good USB Cable: A faulty USB cable can lead to connection issues and failed operations.
  • Read Carefully: Follow each step precisely.
  • CRITICAL WARNING - Do NOT Disconnect During mtkclient Operations: If your phone is disconnected from the PC (or if mtkclient crashes/is forcibly closed) during any active read/write operation (e.g., while dumping firmware, flashing partitions, or unlocking the bootloader), the phone may become unresponsive or "soft-bricked," potentially stuck in BROM or Preloader mode. In such a scenario, it might not power on or be detected correctly.
    • Recovery for Unresponsive Device: If this happens, the most common recovery method for devices like the Nokia 2.3 (which has a non-user-removable battery) is to disconnecting and reconnecting the internal battery. This requires carefully opening the back cover of the phone (which may void your warranty and requires appropriate tools to avoid damage) and temporarily unplugging the battery connector from the mainboard, waiting a few seconds, and then plugging it back in. This procedure effectively cuts all power and can often resolve a device stuck due to a failed flashing operation. Attempt this only if you are comfortable with such a procedure or seek experienced help. Always try other methods first (like holding the power button for an extended period, or trying to re-enter BROM mode).

0. Understanding Connection Modes for mtkclient (BROM Mode)

Most mtkclient operations require the phone to be in BROM (Boot ROM) mode.

  • Power off your Nokia 2.3 completely.
  • Press and hold both Volume Up + Volume Down buttons simultaneously.
  • While holding the buttons, connect the phone to your PC using the USB cable.
  • mtkclient should then detect the device. If not, you might have a driver issue (see driver section above).
  • If mtkclient stays at "Waiting for PreLoader VCOM" or similar, disconnect, ensure drivers are okay, and try reconnecting in BROM mode.

1. Dump Stock Firmware (Crucial Backup!)

It is highly recommended to dump your phone's stock firmware before unlocking the bootloader or making any modifications. This backup can potentially be used to restore your device if something goes wrong.

  • Ensure mtkclient is set up. Your phone should be disconnected and powered off from the previous state (if any).
  • Open a command prompt in the mtkclient directory.
  • Execute the command: 
    python mtk.py rl backup --skip userdata
  • Now, connect your phone in BROM mode as described in Step 0.
  • The process will take some time. The dumped files will be saved in a backup subfolder within the mtkclient directory. Keep this backup in a safe place.
  • Once the process is complete and mtkclient finishes, disconnect your phone from the PC.

2. Unlock the Bootloader

Unlocking the bootloader allows you to flash custom images like GSIs. This step will erase all data on your phone (factory reset).

  • Your phone should be disconnected and powered off from completing the previous step.
  • In the command prompt (in mtkclient directory), type: 
    python mtk.py da seccfg unlock
  • Connect your phone in BROM mode as described in Step 0.
  • mtkclient will perform the unlock. The phone will not automatically reboot after this process.
  • If mtkclient indicates the unlock was successful (or if it completes without errors that suggest failure), it is safe to proceed.
  • Once the unlock process is complete and mtkclient finishes, disconnect your phone from the PC.

3. Flash Modified vendor.img

This specific vendor.img is modified to bypass FBE (File-Based Encryption) checks that prevent most GSIs from booting on the Nokia 2.3.

  • Download the modified vendor image: vendor_mod.bin (Save it to your mtkclient directory or note its path).
  • Your phone should be disconnected and powered off from completing the previous step.
  • In the command prompt, type (replace vendor_mod.bin with the actual path if it's not in the mtkclient directory): 
    python mtk.py w vendor_a,vendor_b vendor_mod.bin,vendor_mod.bin
    Note: This flashes the vendor_mod.bin to both slots (vendor_a and vendor_b) which is standard for A/B partition devices like the Nokia 2.3.
  • Connect your phone in BROM mode.
  • Once the flashing process is complete and mtkclient finishes, disconnect your phone from the PC.

4. Flash Empty/Disabled vbmeta

This step disables Android Verified Boot (AVB), which would otherwise prevent booting with a modified vendor or GSI.

  • You will need vbmeta_a.bin and vbmeta_b.bin files that are either empty or patched to disable verification. You should have these from your full firmware dump (Step 1). If not, you might need to find or create them specifically for your device model and firmware version.

  • Boot your phone into Fastboot Mode:

    • With the phone powered off, press and hold Volume Down + Power button until you see the fastboot/bootloader screen.
    • Connect the phone to your PC.
    • Open a new command prompt (or use the existing one, but ensure ADB/Fastboot drivers are working) and type fastboot devices to check the connection.

  • Flash vbmeta to both slots:

    fastboot --disable-verity --disable-verification flash vbmeta_a vbmeta_a.bin
fastboot --disable-verity --disable-verification flash vbmeta_b vbmeta_b.bin

    (Ensure you have the correct vbmeta_a.bin and vbmeta_b.bin files for your device).

    Note: After fastboot operations, you typically don't need to disconnect/reconnect unless switching modes.

5. Flash the GSI (Generic System Image)

Now you will flash the actual GSI.

  • Download a GSI image compatible with Nokia 2.3. The Nokia 2.3 is an arm32_binder64 device. This means it has a 32-bit ARM system but can run 64-bit userspace components. Look for GSIs with a64 or arm32_binder64 in their name, and typically bvN (vanilla, no GApps, VNDKLite) or bgN (GApps included, VNDKLite) are good choices.

  • Ensure your phone is still in Fastboot Mode.

  • In the command prompt, flash the GSI to the system partition (replace name_of_your_gsi.img with the actual filename of your GSI):

    fastboot flash system name_of_your_gsi.img

    This process can take several minutes.

    Note: After fastboot operations, you typically don't need to disconnect/reconnect unless switching modes.

6. Wipe Userdata (Factory Reset)

This step is mandatory after flashing the GSI and the modified vendor image. It removes leftover FBE encryption configurations and prepares the /data partition for the new system. For the Nokia 2.3, this must be done using mtkclient as fastboot wipe commands may not work correctly.

  • Your phone should be disconnected and powered off from completing the previous fastboot operations (or any prior step).
  • In the command prompt (in mtkclient directory), type: 
    python mtk.py e metadata,userdata
  • Connect your phone in BROM mode as described in Step 0.
  • Once the erase process is complete and mtkclient finishes, disconnect your phone from the PC.
  • After this, you can attempt to boot your phone normally.

The first boot after GSI installation and userdata wipe can take a long time (5-15 minutes). Be patient.

Optional: Install Magisk (Root)

If you want to root your GSI, you can install Magisk. The general process involves patching your device's boot.img

A. Obtain boot.img

  • You should have boot_a.img and boot_b.img from your stock firmware dump (Step 1 in the main guide).
  • Determine the active slot: Before proceeding, you need to know which boot image to patch (boot_a.img or boot_b.img).
    • Boot your phone into Fastboot Mode (Volume Down + Power, then connect USB).
    • In a command prompt, type: fastboot getvar current-slot (or fastboot getvar all and look for (bootloader) current-slot).
    • This will return a or b. Note this down.
  • Copy the boot.img corresponding to your active slot (e.g., if active slot is a, copy boot_a.img) to your phone's internal storage or an SD card. For easier selection in the Magisk app, you can rename this copied file to boot.img on your phone.

B. Patch boot.img with Magisk App

  • Download the latest Magisk APK from the official GitHub repository: https://github.com/topjohnwu/Magisk/releases
  • Install the Magisk APK on your Nokia 2.3 (after the GSI has successfully booted up and is set up).
  • Open the Magisk app.
  • Tap on "Install" (next to "Magisk").
  • Choose "Select and Patch a File" and navigate to where you copied your boot.img.
  • Magisk will patch the file and save it as magisk_patched-[version]_[random_chars].img in your phone's Download folder. Copy this patched boot image back to your PC.

C. Flash Patched boot.img

  • Reboot your phone into Fastboot Mode.
  • In a command prompt on your PC, navigate to where you saved the patched boot image (e.g., magisk_patched.img).
  • Flash the patched boot image to the same slot you identified as active and from which you took the original boot.img.
    • If your active slot was a (and you patched boot_a.img): 
      fastboot flash boot_a magisk_patched.img
    • If your active slot was b (and you patched boot_b.img): 
      fastboot flash boot_b magisk_patched.img
  • It is generally not recommended to flash a patched boot.img meant for one slot to the other slot, or to use the generic fastboot flash boot magisk_patched.img unless you are certain of its compatibility with the active slot system. Sticking to the active slot's boot image is safer.

D. Reboot and Verify

  • Reboot your phone: 
    fastboot reboot
  • Once booted, open the Magisk app. It should show Magisk as installed with the latest version. If it asks to do additional setup, allow it.

Why is this vendor.img needed on Nokia 2.3?

While most modern GSI builds support FBE (file-based encryption), the Nokia 2.3 (MT6761) has a vendor configuration that prevents booting unless encryption is fully initialized by its stock components.

This is due to the following HALs (Hardware Abstraction Layers) located in the stock Android 11 vendor.img:

/vendor/lib/hw/keystore.*.so
/vendor/lib64/hw/keystore.*.so

These libraries are responsible for initializing the hardware-backed keystore during the boot process and expect a valid FBE configuration specific to Nokia's firmware. Since GSI images lack Nokia's proprietary FBE provisioning logic and keys, the presence of these stock keystore HALs leads to a boot failure or bootloop when a GSI tries to boot, as the encryption context cannot be established as expected.

By removing these keystore* HAL files from vendor.img (which is what vendor_mod.bin does), we:

  • Effectively disable the device's specific hardware-backed keystore HAL during early boot.
  • Prevent the FBE checks tied to these HALs from halting the boot process.
  • Allow the GSI to boot on an unencrypted or differently encrypted /data partition (GSIs typically handle their own encryption setup if desired, or run without it if /data is formatted).

Implications of using the modified vendor.img:

  • No hardware-backed keystore features from the stock firmware. This might affect very specific apps that strictly require the device's original hardware keystore for certain cryptographic operations (e.g., some high-security banking apps or DRM for specific content). However, for most apps and general GSI usage, this is not an issue as Android has software-based fallbacks.
  • Some apps requiring the highest level of secure storage might behave differently or report lower security.
  • You must wipe /data (factory reset) after flashing this modified vendor and before booting the GSI for the first time to avoid conflicts.
  • This modified vendor is based on stock Android 11 firmware. It should generally be compatible with GSIs based on Android 11 or higher, but ensure your stock boot.img (or a GSI-compatible boot.img) is also appropriate for the GSI you are using. The primary goal is to make vendor compatible.

Tested working with (examples, many others might work):

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment