DebianOn is an effort to document how to install, configure and use Debian on some specific hardware. Therefore potential buyers would know if that hardware is supported and owners would know how get the best out of that hardware.

The purpose is not to duplicate the Debian Official Documentation, but to document how to install Debian on some specific hardware.

If you need help to get Debian running on your hardware, please have a look at our user support channels where you may find specific channels (mailing list, IRC channel) dedicated to certain types of hardware.

Contents

  1. What's not working
  2. Support
  3. Installation
    1. Known good weekly images
    2. Obtain the Image
    3. Verifying the images
    4. Preparing the Device
    5. Flashing the Image to the Target Device
    6. Fastboot mode
    7. Notes:
      1. General
      2. Qbootctl
      3. Audio
      4. Wi-Fi and Bluetooth
      5. Suspend
      6. Support for serviced devices
      7. Black screen on boot with kernel 6.6 and newer
    8. Default pin and password
    9. Automatic resizing of your filesystem on first boot

What's not working

USB OTG and camera do not work.

Temporarily (as of 2023-08-13), microphone input is distorted and speaker output is broken. Work-arounds: use a bluetooth head set.

Support

If something isn't working for you, you can get in contact with Mobian developers and the Mobian community in various ways. All of them are listed here.

Installation

Known good weekly images

Not all of the weekly images are tested continuously on all devices in all variants. The ones below are known to work and are a good starting point for running testing:

Obtain the Image

Pre-built images for your device are available from https://images.mobian.org/qcom/weekly/, packed in a file named

(where the <family> you are looking for is qcom).

Note that for images built prior to 2024-01-25 the <family> would have been sdm845. and that as well as the qcom directory there are also compatibility links using the old sdm845 and sm7225 family names that lead to the same place.

Verifying the images

Mobian images come with multiple files:

To verify the download, use the following steps:

  1. Import the Mobian signing key from here. Once downloaded, the key can be imported with gpg --import mobian.gpg.

  2. Verify the signature with gpg --verify <downloaded file>.sha256sum.sig.

  3. If the signature is valid, check the other files with shasum -c <downloaded file>.sha256sums

  4. If this prints OK for all files the download is verified.

Preparing the Device

As you would do before installing a custom Android ROM, the bootloader needs to be unlocked. The exact procedure varies depending on the device you own, so we suggest you search the Internet for an unlock guide aimed at your specific device.

We also recommend that you upgrade Android to the latest available version and install all system updates before installing Mobian.

See postmarketOS' installation guide for unlocking bootloader of OnePlus 6 or OnePlus 6T

Flashing the Image to the Target Device

WARNING: Flashing Mobian to your device will wipe your Android installation! Please install recovery software such as TWRP and make sure you understand how to recover your system before proceeding.

Those devices being Android smartphones in the first place, they have secure boot enabled, meaning we can't replace their bootloader and need to rely on Android tools in order to flash Mobian.

In practice, this means we can't flash a single image file, and the downloaded tarball will contain:

Note: Up until 2023-10-22 the archives used to contain an additional image file named mobian-<processor>-phosh-YYYYMMDD.boot.img meant to be flashed to the system partition. This is no longer the case starting with the 2023-10-29 set of images.

As these devices have several variants, which differ only by the device-tree they need, and the DT being part of the bootimg, we provide one bootimg for each variant. You have to flash the one matching your device:

Once you have extracted those files from the tarball, boot your device into fastboot mode, connect it to your computer using a USB cable and run the following commands to install Mobian: 

fastboot flash boot mobian-<processor>-phosh-YYYYMMDD.boot-<model>.img
fastboot -S 100M flash userdata mobian-<processor>-phosh-YYYYMMDD.rootfs.img
fastboot erase dtbo

If all steps above succeeded, reboot your phone.

Fastboot mode

When the device is shut off, the OnePlus 6 (enchilada) can be put in fastboot mode by pressing and keeping pressed the power and volume up buttons, until a screen with a green 'START' writing appears. Different entries can be navigated with volume buttons and entered with power button.

Similarly, the OnePlus 6T (fajita) can be put in fastboot mode by pressing and keeping pressed the power and both volume buttons.

Notes:

General

Qbootctl

As of November 2023, qbootctl is available in Debian but not yet included in SDM845 Mobian images. It is needed to reset slot-retry-count for the active slot to 7 on every boot, otherwise that flag gets decremented at every boot and the device will consider it unbootable when it reaches 0, refusing to boot whatever OS is on that slot.

