Adafruit ESP32-S3 User manual

Adafruit ESP32-S3 TFT Feather
Created by Kattni Rembor
https://learn.adafruit.com/adafruit-esp32-s3-tft-feather
Last updated on 2023-03-16 04:05:25 PM EDT
©Adafruit Industries Page 1 of 263

9
13
23
29
37
39
42
43
48
51
Table of Contents
Overview
Pinouts
• Power
• TFT Display
• ESP32-S3 WiFi Module
• LC709203 Battery Monitor
• BME280 Temperature, Humidity and Pressure Sensor
• Logic Pins
• NeoPixel and Red LED
• STEMMA QT
• Buttons
• Debug
Low Power Usage
Power Management
• Battery + USB Power
• Power Supplies
• Measuring Battery
• ENable pin
• Alternative Power Options
CircuitPython
• CircuitPython Quickstart
Installing the Mu Editor
• Download and Install Mu
• Starting Up Mu
• Using Mu
The CIRCUITPY Drive
• Boards Without CIRCUITPY
Creating and Editing Code
• Creating Code
• Editing Code
• Back to Editing Code...
• Naming Your Program File
Exploring Your First CircuitPython Program
• Imports & Libraries
• Setting Up The LED
• Loop-de-loops
• What Happens When My Code Finishes Running?
• What if I Don't Have the Loop?
Connecting to the Serial Console
• Are you using Mu?
• Serial Console Issues or Delays on Linux
• Setting Permissions on Linux
©Adafruit Industries Page 2 of 263

54
57
62
73
80
81
85
87
91
• Using Something Else?
Interacting with the Serial Console
The REPL
• Entering the REPL
• Interacting with the REPL
• Returning to the Serial Console
CircuitPython Libraries
• The Adafruit Learn Guide Project Bundle
• The Adafruit CircuitPython Library Bundle
• Downloading the Adafruit CircuitPython Library Bundle
• The CircuitPython Community Library Bundle
• Downloading the CircuitPython Community Library Bundle
• Understanding the Bundle
• Example Files
• Copying Libraries to Your Board
• Understanding Which Libraries to Install
• Example: ImportError Due to Missing Library
• Library Install on Non-Express Boards
• Updating CircuitPython Libraries and Examples
• CircUp CLI Tool
CircuitPython Documentation
• CircuitPython Core Documentation
• CircuitPython Library Documentation
Recommended Editors
• Recommended editors
• Recommended only with particular settings or add-ons
• Editors that are NOT recommended
Advanced Serial Console on Windows
• Windows 7 and 8.1
• What's the COM?
• Install Putty
Advanced Serial Console on Mac
• What's the Port?
• Connect with screen
Advanced Serial Console on Linux
• What's the Port?
• Connect with screen
• Permissions on Linux
Frequently Asked Questions
• Using Older Versions
• Python Arithmetic
• Wireless Connectivity
• Asyncio and Interrupts
• Status RGB LED
• Memory Issues
• Unsupported Hardware
©Adafruit Industries Page 3 of 263

97
115
124
126
128
131
Troubleshooting
• Always Run the Latest Version of CircuitPython and Libraries
• I have to continue using CircuitPython 5.x or earlier. Where can I find compatible libraries?
• Bootloader (boardnameBOOT) Drive Not Present
• Windows Explorer Locks Up When Accessing boardnameBOOT Drive
• Copying UF2 to boardnameBOOT Drive Hangs at 0% Copied
• CIRCUITPY Drive Does Not Appear or Disappears Quickly
• Device Errors or Problems on Windows
• Serial Console in Mu Not Displaying Anything
• code.py Restarts Constantly
• CircuitPython RGB Status Light
• CircuitPython 7.0.0 and Later
• CircuitPython 6.3.0 and earlier
• Serial console showing ValueError: Incompatible .mpy file
• CIRCUITPY Drive Issues
• Safe Mode
• To erase CIRCUITPY: storage.erase_filesystem()
• Erase CIRCUITPY Without Access to the REPL
• For the specific boards listed below:
• For SAMD21 non-Express boards that have a UF2 bootloader:
• For SAMD21 non-Express boards that do not have a UF2 bootloader:
• Running Out of File Space on SAMD21 Non-Express Boards
• Delete something!
• Use tabs
• On MacOS?
• Prevent & Remove MacOS Hidden Files
• Copy Files on MacOS Without Creating Hidden Files
• Other MacOS Space-Saving Tips
• Device Locked Up or Boot Looping
Welcome to the Community!
• Adafruit Discord
• CircuitPython.org
• Adafruit GitHub
• Adafruit Forums
• Read the Docs
CircuitPython Essentials
Blink
• LED Location
• Blinking an LED
Digital Input
• LED and Button
• Controlling the LED with a Button
Analog In
• Analog to Digital Converter (ADC)
• Potentiometers
• Hardware
• Wire Up the Potentiometer
• Reading Analog Pin Values
• Reading Analog Voltage Values
©Adafruit Industries Page 4 of 263

