Merge branch 'main' of https://github.com/pine64/website

content/documentation/Ox64/Software/Flashing.adoc

@@ -15,7 +15,7 @@ This page explains how to flash an Ox64 board and a microSD card to boot the sys
 
 == Prepare images for flashing
 
-Download the Ox64 images from the latest OpenBouffalo release. You may skip this whole section if you built your own images as per the instructions in the link:/documentation/Ox64/Software/Building/[Building] page.
+Download the Ox64 images from the latest OpenBouffalo release. You may skip this step if you built your own images as per the instructions in the link:/documentation/Ox64/Software/Building/[Building] page.
 
 [source,console]
 ----
@@ -124,7 +124,7 @@ Next, connect the Ox64 board to the Pico according to the following wiring diagr
 | 
 |===
 
-With the Pico flashed and wired as per the instructions above, we have access to two of the Ox64's UART connections at the same time. This configuration eliminates the need to switch the physical connections for flashing or testing the system.
+With the Pico flashed and wired as per the instructions above, we have access to two of the Ox64's UART ports at the same time. This configuration eliminates the need to switch the physical connections for flashing or testing the system.
 
 Reconnect the Pico to your computer's USB port and verify that we have access to all the serial ports we need:
 
@@ -142,7 +142,14 @@ Expected result:
 
 The Bluepill is an affordable STM32 development board, based on the STM32F103C8T6 chip. We can program it to act as a USB serial adapter, just like we did with the Raspberry Pi Pico.
 
-NOTE: The one catch is that you already need a serial adapter in order to program your Bluepill board. The good news is that you serial adapter does **not** have to be one from from the link:/documentation/Ox64/Further_information/Compatible_UARTs/[Compatible_UARTs] list. The programming has been tested with a TTL to USB converter FT232RL. If you own an SWD-capable debugger (ST-Link, J-link, etc.), you can use that for programming the Bluepill as well.
+[NOTE]
+====
+The one catch is that you already need a serial adapter in order to program your Bluepill board. The good news is that you serial adapter does **not** have to be one from from the link:/documentation/Ox64/Further_information/Compatible_UARTs/[Compatible UARTs] list. These programming instructions have been tested with a FT232RL adapter (which, notably, is listed as _not_ supported on that list).
+
+If you own an SWD-capable debugger (ST-Link, J-link, etc.) you can use that for programming the Bluepill as well, although instead of `stm32flash` you would be using https://openocd.org/[openocd] or other suitable software.
+====
+
+WARNING: Your serial adapter must use 3.3V logic levels.
 
 Download the https://github.com/r2axz/bluepill-serial-monster[Bluepill Serial Monster] firmware:
 
@@ -151,7 +158,6 @@ Download the https://github.com/r2axz/bluepill-serial-monster[Bluepill Serial Mo
 $ mkdir -p ~/ox64/bluepill
 $ cd ~/ox64/bluepill
 $ wget https://github.com/r2axz/bluepill-serial-monster/releases/download/v2.6.4/bluepill-serial-monster.hex
-$ sudo apt install stm32flash
 ----
 
 Put the Bluepill into programming mode:
@@ -160,15 +166,16 @@ Put the Bluepill into programming mode:
 * Connect it to a USB-Serial adapter with A9 to Rx, A10 to Tx, GND to GND, 3v3 to Vcc.
 * Apply power by plugging the USB cable to PC. Press the Reset button.
 
-Find the correct device using `ls /dev/ttyUSB*` and upload the firmware:
+Find your USB serial adapter's device path with `ls /dev/ttyUSB* /dev/ttyACM*` (or similar); for the rest of this section we will refer to it as `/dev/tty[DEVICE]`. Upload the firmware:
 
 [source,console]
 ----
+$ sudo apt install stm32flash
 $ cd ~/ox64/bluepill
 $ stm32flash -w  bluepill-serial-monster.hex /dev/tty[DEVICE]
 ----
 
-After upload, set boot jumpers for boot from flash: Boot0=0, Boot1=0. Remove the USB serial adapter.
+After upload, set boot jumpers for boot from flash: Boot0=0, Boot1=0. Disconnect the USB serial adapter from both the PC and Bluepill board.
 
 Next, connect the Ox64 board to the Bluepill according to the following wiring diagram:
 
@@ -221,25 +228,29 @@ Expected result:
 
 image:/documentation/Ox64/images/ox64_pinout.png[Ox64 pinout,title="Ox64 pinout", 300, float="right"]
 
