OpenStick Image Builder

Image builder for MSM8916 based 4G modem dongles

This builder uses the precompiled kernel provided by postmarketOS for Qualcomm MSM8916 devices.

Note

Branch overview:

• debian : Debian (stable) based image (default branch).
• ubuntu-24.04 : Ubuntu 24.04 LTS (Noble) based image (identical build steps).
• Alpine (upstream) : Refer to the original repository's alpine branch (not maintained here).

Build Instructions

Build locally

This has been tested to work on Ubuntu 22.04, 24.04 and 25.04

• clone

  git clone --recurse-submodules https://github.com/Mio-sha512/OpenStick-Builder.git
  cd OpenStick-Builder/

Quick (Debian branch)

git checkout debian
sudo ./build.sh

Quick (Ubuntu 24.04 branch)

git checkout ubuntu-24.04
sudo ./build.sh

Detailed (same for any branch)

• install dependencies

  sudo scripts/install_deps.sh

• build hyp and lk2nd

  These custom bootloaders allow basic support for an extlinux.conf file, similar to U-Boot and Depthcharge.

  sudo scripts/build_hyp_aboot.sh

• extract Qualcomm firmware

  Extracts the bootloader and creates a new partition table that utilizes the full eMMC space

  sudo scripts/extract_fw.sh

• create rootfs using debootstrap

  sudo scripts/debootstrap.sh

• build gadget-tools

  sudo scripts/build_gt.sh

• create images

  sudo scripts/build_images.sh

The generated firmware files will be stored under the files directory

On the cloud using Github Actions

1. Fork this repo
2. Run the Build workflow
   • click and run Run workflow
   • once the workflow is done, click on the workflow summary and then download the resulting artifact

Customizations

Edit scripts/setup.sh to add/remove packages. Note that this script is running inside the chroot environment.

Firmware Installation

Warning

The following commands can potentially brick your device, making it unbootable. Proceed with caution and at your own risk!

Important

Make sure to perform a backup of the original firmware using the command edl rf orig_fw.bin

Prerequisites

• EDL
• Android fastboot tool

  sudo apt install fastboot
  

Steps

• Ensure that your device is running the stock firmware

• Enter Qualcomm EDL mode using this guide

• Backup required partitions

  The following files are required from the original firmware:

  • fsc.bin
  • fsg.bin
  • modem.bin
  • modemst1.bin
  • modemst2.bin
  • persist.bin
  • sec.bin

  Skip this step if these files are already present

  for n in fsc fsg modem modemst1 modemst2 persist sec; do
      edl r ${n} ${n}.bin
  done

• Install aboot

  edl w aboot aboot.mbn

• Reboot to fastboot

  edl e boot
  edl reset

• Flash firmware

  fastboot flash partition gpt_both0.bin
  fastboot flash aboot aboot.mbn
  fastboot flash hyp hyp.mbn
  fastboot flash rpm rpm.mbn
  fastboot flash sbl1 sbl1.mbn
  fastboot flash tz tz.mbn
  fastboot flash boot boot.bin
  fastboot flash rootfs rootfs.bin

• Restore original partitions

  for n in fsc fsg modem modemst1 modemst2 persist sec; do
      fastboot flash ${n} ${n}.bin
  done

• Reboot

  fastboot reboot

Post-Install

• Network configuration

  ssid	4G-UFI-XX
  password	1234567890
  ip addr	192.168.100.1

• Default user

  username	user
  password	1

• If your device is not based on UZ801, modify /boot/extlinux/extlinux.conf to use the correct devicetree

  sed -i 's/yiming-uz801v3/<BOARD>/' /boot/extlinux/extlinux.conf

  where <BOARD> is

  • thwc-uf896 for UF896 boards
  • thwc-ufi001c for UFIxxx boards
  • jz01-45-v33 for JZxxx boards
  • fy-mf800 for MF800 boards

• To update the kernel of the debian image

• Get the kernel link from: http://mirror.postmarketos.org/postmarketos/master/aarch64/

  wget -O - http://mirror.postmarketos.org/postmarketos/master/aarch64/linux-postmarketos-qcom-msm8916-6.12.1-r2.apk \
          | tar xkzf - -C / --exclude=.PKGINFO --exclude=.SIGN* 2>/dev/null