Difference between revisions of "User:Fxc/Software Draft"

From PINE64
Jump to navigation Jump to search
(Copied from the main article)
 
(new text)
Line 1: Line 1:
== Software ==
== Software ==


At the time of the release, in late 2021, the PinePhone Pro is in an early development stage. That said, the device has benefited greatly from work done on the original PinePhone, which means that even early development images feature all core functionality, such as: functional UI, sensors and even the modem (to a degree).
The software section explains how to install available software releases for the PinePhone Pro to the external or the internal memory and how to boot them and addresses common problems with booting the phone.


The development is expected to proceed very quickly compared to progress done on the original PinePhone as much of the fundamental work can carry over to the new device.
{{Info|Images of the regular PinePhone are not compatible with the PinePhone Pro.}}
You can follow development efforts on [https://xnux.eu/log/ Megi's blog], the dedicated [[PinePhone Pro Development]] section as well as on individual project’s Wiki’s and repositories.
 
=== Software releases ===
 
The [[PinePhone Pro Software Releases]] page has a complete list of currently supported phone-optimized operating system images that work with the PinePhone Pro.


=== Boot order ===
=== Boot order ===


The PinePhone Pro's internal storage (called ''eMMC'') has a higher boot priority than the microSD card (see [[RK3399 boot sequence#Boot sequence details|boot sequence details]] for details regarding the boot sequence).
The RK3399S in the PinePhone Pro searches for the bootloader (for example the ''U-Boot SPL'') in the following order:


The '''Explorer Edition''' comes pre-flashed with an installation of Manjaro (using the Plasma Mobile desktop) on the internal storage. The pre-flashed operating system can be overwritten at any time and it is also possible to wipe the pre-flashed operating system to make the phone boot from a microSD card, please see the [[PinePhone Pro#Installation instructions|installation instructions]] for the details. The eMMC on the Explorer Edition can be bypassed by holding the ''RE'' button underneath the back cover for multiple seconds while booting. Please see the section [[PinePhone Pro#Bypassing the eMMC|bypassing the eMMC]] for details on how to do this.
# SPI flash
# eMMC (the internal memory)
# MicroSD card


The '''Developer Edition''', which was an earlier revision intended for development, was coming with an Android factory OS preinstalled. For details regarding how to remove the bootloader and the preinstalled OS of the eMMC for Developer Edition, please see the relevant [[PinePhone Pro Developer Edition#Nuking the factory AOSP installation|article]]. The eMMC on the Developer Edition can be bypassed by shorting two specific contact points, please join the community chat for any questions regarding the process.
The bootloader on the corresponding storage devices (for example the ''U-Boot SPL'') can deviate from that fixed hardware boot order in software.


=== Installation instructions ===
The SPI flash and the eMMC can be temporarily bypassed at boot by disconnecting them temporarily using the following method, for example in case of the installation on the SPI flash or the eMMC being corrupted:


{{Template:note|Please ask in the [[Main Page#Chat Platforms|community chat]] if you have any questions regarding the installation.}}
* On the '''Explorer Edition''' hold the ''RE'' button underneath the cover for a few seconds, while powering on the device.


As explained in the [[PinePhone Pro#Boot order|boot order]] section, the eMMC has a higher boot priority than the microSD card. On the '''Explorer Edition''' the default installation of U-Boot shipped by the factory points to the microSD card when holding the power key at boot. If the default installation was corrupted or overwritten by a differently configured bootloader, the eMMC may have to be bypassed to boot from microSD card and to alter the eMMC contents.
* On the '''Developer Edition''', which was an earlier revision intended for developers only, the SPI and the eMMC can be bypassed by shorting the bypass contact points while booting. The process is explained in the article [[PinePhone Pro Developer Edition#Nuking the factory AOSP installation|PinePhone Pro Developer Edition]]. Please join the community chat for any questions regarding the process.


{{hint|If the '''battery is fully drained''' U-Boot might fail to boot any installed operating system on the eMMC and microSD card due to a bug.  
The bypass disconnects the SPI and the eMMC while being held and the PinePhone Pro will try to boot from the next available boot medium, which is the microSD card. Note: When holding the ''RE'' button (or when shorting the contact points in case of the ''Developer Edition'') for a longer time at boot the operating system will not initialize the SPI and eMMC and it will not be possible to write to these storage mediums until the next reboot.


If that's the case please start your phone in Maskrom mode and let it charge in that for a few hours. To do that:
{{Info|The bootloader (such as ''U-Boot'') resides in the free space in front of the first partition. Wiping the bootloader from the eMMC to make the PinePhone Pro boot from microSD card can be done using <code>sudo dd if&#61;/dev/zero of&#61;/dev/mmcblk2 seek&#61;64 count&#61;400 conv&#61;fsync</code>. Formatting the drive or deleting the partition table is not sufficient to wipe the bootloader.}}


* Remove any microSD card from the phone and keep it removed for the below procedure
See [[RK3399 boot sequence]] for details regarding the boot sequence.
* Remove the battery, any USB cable and any serial cable
* Reinsert the battery
* Hold the "RE" button underneath the back cover of your '''Explorer Edition''' (or shorting the bypass contact points on the '''Developer Edition''')
* Connect the phone to an USB port of a computer, while still holding the button for some time
* Check if the phone in Maskrom mode appears in the output of the Linux command <code>lsusb</code> on the computer
* Let the phone charge for multiple hours


Note: If the device doesn't appear under ''lsusb'' please try again with a different known good USB-C cable make sure that there is no microSD card in the phone inserted.
=== Installation instructions ===


It can be checked if the battery is charged or not by putting the phone into Maskrom mode and by removing the USB cable for 30 seconds and reinserting it into the computer. If the device reappears under ''lsusb'' the battery is not drained and the installed operating system on the eMMC is instead corrupted, in that case please see the following flashing instructions.
The software releases can be installed (the process is being referred to as ''flashing'') to the eMMC or to an microSD card.
}}


==== Flashing to microSD card ====
==== Flashing to microSD card ====
To install an image to the microSD card:
To install an image to the microSD card:


# Download your chosen image from [[PinePhone Pro Software Releases]]
# Download a compatible image from [[PinePhone Pro Software Releases]]
# Extract the compressed file
# Extract the compressed image
# Write the image to your microSD card using your favorite method, examples:
# Write the image to your microSD card using your favorite method, examples:
#* Using ''dd'': On the device you're flashing the microSD card from, find the correct device under <code>lsblk</code> and then flash the image to the microSD card using <code>sudo dd if=pine.img of=/dev/'''[DEVICE]''' bs=1M status=progress conv=fsync</code>. Make sure the target is the whole microSD card and not its first partition (''sdc1'' or ''mmcblk0p1'' are wrong!).
#* Using ''dd'': On the device you're flashing the microSD card from, find the correct device under <code>lsblk</code> and then flash the image to the microSD card using <code>sudo dd if='''IMAGE.img''' of=/dev/'''[DEVICE]''' bs=1M status=progress conv=fsync</code>. Make sure the target is the whole microSD card and not its first partition (''sdc1'' or ''mmcblk0p1'' are wrong!).
#* Using ''bmaptool'': Make sure to select the correct device using <code>lsblk</code>. Then run bmaptool with the correct device: Download the ''.img.xz'' and the ''.img.bmap'' files, then run <code>bmaptool copy --bmap image.bmap image.xz /dev/'''[DEVICE]'''</code>. This takes around 2.5 minutes to flash a 4 GB file.
#* Using ''bmaptool'': Make sure to select the correct device using <code>lsblk</code>. Then run bmaptool with the correct device: Download the ''IMAGE.xz'' and the 'IMAGE.bmap'' files, then run <code>bmaptool copy --bmap '''IMAGE.bmap''' '''IMAGE.xz''' /dev/'''[DEVICE]'''</code>. This takes around 2.5 minutes to flash a 4 GB file.
#* Using ''a graphical tool'': A graphical tool such as Gnome Disks under Linux or Etcher under Windows may also be used.
#* Using ''a graphical tool'': A graphical tool such as Gnome Disks under Linux or Etcher under Windows may also be used.
# Insert the microSD card into the top slot of the phone
# Insert the microSD card into the top slot of the PinePhone Pro. Make sure the microSD card is inserted all the way and that the notch of the right side of the microSD card is not visible anymore.
# Boot the phone. If there is an '''existing bootloader on the eMMC''' (the eMMC has a [[PinePhone Pro#Boot order|higher boot priority]]) you need to [[PinePhone Pro#Bypassing the eMMC|bypass the eMMC]] at boot and you can [[PinePhone Pro#Wipe U-Boot from the eMMC|wipe the bootloader from the eMMC]] to default boot from the microSD card by default in the freshly booted installation.
# Power on the PinePhone Pro. If there is an '''existing bootloader on the eMMC''' already you need to bypass or wipe the bootloader on the eMMC as explained in the section [[PinePhone Pro#Boot order]]


==== Flashing to the eMMC ====
==== Flashing to the eMMC ====
Flashing to the eMMC can be done by booting an operating system from the microSD and by writing to the eMMC directly from there:


Flashing to the eMMC can be simply done by booting an operating system from the microSD and to flash the eMMC from there:
# Boot an operating system from the microSD card. If there is already a bootloader on the eMMC installed see the section [[PinePhone Pro#Boot order]] to bypass it
 
# Download or copy the desired image to the microSD card as file
# Boot an operating system from the microSD card. If there is already a bootloader on the eMMC installed see the section [[PinePhone Pro#Bypassing the eMMC|bypassing the eMMC]] to bypass it
# Check if the eMMC appears under <code>lsblk</code>. If it doesn't appear in the output of the command, the eMMC wasn't initialized due to applying the above explained bypass method for a too long time during the boot
# Download or copy the new image to the microSD card
# Check if the eMMC appears under <code>lsblk</code>. If it doesn't appear there you held the ''RE'' button in the eMMC bypass for too long (the eMMC didn't initialize then)
# Extract the image
# Extract the image
# Flash the extracted image using <code>sudo dd if='''IMAGE.img''' of=/dev/mmcblk2 bs=1M status=progress conv=fsync</code>
# Flash the extracted image using <code>sudo dd if='''IMAGE.img''' of=/dev/mmcblk2 bs=1M status=progress conv=fsync</code>
# Reboot the phone
# Reboot the PinePhone Pro


==== Bypassing the eMMC ====
=== Troubleshooting ===


The eMMC can always be temporarily bypassed at boot to be able to boot from a microSD card:
If the PinePhone Pro is not booting (either booting incompletely into a boot splash or tty or if the PinePhone Pro is showing no signs of life) this will typically have the following two reasons:


On the '''Explorer Edition''' hold the ''RE'' button underneath the cover for a few seconds, while powering on the device (holding it too long will cause the eMMC to not get initialized after the boot).
{{hint|If the '''battery is fully drained''' U-Boot might fail to boot any installed operating system on the eMMC and microSD card due to a bug.  


On the '''Developer Edition''' short the eMMC bypass contacts while booting.
If that's the case please start your phone in Maskrom mode and let it charge in that for a few hours. To do that:


For details see the section [[PinePhone Pro#Boot order|boot order]].
* Remove any microSD card from the phone and keep it removed for the below procedure
* Remove the battery, any USB cable and any serial cable
* Reinsert the battery
* Hold the "RE" button underneath the back cover of your '''Explorer Edition''' (or shorting the bypass contact points on the '''Developer Edition''')
* Connect the phone to an USB port of a computer, while still holding the button for some time
* Check if the phone in Maskrom mode appears in the output of the Linux command <code>lsusb</code> on the computer
* Let the phone charge for multiple hours


==== Wipe U-Boot from the eMMC ====
Note: If the device doesn't appear under ''lsusb'' please try again with a different known good USB-C cable make sure that there is no microSD card in the phone inserted.
To boot from microSD card permanently, one of the methods is to wipe the bootloader from the eMMC. If no bootloader is found on the eMMC, the phone will boot to the microSD card instead. To wipe U-Boot from the microSD card:


* Boot a GNU/Linux operating system from the microSD card by holding power at boot (or using the above bypass method if the bootloader was altered or the Developer Edition is used)
It can be checked if the battery is charged or not by putting the phone into Maskrom mode and by removing the USB cable for 30 seconds and reinserting it into the computer. If the device reappears under ''lsusb'' the battery is not drained and the installed operating system on the eMMC is instead corrupted, in that case please see the following flashing instructions.
* Type <code>lsblk</code> in a terminal on the phone to list the devices
}}
* Wipe the bootloader using <code>sudo dd if=/dev/zero of=/dev/mmcblk2 seek=64 count=400 conv=fsync</code>
 
The phone should now default to the microSD card at boot.
 
If there are any issues please join the bridged [[Main Page#Community and Support|community PinePhone channel]] and explain your issue and what you've tried so far.
 
=== Software releases ===
 
The [[PinePhone Pro Software Releases]] page has a complete list of currently supported phone-optimized operating system images that work with the PinePhone Pro.

Revision as of 10:14, 12 April 2022

Software

The software section explains how to install available software releases for the PinePhone Pro to the external or the internal memory and how to boot them and addresses common problems with booting the phone.

Note: Images of the regular PinePhone are not compatible with the PinePhone Pro.

Software releases

The PinePhone Pro Software Releases page has a complete list of currently supported phone-optimized operating system images that work with the PinePhone Pro.

Boot order

The RK3399S in the PinePhone Pro searches for the bootloader (for example the U-Boot SPL) in the following order:

  1. SPI flash
  2. eMMC (the internal memory)
  3. MicroSD card

The bootloader on the corresponding storage devices (for example the U-Boot SPL) can deviate from that fixed hardware boot order in software.

The SPI flash and the eMMC can be temporarily bypassed at boot by disconnecting them temporarily using the following method, for example in case of the installation on the SPI flash or the eMMC being corrupted:

  • On the Explorer Edition hold the RE button underneath the cover for a few seconds, while powering on the device.
  • On the Developer Edition, which was an earlier revision intended for developers only, the SPI and the eMMC can be bypassed by shorting the bypass contact points while booting. The process is explained in the article PinePhone Pro Developer Edition. Please join the community chat for any questions regarding the process.

The bypass disconnects the SPI and the eMMC while being held and the PinePhone Pro will try to boot from the next available boot medium, which is the microSD card. Note: When holding the RE button (or when shorting the contact points in case of the Developer Edition) for a longer time at boot the operating system will not initialize the SPI and eMMC and it will not be possible to write to these storage mediums until the next reboot.

Note: The bootloader (such as U-Boot) resides in the free space in front of the first partition. Wiping the bootloader from the eMMC to make the PinePhone Pro boot from microSD card can be done using sudo dd if=/dev/zero of=/dev/mmcblk2 seek=64 count=400 conv=fsync. Formatting the drive or deleting the partition table is not sufficient to wipe the bootloader.

See RK3399 boot sequence for details regarding the boot sequence.

Installation instructions

The software releases can be installed (the process is being referred to as flashing) to the eMMC or to an microSD card.

Flashing to microSD card

To install an image to the microSD card:

  1. Download a compatible image from PinePhone Pro Software Releases
  2. Extract the compressed image
  3. Write the image to your microSD card using your favorite method, examples:
    • Using dd: On the device you're flashing the microSD card from, find the correct device under lsblk and then flash the image to the microSD card using sudo dd if=IMAGE.img of=/dev/[DEVICE] bs=1M status=progress conv=fsync. Make sure the target is the whole microSD card and not its first partition (sdc1 or mmcblk0p1 are wrong!).
    • Using bmaptool: Make sure to select the correct device using lsblk. Then run bmaptool with the correct device: Download the IMAGE.xz and the 'IMAGE.bmap files, then run bmaptool copy --bmap IMAGE.bmap IMAGE.xz /dev/[DEVICE]. This takes around 2.5 minutes to flash a 4 GB file.
    • Using a graphical tool: A graphical tool such as Gnome Disks under Linux or Etcher under Windows may also be used.
  4. Insert the microSD card into the top slot of the PinePhone Pro. Make sure the microSD card is inserted all the way and that the notch of the right side of the microSD card is not visible anymore.
  5. Power on the PinePhone Pro. If there is an existing bootloader on the eMMC already you need to bypass or wipe the bootloader on the eMMC as explained in the section PinePhone Pro#Boot order

Flashing to the eMMC

Flashing to the eMMC can be done by booting an operating system from the microSD and by writing to the eMMC directly from there:

  1. Boot an operating system from the microSD card. If there is already a bootloader on the eMMC installed see the section PinePhone Pro#Boot order to bypass it
  2. Download or copy the desired image to the microSD card as file
  3. Check if the eMMC appears under lsblk. If it doesn't appear in the output of the command, the eMMC wasn't initialized due to applying the above explained bypass method for a too long time during the boot
  4. Extract the image
  5. Flash the extracted image using sudo dd if=IMAGE.img of=/dev/mmcblk2 bs=1M status=progress conv=fsync
  6. Reboot the PinePhone Pro

Troubleshooting

If the PinePhone Pro is not booting (either booting incompletely into a boot splash or tty or if the PinePhone Pro is showing no signs of life) this will typically have the following two reasons:

If the battery is fully drained U-Boot might fail to boot any installed operating system on the eMMC and microSD card due to a bug.

If that's the case please start your phone in Maskrom mode and let it charge in that for a few hours. To do that:

  • Remove any microSD card from the phone and keep it removed for the below procedure
  • Remove the battery, any USB cable and any serial cable
  • Reinsert the battery
  • Hold the "RE" button underneath the back cover of your Explorer Edition (or shorting the bypass contact points on the Developer Edition)
  • Connect the phone to an USB port of a computer, while still holding the button for some time
  • Check if the phone in Maskrom mode appears in the output of the Linux command lsusb on the computer
  • Let the phone charge for multiple hours

Note: If the device doesn't appear under lsusb please try again with a different known good USB-C cable make sure that there is no microSD card in the phone inserted.

It can be checked if the battery is charged or not by putting the phone into Maskrom mode and by removing the USB cable for 30 seconds and reinserting it into the computer. If the device reappears under lsusb the battery is not drained and the installed operating system on the eMMC is instead corrupted, in that case please see the following flashing instructions.