Jump to content

Draft:Porting to a new device/First boot

From postmarketOS Wiki

With the postmarketOS image and kernel generated and flashed, it is now time to test the port and attempt a first boot.

Troubleshooting boot issues

If you're lucky, the device will boot right up - you'll see the postmarketOS boot splash, and eventually you will be greeted by the UI of your choice.

However, it's likely that the port may not work immediately. In those cases, some additional troubleshooting will be needed.

There is a dedicated page with troubleshooting instructions:

Getting individual components working

Note If you can't figure out how to get a component working, don't worry - you can submit your port now and make a merge request to add the feature later. (TODO reword this note)

Even with the system booting, some components may require additional steps to get working. The following pages contain more information:

Useful hints

You may want to customize your install or otherwise experiment with postmarketOS. Some hints for doing this:

Connecting to the device over USB

By default, postmarketOS is configured to set up a private network over USB. If USB works on your device, you can connect it to your computer and access it over SSH (replace user with the username you set during pmbootstrap init):

$ ssh user@172.16.42.1

If the connection fails, see USB Networking for troubleshooting instructions.

Accessing the internet

You have two ways of accessing the internet from the device:

Installing packages on the device

You can use apk, the package manager, to install new packages. Connect to your device over SSH and run the following command as root:

# apk add hello-world

It is also possible to sideload a package built with pmbootstrap directly to the device using pmbootstrap sideload. Run the following command on your computer (adjust parameters to your use case):

$ pmbootstrap sideload --host 172.16.42.1 --user user --arch <arch> package-name

See Installing packages on a running phone for more information.

Building a new system image

Whenever you rebuild a package (or pick a new one to be installed by default in pmbootstrap init), you need to make sure that the package is actually installed in the chroot from which the system image gets generated.

To do this, run pmbootstrap install again; all outdated packages should be updated. Pay attention to the output of pmbootstrap log to see if it actually has been updated. Afterwards, you can reflash the image as described on the previous page.

If something did not work as expected, you can always pmbootstrap zap your chroots to start over with a clean installation.

Recompiling the kernel

To recompile the Linux kernel (e.g. because you want to change your kernel config) and flash it to your device, run the following commands:

$ pmbootstrap build --force linux-vendor-codename
$ pmbootstrap install
$ pmbootstrap sideload linux-vendor-codename  # requires the device to be running and accessible over USB networking or WiFi; this step ensures that kernel modules and other files are copied over correctly
$ pmbootstrap flasher flash_kernel

The last flash_kernel step is only needed if your device has the kernel stored on an extra boot partition. Android/fastboot compatible devices have such a partition, and Maemo/MeeGo Nokia devices (N900, etc.) typically don't use it. If your device does not have a boot partition, update your system partition or SD card.