Skip to content

Commit

Permalink
Merge pull request #32 from Pavlos1/main
Browse files Browse the repository at this point in the history 
Updated the Ox64 flashing guide
  • Loading branch information
@x1y
x1y authored Feb 10, 2024
2 parents 63ccec0 + 47e835f commit 0f13775
Show file tree
Hide file tree
Showing 2 changed files with 143 additions and 92 deletions.
26 changes: 12 additions & 14 deletions content/documentation/Ox64/Software/Building.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,10 @@ menu:
weight: 2
---

Open the terminal and clone the primary Buildroot repository and the specific Buildroot Bouffalo repository:
Open the terminal and clone the upstream Buildroot repository and the Buildroot Bouffalo overlay repository:

cd ~/Downloads/ox64
mkdir -p ~/ox64
cd ~/ox64
git clone https://github.com/buildroot/buildroot
git clone https://github.com/openbouffalo/buildroot_bouffalo

Expand All @@ -21,12 +22,11 @@ Define an environment variable for the Buildroot Bouffalo overlay path:

Change directory into the cloned Buildroot folder:

cd ~/Downloads/ox64/buildroot
cd ~/ox64/buildroot

Apply the default configuration for Pine64 Ox64:

make BR2_EXTERNAL=$BR_BOUFFALO_OVERLAY_PATH pine64_ox64_defconfig
# make clean # deletes all the already compiled object files

Use the `menuconfig` tool to adjust the build settings:

Expand All @@ -42,20 +42,18 @@ Within `menuconfig`, configure the following:
* Set `Target ABI` to `lp64d`
* Under `Toolchain`, enable `Fortran support` and `OpenMP support`

Initiate the build process, but make sure first that your `PATH` variable contains no spaces:
Initiate the build process, but first make sure that your `PATH` variable contains no spaces:

make

Check you got required file for flashing in the `buildroot/output/images` directory.
Buildroot will output to the `~/ox64/buildroot/output/images` directory. Check that you have the required files for flashing:

cd ~/Downloads/ox64/buildroot/output/images
ls | less *808*.bin *.img
cd ~/ox64/buildroot/output/images
ls *808*.bin *.img

Expected files:

* m0_lowload_bl808_m0.bin
* d0_lowload_bl808_d0.bin
* bl808-firmware.bin
* sdcard.img

** bl808-firmware-combo.bin # combined image file (see link:Flashing#optional_create_a_combined_soc_image[Flashing] chapter)
* `m0_lowload_bl808_m0.bin`
* `d0_lowload_bl808_d0.bin`
* `bl808-firmware.bin`
* `sdcard.img`
209 changes: 131 additions & 78 deletions content/documentation/Ox64/Software/Flashing.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,28 +14,45 @@ This page explains how to flash an Ox64 board and a microSD card to boot the sys
== Prepare the environment
You need a Linux machine, a Raspberry Pi Pico to act as a UART adapter, the Ox64 board, and a microSD card.

Start a terminal session and set the working directory to download some files.
First, download the Raspberry Pi Pico firmware that allows it to act as a serial adapter.
You may skip this step if you are using your own serial adapter.
(But see link:/documentation/Ox64/Further_information/Compatible_UARTs/[Compatible_UARTs]
and <<using_a_serial_adapter_other_than_the_pico>>.)

cd ~/Downloads
mkdir ox64 ox64/pico
cd ~/Downloads/ox64/pico
wget https://github.com/Kris-Sekula/Pine64_Ox64_SBC/blob/main/uart/picoprobe.uf2
mkdir -p ~/ox64/pico
cd ~/ox64/pico
wget https://github.com/Kris-Sekula/Pine64_Ox64_SBC/raw/main/uart/picoprobe.uf2

cd ~/Downloads/ox64
mkdir openbouffalo
cd ~/Downloads/ox64/openbouffalo
Next, 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] section.

mkdir -p ~/ox64/openbouffalo
cd ~/ox64/openbouffalo
wget https://github.com/openbouffalo/buildroot_bouffalo/releases/download/v1.0.1/bl808-linux-pine64_ox64_full_defconfig.tar.gz
tar -xvzf bl808-linux-pine64_ox64_full_defconfig.tar.gz

