Flashing the firmware and preparing the SD card

The ESP32 microcontroller on the dev board needs firmware installed (“flashed”). In addition, the logger needs a configuration file added to its MicroSD card to operate correctly.

Flashing the firmware

Downloading the firmware binaries

Go to the ‘releases’ page in the BODAQS github repository here and find the latest firmware release. The releases list includes releases for logger firmware, application software and other things besides. We are interested in firmware releases.

Scroll to the bottom of the release section and download the three .bin files for the Proto F logger.

Which binaries do I need?

A complete set of binaries is three files: a bootloader, a partitions table and the application firmware itself. The first time you flash your logger, you need to flash all three files. If you update the firmware later, you will generally only need to flash the application firmware.

Find the Flash addresses section in the release notes. Note the addresses for each .bin file.

Option 1: Browser flasher for Windows users

Chromium only

The ESPTool requires a chromium-based web browser such as Google Chrome, Microsoft Edge, or Brave

This is the easiest installation method for most Windows users. Use Google Chrome or Microsoft Edge.

Connect the dev board to your computer with a USB data cable and open the Adafruit WebSerial ESPTool here: Adafruit WebSerial ESPTool. Check the baud rate is set to 115200 and click Connect.

When Windows shows a list of serial devices, select the port for your BODAQS board and approve access.

In the three file rows, enter the flash addresses you noted earlier. Click Choose a file and select the downloaded BODAQS binary that matches that row’s address.

Click Program and wait for the flash process to complete.

If the board does not start automatically after flashing, press the Reset button on the board or unplug and reconnect it. (If you are building the logger and flashing firmware for the first time, you can delay this step until the OLED display is installed).

Option 2: ESPtool for Mac, Linux, and advanced users

• This option is recommended for Mac and Linux users, and for Windows users who prefer a command-line method.

Via Pip (preferred)

Note

For comprehensive setup for Apple computers see The official installation guide

• Install Python 3.10 or newer if it is not already installed.
• Install esptool by running:

  pip install esptool

Via Homebrew (MacOs only)

Caution

The homebrew method is a quick way to get esptool installed on macOS, but it may not always have the latest version. For best results, install via pip

If you have Homebrew installed, you can install esptool by running:

brew install esptool

---

Once you have your firmware file and ESPtool installed, follow these steps to flash the firmware:

• Connect your BODAQS board to your computer with a USB data cable.

• Identify the serial port used by the board:
• Windows: something like COM3
• Mac: something like /dev/cu.usbmodem...
• Linux: something like /dev/ttyACM0 or /dev/ttyUSB0
• Open a terminal or command prompt in the folder containing the downloaded firmware file.
• Run the following command, replacing the port name and file name as needed:

esptool --chip esp32s3 --port YOUR_PORT write-flash 0x0 bodaqs-firmware.bin

• Example on Windows:

esptool --chip esp32s3 --port COM3 write-flash 0x0 bodaqs-firmware.bin

• Example on Mac or Linux:

esptool --chip esp32s3 --port /dev/cu.usbmodemXXXX write-flash 0x0 bodaqs-firmware.bin

• Wait for the flash process to complete.
• If the board does not start automatically after flashing, press the Reset button on the board or unplug and reconnect it.

If flashing does not work

• Check that your USB cable supports data, not just charging.
• Try a different USB port.
• Close any serial monitor or other software that may already be using the serial port.
• Try unplugging and reconnecting the board.
• If needed, restart the board and try again.
• If browser flashing does not work, use the ESPtool method instead.

Preparing the MicroSD card

Connect the MicroSD card to your computer and format it in FAT32.

Create a folder named ‘config’ in the card’s root directory. Download the config file here and place it in the config directory.

Open the config file in a text editor and change the timezone to suit your location. The ‘tz’ parameter requires a POSIX string - you can find a list of them here

Add some wifi credentials for one or more WiFi networks (if you plan on running the logger in station mode). You may like to change the logger’s SSID and password for Access Point mode too.

Save the config file and eject the MicroSD card. Install it in the MicroSD slot in the PCB.