Draft:Porting to a new device/First boot
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
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:
- WiFi - WiFi
- Display - Display, Screen Calibration
- Touchscreen - Touchscreen
- Audio - Audio
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:
- USB Internet - sharing the internet connection from your computer to your device over USB. Requires working USB networking.
- WiFi, if your device has it and you got it to work (see #Getting individual components working section above).
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.