Quick Start
The quickest first success on this board is to light its RGB LED. Pick your environment below: each tab installs the tools, uploads a program that blinks the LED, and shows what you should see.
- Arduino
- MicroPython
- ESP-IDF
1. Install the platform
Install the Arduino IDE from arduino.cc, then open it.
2. Install the board definitions
The board runs on Espressif's Arduino core for the ESP32. In the Arduino IDE, open the Preferences window and enter this URL into the Additional Board Manager URLs field:
https://espressif.github.io/arduino-esp32/package_esp32_index.json
Then open Boards Manager from the Tools > Board menu and install the esp32 platform.
3. Select the board
The ESP32 core has no entry of its own for this board yet, so use the generic one for its chip:
- Connect the board to your computer with the USB-C cable.
- Choose Tools > Board > esp32 > ESP32S3 Dev Module.
- Set Tools > Flash Size to 8MB (64Mb) and Tools > PSRAM to OPI PSRAM. These match the module's 8 MB of flash and 8 MB of octal PSRAM.
- Pick the board's serial port under Tools > Port.
A CH340K chip (a USB-to-serial converter) sits between the USB-C connector and the ESP32-S3, so your computer needs the CH340 driver to see the port. Keep Tools > USB CDC On Boot at its default, Disabled: Serial then uses UART0, and that is where the CH340K is wired.
4. Upload your first program
The board's RGB LED is a WS2812B, an addressable LED that takes colour data on one pin rather than a plain on/off level. It sits on GPIO6, and the core's rgbLedWrite() function drives it. This sketch blinks it white once a second, which is the quickest way to see that the upload worked.
// Blink the onboard WS2812B RGB LED (next to the IO6 label): 0.5 s on, 0.5 s off.
// The generic ESP32S3 Dev Module defines RGB_BUILTIN as GPIO48,
// so the pin is set here to this board's LED pin.
const uint8_t RGB_LED_PIN = 6;
void setup()
{
}
void loop()
{
rgbLedWrite(RGB_LED_PIN, 64, 64, 64); // LED on, white at a quarter of full brightness
delay(500);
rgbLedWrite(RGB_LED_PIN, 0, 0, 0); // LED off
delay(500);
}
rgbLedWrite(pin, red, green, blue) comes with the ESP32 board package. Equal red, green and blue values give white, and all three at 0 turn the LED off.
5. What to expect
Click Upload in the Arduino IDE. The board has automatic reset, so the upload starts without you pressing a button. The sketch prints nothing to Serial Monitor; its result is on the board. The RGB LED next to the IO6 label, just above the USER and RESET buttons, turns white for half a second and off for half a second.
6. Troubleshooting
If the board is not detected or the upload fails, continue with Troubleshooting.
1. Install the platform
MicroPython goes onto the board with the esptool.py program, which you can find in Espressif's esptool documentation. On Windows, the installed program may be called esptool instead of esptool.py.
esptool needs Python 3.10 or newer. Its installation guide installs the latest stable release with pip:
pip install esptool
If that gives an error on your Python installation, try python -m pip install esptool or pip3 install esptool.
2. Install the firmware
The board's module has 8 MB of octal PSRAM, so it needs the ESP32_GENERIC_S3 firmware with Octal-SPIRAM support (the SPIRAM_OCT variant). Download its latest .bin file from the ESP32_GENERIC_S3 download page.
Connect the board with the USB-C cable. If you are putting MicroPython on the board for the first time, erase the entire flash first:
esptool.py erase_flash
Then deploy the firmware to the board, starting at address 0:
esptool.py --baud 460800 write_flash 0 ESP32_BOARD_NAME-DATE-VERSION.bin
Replace ESP32_BOARD_NAME-DATE-VERSION.bin with the .bin file you downloaded. If flashing starts and then fails partway through, remove the --baud 460800 option to flash at the slower default speed.
3. Select the board and port
esptool.py tries to find the board's serial port by itself. If that fails, or more than one Espressif board is connected, pass the port with --port:
esptool.py --port PORTNAME erase_flash
esptool.py --port PORTNAME --baud 460800 write_flash 0 ESP32_BOARD_NAME-DATE-VERSION.bin
On Linux the port name is usually similar to /dev/ttyUSB or /dev/ttyACM0, on a Mac /dev/cu.usbmodem01, and on Windows COM4.
The MicroPython prompt (the REPL) is on UART0, which may be connected to a USB-serial converter, or on the chip's built-in USB. On this board, UART0 goes to the CH340K USB-to-serial chip on the USB-C connector. Open the board's serial port in a terminal program at 115200 baud.
4. Upload your first program
The RGB LED on GPIO6 is a WS2812B, so MicroPython drives it with the neopixel module rather than a plain Pin. Press Ctrl-E at the prompt to enter paste mode, paste the program, then press Ctrl-D to run it.
# Blink the onboard RGB LED on GPIO6: 0.5 s on, 0.5 s off.
from machine import Pin
from neopixel import NeoPixel
import time
led = NeoPixel(Pin(6, Pin.OUT), 1) # one WS2812B LED on GPIO6
while True:
led[0] = (64, 64, 64) # equal red, green and blue: white
led.write()
time.sleep(0.5)
led[0] = (0, 0, 0) # off
led.write()
time.sleep(0.5)
NeoPixel(pin, n) creates a driver for n LEDs on that pin. Setting led[0] stores a colour as red, green and blue values, and write() sends it to the LED.
5. What to expect
The RGB LED blinks white once a second. The program prints nothing. The RGB LED next to the IO6 label, just above the USER and RESET buttons, turns white for half a second and off for half a second.
6. Troubleshooting
If the REPL does not respond or firmware flashing fails, continue with Troubleshooting.
1. Install the platform
Install ESP-IDF v6.1 by following Espressif's Get Started guide for the ESP32-S3. It has a page each for Windows, Linux and macOS.
2. Set the target
Copy ESP-IDF's blink example into your working folder, go into it and set the chip:
cd ~/esp
cp -r $IDF_PATH/examples/get-started/blink .
cd ~/esp/blink
idf.py set-target esp32s3
3. Configure the project
Open the configuration menu:
idf.py menuconfig
Under Example Configuration, set:
- Blink LED type to LED strip, because the board's LED is an addressable WS2812B;
- Blink GPIO number to
6.
Leave Blink period in ms at its default, 1000. Save and leave the menu.
4. Build and flash your first program
Connect the board with the USB-C cable, then build, flash and open the monitor in one command. Replace PORT with the board's serial port.
idf.py -p PORT flash monitor
5. What to expect
The monitor resets the board and prints its start-up log, then the program's
output. The first lines of that output are below, and a new line follows every
second while the program runs. Press Ctrl+] to leave the monitor. The RGB LED next to the IO6 label lights white for one second, then stays off for one second.I (315) example: Example configured to blink addressable LED!
I (325) example: Turning the LED OFF!
I (1325) example: Turning the LED ON!
I (2325) example: Turning the LED OFF!
I (3325) example: Turning the LED ON!
6. Troubleshooting
If the project does not build or flash, continue with Troubleshooting.