There are two versions of the Kaluga board, v1.2 and v1.3. Check which version you have, and install the correct build of CircuitPython. The board revisions change the pinout of the camera connector slightly.

Now, use the breakout USB connection in lieu of either of the built-in USB Micro B ports to install and use CircuitPython.

Start by connecting the USB Breakout Cable to the Kaluga board.

  • Black: Use a Male/Female Extension Jumper Wire to connect to GND
  • White: Connect to IO19
  • Green: Connect to IO20
  • Red: Use a Male/Female Extension Jumper Wire to connect to 5V
Do not connect the Red wire to 3V3, it will irreversibly damage the Kaluga.

If you're familiar with our other products and chipsets you may be famliar with our drag-n-drop bootloader, a.k.a UF2. We have a UF2 bootloader for the ESP32-S2, that will let you drag firmware on/off a USB disk drive.

Unlike the M0 (SAMD21) and M4 (SAMD51) boards, there is no bootloader protection for the UF2 bootloader. That means it is possible to erase or damage the bootloader, especially if you upload Arduino sketches to ESP32S2 boards that doesn't "know" there's a bootloader it should not overwrite!

However, thanks to the ROM bootloader, you don't have to worry about it if the UF2 bootloader is damaged. The ROM bootloader can never be disabled or erased, so its always there if you need it! You can simply re-load the UF2 bootloader (USB-disk-style) with the ROM bootloader (non-USB-drive)

You can use the TinyUF2 bootloader to load code directly, say CircuitPython or the binary output of an Arduino compilation or you can use it to load a second bootloader on, like UF2 which has a drag-n-drop interface.

Installing the UF2 bootloader will erase your board's firmware which is also used for storing CircuitPython/Arduino/Files! Be sure to back up your data first.

Method 1: WebSerial ESPTool / esptool

This section outlines using WebSerial ESPTool or esptool to flash the UF2 bootloader onto your ESP32-S2 board.

Step 1. Download the tinyuf2 combined.bin file here

Note that this file is 3MB but that's because the bootloader is near the end of the available flash. It's not actually 3MB large, most of the file is empty but its easier to program if we give you one combined 'swiss cheese' file. Save this file to your desktop or wherever you plan to run esptool from

Step 2. Place your board in bootloader mode

Entering the bootloader is easy. Complete the following steps.

  1. Make sure your ESP32-S2 is plugged into USB port to your computer using a data/sync cable. Charge-only cables will not work!
  2. Turn on the On/Off switch - If your board has a power switch, check that you see the OK light on so you know the board is powered, a prerequisite!
  3. Press and hold the DFU / Boot0 button down. Don't let go of it yet!
  4. Press and release the Reset button. You should have the DFU/Boot0 button pressed while you do this.
  5. Now you can release the DFU / Boot0 button

Because there are several incompatible versions of the Kaluga TFT display, the bootloader's screen may appear incorrectly or not at all. This does not affect its operation.

Check for a new serial / COM port

On Windows check the Device manager - you will see a COM port, for example here its COM88. You may also see another "Other device" called ESP32-S2

It's best to do this with no other dev boards plugged in so you don't get confused about which COM port is the ESP32-S2

On Mac/Linux you will need to find the tty name which lives under /dev

On Linux, try ls /dev/ttyS* for example, to find the matching serial port name. In this case it shows up as /dev/ttyS87. If you don't see it listed try ls /dev/ttyA* on some Linux systems it might show up like /dev/ttyACM0

On Mac, try ls /dev/cu.usbmodem* for example, to find the matching serial port name. In this case, it shows up as /dev/cu.usbmodem01

It's best to do this with no other dev boards plugged in so you don't get confused about which serial port is the ESP32-S2

Step 3 Option A. Use the Web Serial ESPTool to upload

The WebSerial ESPTool was designed to be a web-capable option for programming ESP32-S2 boards. It allows you to erase the contents of the microcontroller and program up to 4 files at different offsets.

You will have to use the Chrome browser for this to work, Safari and Firefox, etc are not supported because we need Web Serial and only Chrome is supporting it to the level needed.

Enable Web Serial (For older chrome)

As of chrome 89, Web Serial is already enabled, so this step is only necessary on older browsers.

Visit chrome://flags from within Chrome. Find and enable the Experimental Web Platform features

Restart Chrome

Connecting

In the Chrome browser visit https://adafruit.github.io/Adafruit_WebSerial_ESPTool/. It should look like the image to the left.

Press the Connect button in the top right of the web browser. You will get a pop up asking you to select the COM or Serial port.

Remember, you should remove all other USB devices so only the ESP32-S2 board is attached, that way there's no confusion over multiple ports!