After installing qbootctl, until Debian bug #1057918 is fixed, one can either use systemctl edit qbootctl to edit the unit's config, in order to add: 

[Install]
WantedBy=multi-user.target

or alternatively execute the following in a console 

echo -e "\n[Install]\nWantedBy=multi-user.target" | sudo tee -a /lib/systemd/system/qbootctl.service

Please note, qbootctl gets the active slot by looking for a androidboot.slot_suffix string (that's not yet implemented in Mobian) inside /proc/cmdline: if that string it's not found, it considers the active slot to be 'a'.

So if you have installed to slot 'b' you can currently work around this by also adding the following while editing the unit's config: 

[Service]
ExecStart=
ExecStart=/usr/bin/qbootctl -m b

Having added any required config tweaks, you can enable the unit thus: 

sudo systemctl enable qbootctl

Recovering from refusal to boot, due to not having installed qbootctl

Assuming you installed on slot 'b', you should be able to reset the counter, by running this on your computer (while the phone's plugged in and in fastboot mode): 

fastboot --set-active=a
fastboot --set-active=b

Installation in slot b is currently untested.

Audio

General Audio

Voice Call

The /etc/q6voiced.conf content (tested with enchilada) 

q6voice_card=0
q6voice_device=6

[Unit]
Description=Disable pulseaudio/pipewire suspend-on-idle module during call
After=ModemManager.service
ConditionUser=!@system

[Service]
ExecStart=/usr/local/bin/call_audio_idle_suspend_workaround.sh

Restart=on-failure
RestartSec=10s

[Install]
WantedBy=default.target

Wi-Fi and Bluetooth

In order to keep a stable MAC address for the Wi-Fi wlan0 interface and to set the MAC address of Bluetooth hci0 interface. You need to set it every boot, there is a tool from pmOS which was developed for this task bootmac

Suspend

While in suspend the phone by default will NOT resume on call, It can be enabled according to the pmOS Wiki page for the SDM845 SoC page. The setting is on the /sys partition. There is a tool packaged in debian sysfsutils which can change /sys settings on boot like sysctl for /proc/sys. Add the following file in /etc/sysfs.d/ to enable all wake-up events (SMS, calls, network change ...) from the modem 

bus/rpmsg/devices/4080000.remoteproc:glink-edge.IPCRTR.-1.-1/power/wakeup = enabled

Support for serviced devices

cd /usr/lib/linux-image-6.6-sdm845/qcom/
sudo dtc sdm845-oneplus-enchilada.dtb -o temp.dts
sudo sed -i 's/bq27441/bq27541/' temp.dts 
sudo sed -i 's/bq27411/bq27541/' temp.dts
sudo dtc temp.dts -o sdm845-oneplus-enchilada.dtb 
sudo update-initramfs -u
sudo /etc/kernel/postinst.d/zz-qcom-bootimg 6.6-sdm845

Black screen on boot with kernel 6.6 and newer

Please note: procedures reported in this section should not be needed any more, after mobian-recipes#c8534fb0 and mobian-recipes#1aae0572. Weekly images built since 20240915 should be fine with respect to this. This section is kept for reference and for fixing older images/systems.

As reported in the relevant pmOS edge breakage report, starting with kernel version 6.6, it can happen that the device boots into black screen: the device is actually on, but there is no way to turn the screen on. This can be especially annoying on the first boot of a freshly flashed system, because some tweaks (e.g. audio) cannot be applied in a later stage. Workaround for this issue until a proper upstream fix is found:

This applies to both fajita and enchilada. Note that that the kernel command line might already include console=ttyMSM0,115200 but you still need to append loglevel=7 .

The procedure to apply the workaround to an already flashed system (e.g. when upgrading to a kernel version that is affected): 

$ ls -lah /dev/disk/by-partlabel/
[...]
lrwxrwxrwx 1 root root   11 29 mag  1970 boot_a -> ../../sde11
lrwxrwxrwx 1 root root   11 29 mag  1970 boot_b -> ../../sde39
[...]

Default pin and password

The default user is mobian and has the password 1234 . It is also used as PIN on the unlock screen.

The root user is locked by default.

You should change the user password: please check man passwd on whatever Debian command-line interface for more information about this. If you want to access your phone via ssh, please check SSH#Installation_of_the_server and SSH#With_password about the right way to do so.

Automatic resizing of your filesystem on first boot

After flashing the image and booting for the first time, Mobian will resize the root filesystem to take all possible space on the disk. This can take a while and will only happen on first boot. So grab a ${DRINK_OF_CHOICE} and be patient.