diff --git a/content/documentation/Ox64/Software/Flashing.adoc b/content/documentation/Ox64/Software/Flashing.adoc index 1b81d348..a16e1a43 100644 --- a/content/documentation/Ox64/Software/Flashing.adoc +++ b/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,9 +228,13 @@ 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: @@ -231,7 +242,7 @@ Refer to the pinout image below. Connect your UART adapter as follows: * 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 <> and <>, 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 <> and <>, but replace all occurrences of `/dev/ttyACM1` with `/dev/tty[DEVICE]`. Next, power off the Ox64 and re-connect your UART adapter as follows: @@ -239,7 +250,7 @@ Next, power off the Ox64 and re-connect your UART adapter as follows: * TX -> RXD / GPIO17 / pin 31 * GND -> any ground (e. g. pin 33) -Then, follow the instructions in <>, 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 <>, 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 <> 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 ---- 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 <