cd ~/Downloads/ox64
mkdir ox64/devcube
cd ~/Downloads/ox64/devcube
NOTE: If you built your own images, substitute `~/ox64/openbouffalo` with
`~/ox64/buildroot/output/images` in all instructions that follow.

In any case, verify that you have all the required image files:

* `m0_lowload_bl808_m0.bin` -- Startup code for the M0 core.
* `d0_lowload_bl808_d0.bin` -- Startup code for the D0 core.
* `bl808-firmware.bin` -- OpenSBI and UBoot DTB files. Runs on the D0 core.
* `sdcard.img` -- Kernel and root filesystem. Runs on the D0 core.

Next, download the latest DevCube flashing tool from BouffaloLab's website. You may skip this
step if you are using the <<cli_flashing_method>>.

mkdir -p ~/ox64/devcube
cd ~/ox64/devcube
wget https://dev.bouffalolab.com/media/upload/download/BouffaloLabDevCube-v1.8.8.zip
unzip BouffaloLabDevCube-v1.8.8.zip
chmod u+x BLDevCube-ubuntu

If you are not creating a combined image (see below) you may need an older version of the DevCube.
In that case, download v1.8.3 from one of the mirrors below:
If you are not creating 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:

* 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
Expand All @@ -47,43 +64,45 @@ Verify that your copy of `BouffaloLabDevCube-v1.8.3.zip` matches the hashes belo
* SHA1: `0f2619e87d946f936f63ae97b0efd674357b1166`
* SHA256: `e6e6db316359da40d29971a1889d41c9e97d5b1ff1a8636e9e6960b6ff960913`

You'll need the following files to flash the BL808 SoC (M0 core, D0 core, excluding only Low Power core) and the SD card.

m0_lowload_bl808_m0.bin - Runs on the M0 wireless core and forwards interupts to the D0 for several peripherals
d0_lowload_bl808_d0.bin - Runs on the D0 multimedia core; pre-loads opensbi, the kernel and uboot dts files into ram
bl808-firmware.bin - Runs on the D0 multimedia core; contains opensbi, uboot dtb files
sdcard.img - Runs on the D0 multimedia core; contains the kernel and rootfs

== 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+).

cd ~/Downloads/ox64/buildroot/output/images
fallocate -l 0x800000 bl808-firmware-combo.bin
dd conv=notrunc if=m0_lowload_bl808_m0.bin of=bl808-firmware-combo.bin
dd conv=notrunc if=d0_lowload_bl808_d0.bin of=bl808-firmware-combo.bin seek=$((0x100000))B
cat bl808-firmware.bin >> bl808-firmware-combo.bin

== Establish serial communication from PC to Ox64 using Pi Pico
----
cd ~/ox64/openbouffalo
Open a terminal and check the connected USB serial devices.
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
----

ls /dev/ttyACM*
== Establish serial communication from PC to Ox64 using Pi Pico

Set 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
* Release the BootSel button

NOTE: You could also ground pin28 to TP6 while powering.
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).

Copy `picoprobe.uf2` file into the new device `/media/<user>/RPI-RP2`.

cp ~/Downloads/ox64/pico/picoprobe.uf2 /media/<user>/RPI-RP2
cp ~/ox64/pico/picoprobe.uf2 /media/<user>/RPI-RP2

After flashing, verify that you have two serial interfaces (when the Pico is connected to your PC):

----
$ ls /dev/ttyACM*
After flashing, the device will auto-set in serial UART communication mode according to the following wiring diagram.
/dev/ttyACM0
/dev/ttyACM1
----

Next, connect the Ox64 board to the Pico according to the following wiring diagram:

OX64 PI PICO
uart0_Tx_GPIO14_pin1 <-> uart0_Rx_pin17
Expand All @@ -93,40 +112,44 @@ After flashing, the device will auto-set in serial UART communication mode accor
gnd_pin38 <-> gnd_pin38/3
vbus5v_pin40 <-> vbus5v_pin40

