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 all commits
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
100 changes: 55 additions & 45 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 @@ -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:

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

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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -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]
----
Expand Down Expand Up @@ -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

Expand All @@ -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]
----
Expand All @@ -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:
Expand All @@ -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:
Expand Down Expand Up @@ -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
----
Expand All @@ -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
----
Expand Down
Loading