On some systems, such as MacOS, there may be additional system ports that appear in the list.

The Javascript code will now try to connect to the ROM bootloader. It may timeout for a bit until it succeeds. On success, you will see that it is Connected and will print out a unique MAC address identifying the board.

Once you have successfully connected, the command toolbar will appear.

Erasing the Contents

If you would like to erase the entire flash area so that you can start with a clean slate, you can use the erase feature. We recommend doing this if you are having issues.

To erase the contents, click the Erase button. You will be prompted whether you want to continue. Click OK to continue or if you changed your mind, just click cancel.

Programming the Microcontroller

Programming the microcontroller can be done with up to 4 files at different locations, but with the tinyuf2combo BIN file, which you should have downloaded under Step 1 on this page, you only need to use 1 file.

You can click on Choose a file... from any of the available buttons. It will only attempt to program buttons with a file and a unique location. Then select the Adafruit CircuitPython BIN files (not the UF2 file!)

Verify that the Offset box next to the file location you used is 0x0.

Once you choose a file, the button text will change to match your filename. You can then select the Program button to start flashing.

A progress bar will appear and after a minute or two, you will have written the firmware.

After using the tool, press the reset button to get out of bootloader mode and launch the new firmware!

Step 3. Option B. Use esptool.py to upload (for advanced users)

Once you have entered ROM bootloader mode, you can then use Espressif's esptool program to communicate with the chip! esptool is the 'official' programming tool and is the most common/complete way to program an ESP chip.

Install ESPTool.py

You will need to use the command line / Terminal to install and run esptool.

You will also need to have pip and Python installed (any version!)

Install the latest version using pip (you may be able to run pip without the 3 depending on your setup):

pip3 install --upgrade esptool

Then, you can run:

esptool.py

Test the Installation

Run esptool.py in a new terminal/command line and verify you get something like the below:

Make sure you are running esptool v3.0 or higher, which adds ESP32-S2 support

Run the following command, replacing the identifier after --port with the COMxx, /dev/cu.usbmodemxx or /dev/ttySxx you found above.

esptool.py --port COM88 chip_id

You should get a notice that it connected over that port and found an ESP32-S2

Installing the Bootloader

Run this command and replace the serial port name with your matching port and the file you just downloaded

esptool.py --port COM88 write_flash 0x0 tinyuf2_combo.bin

Don't forget to change the --port name to match.

There might be a bit of a 'wait' when programming, where it doesn't seem like it's working. Give it a minute, it has to erase the old flash code which can cause it to seem like it's not running.

You'll finally get an output like this:

Step 4. Reset the board

Click the RESET button to launch the bootloader. You'll see a new disk drive on your computer with the name KALUGA1BOOT.

You're now ready to copy the CircuitPython UF2 on to the drive which will set up CircuitPython!

Method 2: Flash an Arduino Sketch

This section outlines flashing an Arduino sketch onto your ESP32-S2 board, which automatically installs the UF2 bootloader as well.

Arduino IDE Setup

If you don't already have the Arduino IDE installed, the first thing you will need to do is to download the latest release of the Arduino IDE. ESP32-S2 requires version 1.8 or higher. Click the link to download the latest.

After you have downloaded and installed the latest version of Arduino IDE, you will need to start the IDE and navigate to the Preferences menu. You can access it from the File > Preferences menu in Windows or Linux, or the Arduino > Preferences menu on OS X.

The Preferences window will open.

In the Additional Boards Manager URLs field, you'll want to add a new URL. The list of URLs is comma separated, and you will only have to add each URL once. The URLs point to index files that the Board Manager uses to build the list of available & installed boards.

Copy the following URL.

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json

Add the URL to the the Additional Boards Manager URLs field (highlighted in red below).

Click OK to save and close Preferences.

In the Tools > Boards menu you should see the ESP32 Arduino menu. In the expanded menu, it should contain the ESP32 boards along with all the latest ESP32-S2 boards.

Now that your IDE is setup, you can continue on to loading the sketch.

Load the Blink Sketch

In the Tools > Boards menu you should see the ESP32 Arduino menu. In the expanded menu, look for the menu option for the ESP32S2 Dev Module, and click on it to choose it.

Open the Blink sketch by clicking through File > Examples > 01.Basics > Blink.

Once open, click Upload from the sketch window.

Once successfully uploaded, the little red LED will begin blinking once every second. At that point, you can now enter the bootloader.

This guide was first published on Jun 29, 2021. It was last updated on Mar 28, 2024.

This page (Install TinyUF2 on Espressif Kaluga) was last updated on Mar 08, 2024.

Text editor powered by tinymce.