== Flashing the Ox64
[NOTE]
====
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.
There are two new ports to choose from, `/dev/ttyACM0` for serial console and `/dev/ttyACM1` for DevCube flashing.
* `/dev/ttyACM0` connects to the D0 core's (i.e. Linux's) serial console
* `/dev/ttyACM1` is used for flashing (but also connects to the M0 core's serial console)
minicom -b 2000000 -D /dev/ttyACM0
This configuration eliminates the need to switch the physical connections to the Ox64 board
between flashing and testing the system.
====

Set the Ox64 board into programming mode.
== Flashing the Ox64
Put the Ox64 into programming mode:

* Press the BOOT button
* Apply power or re-plug the USB cable
* Release the BOOT button

Close `minicom`.

=== BLDevCube flashing method

Open a new terminal window to run the DevCube flasher.

cd ~/Downloads/ox64/devcube
cd ~/ox64/devcube
./BLDevCube-ubuntu

Select chip [BL808], press Finish and set for EACH tabs [MCU] and [IOT]. When you switch between tabs double check these common setting.
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 (make sure you don't use /dev/ttyACM0, it's used by the minicom console)
Uart rate 2000000 (set a lower rate to avoid errors, i.e. 230400)
UART TX is physical pin 1/GPIO 14
UART RX is physical pin 2/GPIO 15
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:

Enable 'Single Download'
Image Address [0x0], [PATH to bl808-firmware-combo.bin]
Click 'Create & Download' again and wait until it's done
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:
Expand All @@ -147,71 +170,101 @@ For those who do not want to use the DevCube, BouffaloLab provides open-source f

First, 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 virtualenv python3-virtualenv python3.11-venv
python3 -m venv ~/ox64_venv
. ~/ox64_venv/bin/activate
pip install bflb-iot-tool # we are *not* using bflb-mcu-tool
----
sudo apt install python3-venv
python3 -m venv ~/ox64_venv
. ~/ox64_venv/bin/activate
pip install bflb-iot-tool # we are *not* using bflb-mcu-tool
----

NOTE: Each time you open a new terminal window you will need to re-run `. ~/ox64_venv/bin/activate` to reactivate the virtual environment.

Next, set up some environment variables to save typing them out later:

PORT=/dev/ttyACM1 # this will depend on which serial adapter you use
BAUD=115200 # safe value for macOS, if using Linux set to 2000000 for faster flashing
BAUD=230400 # safe value for macOS, if using Linux set to 2000000 for faster flashing

Change directory to the location of your image files:

cd ~/Downloads/ox64/buildroot/output/images
cd ~/ox64/openbouffalo

Finally, flash the Ox64. If you created a **combined image** then run the following command:

bflb-iot-tool --chipname bl808 --interface uart --port $PORT --baudrate $BAUD --addr 0x0 \
--firmware bl808-firmware-combo.bin --single
--firmware bl808-combined.bin --single

Otherwise:

bflb-iot-tool --chipname bl808 --interface uart --port $PORT --baudrate $BAUD --addr 0x000000 \
--firmware m0_lowload_bl808_m0.bin --single

bflb-iot-tool --chipname bl808 --interface uart --port $PORT --baudrate $BAUD --addr 0x100000 \
--firmware d0_lowload_bl808_d0.bin --single

bflb-iot-tool --chipname bl808 --interface uart --port $PORT --baudrate $BAUD --addr 0x800000 \
--firmware bl808-firmware.bin --single
----
bflb-iot-tool --chipname bl808 --interface uart --port $PORT --baudrate $BAUD --addr 0x0 \
--firmware m0_lowload_bl808_m0.bin --single
bflb-iot-tool --chipname bl808 --interface uart --port $PORT --baudrate $BAUD --addr 0x100000 \
--firmware d0_lowload_bl808_d0.bin --single
bflb-iot-tool --chipname bl808 --interface uart --port $PORT --baudrate $BAUD --addr 0x800000 \
--firmware bl808-firmware.bin --single
----

If you get permission errors when running any of the commands above, you may need to add your user to the `dialout` group. Running the commands as `root` is not recommended since this will make `bflb-iot-tool` create root-owned files in your home directory.


== Flashing the microSD card

Insert microSD card into PC, locate its device file (`/dev/sdb`, for example), erase the start of the card and proceed to flashing.
Insert the microSD card into your PC, locate its device file (`/dev/sdb`, for example), and write the image:

cd ~/Downloads/ox64/buildroot/output/images
sudo dd if=/dev/zero of=/dev/sdb count=1 bs=32768
cd ~/ox64/openbouffalo
sudo dd if=sdcard.img of=/dev/sdb bs=1M status=progress conv=fsync

== Booting for the first time

Insert microSD card into Ox64 and set a UART connection to the Ox64 board, using the following parameters.
Insert the microSD card into your Ox64 and open a UART connection to the Ox64 board:

* UART TX is physical pin 32/GPIO 16
* UART RX is physical pin 31/GPIO 17
* Baud rate is 2000000
minicom -b 2000000 -D /dev/ttyACM0

Choose from serial devices `/dev/ttyACM0` and `/dev/ttyACM1`, using the lower number.
Re-apply power to the Ox64 and you will see Linux booting up. When prompted, log in
as `root` with no password.

minicom -b 2000000 -D /dev/ttyACM0

Re-apply power to the Ox64 and enjoy the booting!
== Appendix

=== Using a serial adapter other than the Pico
If you are using one of the
link:/documentation/Ox64/Further_information/Compatible_UARTs/[supported UART adapters]
that isn't the Pico, you will only have one serial interface available to you. For the purposes
of this guide, let's say it is `/dev/ttyUSB0`.

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:

* RX -> UART0_TX / GPIO14 / pin 1
* TX -> UART0_RX / GPIO15 / pin 2
* GND -> any ground (e.g. pin 3)

Then, follow the instructions in <<flashing_the_ox64>> and <<flashing_the_microsd_card>>, but
replace all occurrences of `/dev/ttyACM1` with `/dev/ttyUSB0`.

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>>, but replace all occurrences of
`/dev/ttyACM0` with `/dev/ttyUSB0`. You should now have a working Linux system.

image:/documentation/Ox64/images/ox64_pinout.png[Pinout of the production version,title="Pinout of the production version", 300]

== Adding Nuttx RTOS
=== Adding Nuttx RTOS

Get Nuttx image from lupyen's github page. More info on building on https://nuttx.apache.org/docs/latest/platforms/risc-v/bl808/boards/ox64/index.html.

cd ~/Downloads/ox64
mkdir nuttx
cd ~/Downloads/ox64/nuttx
mkdir -p ~/ox64/nuttx
cd ~/ox64/nuttx
wget https://github.com/lupyuen2/wip-pinephone-nuttx/releases/download/bl808d-1/Image
sudo mv Image ImageNuttx

Expand All @@ -238,13 +291,13 @@ Partition the microSD card.

Mount the `sdcard.img` image, copy `boot` and `rootfs`. Add `ImageNuttx` and edit `/extlinux/extlinux.conf` to add a new Nuttx boot option.

cd ~/Downloads/ox64/buildroot/output/images
cd ~/ox64/openbouffalo
sudo losetup -P /dev/loop1 sdcard.img

sudo dd if=/dev/loop1p2 of=/dev/sdb2 bs=1M status=progress conv=fsync
sudo mkdir /mnt/nuttx_boot_sd
sudo mount /dev/sdb2 /mnt/nuttx_boot_sd/
sudo scp -r ~/Downloads/ox64/nuttx/ImageNuttx /mnt/nuttx_boot_sd
sudo scp -r ~/ox64/nuttx/ImageNuttx /mnt/nuttx_boot_sd

cd /mnt/nuttx_boot_sd/extlinux
sudo nano extlinux.conf
Expand All @@ -257,7 +310,7 @@ Mount the `sdcard.img` image, copy `boot` and `rootfs`. Add `ImageNuttx` and edi
sudo dd if=/dev/loop1p3 of=/dev/sdb3 bs=1M status=progress conv=fsync
sudo mkdir /mnt/nuttx_rootfs_sd
sudo mount /dev/sdb3 /mnt/nuttx_rootfs_sd/
sudo scp -r ~/Downloads/ox64/nuttx/ImageNuttx /mnt/nuttx_rootfs_sd/boot
sudo scp -r ~/ox64/nuttx/ImageNuttx /mnt/nuttx_rootfs_sd/boot

cd /mnt/nuttx_rootfs_sd/boot/extlinux
sudo nano extlinux.conf
Expand Down

0 comments on commit 0f13775

Please sign in to comment.