-Check that your serial adapter is on the link:/documentation/Ox64/Further_information/Compatible_UARTs/[Compatible_UARTs] list. You will (most likely) only have one serial interface available to you.
+Check that your serial adapter is on the link:/documentation/Ox64/Further_information/Compatible_UARTs/[Compatible UARTs] list. You will (most likely) only have one serial interface available to you; unlike the previous options you will be using this same serial interface for both flashing and testing the system.
+
+Find its device path with `ls /dev/ttyUSB* /dev/ttyACM*` (or similar); for the rest of this section we will refer to it as `/dev/tty[DEVICE]`.
 
-In addition, you will need a way of powering your Ox64. If your serial adapter has a 5V line, you can connect it to VBUS (pin 40). Otherwise, you can connect either the micro-B or the USB-C port on the Ox64 to any 5V power supply.
+You will also need a way of powering your Ox64. If your serial adapter has a 5V line, you can connect it to VBUS (pin 40). Otherwise, you can connect either the micro-B or the USB-C port on the Ox64 to any 5V power supply.
+
+WARNING: Your serial adapter must use 3.3V logic levels.
 
 Refer to the pinout image below. Connect your UART adapter as follows:
 
 * RX -> UART0_TX / GPIO14 / pin 1
 * TX -> UART0_RX / GPIO15 / pin 2
 * GND -> any ground (e. g. pin 3)
 
-Proceed with the instructions in the sections that follow, up to and including <<flashing_the_ox64>> and <<flashing_the_microsd_card>>, finding the correct device path to your serial adapter under `ls /dev/ttyUSB*`.
+Proceed with the instructions in the sections that follow, up to and including <<flashing_the_ox64>> and <<flashing_the_microsd_card>>, but replace all occurrences of `/dev/ttyACM1` with `/dev/tty[DEVICE]`.
 
 Next, power off the Ox64 and re-connect your UART adapter as follows:
 
 * RX -> TXD / GPIO16 / pin 32
 * TX -> RXD / GPIO17 / pin 31
 * GND -> any ground (e. g. pin 33)
 
-Then, follow the instructions in <<booting_for_the_first_time>>, finding the correct device path to your serial adapter under `ls /dev/ttyUSB*`. You should then have a working Linux system.
+Then, follow the instructions in <<booting_for_the_first_time>>, but replace all occurrences of `/dev/ttyACM0` with `/dev/tty[DEVICE]`. You should then have a working Linux system.
 
 == Download flashing tools
 
@@ -275,7 +286,7 @@ $ unzip BouffaloLabDevCube-v1.8.9.zip
 $ chmod u+x BLDevCube-ubuntu
 ----
 
-If you did not create a <<optional_create_a_combined_soc_image, combined image>> you may need an older version of the DevCube. In that case, download v1.8.3 from one of the mirrors below:
+If you did not create a link:#optional_create_a_combined_soc_image[combined image] you may need an older version of the DevCube. In that case, download v1.8.3 from one of the mirrors below:
 
 * https://openbouffalo.org/static-assets/bldevcube/BouffaloLabDevCube-v1.8.3.zip
 * https://hachyderm.io/@mkroman/110787218805897192[] > https://pub.rwx.im/~mk/bouffalolab/BouffaloLabDevCube-v1.8.3.zip
@@ -297,12 +308,12 @@ Put the Ox64 into programming mode:
 
 === CLI flashing method
 
-Set up some environment variables to save typing them out later. Find the correct device path to your serial adapter under `ls /dev/ttyUSB*` or `ls /dev/ttyACM*`:
+Set up some environment variables to save typing them out later:
 
 [source,console]
 ----
-$ PORT=/dev/tty[DEVICE]
-$ BAUD=230400  # safe value for macOS, set 2000000 for faster flashing on Linux
+$ PORT=/dev/ttyACM1
+$ BAUD=230400  # safe value for macOS, set to 2000000 for faster flashing on Linux
 ----
 
 Change directory to the location of your image files:
@@ -314,7 +325,7 @@ $ cd ~/ox64/openbouffalo/firmware # if you downloaded pre-built images
 $ cd ~/ox64/buildroot/output/images # if you built your own images
 ----
 
-Finally, flash the Ox64. If you created a **combined image** then run the command below:
+Finally, flash the Ox64. If you created a link:#optional_create_a_combined_soc_image[combined image] then run the command below:
 
 [source,console]
 ----
@@ -350,37 +361,38 @@ $ ./BLDevCube-ubuntu
 
 Select chip [BL808], press Finish, and configure BOTH the [MCU] and [IOT] tabs as follows. When you switch between tabs double check that they still match the settings below:
 