137
143
147
157
165
170
175
181
NeoPixel LED
• NeoPixel Location
• NeoPixel Color and Brightness
• RGB LED Colors
• NeoPixel Rainbow
CircuitPython Internet Test
• Secrets File
Adafruit IO: Send and Receive Data
• NeoPixel Location
• Adafruit IO Feeds and Dashboard
• Adafruit IO Example Secrets
• Adafruit IO Example Code
• NeoPixel Color Change
• Code Walkthrough
I2C
• I2C and CircuitPython
• Necessary Hardware
• Wiring the MCP9808
• Find Your Sensor
• I2C Sensor Data
• Where's my I2C?
Storage
• Wiring for MCP9808
• The boot.py File
• The code.py File
• Logging the Temperature
• Recovering a Read-Only Filesystem
Capacitive Touch
• One Capacitive Touch Pin
• Pin Location
• Reading Touch on the Pin
• Multiple Capacitive Touch Pins
• Pin Location
• Reading Touch on the Pins
• The Available Touch-Capable Pins
I2S
• I2S and CircuitPython
• Necessary Hardware
• Wiring the MAX98357A
• I2S Tone Playback
• I2S WAV File Playback
• CircuitPython I2S-Compatible Pin Combinations
Multitasking with asyncio
• asyncio Demonstration
• Wiring
• asyncio Example Code
• Code Walkthrough
• My program ended? What happened?
©Adafruit Industries Page 5 of 263

189
192
195
204
208
211
222
230
236
249
Arduino IDE Setup
Using with Arduino IDE
• Blink
• Select ESP32-S2/S3 Board in Arduino IDE
• Launch ESP32-S2/S3 ROM Bootloader
• Load Blink Sketch
Arduino Blink
• Pre-Flight Check: Get Arduino IDE & Hardware Set Up
• Start up Arduino IDE and Select Board/Port
• New Blink Sketch
• Verify (Compile) Sketch
• Upload Sketch
• Native USB and manual bootloading
• Enter Manual Bootload Mode
• Finally, a Blink!
I2C Scan Test
• Common I2C Connectivity Issues
• Perform an I2C scan!
• Wiring the MCP9808
LC709203 Simple Data
• Arduino Library Installation
• LC709203 Simple Data Example
WiFi Test
• WiFi Connection Test
• Secure Connection Example
• JSON Parsing Demo
Usage with Adafruit IO
• Install Libraries
• Adafruit IO Setup
• Code Usage
WipperSnapper Setup
• What is WipperSnapper
• Sign up for Adafruit.io
• Add a New Device to Adafruit IO
• Feedback
• Troubleshooting
• "Uninstalling" WipperSnapper
WipperSnapper Usage
• Blink a LED
• Read a Push-Button
• Read an I2C Sensor
• Going Further
Factory Reset
• Factory Reset Firmware UF2
• Factory Reset and Bootloader Repair
• Download .bin and Enter Bootloader
©Adafruit Industries Page 6 of 263

260
261
262
• Step 1. Download the factory-reset-and-bootloader.bin file
• Step 2. Enter ROM bootloader mode
• The WebSerial ESPTool Method
• Connect
• Erase the Contents
• Program the ESP32-S2/S3
• The esptool Method (for advanced users)
• Install ESPTool.py
• Test the Installation
• Connect
• Installing the Bootloader
• Reset the board
• Older Versions of Chrome
• TheFlash an Arduino Sketch Method
• Arduino IDE Setup
• Load the Blink Sketch
Install UF2 Bootloader
Downloads
• Files
• Schematic and Fab Print
FAQ
©Adafruit Industries Page 7 of 263

