BlackBerry KEY2 Generic (blackberry-key2-generic)

U-Boot
Primary Bootloader Whether it is possible to replace stock bootloader with U-Boot.	Broken
Secondary Bootloader Whether it is possible to chainload U-Boot from stock bootloader.	Works
Mainline Whether latest upstream versions of U-Boot are not broken and it is possible to use them.	Partial
Internal Storage Whether it is possible to boot from internal storage (e.g. eMMC or UFS).	Works
SD card Whether it is possible to boot from SD card.	Works
USB Host Whether it is possible to boot from a USB storage or connect a keyboard.	Untested
USB Peripheral Whether it is possible to use device as a peripheral in U-Boot, e.g. for fastboot mode.	Works
Display	Works
Keyboard	Broken
Buttons Whether it is possible to navigate in boot menu or grub with volume and power buttons.	Works

Features
Flashing Whether it is possible to flash the device with pmbootstrap flasher.	Partial
USB Networking After connecting the device with USB to your PC, you can connect to it via telnet (initramfs) or SSH (booted system).	Works
Internal storage eMMC, SD cards, UFS...	Works
SD card Also includes other external storage cards.	Works
Battery Whether charging and battery level reporting work.	Partial
Screen Whether the display works; ideally with sleep mode and brightness control.	Works
Touchscreen	Works
Keyboard Whether the built-in physical keyboard works.	Works
Multimedia
3D Acceleration	Partial
Audio Audio playback, microphone, headset and buttons.	Broken
Camera	Broken
Camera Flash	Broken
Connectivity
WiFi	Works
Bluetooth	Works
GPS	Broken
NFC Near Field Communication	Broken
Modem
Calls	Broken
SMS	Broken
Mobile data	Broken
Miscellaneous
FDE Full disk encryption and unlocking with unl0kr.	Untested
USB OTG USB On-The-Go or USB-C Role switching.	Broken
HDMI/DP Video and audio output with HDMI or DisplayPort.	Untested
Sensors
Accelerometer Handles automatic screen rotation in many interfaces.	Works
Ambient Light Measures the light level; used for automatic screen dimming in many interfaces.	Untested
Hall Effect Measures magnetic fields; usually used as a flip cover sensor	Untested
Haptics	Broken
Power Sensor Sensor to monitor current, voltage and power. Not fuel gauge!	Untested

BlackBerry KEY2 Generic
	; KEY2 (left) and Key2 LE (right) running sxmo
Manufacturer	BlackBerry
Name	KEY2 Generic
Codename	blackberry-key2-generic
Released	2018
Type	generic
Hardware
Chipset	Qualcomm Snapdragon 660 (SDM660) ; Qualcomm Snapdragon 636 (SDM636)
CPU	Octa-core (4x1.8 GHz Kryo 260 Gold ; 4x1.6 GHz Kryo 260 Silver)
GPU	Adreno 509 / Adreno 512
Display	1620x1080@60Hz 4.5" IPS LCD
Storage	32/64GB
Memory	6GB / 4GB
Architecture	aarch64
Software
Original software The software and version the device was shipped with.	Android 8.1 Oreo
Extended version The most recent supported version from the manufacturer.	Android 8.1 Oreo
FOSS bootloader	no
postmarketOS
Category	testing
Pre-built images Whether pre-built images are available from the postmarketOS Installation page.	no
Mainline Instead of a Linux kernel fork, it is possible to run (Close to) Mainline.	yes
pmOS kernel The kernel version that runs on the device's port.	6.19.10
Unixbench score Unixbench Whetstone/Dhrystone score. See Unixbench.	2125.9
Device package	device-blackberry-key2-generic
Kernel package	linux-postmarketos-qcom-sdm660
Firmware package	firmware-blackberry-key2-generic
Initial MR Initial merge request.	pmaports!6830

This is a generic device port consolidating BlackBerry KEY2 (blackberry-athena) and BlackBerry KEY2 LE (blackberry-luna).

Contributors

Maintainers

User:Sajattack

Users owning this device

KEY2 (athena)

BotchedRPR (Notes: Works, LineageOS 22.2)
DiabloSat (Notes: without display)
Jarocks
MarshJ (Notes: Running Droidian)
Metaphy (Notes: Replaced Screen)
R00t
Sajattack (Notes: BOE / Livata Variant, also borrowing a synaptics variant)

KEY2 LE (luna)

BotchedRPR (Notes: Works, audio subsystem dead. LineageOS 22.2)
DiabloSat (Notes: bought for 3000 UAH, slightly damaged case)
Jarocks
R00t
Sajattack (Notes: BOE / Livata Variant)

Status

The port runs with feature support as indicated. GPU crash is pretty consistently hanging the device unless the GPU is disabled in #Post-installation_setup.