-----
-Interface: UART
-Port/SN: /dev/ttyACM1 or /dev/ttyUSB0 (/dev/ttyACM0 it's already used by the minicom console)
-Uart rate 230400 (safe value for macOS, set 2000000 for faster flashing on Linux)
-----
 
-If you created a **combined image** then you only need to use the [IOT] tab:
+[cols="~,~"]
+|===
+|Interface
+|UART
 
-----
-Enable 'Single Download'
-Image Address [0x0], [PATH to bl808-combined.bin]
-Click 'Create & Download' and wait until it's done
-Close DevCube
-----
+|Port/SN
+|`/dev/ttyACM1`
+
+|UART rate
+|230400 (safe value for macOS, set to 2000000 for faster flashing on Linux)
+|===
+
+If you created a link:#optional_create_a_combined_soc_image[combined image] then you only need to use the [IOT] tab:
+
+* Enable 'Single Download'
+* Image Address [0x0], [PATH to bl808-combined.bin]
+* Click 'Create & Download' and wait until it's done
+* Close DevCube
 
 Otherwise, start in the [MCU] tab:
 
-----
-M0 Group[group0], Image Address [0x58000000], [PATH to m0_lowload_bl808_m0.bin]
-D0 Group[group0], Image Address [0x58100000], [PATH to d0_lowload_bl808_d0.bin]
-Click 'Create & Download' and wait until it's done
-----
+* M0 Group[group0], Image Address [0x58000000], [PATH to m0_lowload_bl808_m0.bin]
+* D0 Group[group0], Image Address [0x58100000], [PATH to d0_lowload_bl808_d0.bin]
+* Click 'Create & Download' and wait until it's done
 
 Then, switch to the [IOT] tab:
 
-----
-Enable 'Single Download'
-Image Address [0x800000], [PATH to bl808-firmware.bin]
-Click 'Create & Download' again and wait until it's done
-Close DevCube
-----
+* Enable 'Single Download'
+* Image Address [0x800000], [PATH to bl808-firmware.bin]
+* Click 'Create & Download' again and wait until it's done
+* Close DevCube
 
 == Flashing the microSD card
 
@@ -406,7 +418,7 @@ Open a terminal window to connect to the D0 core’s (i.e. Linux’s) serial con
 $ minicom -b 2000000 -D /dev/ttyACM0
 ----
 
-If you are using a Pico or Bluepill as your serial interface, open another terminal window to to monitor the M0 core’s serial console (reminder: `/dev/ttyACM1` is the same port we previously used for flashing):
+If you are using a Pico or Bluepill as your serial adapter, open another terminal window to to monitor the M0 core’s serial console (reminder: `/dev/ttyACM1` is the same port we previously used for flashing):
 
 [source,console]
 ----
@@ -415,9 +427,9 @@ $ minicom -b 2000000 -D /dev/ttyACM1
 
 Re-apply power to the Ox64.
 
-On the _ttyACM0_ console you will see Linux booting up. When prompted, log in as _root_ with no password. In case the SD card is missing or empty, you'll get a `Card did not respond to voltage select! : -110` error.
+On the main/D0 console (`/dev/ttyACM0`) you will see Linux booting up. When prompted, log in as `root` with no password. In case the SD card is missing or empty, you'll get a `Card did not respond to voltage select! : -110` error.
 
-On the `ttyACM1` console you'll see the following log, until the sytem is fully loaded:
+On the M0 console (`/dev/ttyACM1`) you'll see following messages until the sytem is fully loaded:
 
 ----
 [I][MBOX] Mailbox IRQ Stats:
@@ -426,14 +438,14 @@ On the `ttyACM1` console you'll see the following log, until the sytem is fully
 [I][MBOX] Unhandled Interupts: 0 Unhandled Signals 0
 ----
 
-Once the system is running you'll be able to manage the M0 multimedia core, such as Wi-Fi settings and more. When prompted, type `help` to see the available commands.
+Once the system is running, the "MBOX" logs will abruptly disappear and you'll be able to manage the M0 multimedia core, i.e. wifi settings, etc. When prompted, type `help` to see available commands.
 
 === Connecting the Ox64 to your WiFi network
 The simplest way to connect is to run the following command from the Linux console (i.e. `/dev/ttyACM0`):
 
 [source,console]
 ----
-$ blctl connect_ap [YourSSID] [YourPassword]
+$ blctl connect_ap <YourSSID> <YourPassword>
 ----
 
 Wait for it to connect (if you're monitoring the M0 console on `/dev/ttyACM1` it should tell you when it's done), then run the following command from the Linux console:
@@ -490,7 +502,6 @@ $ sudo tee -a /mnt/extlinux/extlinux.conf <<EOF
  LABEL PINE64 OX64 Nuttx
         KERNEL ../ImageNuttx
         FDT ../bl808-pine64-ox64.dtb
-        APPEND root=PARTLABEL=rootfs rootwait rw rootfstype=ext4 console=ttyS0,2000000 loglevel=8 earlycon=sbi
  EOF
 $ sudo umount /mnt
 ----
@@ -505,7 +516,6 @@ $ sudo tee -a /mnt/boot/extlinux/extlinux.conf <<EOF
  LABEL PINE64 OX64 Nuttx
         KERNEL ../ImageNuttx
         FDT ../bl808-pine64-ox64.dtb
-        APPEND root=PARTLABEL=rootfs rootwait rw rootfstype=ext4 console=ttyS0,2000000 loglevel=8 earlycon=sbi
  EOF
 $ sudo umount /mnt
 ----

content/documentation/PinePhone_Pro/Software/Multi-distribution_image.adoc

@@ -37,15 +37,15 @@ $ ATTR=RequiredPartition,LegacyBIOSBootable
 $ SIZE=11GiB
 
 $ declare -A NameUrl
-NameUrl[uboot]=https://xff.cz/kernels/bootloaders-2024.04/ppp.tar.gz
-#NameUrl[uboot]=https://megous.com/dl/tmp/ppp.tar.gz # test build
-NameUrl[arch]=https://github.com/dreemurrs-embedded/Pine64-Arch/releases/download/20240326/archlinux-pinephone-pro-phosh-20240326.img.xz
-NameUrl[manjaro]=https://github.com/manjaro-pinephone/phosh/releases/download/beta37/Manjaro-ARM-phosh-pinephonepro-beta37.img.xz
-NameUrl[mobian]=https://images.mobian.org/pinephonepro/weekly/mobian-rockchip-phosh-20240324.img.xz
-NameUrl[pmos]=https://images.postmarketos.org/bpo/v23.12/pine64-pinephonepro/phosh/20240403-0443/20240403-0443-postmarketOS-v23.12-phosh-22.3-pine64-pinephonepro.img.xz
-NameUrl[sailfish]=https://gitlab.com/sailfishos-porters-ci/dont_be_evil-ci/-/jobs/artifacts/master/download?job=pinephonepro-rootfs
-NameUrl[ut]=https://ci.ubports.com/job/focal-hybris-rootfs-arm64/job/master/lastSuccessfulBuild/artifact/ubuntu-touch-pinephone-pro-img-arm64.raw.xz
-NameUrl[extra]=
+$ NameUrl[uboot]=https://xff.cz/kernels/bootloaders-2024.04/ppp.tar.gz
+$ #NameUrl[uboot]=https://megous.com/dl/tmp/ppp.tar.gz # test build
+$ NameUrl[arch]=https://github.com/dreemurrs-embedded/Pine64-Arch/releases/download/20240326/archlinux-pinephone-pro-phosh-20240326.img.xz
+$ NameUrl[manjaro]=https://github.com/manjaro-pinephone/phosh/releases/download/beta37/Manjaro-ARM-phosh-pinephonepro-beta37.img.xz
+$ NameUrl[mobian]=https://images.mobian.org/pinephonepro/weekly/mobian-rockchip-phosh-20240324.img.xz
+$ NameUrl[pmos]=https://images.postmarketos.org/bpo/v23.12/pine64-pinephonepro/phosh/20240403-0443/20240403-0443-postmarketOS-v23.12-phosh-22.3-pine64-pinephonepro.img.xz
+$ NameUrl[sailfish]=https://gitlab.com/sailfishos-porters-ci/dont_be_evil-ci/-/jobs/artifacts/master/download?job=pinephonepro-rootfs
+$ NameUrl[ut]=https://ci.ubports.com/job/focal-hybris-rootfs-arm64/job/master/lastSuccessfulBuild/artifact/ubuntu-touch-pinephone-pro-img-arm64.raw.xz
+$ NameUrl[extra]=
 ----
 
 [#rk2aw]
@@ -59,7 +59,7 @@ Boot up the PinePhone Pro's stock operating system and start a shell session. Yo
 ----
 $ curl -O https://xff.cz/kernels/bootloaders-2024.04/ppp.tar.gz
 $ tar -xvzf ppp.tar.gz
-$ cd /ppp
+$ cd ppp
 $ sudo ./spinor-flash-initial-setup.sh
 ----
 
@@ -174,23 +174,36 @@ Syncing disks.
 [#uboot]
 == Install U-Boot
 
-This is the same `ppp.tar.gz` from the link:#rk2aw[rk2aw section]; if you already have a copy of it on your computer then you don't have to download it again. Otherwise, download it and write the `u-boot-rockchip.bin` file in the first sectors of the device, in order to display the graphical distribution selector when the phone boots.
+In order to display the graphical distribution selector when the phone boots, we need to install a custom version of the U-Boot bootloader.
+
+First, use the following commands to download the required U-Boot image. Note that we are downloading the same _ppp.tar.gz_ archive as we did in the link:#rk2aw[rk2aw section]; if you already have a copy of this archive on your computer, you may skip the download and simply extract its contents into `~/$BASE/downloads/`.
 
 [source,console]
 ----
 $ NAME=uboot
 $ mkdir -p ~/$BASE/downloads && cd ~/$BASE/downloads
 $ wget ${NameUrl[$NAME]}
 $ tar -xvzf $(basename "${NameUrl[$NAME]}")
+----
+
+Then, use the following command to install the U-Boot image to the correct location on the microSD/eMMC:
+
+[source,console]
+----
 $ sudo dd if=ppp/foss/u-boot-rockchip.bin of=/dev/$DEV bs=512 seek=64 status=progress conv=fsync
 ----
 
-NOTE: If you are interested in building this U-Boot image yourself, you will need to copy the `ppp/foss/.config` file from the archive above to the root of your U-Boot source directory. The source code for this build can also be downloaded from link:https://xff.cz/git/u-boot/tree/?h=ppp-2023.07[xff.cz]
+[TIP]
+====
+If you are interested in building this U-Boot image yourself, you can download the source code from link:https://xff.cz/git/u-boot/tree/?h=ppp-2023.07[xff.cz]. However, you will still need a copy of _ppp.tar.gz_ since it contains the U-Boot build configuration file (`ppp/foss/.config`).
+
+Copy this file to the root of your U-Boot source directory, keeping the name `.config`. You can then use `make` to initiate the build process.
+====
 
 [#building]
 == Build the partitions
 
-Make sure you download an updated file from link:/documentation/PinePhone_Pro/Software/Releases[relases page] and set properly the link:#variables[needed variables].
+Make sure you download an updated file from link:/documentation/PinePhone_Pro/Software/Releases[relases page]. You will need to build each partition one by one, setting properly the link:#variables[variables] and using specific commands according the selected distribution. When you reach the link:#building_repeat[building repeat advice], come back to this point and build the next distribution.
 
 === Arch, Manjaro, Mobian, postmarketOS
 
@@ -347,7 +360,7 @@ menu label $NAME
 ## uncomment next line for all distros, excluding UT
 #append root=PARTLABEL=$BASE-$NAME console=ttyS2,115200 console=tty0 loglevel=7 rw rootwait
 
-## uncomment next line for UT
+## uncomment next line for UT only
 #append root=PARTLABEL=$BASE-$NAME console=ttyS2,115200 console=tty loglevel=7 systempart=/dev/disk/by-partlabel/$BASE-$NAME datapart=/dev/disk/by-partlabel/$BASE-$NAME-data security=apparmor rw rootwait
 
 EOF
@@ -411,7 +424,8 @@ $ sudo e2fsck -f /dev/disk/by-partlabel/$BASE-$NAME
 $ sudo resize2fs /dev/disk/by-partlabel/$BASE-$NAME
 ----
 
-IMPORTANT: Repeat the link:#building[building process] for each needed distribution, adapting link:#variables[needed variables].
+[#building_repeat]
+IMPORTANT: Repeat the link:#building[building process] for the next distribution, adapting link:#variables[needed variables].
 
 == Follow-up notes
 

content/documentation/PineTime/Accessory/Cases.adoc

@@ -14,6 +14,7 @@ There are no cases for PineTime yet, but some cases for Fitbit are suitable for
 The community designed the following cases:
 
 * https://www.thingiverse.com/thing:4172849[PineTime Smart Watch case by dara0s at thingiverse]
+* https://www.thingiverse.com/thing:6578148[PineTime Flexible Cover by AmbiSpace at thingiverse]
 * https://www.thingiverse.com/thing:4651462[PineTime dev kit back fix by joaquimorg at thingiverse]
 * https://www.thingiverse.com/thing:4763267[PineTime dev kit charging holder v4 by zevix81 at thingiverse]
 * https://www.prusaprinters.org/prints/88913-pinetime-charger-case[PineTime Charger Travel Case by brett at PrusaPrinters]