Difference between revisions of "PinePhone"

From Maemo Leste Wiki
Jump to navigationJump to search
m (Added steps to enable outgoing calls over VoLTE)
 
(96 intermediate revisions by 7 users not shown)
Line 21: Line 21:
}}
}}


The first Pinephone (braveheart) phone
This is for all PinePhones starting with the first Pinephone (Braveheart) phone, but not for the PinePhone Pro.


== Notes ==
== Notes ==


''' [https://maedevu.maemo.org/images/pinephone/ Testing images repo.] '''
Go here for '''[https://maedevu.maemo.org/images/pinephone/ latest images to test.] ''' Please [[Main_Page#Links|get in touch with us]] to report any issues or learn how to help out with the project.


''' What you can do with the 20200223 image:'''
== Status ==
 
Currently, most things work, for example you can:


* Run any applications in Debian and Devuan on your phone
* Run any applications in Debian and Devuan on your phone
* Connect to wifi
* Connect to wifi
* Use the terminal
* Use the terminal
* (With not yet finished userspace, terminal only) connect to 2G/3G/4G data connections
* Connect to 2G/3G/4G data connections
 
* Make and receive phone calls and SMS
''' TODO mention/link to:'''
* PinePhone keyboard is supported


* USB peripheral
* Develop for Maemo Leste and work on applications that interface with modems
* Make it work on latest pine64 kernel
''' Note that: '''
* Virtual keyboard should work in all gtk2 applications (not yet in gtk3 and qt, but this is coming).
* Default virtual keyboard is set to off. You may want to go to setting and change that first for using the terminal. Click the top left corner->"Settings"->"Text input"->check the "Use virtual keyboard" option. You may also want to change the keyboard layout by changing the dictionary setting.
* WiFi and terminal work.
* Some rendering bugs in portrait mode remain, so the default desktop orientation is landscape for now (<code>xrandr -o right</code>). Please note that if orientation is changed (e.g. with <code>xrandr -o normal</code>) the ui will still be reading original key positions.
* Screen brightness adjustments in UI do not work on the Pinephone yet. There is also a user reported when "brightness" UI setting is set to minimum (no visual change normally), the screen will stay black after reboot with WiFi set to ON with kill switch. However screen is normal after reboot if WiFi set to OFF with kill switch even minimum "brightness" UI setting. You may still change the screen brightness with terminal commands: <code>xrandr --output DSI-1 --brightness 0.5</code>
* Performance is not bad, but will get better, with hildon-desktop optimisations and as lima improves.
* We are not shipping the latest Pinephone kernel yet (feel free to work on that, or anything above!)
* Many "games" packages in the Application Manager don't work well yet.
* For some reason the X cursor is still shows (usually it's hidden)
*
== Status ==


{| class="wikitable"
{| class="wikitable"
Line 60: Line 44:
! Notes
! Notes
|-
|-
| Kernel version || 5.4 || Mainline + some patches: https://gitlab.com/pine64-org/linux/tree/pine64-kernel-5.4.y
| Kernel version || 5.15 || Mainline + some patches: https://github.com/maemo-leste/pine64-kernel
|-
|-
| Serial || Yes || Via headphone jack (disable headphone switch)
| Serial || Yes || Via headphone jack (disable headphone switch)
Line 68: Line 52:
| Wireless || Yes || Involves installing out of tree driver
| Wireless || Yes || Involves installing out of tree driver
|-
|-
| Ethernet || N/A ||
| Ethernet || N/A || ps: USB Ethernet adapter tested and works
|-
|-
| Bluetooth || ? ||  
| Bluetooth || YES || No UI integration yet
|-
|-
| Infrared || N/A || TX only (hardware limitation).  
| Infrared || N/A || TX only (hardware limitation).  
|-
|-
| USB C || Yes || Peripheral/slave only, exposes network gadget by default. Host Untested
| USB C || Yes || Peripheral/slave, exposes network gadget by default. Host Untested
|-
|-
| Keyboard || N/A || !
| Keyboard || Yes || When a PP keyboard is connected, it works out-of-the-box
|-
|-
| Screen || Yes || Modesetting driver
| Screen || Yes || Modesetting driver
|-
|-
| 3D Acceleration || Yes || lima (!)
| 3D Acceleration || Yes || mesa-lima
|-
|-
| Touchscreen || Yes || Capacitive
| Touchscreen || Yes || Capacitive
|-
|-
| Audio || Yes ||
| Audio || Yes || Pulseaudio and UCM units
|-
| 2G/3G/4G data || YES || Works with ofono;
|-
|-
| 2G/3G data || WIP || Works with ofono; UI underway: https://github.com/maemo-leste/connui-cellular ; see https://github.com/maemo-leste/bugtracker/issues/76
| SMS || YES || Works with ofono, will using telepathy-ring. Sphone and Conversations are currently available
|-
|-
| SMS || WIP || Works with ofono, will using telepathy-ring, no UI yet, not enabled by default
| Phone calls || YES || Works with ofono; Calls work with sphone as UI
|-
|-
| Phone calls || WIP || Reported to work, not enabled by default, community is quite far along, needs to work package their work
| VoLTE || YES || Quectel EG25 has VoLTE support, no userland required, but setting VoLTE profile might be needed
|-
|-
| Accelerometer || ? || Available as input device, needs MCE work
| Accelerometer || Yes ||
|-
|-
| Proximity sensor || ? ||  
| Proximity sensor || Yes ||  
|-
|-
| RGB LED || WIP || Works, but mce can't deal with LEDs without controllers yet.
| RGB LED || WIP || Works, but mce can't deal with LEDs without controllers yet.
Line 100: Line 86:
| Vibration Motor || ? ||  
| Vibration Motor || ? ||  
|-
|-
| GPS || WIP || Should work on the modem
| GPS || WIP || Works with WIP Leste GPS stack
|-
| Cameras || WIP || Driver present for rear (OV5640) and front (GC2145) cameras. User space support in progress with libcamera.
|}
|}
=== More Information ===
* Virtual keyboard should work in all gtk2 applications (not yet in gtk3 and qt, but this is coming).
* Default virtual keyboard is set to on. You can check by tapping the top left corner->"Settings"->"Text input"-> ensure the "Use virtual keyboard" option is checked. You may also want to change the keyboard layout by changing the dictionary settings.
* WiFi and terminal work.
* Some rendering bugs in portrait mode remain, so the default desktop orientation is landscape for now (<code>xrandr -o right</code>). Please note that if orientation is changed (e.g. with <code>xrandr -o normal</code>) the ui will still be reading original key positions.
* Screen brightness adjustments in UI do not work on the Pinephone yet. There is also a user reported when "brightness" UI setting is set to minimum (no visual change normally), the screen will stay black after reboot with WiFi set to ON with kill switch. However screen is normal after reboot if WiFi set to OFF with kill switch even minimum "brightness" UI setting. You may still change the screen brightness with terminal commands: <code>xrandr --output DSI-1 --brightness 0.5</code>
* Performance is not bad, but will get better, with hildon-desktop optimisations and as lima improves.
* Many "games" packages in the Application Manager don't work well yet.
* '''VoLTE should work out-of-the-box.''' If not, please set the VoLTE profile via AT commands. For example, for T-Mobile in US, do:
$ echo 'AT+QMBNCFG="select","Commercial-TMO_VoLTE"' | atinout - /dev/EG25.AT -
In order to list all specific VoLTE profiles, use:
$ echo 'AT+QMBNCFG="list"' | atinout - /dev/EG25.AT -
To enable calling out over VoLTE, use:
$ echo 'AT+QCFG="ims",1' | atinout - /dev/EG25.AT -
Reboot the modem by rebooting the phone.


== Installation ==
== Installation ==
Unlike most phones, it's pretty simple.
=== SD Card Installation ===
==== Prepare the SD card ====
Create a new msdos partition table using fdisk


(Work in Progress)
$ sudo fdisk /dev/''SDCARD''
# press 'p' to view current table
# press 'o' to erase and make a new table
# press 'w' to write changes and quit


Unlike most phones, it's pretty simple.
==== Write the image to an SD-Card. ====


Download the image and the corresponding <code>.sha</code> file, then verify the image's integrity:
Download the latest image and the associated checksum file from [https://maedevu.maemo.org/images/pinephone/ here].


  $ cat maemo-leste-*-arm64-pinephone-*.img.sha
  $ wget https://maedevu.maemo.org/images/pinephone/''DATE''/''IMAGE FILE''
$ wget https://maedevu.maemo.org/images/pinephone/''DATE''/''CHECKSUM FILE''
  $ sha256sum maemo-leste-*-arm64-pinephone-*.img.xz
  $ sha256sum maemo-leste-*-arm64-pinephone-*.img.xz
$ cat maemo-leste-*-arm64-pinephone-*.img.xz.sha56
Compare the output. If they do not match, stop and ask someone in the project for help. If the checksums match, extract the image:
$ unxz maemo-leste-*-arm64-pinephone-*.img.xz
Write the image to microSD. '''''Be very careful with this step''''' to select the correct device.
$ dd if=maemo-leste-*-arm64-pinephone-*.img /path/to/sd-card bs=4M status=progress conv=fsync
Block size set to 4M will work most of the time. If not, try 1M, although this will take considerably longer. Do not use partition numbers, or it won't boot. For example: sdd, not sdds1 or sddp1; mmcblk0, not mmcblk0p1. In most cases with SD cards, your computer might read the SD card as mmcblk0 or something similar.
<small>Make absolutely sure you replace the input file <code>if=</code> argument with the path to your file, and the <code>/dev/sdX</code> in the output file <code>of=</code> argument with the correct device name. This is very important, as you will lose all the data on the device you selected, make sure it is the correct one. You can use Gnome Disks, gparted, [https://etcher.io/ Etcher], etc...your choice. Again, as with all of these tools, be careful to select the microSD card not your computer hard drive.</small>
=== eMMC Installation ===
'''Some notes have been adapted from the [https://wiki.pine64.org/wiki/PinePhone_Installation_Instructions#Installation_to_the_eMMC Pine64 Wiki]'''.
==== Preparing the .img file for eMMC boot ====
Download the .img.xz version of the image and extract it:
$ unxz -k maemo-leste-*-arm64-pinephone-*.img.xz
The image, by default, points to <code>/dev/mmcblk0</code> for SD cards, which must be modified to point to <code>/dev/mmcblk2</code> for the eMMC.  To start, mount the image to a loop device.
$ sudo losetup -P /dev/loop0 maemo-leste-*-arm64-pinephone-*.img
Mount the second partition to /mnt and the first partition to /mnt/boot and enter /mnt:
$ sudo mount /dev/loop0p2 /mnt
$ sudo mount /dev/loop0p1 /mnt/boot
$ cd /mnt
Use the editor of your choice to edit <code>/mnt/etc/fstab</code>, replacing <code>/dev/mmcblk0</code> with <code>/dev/mmcblk2</code>.
Now we need to edit <code>boot.scr</code>. For that you will need to download <code>boot.txt</code> from Maemo Leste github:
$ cd /mnt/boot
$ sudo wget https://raw.githubusercontent.com/maemo-leste/pine64-uboot/master/boot.txt
Now we do the same step as we did for the fstab, replacing <code>/dev/mmcblk0</code> with <code>/dev/mmcblk2</code> in <code>boot.txt</code>.
To regenerate <code>boot.scr</code> you need to install <code>u-boot-tools</code> first to be able to use mkimage.
Regenerate <code>boot.scr</code>:
$ sudo mkimage -A arm -O linux -T script -C none -a 0 -e 0 -d boot.txt boot.scr
Leave /mnt and unmount the partitions:
$ cd ~
$ sudo umount -R /mnt
We can now save the image we just modified using dd:
$ sudo dd if=/dev/loop0 of=maemo-leste-1.0-arm64-pinephone-EMMC.img
The image is now ready to be installed to the eMMC.
We can now remove the loop device we created earlier:
$ sudo losetup -d /dev/loop0
==== Install Using Tow-Boot ====
If you [https://tow-boot.org/devices/pine64-pinephoneA64.html flashed tow-boot to the PinePhone] the eMMC can be flashed by holding vol+ on startup to boot into USB Mass Storage mode.
The process of flashing Maemo Leste to the eMMC is identical to that of any other storage medium - e.g. a microSD card. You can use the <i>dd</i> command or a utility such as Etcher or Gnome Disks, etc.
==== Install Using JumpDrive ====
You can flash Maemo Leste to eMMC using JumpDrive. This utility boots from microSD and exposes the internal eMMC flash storage when the PinePhone is connected to a computer.
The process of flashing Maemo Leste to the exposed and mounted eMMC is identical to that of any other storage medium - e.g. a microSD card.
[https://wiki.pine64.org/wiki/PinePhone_Installation_Instructions#Using_JumpDrive JumpDrive instructions are on the Pine64 wiki.]
==== Install from the booted microSD ====
# Flash Maemo Leste to the microSD card
# Insert microSD card and boot the phone
# Download the latest Maemo Leste image on the booted OS; if you get errors during download, you'll have to expand the partition; and don't forget to re-check the checksums when you download.
# Extract the image file so that it only ends in ".img"
# Flash the image file to eMMC using <code>dd if='''IMAGE.img''' of=/dev/'''mmcblkX''' bs=1M status=progress conv=fsync</code> where X is the number label of the eMMC (of the disk, not the partition!). Use the command <code>lsblk</code> to check your devices: typically with the current kernel the microSD card is ''/dev/mmcblk0'' and the eMMC is ''/dev/mmcblk2'' but as always with ''dd'' be extremely cautious to get the devices correct.
# Turn off phone, remove microSD card and then turn on the phone.
== Post-Installation ==
=== How to take a picture ===
Maemo userland to take pictures or make videos is ready yet. The default camera app is pinhole: https://github.com/piggz/harbour-pinhole/
Both cameras (rear and front) are supported. Work in ongoing to improve the camera app.
To open the (pinhole) camera from the terminal:
$ harbour-pinhole
Or open it from Maemo desktop "Camera" icon.
In order to trigger auto-focus:
$ v4l2-ctl -d /dev/v4l-subdev1 -c focus_automatic_continuous=1
Or trigger autofocus using the commands to start and stop manually:
$ v4l2-ctl -d /dev/v4l-subdev1 -c auto_focus_start=1
then wait till it gets the focus where you want, then
$ v4l2-ctl -d /dev/v4l-subdev1 -c auto_focus_stop=1
You can use this script as reference to take a picture:
https://github.com/OpenMandrivaAssociation/pinephone-tools/blob/master/camera-setup
Or use libcamera tools (libcamera-tools package). To list the cameras:
$ cam -l
Example to capture 10 pictures with the rear camera:
$ cam --camera "/base/i2c-csi/rear-camera@4c" --file=/home/user/some_dir --capture=10
Example to capture 10 pictures with the front camera:
$ cam --camera "/base/i2c-csi/front-camera@3c" --file=/home/user/some_dir --capture=10
And then, conver the raw ".bin" files to some useful format with ffmpeg or any other image conversion tool. Example:
$ ffmpeg -f image2 -vcodec rawvideo -s 1600x1200 -pix_fmt bayer_bggr8 -i picture.bin converted_picture.jpeg
Other option is to use "cam" to capture to DNG. Example:
$ cam --camera "/base/i2c-csi/rear-camera@4c" --file=/home/user/frame-#.dng --capture=10
And then convert to .ppm (for .tiff use "-T" cmd line parameter). Eg:
$ dcraw frame-cam0-stream0-000001.dng
Also the graphical tool "qcam" is working! Run it with:
$ qcam -r gles -spixelformat=NV21,width=1280,height=720 -platform xcb -style=fusion
=== Enabling Flash Light / Torch ===
Enable:
$  echo 1 > /sys/class/leds/white:flash/brightness
Disable:
$ echo 0 > /sys/class/leds/white:flash/brightness
Trigger flash strobe:
$ echo 1 > /sys/class/leds/white:flash/flash_strobe
=== PinePhone Keyboard ===
First of all, make sure you have the latest firmware loaded in the keyboard (firmware is here: https://github.com/maemo-leste-upstream-forks/pinephone-keyboard/tree/master/firmware/build and userland here: https://github.com/maemo-leste-upstream-forks/pinephone-keyboard ):
$ ppkb-i2c-flasher -e i2c -i fw-user.bin write reset
Load the xkb layout ( available here: https://codeberg.org/phalio/ppkb-layouts/src/branch/main/xkb )
$ setxkbmap pp altgr
=== Suspend ===
Suspend can be triggered with:
$ echo mem > /sys/power/state
A temporary workaround for calling suspend from UI is here: https://github.com/rafael2k/maemo-suspend/
=== Volume Applet ===
Volume applet ( https://github.com/maemo-leste/maemo-statusmenu-volume ) needs a change in "sink_name" at "/usr/share/maemo-statusmenu-volume/sinks.ini". Edit the sinks.ini in order the sink_name is:
sink_name=alsa_output.0.HiFi__hw_PinePhone_0__sink
=== Installing apps ===
* Apps can be installed just as on any Devuan system with:
$ sudo apt install ''package-name''
* There is also the app store.
=== Launching apps ===
This works for any app. Say for instance, you want to run Iceweasel/Firefox:
* Launch apps from the desktop
* Launch apps from your console:
$ iceweasel &
* Install a universal app launcher that you can run from desktop:
$ sudo apt install desktop-cmd-exec
=== Make apps show up on desktop ===
Apps installed via apt, or otherwise not installed from the app store, don't come with desktop icons pre-configured and so won't show up on the desktop. If you want desktop icons for your apps, you have to edit .desktop files for the apps you want to show up on the desktop, see ([https://wiki.archlinux.org/title/Desktop_entries examples])
To view a list of currently installed apps, do:
$ sudo apt list --installed | less
This should help you figure out for which apps to configure .desktop icons. A benefit with all this is that you can decide which apps you want to show or hide.
=== Unhide the keyboard ===
The virtual keyboard can be summoned by hitting the volume-up key while the cursor is in a text field (such as the URL bar in a web browser like Firefox). This will be fixed in a future release (image tested: 20220731).
=== Note about Calculator ===


or
The default GUI calculator works (08/15/2022) but you won't see the numbers appear on screen until after you touch the next key. It should be used in landscape mode for best results, as there are additional display issues in portrait mode.


$ cat maemo-leste-*-arm64-pinephone-*.tar.gz.sha
=== Time zone / World Clock ===
$ sha256sum maemo-leste-*-arm64-pinephone-*.tar.gz


Verify that the number that each command spits out is exactly the same number. If it is not, do not use the image. Try redownloading or ask for help.
Currently (06/15/2022) the interface to the default GUI clock has a few bugs but the workaround is to:


dd the image to an sd card. If using a Windows machine, you can use [https://etcher.io/ Etcher] NOTE: Etcher does not warn you before starting the flashing operation, so please be extra careful that you choose the correct device to flash to.
* Go to Settings > Date and Time > and adjust time zone and date and time there. This also has some bugs, but only in portrait mode.


How to dd to the SD card:
* Or just use the console:


In a terminal window, use the command below, making sure you replace the input file <code>if=</code> argument with the path to your file, and the <code>/dev/sdX</code> in the output file <code>of=</code> argument with the correct device name. This is very important, as you will lose all the data on the hard drive if you provide the wrong device name. Make sure the device name is the name as described above, with no partition numbers. For example: sdd, not sdds1 or sddp1; mmcblk0, not mmcblk0p1. In most cases with SD cards, your computer might read the SD card as mmcblk0 or something similar. Don't copy and paste this command, type it out and use TAB completion.
$ sudo date -s HH:MM
$ sudo date -s YYYYMMDD
$ sudo ln -s /usr/share/zoneinfo/YOURREGION/YOURCITY /etc/localtime


$ dd bs=4M if=maemo-leste-*-arm64-pinephone-*.img.*z of=/dev/sdX conv=fsync


Please note that block size set to 4M will work most of the time. If not, try 1M, although this will take considerably longer. Also note that if you are not logged in as root you will need to prefix this with sudo.


Then insert SD card, replace the back cover, and turn it on.
=== More Tips & Tricks ===


These steps should work in theory, but at the moment the image is unbootable.
Visit [https://leste.maemo.org/Tricks '''this page'''] for more general advice on customizing Maemo on your PinePhone.


[[Category:Device]]
[[Category:Device]]

Latest revision as of 19:53, 27 January 2024

This page or section is a stub. Ask how you can help improve leste.maemo.org by visiting #maemo-leste, look at the bugtracker (https://github.com/maemo-leste/bugtracker) or if you are able to contribute to the current page, then you are welcome to do so.

PinePhone
Manufacturer Pine64
Specifications
SoC Allwinner A64
Hardware Features
Software Features

This is for all PinePhones starting with the first Pinephone (Braveheart) phone, but not for the PinePhone Pro.

Notes

Go here for latest images to test. Please get in touch with us to report any issues or learn how to help out with the project.

Status

Currently, most things work, for example you can:

  • Run any applications in Debian and Devuan on your phone
  • Connect to wifi
  • Use the terminal
  • Connect to 2G/3G/4G data connections
  • Make and receive phone calls and SMS
  • PinePhone keyboard is supported


Feature Leste supported Notes
Kernel version 5.15 Mainline + some patches: https://github.com/maemo-leste/pine64-kernel
Serial Yes Via headphone jack (disable headphone switch)
Charging Yes
Wireless Yes Involves installing out of tree driver
Ethernet N/A ps: USB Ethernet adapter tested and works
Bluetooth YES No UI integration yet
Infrared N/A TX only (hardware limitation).
USB C Yes Peripheral/slave, exposes network gadget by default. Host Untested
Keyboard Yes When a PP keyboard is connected, it works out-of-the-box
Screen Yes Modesetting driver
3D Acceleration Yes mesa-lima
Touchscreen Yes Capacitive
Audio Yes Pulseaudio and UCM units
2G/3G/4G data YES Works with ofono;
SMS YES Works with ofono, will using telepathy-ring. Sphone and Conversations are currently available
Phone calls YES Works with ofono; Calls work with sphone as UI
VoLTE YES Quectel EG25 has VoLTE support, no userland required, but setting VoLTE profile might be needed
Accelerometer Yes
Proximity sensor Yes
RGB LED WIP Works, but mce can't deal with LEDs without controllers yet.
Vibration Motor ?
GPS WIP Works with WIP Leste GPS stack
Cameras WIP Driver present for rear (OV5640) and front (GC2145) cameras. User space support in progress with libcamera.

More Information

  • Virtual keyboard should work in all gtk2 applications (not yet in gtk3 and qt, but this is coming).
  • Default virtual keyboard is set to on. You can check by tapping the top left corner->"Settings"->"Text input"-> ensure the "Use virtual keyboard" option is checked. You may also want to change the keyboard layout by changing the dictionary settings.
  • WiFi and terminal work.
  • Some rendering bugs in portrait mode remain, so the default desktop orientation is landscape for now (xrandr -o right). Please note that if orientation is changed (e.g. with xrandr -o normal) the ui will still be reading original key positions.
  • Screen brightness adjustments in UI do not work on the Pinephone yet. There is also a user reported when "brightness" UI setting is set to minimum (no visual change normally), the screen will stay black after reboot with WiFi set to ON with kill switch. However screen is normal after reboot if WiFi set to OFF with kill switch even minimum "brightness" UI setting. You may still change the screen brightness with terminal commands: xrandr --output DSI-1 --brightness 0.5
  • Performance is not bad, but will get better, with hildon-desktop optimisations and as lima improves.
  • Many "games" packages in the Application Manager don't work well yet.
  • VoLTE should work out-of-the-box. If not, please set the VoLTE profile via AT commands. For example, for T-Mobile in US, do:
$ echo 'AT+QMBNCFG="select","Commercial-TMO_VoLTE"' | atinout - /dev/EG25.AT -

In order to list all specific VoLTE profiles, use:

$ echo 'AT+QMBNCFG="list"' | atinout - /dev/EG25.AT -

To enable calling out over VoLTE, use:

$ echo 'AT+QCFG="ims",1' | atinout - /dev/EG25.AT -

Reboot the modem by rebooting the phone.

Installation

Unlike most phones, it's pretty simple.

SD Card Installation

Prepare the SD card

Create a new msdos partition table using fdisk

$ sudo fdisk /dev/SDCARD 
  1. press 'p' to view current table
  2. press 'o' to erase and make a new table
  3. press 'w' to write changes and quit

Write the image to an SD-Card.

Download the latest image and the associated checksum file from here.

$ wget https://maedevu.maemo.org/images/pinephone/DATE/IMAGE FILE
$ wget https://maedevu.maemo.org/images/pinephone/DATE/CHECKSUM FILE
$ sha256sum maemo-leste-*-arm64-pinephone-*.img.xz
$ cat maemo-leste-*-arm64-pinephone-*.img.xz.sha56

Compare the output. If they do not match, stop and ask someone in the project for help. If the checksums match, extract the image:

$ unxz maemo-leste-*-arm64-pinephone-*.img.xz

Write the image to microSD. Be very careful with this step to select the correct device.

$ dd if=maemo-leste-*-arm64-pinephone-*.img /path/to/sd-card bs=4M status=progress conv=fsync

Block size set to 4M will work most of the time. If not, try 1M, although this will take considerably longer. Do not use partition numbers, or it won't boot. For example: sdd, not sdds1 or sddp1; mmcblk0, not mmcblk0p1. In most cases with SD cards, your computer might read the SD card as mmcblk0 or something similar.

Make absolutely sure you replace the input file if= argument with the path to your file, and the /dev/sdX in the output file of= argument with the correct device name. This is very important, as you will lose all the data on the device you selected, make sure it is the correct one. You can use Gnome Disks, gparted, Etcher, etc...your choice. Again, as with all of these tools, be careful to select the microSD card not your computer hard drive.

eMMC Installation

Some notes have been adapted from the Pine64 Wiki.

Preparing the .img file for eMMC boot

Download the .img.xz version of the image and extract it:

$ unxz -k maemo-leste-*-arm64-pinephone-*.img.xz

The image, by default, points to /dev/mmcblk0 for SD cards, which must be modified to point to /dev/mmcblk2 for the eMMC. To start, mount the image to a loop device.

$ sudo losetup -P /dev/loop0 maemo-leste-*-arm64-pinephone-*.img

Mount the second partition to /mnt and the first partition to /mnt/boot and enter /mnt:

$ sudo mount /dev/loop0p2 /mnt
$ sudo mount /dev/loop0p1 /mnt/boot
$ cd /mnt

Use the editor of your choice to edit /mnt/etc/fstab, replacing /dev/mmcblk0 with /dev/mmcblk2.

Now we need to edit boot.scr. For that you will need to download boot.txt from Maemo Leste github:

$ cd /mnt/boot
$ sudo wget https://raw.githubusercontent.com/maemo-leste/pine64-uboot/master/boot.txt

Now we do the same step as we did for the fstab, replacing /dev/mmcblk0 with /dev/mmcblk2 in boot.txt.


To regenerate boot.scr you need to install u-boot-tools first to be able to use mkimage.

Regenerate boot.scr:

$ sudo mkimage -A arm -O linux -T script -C none -a 0 -e 0 -d boot.txt boot.scr

Leave /mnt and unmount the partitions:

$ cd ~
$ sudo umount -R /mnt

We can now save the image we just modified using dd:

$ sudo dd if=/dev/loop0 of=maemo-leste-1.0-arm64-pinephone-EMMC.img

The image is now ready to be installed to the eMMC.

We can now remove the loop device we created earlier:

$ sudo losetup -d /dev/loop0

Install Using Tow-Boot

If you flashed tow-boot to the PinePhone the eMMC can be flashed by holding vol+ on startup to boot into USB Mass Storage mode.

The process of flashing Maemo Leste to the eMMC is identical to that of any other storage medium - e.g. a microSD card. You can use the dd command or a utility such as Etcher or Gnome Disks, etc.

Install Using JumpDrive

You can flash Maemo Leste to eMMC using JumpDrive. This utility boots from microSD and exposes the internal eMMC flash storage when the PinePhone is connected to a computer.

The process of flashing Maemo Leste to the exposed and mounted eMMC is identical to that of any other storage medium - e.g. a microSD card.

JumpDrive instructions are on the Pine64 wiki.

Install from the booted microSD

  1. Flash Maemo Leste to the microSD card
  2. Insert microSD card and boot the phone
  3. Download the latest Maemo Leste image on the booted OS; if you get errors during download, you'll have to expand the partition; and don't forget to re-check the checksums when you download.
  4. Extract the image file so that it only ends in ".img"
  5. Flash the image file to eMMC using dd if=IMAGE.img of=/dev/mmcblkX bs=1M status=progress conv=fsync where X is the number label of the eMMC (of the disk, not the partition!). Use the command lsblk to check your devices: typically with the current kernel the microSD card is /dev/mmcblk0 and the eMMC is /dev/mmcblk2 but as always with dd be extremely cautious to get the devices correct.
  6. Turn off phone, remove microSD card and then turn on the phone.

Post-Installation

How to take a picture

Maemo userland to take pictures or make videos is ready yet. The default camera app is pinhole: https://github.com/piggz/harbour-pinhole/

Both cameras (rear and front) are supported. Work in ongoing to improve the camera app.

To open the (pinhole) camera from the terminal:

$ harbour-pinhole

Or open it from Maemo desktop "Camera" icon.

In order to trigger auto-focus:

$ v4l2-ctl -d /dev/v4l-subdev1 -c focus_automatic_continuous=1

Or trigger autofocus using the commands to start and stop manually:

$ v4l2-ctl -d /dev/v4l-subdev1 -c auto_focus_start=1

then wait till it gets the focus where you want, then

$ v4l2-ctl -d /dev/v4l-subdev1 -c auto_focus_stop=1

You can use this script as reference to take a picture: https://github.com/OpenMandrivaAssociation/pinephone-tools/blob/master/camera-setup

Or use libcamera tools (libcamera-tools package). To list the cameras:

$ cam -l

Example to capture 10 pictures with the rear camera:

$ cam --camera "/base/i2c-csi/rear-camera@4c" --file=/home/user/some_dir --capture=10

Example to capture 10 pictures with the front camera:

$ cam --camera "/base/i2c-csi/front-camera@3c" --file=/home/user/some_dir --capture=10

And then, conver the raw ".bin" files to some useful format with ffmpeg or any other image conversion tool. Example:

$ ffmpeg -f image2 -vcodec rawvideo -s 1600x1200 -pix_fmt bayer_bggr8 -i picture.bin converted_picture.jpeg

Other option is to use "cam" to capture to DNG. Example:

$ cam --camera "/base/i2c-csi/rear-camera@4c" --file=/home/user/frame-#.dng --capture=10

And then convert to .ppm (for .tiff use "-T" cmd line parameter). Eg:

$ dcraw frame-cam0-stream0-000001.dng

Also the graphical tool "qcam" is working! Run it with:

$ qcam -r gles -spixelformat=NV21,width=1280,height=720 -platform xcb -style=fusion

Enabling Flash Light / Torch

Enable:

$  echo 1 > /sys/class/leds/white:flash/brightness

Disable:

$ echo 0 > /sys/class/leds/white:flash/brightness

Trigger flash strobe:

$ echo 1 > /sys/class/leds/white:flash/flash_strobe

PinePhone Keyboard

First of all, make sure you have the latest firmware loaded in the keyboard (firmware is here: https://github.com/maemo-leste-upstream-forks/pinephone-keyboard/tree/master/firmware/build and userland here: https://github.com/maemo-leste-upstream-forks/pinephone-keyboard ):

$ ppkb-i2c-flasher -e i2c -i fw-user.bin write reset

Load the xkb layout ( available here: https://codeberg.org/phalio/ppkb-layouts/src/branch/main/xkb )

$ setxkbmap pp altgr

Suspend

Suspend can be triggered with:

$ echo mem > /sys/power/state

A temporary workaround for calling suspend from UI is here: https://github.com/rafael2k/maemo-suspend/

Volume Applet

Volume applet ( https://github.com/maemo-leste/maemo-statusmenu-volume ) needs a change in "sink_name" at "/usr/share/maemo-statusmenu-volume/sinks.ini". Edit the sinks.ini in order the sink_name is:

sink_name=alsa_output.0.HiFi__hw_PinePhone_0__sink

Installing apps

  • Apps can be installed just as on any Devuan system with:
$ sudo apt install package-name
  • There is also the app store.

Launching apps

This works for any app. Say for instance, you want to run Iceweasel/Firefox:

  • Launch apps from the desktop
  • Launch apps from your console:
$ iceweasel &
  • Install a universal app launcher that you can run from desktop:
$ sudo apt install desktop-cmd-exec

Make apps show up on desktop

Apps installed via apt, or otherwise not installed from the app store, don't come with desktop icons pre-configured and so won't show up on the desktop. If you want desktop icons for your apps, you have to edit .desktop files for the apps you want to show up on the desktop, see (examples)

To view a list of currently installed apps, do:

$ sudo apt list --installed | less

This should help you figure out for which apps to configure .desktop icons. A benefit with all this is that you can decide which apps you want to show or hide.

Unhide the keyboard

The virtual keyboard can be summoned by hitting the volume-up key while the cursor is in a text field (such as the URL bar in a web browser like Firefox). This will be fixed in a future release (image tested: 20220731).

Note about Calculator

The default GUI calculator works (08/15/2022) but you won't see the numbers appear on screen until after you touch the next key. It should be used in landscape mode for best results, as there are additional display issues in portrait mode.

Time zone / World Clock

Currently (06/15/2022) the interface to the default GUI clock has a few bugs but the workaround is to:

  • Go to Settings > Date and Time > and adjust time zone and date and time there. This also has some bugs, but only in portrait mode.
  • Or just use the console:
$ sudo date -s HH:MM
$ sudo date -s YYYYMMDD
$ sudo ln -s /usr/share/zoneinfo/YOURREGION/YOURCITY /etc/localtime


More Tips & Tricks

Visit this page for more general advice on customizing Maemo on your PinePhone.