You will want to use a UI not relying on 3D acceleration (e.g. sxmo-dwm), also see instructions to disable GPU usage in post-installation setup below.

General

This section describes general points that will be used repeatedly throughout this guide.

How to enter flash mode

Hold Volume Down while powering on, easy.

Uboot

After completing the #Bootloader Unlock step, you are able to start U-Boot. This is a fundamental step, not only for performing #Backups but also for later booting PostmarketOS.

Download U-Boot

You will have to obtain U-Boot for the device separately, as it's not included in pmaports. Prebuilt binaries are available here.

You will need to be logged in to access the download:

Setup (on Linux)

Use Blackberry_Key2_Unlocker (Python)

To boot your device with U-Boot, go to the Blackberry_Key2_Unlocker directory as previously described in #Setup Kibo on Linux.

The Python script requires a dependency; if the script does not run on your system, you can simply install it, for example like this:

python3 -m venv venv
source venv/bin/activate
pip install libusb1

After that, you can start U-Boot. As an argument, you need to specify the U-Boot image, for example:

python3 bb_key2_unlocker.py /path/to/boot-uboot-sdm660-bbry-athena-boe.img

This command may need to be repeated several times for it to work. In my case, it helped to select “Reboot into fastboot” on the BlackBerry and then execute the exploit as soon as the device reappeared in “dmesg -w”. On the second attempt of running the command, it usually worked.

Interestingly, rebooting into fastboot mode using the fastboot command “fastboot reboot fastboot” did not have the same effect.

Use k2fb (precompiled)

Replace orangefox.img in the exploit with u-boot.img, built from sdm660-mainline, then call the script ./run-twrp.sh to start U-Boot. It may take a few tries for the exploit to work.

Enter the U-Boot menu by holding Volume Up while U-Boot starts (after k2fb has sent the fastboot "get-flash-status" command)

Use U-Boot

In general, after executing the chosen exploit to start U-Boot, press Volume Up to enter the U-Boot menu. If you don’t do that, U-Boot will try to find an image on the partitions to boot from.

USB Mass Storage mode

If you select this mode in the U-Boot menu, all partitions on your device will be exposed over USB, allowing you to read from and write to all partitions from a computer (preferably running Linux).

Boot from eMMC

In this mode, U-Boot tries to find an image on the partitions that it can boot from.

Different display panels depending on the variant

Both the Key2 and Key2 LE were manufactured with either of two different display panels.

There is livata/BOE and synaptics.

To find out which one your device has before attempting an installation, you can boot the android recovery or uboot, open the included terminal or connect via adb shell, and run:

# cat /proc/cmdline | grep Panel.Name

The log should have either of:

mdss_dsi_panel_init: Panel Name = Livata video mode dsi panel (this is the panel named boe in the port)
mdss_dsi_panel_init: Panel Name = Synaptics video mode dsi panel (this is the panel named synaptics in the port.)

After doing the #Bootloader Unlock, flash the corresponding U-Boot image for the correct panel to ensure your display and touchscreen work correctly.

Bootloader Unlock

There are several 3rdparty bootloader unlock tools available in #See also.

Kibo is recommended for Linux, and Windows users can make use of the untethered unlock tool from krab and friends. Previous tethered unlocks are less useful and no longer necessary.

WARNING: Even more than on other devices, one needs to be extremely careful manipulating the data on the internal flash. Due to the heavily locked down nature of the Blackberry devices, it is easily possible to get the device into a state where it can neither boot nor be re-flashed, with no known way to recover ("bricked", permanently).

The exploit ships with (and by default installs and runs) a custom android recovery, it is suggested to use that (or U-Boot later) to first make a backup of all your data and all system partitions.

Setup Kibo on Linux

git clone https://github.com/BotchedRPR/kibo
cd kibo 
mkdir build
cd build 
cmake ..
make

Connect your BlackBerry and test your installation with the following command in the kibo "build" directory:

./kibo devinfo

For Kibo to work properly, some additional files still need to be prepared that we need for the exploit. Unfortunately, the filenames are hardcoded in Kibo.

