Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Ox64 flashing guide: clarifications regarding serial interfaces #78

Merged
merged 3 commits into from
Apr 7, 2024
Merged

Ox64 flashing guide: clarifications regarding serial interfaces #78

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a64d526
Ox64 flashing guide: clarifications regarding serial interfaces
Pavlos1 Mar 27, 2024
bfc8b24
Partial revert of #77
Pavlos1 Apr 7, 2024
dff562a
Merge remote-tracking branch 'upstream/main'
Pavlos1 Apr 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 53 additions & 40 deletions content/documentation/Ox64/Software/Flashing.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
----
Expand Down Expand Up @@ -103,7 +103,7 @@ Next, connect the Ox64 board to the Pico according to the following wiring diagr
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.
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:

Expand All @@ -121,7 +121,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:

Expand All @@ -130,7 +137,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:
Expand All @@ -139,15 +145,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 the USB serial adapter's device path with `ls /dev/ttyUSB* /dev/ttyACM*` (or similar), and 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:

Expand Down Expand Up @@ -176,25 +183,25 @@ Expected result:

=== Option 3: Generic UART adapter

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 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.

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.
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>>.

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>>. You should then have a working Linux system.

image:/documentation/Ox64/images/ox64_pinout.png[Ox64 pinout,title="Ox64 pinout", 300]

Expand Down Expand Up @@ -232,7 +239,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
Expand All @@ -252,14 +259,16 @@ Put the Ox64 into programming mode:
* Apply power or re-plug the USB cable
* Release the BOOT button

For the remainder of this section, replace all occurrences of `/dev/tty[DEVICE]` with the serial port that will be used for _flashing_. If you are using a Pico or Bluepill as your serial adapter, this will be `/dev/ttyACM1`. If you are using a generic serial adapter, find its device path with `ls /dev/ttyUSB* /dev/ttyACM*` or similar.

=== 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
$ BAUD=230400 # safe value for macOS, set to 2000000 for faster flashing on Linux
----

Change directory to the location of your image files:
Expand All @@ -271,7 +280,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]
----
Expand Down Expand Up @@ -307,31 +316,37 @@ $ ./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)
----
[cols="~,~"]
|===
|Interface
|UART

|Port/SN
|`/dev/tty[DEVICE]`

|UART rate
|230400 (safe value for macOS, set to 2000000 for faster flashing on Linux)
|===

If you created a **combined image** then you only need to use the [IOT] tab:
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
* 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

Expand All @@ -350,14 +365,14 @@ $ sudo dd if=sdcard.img of=/dev/[DEVICE] bs=1M status=progress conv=fsync

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. If you are using a Pico or Bluepill as your serial adapter, this will be `/dev/ttyACM0`. If you are using a generic serial adapter, use the same `/dev/tty[DEVICE]` file as you did in the flashing section:

[source,console]
----
$ minicom -b 2000000 -D /dev/ttyACM0
$ minicom -b 2000000 -D /dev/tty[DEVICE]
Copy link
Contributor

@giorez giorez Mar 27, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was not able to solve the clarification as you propose in this PR, but in genreal you did a great job. But regarding ttyACM0 and ttyACM1 is really important to make clear there are 2 ports linked to different cores of ox64, and how to open the two ports without guessing the command.

----

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]
----
Expand All @@ -366,19 +381,19 @@ $ 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 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same as above


On the `ttyACM1` console you'll see following log, until the sytem is fully loaded.
On the M0 console you'll see following messages until the sytem is fully loaded:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same as above


[I][MBOX] Mailbox IRQ Stats:
[I][MBOX] Peripheral SDH (33): 0
[I][MBOX] Peripheral GPIO (60): 0
[I][MBOX] Unhandled Interupts: 0 Unhandled Signals 0

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.
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`):
The simplest way to connect is to run the following command from the Linux console:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same as above


[source,console]
----
Expand Down Expand Up @@ -439,7 +454,6 @@ $ sudo tee -a /mnt/extlinux/extlinux.conf <<EOF
LABEL Pine64 0X64 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
----
Expand All @@ -454,7 +468,6 @@ $ sudo tee -a /mnt/boot/extlinux/extlinux.conf <<EOF
LABEL Pine64 0X64 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
----
Expand Down
Loading