diff --git a/content/documentation/Ox64/Software/Building.adoc b/content/documentation/Ox64/Software/Building.adoc index b4ef5078..8e12e88e 100644 --- a/content/documentation/Ox64/Software/Building.adoc +++ b/content/documentation/Ox64/Software/Building.adoc @@ -9,30 +9,30 @@ menu: weight: 2 --- -Open the terminal and clone the upstream Buildroot repository and the Buildroot Bouffalo overlay repository. +Start the buinding process cloning both the upstream Buildroot repository and the Buildroot Bouffalo overlay repository: mkdir -p ~/ox64 cd ~/ox64 git clone https://github.com/buildroot/buildroot git clone https://github.com/openbouffalo/buildroot_bouffalo -Define an environment variable for the Buildroot Bouffalo overlay path. +Define an environment variable for the Buildroot Bouffalo overlay path: export BR_BOUFFALO_OVERLAY_PATH=$(pwd)/buildroot_bouffalo -Change directory into the cloned Buildroot folder. +Change directory into the cloned Buildroot folder: cd ~/ox64/buildroot -Apply the default configuration for Pine64 Ox64. +Apply the default configuration for Pine64 Ox64: make BR2_EXTERNAL=$BR_BOUFFALO_OVERLAY_PATH pine64_ox64_defconfig -Use the `menuconfig` tool to adjust the build settings. +Use the `menuconfig` tool to adjust the build settings: make menuconfig -Within `menuconfig`, configure the following. +Within `menuconfig`, configure the following: * Navigate to `Target Options` * Enable `Integer Multiplication and Division (M)` @@ -42,34 +42,8 @@ Within `menuconfig`, configure the following. * Set `Target ABI` to `lp64d` * Under `Toolchain`, enable `Fortran support` and `OpenMP support` -Initiate the build process, but first make sure that your `PATH` variable contains no spaces. +Initiate the build process, but first make sure that your `PATH` variable contains no spaces: make -Buildroot will output to the `~/ox64/buildroot/output/images` directory. - -== Optional: create a combined SoC image - -Use the following commands to combine `m0_lowload_bl808_m0.bin`, `d0_lowload_bl808_d0.bin`, and `bl808-firmware.bin` into a single image. This is mainly useful for troubleshooting (e. g. when using DevCube v1.8.4 or later for flashing process). - ----- -cd ~/ox64/buildroot/output/images - -fallocate -l 0x800000 bl808-combined.bin -dd conv=notrunc if=m0_lowload_bl808_m0.bin of=bl808-combined.bin -dd conv=notrunc if=d0_lowload_bl808_d0.bin of=bl808-combined.bin seek=$((0x100000))B -cat bl808-firmware.bin >> bl808-combined.bin ----- - -== Check that you have the required files for flashing - - cd ~/ox64/buildroot/output/images - ls *808*.bin *.img - -Expected files: - -* `sdcard.img` -* `m0_lowload_bl808_m0.bin` -* `d0_lowload_bl808_d0.bin` -* `bl808-firmware.bin` -* `bl808-combined.bin` (if you created the combined image) +Buildroot will output to the `~/ox64/buildroot/output/images` directory. diff --git a/content/documentation/Ox64/Software/Flashing.adoc b/content/documentation/Ox64/Software/Flashing.adoc index c6d313cc..310f2e55 100644 --- a/content/documentation/Ox64/Software/Flashing.adoc +++ b/content/documentation/Ox64/Software/Flashing.adoc @@ -9,7 +9,7 @@ menu: weight: 3 --- -This page explains how to flash an Ox64 board and a microSD card to boot the system. You will need a Linux machine, a serial UART adapter, the Ox64 board, and a microSD card. +This page explains how to flash an Ox64 board and a microSD card to boot the system. You will need a Linux computer, a serial UART adapter, the Ox64 board, and a microSD card. == Prepare images for flashing @@ -55,13 +55,13 @@ In this section we will configure and wire up a UART adapter in order to flash t === Option 1: Raspberry Pi Pico -First, download the Raspberry Pi Pico firmware that allows it to act as a serial UART adapter. +First, download the Raspberry Pi Pico firmware that allows it to act as a serial UART adapter: mkdir -p ~/ox64/pico cd ~/ox64/pico wget https://github.com/Kris-Sekula/Pine64_Ox64_SBC/raw/main/uart/picoprobe.uf2 -Put the Raspberry Pi Pico board into programming mode. +Put the Raspberry Pi Pico board into programming mode: * Press the BootSel button * Apply power by plugging the USB cable to PC @@ -69,23 +69,23 @@ Put the Raspberry Pi Pico board into programming mode. NOTE: As an alternative to pressing the BootSel button, you can also connect the probe point `TP6` (located on the bottom of the Pico board) to any ground point (e.g. pin 28). -The Pico will now appear as a USB mass storage device. Copy the `UF2` file to program it. +The Pico will now appear as a USB mass storage device. Copy the `UF2` file to program it: cp ~/ox64/pico/picoprobe.uf2 /media//RPI-RP2 -Next, connect the Ox64 board to the Pico according to the following wiring diagram. +Next, connect the Ox64 board to the Pico according to the following wiring diagram: - OX64 PI PICO /dev/tty - uart0_Tx_GPIO14_pin1 <-> uart0_Rx_pin17 ACM1 for flashing - uart0_Rx_GPIO15_pin2 <-> uart0_Tx_pin16 ACM1 for flashing - Rxd_GPIO17_pin31 <-> uart1_Tx_pin6 ACM0 for serial console - Txd_GPIO16_pin32 <-> uart1_Rx_pin7 ACM0 for serial console + OX64 PI PICO /dev/tty + uart0_Tx_GPIO14_pin1 <-> uart0_Rx_pin17 <-> ACM1 for flashing + uart0_Rx_GPIO15_pin2 <-> uart0_Tx_pin16 <-> ACM1 for flashing + Rxd_GPIO17_pin31 <-> uart1_Tx_pin6 <-> ACM0 for serial console + Txd_GPIO16_pin32 <-> uart1_Rx_pin7 <-> ACM0 for serial console gnd_pin38 <-> gnd_pin38/3 vbus5v_pin40 <-> vbus5v_pin40 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. -Reconnect the Pico to your computer's USB port and verify that we have access to all the serial ports we need. +Reconnect the Pico to your computer's USB port and verify that we have access to all the serial ports we need: ls /dev/ttyACM* @@ -98,41 +98,41 @@ 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. 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. 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. -Download the https://github.com/r2axz/bluepill-serial-monster[Bluepill Serial Monster] firmware. +Download the https://github.com/r2axz/bluepill-serial-monster[Bluepill Serial Monster] firmware: 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. +Put the Bluepill into programming mode: * Set boot jumpers for booting from rom: Boot0=1, Boot1=0. * 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. -Upload the firmware. Replace `/dev/ttyUSB0` with the device path of your USB serial adapter. +Upload the firmware. Replace `/dev/ttyUSB0` with the device path of your USB serial adapter: cd ~/ox64/bluepill stm32flash -w bluepill-serial-monster.hex /dev/ttyUSB0 After upload, set boot jumpers for boot from flash: Boot0=0, Boot1=0. Remove the USB serial adapter. -Next, connect the Ox64 board to the Bluepill according to the following wiring diagram. +Next, connect the Ox64 board to the Bluepill according to the following wiring diagram: - OX64 Bluepill /dev/tty - uart0_Tx_GPIO14_pin1 <-> uart0_Rx_A3 ACM1 for flashing - uart0_Rx_GPIO15_pin2 <-> uart0_Tx_A2 ACM1 for flashing - Rxd_GPIO17_pin31 <-> uart1_Tx_A9 ACM0 for serial console - Txd_GPIO16_pin32 <-> uart1_Rx_A10 ACM0 for serial console + OX64 Bluepill /dev/tty + uart0_Tx_GPIO14_pin1 <-> uart0_Rx_A3 <-> ACM1 for flashing + uart0_Rx_GPIO15_pin2 <-> uart0_Tx_A2 <-> ACM1 for flashing + Rxd_GPIO17_pin31 <-> uart1_Tx_A9 <-> ACM0 for serial console + Txd_GPIO16_pin32 <-> uart1_Rx_A10 <-> ACM0 for serial console gnd_pin38 <-> GND vbus5v_pin40 <-> 5V With the Bluepill 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. -Connect the Bluepill to your computer's USB port and verify that we have access to all the serial ports we need. +Connect the Bluepill to your computer's USB port and verify that we have access to all the serial ports we need: ls /dev/ttyACM* @@ -148,7 +148,7 @@ Check that you serial adapter is on the link:/documentation/Ox64/Further_informa 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. -Refer to the pinout image below. Connect your UART adapter as follows. +Refer to the pinout image below. Connect your UART adapter as follows: * RX -> UART0_TX / GPIO14 / pin 1 * TX -> UART0_RX / GPIO15 / pin 2 @@ -156,7 +156,7 @@ Refer to the pinout image below. Connect your UART adapter as follows. Proceed with the instructions in the sections that follow, up to and including <> and <>, but replace all occurrences of `/dev/ttyACM1` with `/dev/ttyUSB0`. -Next, power off the Ox64 and re-connect your UART adapter as follows. +Next, power off the Ox64 and re-connect your UART adapter as follows: * RX -> TXD / GPIO16 / pin 32 * TX -> RXD / GPIO17 / pin 31 @@ -175,7 +175,7 @@ You have a choice of flashing software: === CLI packages installation -Install `bflb-iot-tool` using your preferred method of managing PIP packages. One option is to set up a Python virtual environment as follows. +Install `bflb-iot-tool` using your preferred method of managing PIP packages. One option is to set up a Python virtual environment as follows: sudo apt install python3-venv python3 -m venv ~/ox64_venv @@ -186,7 +186,7 @@ NOTE: Each time you open a new terminal window you will need to re-run `. ~/ox64 === DevCube installation -Download the latest DevCube flashing tool from BouffaloLab's website. +Download the latest DevCube flashing tool from BouffaloLab's website: mkdir -p ~/ox64/devcube cd ~/ox64/devcube @@ -194,21 +194,21 @@ Download the latest DevCube flashing tool from BouffaloLab's website. unzip BouffaloLabDevCube-v1.8.9.zip chmod u+x BLDevCube-ubuntu -If you did not create a <> 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 <> 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 * https://we.tl/t-eJWShQJ4iF * https://cdn.discordapp.com/attachments/771032441971802142/1145565853962735639/BouffaloLabDevCube-v1.8.3.zip -Verify that your copy of `BouffaloLabDevCube-v1.8.3.zip` matches the hashes below. +Verify that your copy of `BouffaloLabDevCube-v1.8.3.zip` matches the hashes below: * SHA1: `0f2619e87d946f936f63ae97b0efd674357b1166` * SHA256: `e6e6db316359da40d29971a1889d41c9e97d5b1ff1a8636e9e6960b6ff960913` == Flashing the Ox64 -Put the Ox64 into programming mode. +Put the Ox64 into programming mode: * Press the BOOT button * Apply power or re-plug the USB cable @@ -216,23 +216,23 @@ Put the Ox64 into programming mode. === CLI flashing method -Set up some environment variables to save typing them out later. +Set up some environment variables to save typing them out later: PORT=/dev/ttyACM1 # or /dev/ttyUSB0, this will depend on which serial adapter you use BAUD=230400 # safe value for macOS, if using Linux set to 2000000 for faster flashing -Change directory to the location of your image files. +Change directory to the location of your image files: cd ~/ox64/openbouffalo/firmware # if you downloaded pre-built images # or 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 **combined image** then run the command below: bflb-iot-tool --chipname bl808 --interface uart --port $PORT --baudrate $BAUD --addr 0x0 \ --firmware bl808-combined.bin --single -Otherwise, run the following commands. +Otherwise, run the following commands: bflb-iot-tool --chipname bl808 --interface uart --port $PORT --baudrate $BAUD --addr 0x0 \ --firmware m0_lowload_bl808_m0.bin --single @@ -247,31 +247,31 @@ If you get permission errors when running any of the commands above, you may nee === BLDevCube flashing method -Open a new terminal window to run the DevCube flasher. +Open a new terminal window to run the DevCube flasher: cd ~/ox64/devcube ./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. +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 (make sure you don't use /dev/ttyACM0, it's used by the minicom console) Uart rate 230400 (safe value for macOS, if using Linux set to 2000000 for faster flashing) -If you created a **combined image** then you only need to use the [IOT] tab. +If you created a **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. +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 -Then, switch to the [IOT] tab. +Then, switch to the [IOT] tab: Enable 'Single Download' Image Address [0x800000], [PATH to bl808-firmware.bin] @@ -280,22 +280,22 @@ Then, switch to the [IOT] tab. == Flashing the microSD card -Insert the microSD card into your PC, locate its device file (`/dev/sdb`, for example), and write the image. +Insert the microSD card into your PC, locate its device file `/dev/[DEVICE]` and write the image: cd ~/ox64/openbouffalo/firmware # if you downloaded pre-built images # or cd ~/ox64/buildroot/output/images # if you built your own images - sudo dd if=sdcard.img of=/dev/sdb bs=1M status=progress conv=fsync + sudo dd if=sdcard.img of=/dev/[DEVICE] bs=1M status=progress conv=fsync == Booting for the first time Power off your Ox64 and insert the microSD card. -Open a terminal window to connect to the D0 core’s (i.e. Linux’s) serial console. +Open a terminal window to connect to the D0 core’s (i.e. Linux’s) serial console: 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 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): minicom -b 2000000 -D /dev/ttyACM1 @@ -313,11 +313,11 @@ On the `ttyACM1` console you'll see following log, until the sytem is fully load Once the system is running 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 netowrk -The simplest way to connect is to run the following command from the Linux console (i.e. `/dev/ttyACM0`). +The simplest way to connect is to run the following command from the Linux console (i.e. `/dev/ttyACM0`): 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. +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: udhcpc -i bleth0 @@ -331,26 +331,26 @@ For more information on using the `blctl` command, see https://github.com/bouffa In this section, we will set up our Ox64 to dual-boot both Linux and the NuttX real-time operating system. For more information see the https://nuttx.apache.org/docs/latest/platforms/risc-v/bl808/boards/ox64/index.html[official documentation]. -First, write the normal Linux image to the SD card if you have not done so already. For the purposes of this guide we will assume the SD card's device file is `/dev/sdb`. +First, write the normal Linux image to the SD card if you have not done so already. Make sure to set proper [DEVICE] name in the following cod, in example `/dev/sdb`: cd ~/ox64/openbouffalo/firmware # if you downloaded pre-built images # or cd ~/ox64/buildroot/output/images # if you built your own images - sudo dd if=/sdcard.img of=/dev/sdb bs=1M conv=fsync status=progress + sudo dd if=/sdcard.img of=/dev/[DEVICE] bs=1M conv=fsync status=progress -Run the following command to re-read the partition tables. Re-inserting the SD card works too. +Run the following command to re-read the partition tables. Re-inserting the SD card works too: - sudo blockdev --rereadpt /dev/sdb + sudo blockdev --rereadpt /dev/[DEVICE] -Download the NuttX image. +Download the NuttX image: mkdir -p ~/ox64/nuttx cd ~/ox64/nuttx wget -O ImageNuttx https://github.com/lupyuen2/wip-pinephone-nuttx/releases/download/bl808d-1/Image -Mount the boot partition and make the required modifications. +Mount the boot partition and make the required modifications: - sudo mount /dev/sdb2 /mnt + sudo mount /dev/[DEVICE]2 /mnt sudo cp ImageNuttx /mnt/ sudo tee -a /mnt/extlinux/extlinux.conf <> section; if you a Then write the U-Boot image to the device using the following command: ---- -sudo dd if=ppp/foss/u-boot-rockchip.bin of=/dev/$DEVICE bs=512 seek=64 status=progress conv=fsync +sudo dd if=$WORKDIR/rk2aw/ppp/foss/u-boot-rockchip.bin of=/dev/$DEVICE bs=512 seek=64 status=progress conv=fsync ---- 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. === Build the partitions -Download, decompress and mount the distribution image on your Linux computer. Copy root filesystem and boot to needed partition. Make sure you use an updated image from link:/documentation/PinePhone_Pro/Software/Releases[relases download link] for each distribution. +Download and decompress each distribution image on your Linux computer, making sure you use an updated file from relases download link:/documentation/PinePhone_Pro/Software/Releases[relases download link]. ---- -mkdir -p ~/ppp/distros -cd ~/ppp/distros -wget $DISTROURL +mkdir -p $WORKDIR/distros +cd $WORKDIR/distros +wget $DISTROURL xz -v -d -k IMAGE.*.xz mv IMAGE.img $PARTNAME.img ---- +Only for Sailfish distribution, use an adatped command to download and decompress the image: + +---- +mkdir -p $WORKDIR/distros +cd $WORKDIR/distros +wget $DISTROURL -O artifacts.zip +unzip artifacts.zip +mv pinephonepro/*/sfe-pinephonepro*.tar.bz2 sailfish.tar.bz2 +mkdir -p $WORKDIR/distros/sailfishfs +sudo tar -xvf sailfish.tar.bz2 -C sailfishfs/ > /dev/null +---- + +Mount the image for needed distribution, excluding Sailfish image: + ---- +cd $WORKDIR/distros sudo losetup -P /dev/loop0 $PARTNAME.img sudo mkdir -p /mnt/$PARTNAME/boot /mnt/$PARTNAME/root /mnt/$PARTNAME/device sudo mount /dev/loop0p1 /mnt/$PARTNAME/boot/ sudo mount /dev/loop0p2 /mnt/$PARTNAME/root/ ---- +Only for Sailfish distribution, you ought to copy the extracted files directly into the device: + +---- +#sudo mkfs.ext4 -F /dev/$DEVICE$PARTNUMBER # optional +sudo mkdir -p /mnt/$PARTNAME/device +sudo mount /dev/$DEVICE$PARTNUMBER /mnt/$PARTNAME/device +sudo scp -r $WORKDIR/distros/sailfishfs/* /mnt/$PARTNAME/device +---- + +For all other distributions copy `rootfs` and `boot` content: + ---- sudo dd if=/dev/loop0p2 of=/dev/$DEVICE$PARTNUMBER bs=1M status=progress conv=fsync sudo mount /dev/$DEVICE$PARTNUMBER /mnt/$PARTNAME/device/ sudo scp -r /mnt/$PARTNAME/boot/* /mnt/$PARTNAME/device/boot -# sudo mv /mnt/$PARTNAME/device/boot/boot.scr /mnt/$PARTNAME/device/boot/boot.scrORIG # rename if present ---- -Replace/create `/boot/extlinux/extlinux.conf` and `/etc/fstab` files: +Remame `/boot/boot.scr` to keep graphical menu clean: + +---- +[ ! -f /mnt/$PARTNAME/device/boot/boot.scr ] || sudo mv /mnt/$PARTNAME/device/boot/boot.scr /mnt/$PARTNAME/device/boot/boot.scrORIG # rename if exist +[ ! -f /mnt/$PARTNAME/device/boot/boot.pinephonepro.scr ] || sudo mv /mnt/$PARTNAME/device/boot/boot.pinephonepro.scr /mnt/$PARTNAME/device/boot/boot.pinephonepro.scrORIG # rename if exist +---- + +Rename original and write the new `/boot/extlinux/extlinux.conf` file, making sure you remove `#` comment for needed distribution: ---- sudo mkdir -p /mnt/$PARTNAME/device/boot/extlinux -# sudo mv /mnt/$PARTNAME/device/boot/extlinux/extlinux.conf /mnt/$PARTNAME/device/boot/extlinux/extlinux.confORIG # rename if present +[ ! -f /mnt/$PARTNAME/device/boot/extlinux/extlinux.conf ] || sudo mv /mnt/$PARTNAME/device/boot/extlinux/extlinux.conf /mnt/$PARTNAME/device/boot/extlinux/extlinux.confORIG # rename if exist sudo tee /mnt/$PARTNAME/device/boot/extlinux/extlinux.conf <