These are ELF files required for this exploit to work. To obtain them, please clone the following repository (beside the kibo folder), which contains these files. This repository will also be used later to backup/boot PostmarketOS (see #Use Blackberry_Key2_Unlocker (Python)).

git clone https://github.com/agreenbhm/Blackberry_Key2_Unlocker

Now copy the files to the location where Kibo expects them, using the correct filenames:

mkdir -p kibo/build/ldr
cp Blackberry_Key2_Unlocker/160 kibo/build/ldr/acq160.exe # please modify if you have the 575 model

With the following command you can now unlock your device. After confirming the unlock on the device, the mode in Fastboot at the top will change from PRODUCT to FACTORY.

./kibo unlock

Backup

Go into the #USB Mass Storage mode

Then make a new folder and run the backup script.

Installation

This port is currently in an early stage, but the code is published, and if you are feeling adventurous, you can build it and install/run it on your device.

Advanced knowledge of Linux and some experience with embedded software development is recommended.

(There are no pre-built images, installation via pmbootstrap is required.)

Read and understand the source install instructions (Installation/Using pmbootstrap). You might even want to try this with another, more mature port (on another device!) first, to familiarize yourself with the process.

You will have to install the most recent version of pmbootstrap from git, any version shipped by your distro is most likely outdated.

When running pmbootstrap init select vendor blackberry, device key2-generic. For the user interface you will probably want to select sxmo-dwm until the GPU crash issue is resolved, as Sxmo is the only interface usable (albeit advanced) on a phone without hardware 3D acceleration.

Run pmbootstrap install --split to generate separate boot and rootfs images.

The port uses an EFI boot setup via U-Boot instead of the more usual android bootimg, the boot image generated by pmbootstrap is an EFI system partition that cannot be booted directly.

More details can be found in pmaports MR !7199.

Once you have all this built, you can install on the device.

WARNING: Even more than on other devices, one needs to be extremely careful manipulating the data on the internal flash. Due to the heavily locked down nature of the Blackberry devices, it is easily possible to get the device into a state where it can neither boot nor be re-flashed, with no known way to recover ("bricked", permanently)

If not done previously for backup purposes (recommended!), flash the U-Boot bootimg into the recovery partition (by modifying the script provided with the k2fb exploit, adjusting it to flash it instead of the android recovery).

You can flash the postmarketOS boot and root image to any partition on the internal flash (or an sdcard partition, which is safer), using cache for the boot image and system or userdata for the root image has been tested. (One may want to flash root to userdatato have more space (but forego the option to re-flash without data loss), or mount the userdata partition at /home later to have space for data.)

You can install the boot/root partitions either with fastboot, or U-Boot USB mass storage (typically more reliable).

Fastboot

Make sure you have run the exploit to unlock the bootloader.

fastboot flash recovery u-boot.img
fastboot flash cache blackberry-key2-generic-boot.img
fastboot flash userdata blackberry-key2-generic-root.img

U-Boot

Go into the #USB Mass Storage mode

dd if=blackberry-key2-generic-boot.img of=/dev/disk/by-partlabel/cache oflag=direct bs=8M status=progress
dd if=blackberry-key2-generic-root.img of=/dev/disk/by-partlabel/userdata oflag=direct bs=8M status=progress

Booting finally into PostmarketOS

Then start U-Boot and perform the following step #Boot from eMMC.

Post-installation setup

Some things that are currently broken or not yet automatically set up need to be fixed after installation:

If the device boots but you can't operate it, it should be possible to access it remotely via USB Networking. You can also setup WiFi (via the Sxmo UI, or after logging in via USB) and then use that for SSH access.

(This does not seem to suffice anymore, with a more recent kernel the screen blacks out unless the gpu driver is also blacklisted, see below.)

GPU

Until the GPU crash is fixed, you will want to disable graphics acceleration completely.

create /etc/profile.d/force-swrast.sh and write the following contents

export LIBGL_ALWAYS_SOFTWARE=1
export QT_XCB_FORCE_SOFTWARE_OPENGL=1
export MESA_LOADER_DRIVER_OVERRIDE=kms_swrast
export WLR_RENDERER_ALLOW_SOFTWARE=1

If you still have graphical glitches, as a last resort, add

export WLR_RENDERER=pixman

Missing characters in text on X11 Based DEs

If you are experiencing the same problem as described in this issue, you can resolve it by disabling 2D acceleration as follows:

cat >/etc/X11/xorg.conf.d/20-modesetting.conf <<'EOF'
Section "Device"
    Identifier "modesetting"
    Driver "modesetting"
    Option "AccelMethod" "none"
EndSection
EOF

Unfortunately, this option has the following effects:

Reduced desktop performance
Higher CPU usage
Slower window movements
Reduced performance when using compositing (e.g. KDE Plasma or XFCE with a compositor)
Video playback may require more CPU resources

Keyboard

If you're using systemd, run the following command, which should in theory set the correct keymap for X11 and Wayland, but in practice may do nothing, depending upon how the desktop environment chooses to respect locale settings:

localectl set-x11-keymap us blackberry-key2

If you're using X11, ensure you install device-blackberry-key2-generic-x11, which contains rules to setup xkb.

If you're using a Gnome-based DE, ask them to add support for selecting a keyboard model

Known issues

Keyboard is not detected

If the keyboard is not properly detected, it can help to reload the kernel module as follows:

rmmod stmpe_keypad
sleep 1
modprobe stmpe_keypad