©Adafruit Industries Page 8 of 263

Overview
We've got a new machine here at Adafruit, it can uncover your deepest desires. Don't
believe me? I'll turn it on right now to prove it to you!
What, you want your very own soft serve ice cream machine? OK, well, that's not
something we can provide. But we can provide your second-deepest desire: an
ESP32-S3 Feather board with a built in IPS TFT color display. It's got all the delicious
creamy goodness features of a Feather main board, the comforting warmth of an
ESP32-S3 WiFi+BLE microcontroller, and the crispness of a 240x135 pixel color TFT
display.
All that and it will even plug in nicely into a breadboard, terminal block wing(), or Feat
her Doubler() or even just stack on top of another wing.
©Adafruit Industries Page 9 of 263

This Feather comes with native USB and 4 MB Flash + 2 MB of PSRAM, so it is perfect
for use with CircuitPython or Arduino withlow-cost WiFi. Native USB means it can act
like a keyboard or a disk drive. WiFi means it's awesome for IoT projects. And Feather
means it works with the large community of Feather Wings for expandability.
The ESP32-S3 is a highly-integrated, low-power, 2.4 GHz Wi-Fi/BLE System-on-Chip
(SoC) solution thathasbuilt-in native USBas well as some other interesting new
technologies like Time of Flight distance measurements and AI acceleration. With its
state-of-the-art power and RF performance, this SoC is an ideal choice for a wide
variety of application scenarios relating to theInternet of Things (IoT)(),wearable
electronics(), and smart homes.
The BLE implementation in CircuitPython for the ESP32-S3 is still under
development and has limitations. Currently, your program can act as a central,
and connect to a peripheral. You can advertise, but you cannot create services.
You cannot advertise anonymously. Pairing and bonding are not supported.
©Adafruit Industries Page 10 of 263

The Feather ESP32-S3 has a dual-core 240 MHz chip, so it is comparable to ESP32's
dual-core. However, there is no BluetoothClassicsupport, only Bluetooth LE. This
chip is a great step up from the earlier ESP32-S2! This ESP32-S3 mini-module we are
using on the Feather comes with 4 MB flash and 2 MB PSRAM, as well as 512KB of
SRAM, so it's perfect for use with CircuitPython support or any time massive buffers
are needed: for fast memory access use SRAM, for slower-but-roomier access use
PSRAM. It's also great for use in ESP-IDF or with Arduino support.
The color TFT is connected to the SPI pinsand uses additional pins for control that
are not exposed to the breakout pads. It's the same display as you see here, with
©Adafruit Industries Page 11 of 263

