kumquat-readthedocs/docs/software/esp32firmware.md

Flashing the ESP32

This guide provides detailed steps to flash the ESP32 module on the Kumquat board. The ESP32 is used for WiFi and Bluetooth via the ESP-Hosted-NG firmware, which is provided by Espressif. To perform flashing or other configuration tasks, you must first stop the driver and disable the SDIO bus to gain control over the ESP32 strapping pins.

Prerequisites

Before proceeding, ensure you have:

• esptool.py, espefuse.py, and espsecure.py pre-installed on the Kumquat demo image. These tools are available by default.

• A valid ESP-Hosted-NG firmware file. You can download the latest version using the following command:

  wget https://github.com/espressif/esp-hosted/releases/download/release%2Fng-v1.0.2/ESP-Hosted-NG_release_v1.0.2.tgz
  

• Extract the downloaded file:

  tar -xzvf ESP-Hosted-NG_release_v1.0.2.tgz
  

• The ESP-Hosted-NG firmware is located inside /ESP-Hosted-NG_release_v1.0.2/esp32/sdio_only/.

Step-by-Step Instructions

Step 1: Stop the ESP32 Driver

First, stop the running ESP-Hosted driver. This driver is responsible for WiFi and Bluetooth functionality on the ESP32:

/etc/init.d/S35esphosted stop

This will release control of the ESP32 and allow you to flash it.

Step 2: Disable the SDIO Bus

You need to disable the SDIO bus because the D0 strapping pin of the ESP32 is controlled via the SDIO bus. Disabling the bus ensures that the ESP32 can enter bootloader mode without interference.

echo "1c10000.mmc" > /sys/bus/platform/drivers/sunxi-mmc/unbind

Step 3: Set ESP32 to Bootloader Mode

Next, set the ESP32 to bootloader mode by adjusting the GPIO pins:

• Set the strapping pins to bootloader mode:

  gpioset $(gpiofind ESP_nBOOT)=0 && gpioset $(gpiofind ESP_D0)=0
  

• Reset the ESP32 to apply the changes:

  gpioset $(gpiofind ESP_nRST)=0 && gpioset $(gpiofind ESP_nRST)=1
  

At this point, the ESP32 is ready to be flashed.

Step 4: Setting Flash Voltage (If Needed)

If you have replaced the ESP32 on the Kumquat board, you'll need to set the flash voltage to 3.3V by burning the e-fuse.

• Run the following command during the bootloader mode:

  espefuse.py -p /dev/ttyS1 -b 115200 --chip esp32 set_flash_voltage 3.3V
  

• When prompted, type BURN in all caps to confirm and permanently burn the fuse. This step cannot be undone.

Step 5: Flash the ESP-Hosted-NG Firmware

Once the ESP32 is in bootloader mode, you can flash the ESP-Hosted-NG firmware:

• Navigate to the firmware directory:

  cd /ESP-Hosted-NG_release_v1.0.2/esp32/sdio_only/
  

• Run the flashing command using esptool.py:

  esptool.py -p /dev/ttyS1 -b 115200 --chip esp32 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader.bin 0x8000 partition-table.bin 0xd000 ota_data_initial.bin 0x10000 network_adapter.bin
  

Step 6: Reset ESP32 to Normal Flashing Mode

After flashing the ESP32, reset the strapping pins back to normal operation:

gpioset $(gpiofind ESP_nBOOT)=0

Reset the ESP32 again to apply the changes:

gpioset $(gpiofind ESP_nRST)=0 && gpioset $(gpiofind ESP_nRST)=1

Step 7: Re-enable the SDIO Bus

Rebind the SDIO bus to restore communication with the ESP32 module:

echo "1c10000.mmc" > /sys/bus/platform/drivers/sunxi-mmc/bind

Step 8: Restart the ESP-Hosted Driver

Finally, restart the ESP-Hosted driver to enable WiFi and Bluetooth services:

/etc/init.d/S35esphosted start

Summary

This guide covers the process of flashing the ESP32 on the Kumquat board. You'll need to stop the driver, disable the SDIO bus, and adjust GPIOs to put the ESP32 into bootloader mode. After flashing the firmware, reset the ESP32 and restore the SDIO bus and driver. If replacing the ESP32, don't forget to set the flash voltage using espefuse.py.