240x135 pixels and is IPS() so you get bright color at any angle. The backlight is also
connected to a separate pin so you can PWM the backlight up and down as desired.
For low power usages, the Feather has a secondlow-dropout 3.3Vregulator. The
regulator is controlled with a GPIO pin on the enable line and can shut off power to
the Stemma QT port and TFT. There is also a separate power pin for the NeoPixel that
can be used to disable it for even lower quiescent power. With everything off and in
deep sleep mode, the TFT feather uses about 100uA of current.
Features:
ESP32-S3 Dual Core 240MHz Tensilica processor- the next generation of
ESP32-Sx, with native USB so it can act like a keyboard/mouse, MIDI device,
disk drive, etc!
Mini module has FCC/CE certification and comes with 4 MByte of Flash and 2
MByte of PSRAM - you can have huge data buffers.
Color 1.14" IPS TFT with 240x135 pixels()- bright and colorful display with
ST7789 chipset that can be viewed at any angle angle.
Power options- USB type CorLipoly battery
Built-in battery charging when powered over USB-C.
LiPoly battery monitor - LC709203 chip actively monitors your battery for
voltage and state of charge / percentage reporting over I2C.
Reset and DFU(BOOT0) buttons to get into the ROM bootloader (which is a USB
serial port so you don't need a separate cable!)
Serial debug output pin(optional, for checking the hardware serial debug
console)
•
•
•
•
•
•
•
•
©Adafruit Industries Page 12 of 263

STEMMA QTconnector for I2C devices, with switchable power, so you can go
into low power mode.
On/Charge/UserLEDs + statusNeoPixelwith pin-controlled power for low power
usage.
Low Power friendly! In deep sleep mode, we can get down to 80~100uA of
current draw from the Lipoly connection. Quiescent current is from the power
regulator, ESP32-S2 chip, and Lipoly monitor. Turn off the NeoPixel and external
I2C/TFT power for the lowest quiescent current draw.
Works with Arduino or CircuitPython
Pinouts
•
•
•
•
©Adafruit Industries Page 13 of 263

PrettyPins PDF on GitHub().
Power
©Adafruit Industries Page 14 of 263

There are two ways you can power the Feather ESP32-S3, as well as other related
pins.
USB-C port - This is used for both powering and programming the board. You
can power it with any USB C cable. When USB is plugged in it will charge the
LiPoly battery.
LiPoly connector/charger - You can plug in any 250mAh or larger 3.7/4.2V LiPoly
battery into this JST 2-PH port to both power your Feather and charge the
battery. The battery will charge from the USB power when USB is plugged in. If
the battery is plugged in and USB is plugged in, the Feather will power itself
from USB and it will charge the battery up.
CHG LED - When the battery is charging, the yellow CHG LED will be lit. When
charging is complete, the LED will turn off. If there's no battery plugged in, the
CHD LED may blink rapidly - this is expected!
GND - This is the common ground for all power and logic.
BAT - This is the positive voltage to/from the 2-pin JST jack for the optional
LiPoly battery.
USB - This is the positive voltage to/from the USB C jack, if USB is connected.
EN - This is the 3.3V regulator's enable pin. It's pulled up, so connect to ground
to disable the 3.3V regulator.
3.3V - These pins are the output from the 3.3V regulator, they can supply
500mA peak.
TFT Display
On the front of the board is a color 1.14" IPS TFT with 240x135 pixels(). It's a bright
and colorful display with ST7789 chipset that can be viewed at any angle.
•
•
•
•
•
•
•
•
©Adafruit Industries Page 15 of 263

There is a power pin that must be pulled high for the display to work. This is done
automatically by CircuitPython and Arduino. The pin is available in CircuitPython and
in Arduino as TFT_I2C_POWER .
ESP32-S3 WiFi Module
This is the ESP32-S3 module.
The ESP32-S3 is a highly-integrated, low-power, 2.4 GHz Wi-Fi/BLE System-on-Chip
(SoC) solution thathasbuilt-in native USBas well as some other interesting new
technologies like Time of Flight distance measurements and AI acceleration. With its
state-of-the-art power and RF performance, this SoC is an ideal choice for a wide
variety of application scenarios relating to theInternet of Things (IoT)(),wearable
electronics(), and smart homes.
The Feather ESP32-S3 has a dual-core 240 MHz chip, so it is comparable to ESP32's
dual-core. However, there is no BluetoothClassicsupport, only Bluetooth LE. This
chip is a great step up from the earlier ESP32-S2! This ESP32-S3 mini-module we are
using on the Feather comes with 4MB flash and 2 MB PSRAM, as well as 512KB of
SRAM, so it's perfect for use with CircuitPython support or any time massive buffers
are needed: for fast memory access use SRAM, for slower-but-roomier access use
PSRAM. It's also great for use in ESP-IDF or with Arduino support.
The 4 MB of flash is inside the module and is used for both program firmware and
filesystem storage. For example, in CircuitPython, we have 3 MB set aside for program
If you run into I2C or TFT power issues on Arduino, ensure you are using the
latest Espressif board support package. If you are still having issues, you may
need to manually pull the pin HIGH in your code.
©Adafruit Industries Page 16 of 263

firmware (this includes two OTA option spots as well) and a 1MB section for
CircuitPython scripts and files.
LC709203 Battery Monitor
The Adafruit LC709203F LiPoly / LiIon Fuel Gauge and Battery Monitorreports the
voltage and charge percent over I2C. Connect it to your Lipoly or LiIon battery() and
it will let you know the voltage of the cell, and it does the annoying math of decoding
the non-linear voltage to get you a valid percentage as well!
The battery monitor is available over I2C on address0x0B. Our Arduino() or CircuitPy
thon/Python() library code allows you to to set the pack size (mAh of the battery, this
helps tune the calculation) and read the voltage and percentage whenever you like.
There is no pin on the Feather ESP32-S3 that returns battery voltage, but this I2C
monitor makes it super simple to get that data!
There is a power pin that must be pulled high for the sensor to work. This is done
automatically by CircuitPython and Arduino. The pin is available in CircuitPython and
in Arduino as TFT_I2C_POWER .
This battery monitor does not currently work with CircuitPython! The issue is
being tracked here: https://github.com/adafruit/circuitpython/issues/6311
If you run into I2C or TFT power issues on Arduino, ensure you are using the
latest Espressif board support package. If you are still having issues, you may
need to manually pull the pin HIGH in your code.
©Adafruit Industries Page 17 of 263

BME280 Temperature, Humidity and Pressure Sensor
The ESP32-S3 TFT Feather comes with an unpopulated space for a BME280
Temperature, Humidity and Barometric Pressure Sensor.
The sensor connects over I2C (at address 0x77), and provides immediate ambient
weather sensing. It is rated for measuring humidity with ±3% accuracy, barometric
pressure with ±1 hPa absolute accuracy, and temperature with ±1.0°C accuracy.
Because pressure changes with altitude, and the pressure measurements are so
good, you can also use it as an altimeter with ±1 meter or better accuracy!
There is a power pin that must be pulled high for the sensor to work. This is done
automatically by CircuitPython and Arduino. The pin is available in CircuitPython and
in Arduino as TFT_I2C_POWER .
There is currently no BME280 sensor shipped on the ESP32-S3 TFT Feather -
only a space for it!
If you run into I2C or TFT power issues on Arduino, ensure you are using the
latest Espressif board support package. If you are still having issues, you may
need to manually pull the pin HIGH in your code.
©Adafruit Industries Page 18 of 263

Logic Pins
These are the logic pins that can be used to connect FeatherWings, sensors, servos,
LEDs and more!
No pins are shared, and no pins are 'special' bootstrapping pins, so you can use any
of them for input, or output, will pullups or pulldowns, without worry.
ESP32 chips allow for 'multiplexing' of almost all signals so it isn't like some pins can
do PWM and others can. You can connect any of the available PWM channels, I2S
channels, UART, I2C or SPI ports to any pin. There are some exceptions....
There are six analog pins.
A0 thru A5 can also be analog inputs. A0 thru A4 are on ADC2, and A5 is on
ADC1.
•
©Adafruit Industries Page 19 of 263

The SPI pins are on the ESP32-S3 high-speed peripheral. You can set any pins to be
the low-speed peripheral but you won't get the speedy interface!
SCK - This is the SPI clock pin.
MOSI - This is the SPI Microcontroller Out / Sensor In pin.
MISO - This is the SPI Microcontroller In / Sensor Out pin.
The UART interface.
RX - This is the UART receive pin. Connect to TX (transmit) pin on your sensor or
breakout.
TX - This is the UART transmit pin. Connect to RX (receive) pin on your sensor or
breakout.
The I2C interface. This is shared by the STEMMA QT connector.
SCL - This is the I2C clock pin. There is a 5k pullup on this pin.
SDA - This is the I2C data pin. There is a 5k pullup on this pin.
In CircuitPython, you can use the STEMMA connector with board.SCL and boa
rd.SDA , or board.STEMMA_I2C() .
There is an I2C power pin that needs to be pulled high for the STEMMA QT
connector, the LC709203, and the BME280 sensor (if present) to work properly.
CircuitPython and Arduino do this automatically. It is available in CircuitPython
and Arduino as TFT_I2C_POWER .
The digital pins.
D5-D6, D9-D13 - These are digital pins. D5, D6, D9 and D10 are on ADC1. D11-
D13 are on ADC2.
Check the ESP32-S3 datasheet or the PrettyPins diagram above for the ADC channel
names for each pin if you need em!
•
•
•
•
•
•
•
•
•
•
If you run into I2C or TFT power issues on Arduino, ensure you are using the
latest Espressif board support package. If you are still having issues, you may
need to manually pull the pin HIGH in your code.
©Adafruit Industries Page 20 of 263