Skip to content

Instantly share code, notes, and snippets.

Last active August 31, 2022 20:11
Show Gist options
  • Save askpatrickw/0a276c7e2d4f54e442b2cb6eaa0d32ea to your computer and use it in GitHub Desktop.
Save askpatrickw/0a276c7e2d4f54e442b2cb6eaa0d32ea to your computer and use it in GitHub Desktop.

Official Docs

You can get really good official docs here now

Below are the old notes (19 Oct 2020)

ESP32-S2 CircuitPython Getting Started

This is all pre-release stuff so while it worked for me at the time I wrote it, it might be changed.

Download a build from Adafruit.

Get the pre-release ESPTOOL.PY

  • Do the first three(3) streps in the Getting Started Guide
  • Pip install the pre-release esptool: pip install -e ~/esp/esp-idf/components/esptool_py/esptool
  • Check the esptool version. You should see:
➜ version v3.0-dev

Flash the Device

Espressif WROOM and WROVER

NOTE: I have a wrover, so the commands below are for that you use WROOM if you have that boad. NOTE: This is using the Saola's USB port (the one on the board) not the ESP32-S2's native USB.

On Mac: look for the port in ls /dev.tty* 99.9% its the USB one.
on Windows it's a com# --chip esp32s2 --port /dev/tty.usbserial-1420 -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode dio --flash_freq 40m --flash_size 4MB 0x0000 adafruit-circuitpython-espressif_saola_1_wrover-en_US-5.4.0-beta.1.bin

The output I saw was: v3.0-dev
Serial port /dev/tty.usbserial-1420
Chip is ESP32-S2
Features: WiFi
Crystal is 40MHz
MAC: 7c:df:a1:00:7d:a8
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 460800
Configuring flash size...
Compressed 395888 bytes to 222622...
Wrote 395888 bytes (222622 compressed) at 0x00000000 in 5.3 seconds (effective 601.1 kbit/s)...
Hash of data verified.

You know you have the wrong if it doesn't like your --chip esp32s2 cli option.

UnexpectedMaker FeatherS2

NOTE: Now we will be using the ESP32-S2 Native USB --chip esp32s2 -p /dev/cu.usbmodem01 --no-stub -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode qio --flash_freq 40m --flash_size 16MB 0x0000 adafruit-circuitpython-unexpectedmaker_feathers2-en_US-20200815-41be0fd.bin

The output I saw was: v3.0-dev
Serial port /dev/cu.usbmodem01
Chip is ESP32-S2
Features: WiFi
Crystal is 40MHz
MAC: 7c:df:a1:00:8c:1c
Changing baud rate to 460800
Enabling default SPI flash mode...
Configuring flash size...
Erasing flash...
Took 1.58s to erase flash block
Wrote 481280 bytes at 0x00000000 in 13.1 seconds (295.0 kbit/s)...
Hash of data verified.

Hard resetting via RTS pin...

Tap the reset button and you should have a CircuitPy drive show up.

USB Native Connectivity with the Espressif WROOM and WROVER

The ESP32-S2 has native USB support which enables it to show up as a USB drive on your PC. This is a must-have for CircuitPython. THe USB port on the WROVER is not the native one. To access the native port you to have to connect a USB cable to the pins on the WROVER.

Adafruit USB-A Breakout Cable

Watch @tannewt wire it up with the Adafruit USB-A Breakout Cable

D- White 19
D+ Green 20
5VDC Red 5V
Ground Black GND

USB-C Breakout Board

I used an Adafruit USB C Breakout Board - Downstream Connection 4094 and put my WROVER on a breadboard.

Header Pin WROVER Pin
Ground GND
CC1 --
D- 19
D+ 20
SBU1 --
CC2 --

Known Issues

I've seen intermittent issues where the Native USB won't show up in MacOS. So far, it appears as though if I reboot it then works. No pattern yet has been figured out.


Other USB Pinouts

I did not use these, let me know if they need to be corrected

USB 3.0

USB 3.0 Pinout

5VDC 1 5V
D- 2 19
D+ 3 20
Ground 4 GND

USB 3.0 Pinout


USB-C Pinout

D- A7\B7 19
D+ A6\B6 20
5VDC A9\B4 5V
Ground A1\B12 OR B1\A12 GND

USB C Pinout

Building CircuitPython for ESP32-S2 Boards

  • Do the first four(4) streps in the (Getting Started Guide)[].
    • If you've already done 1-3, just do 4.
  • Follow the (Building CircuitPython setup steps)[]
    • You do NOT need to install the GCC for Arm (gcc-arm-embedded on MacOS). The IDF handles that (This is Xtensa not ARM).
    • Follow the steps right through Build CircuitPython.
  • After you build mpy-cross, you are ready to build the ESP32-S2 port of CircuitPython for your board.
  • Have a look in circruitpython/ports/esp32s2/boards and take note the board names.
  • From circruitpython/ports/esp32s2/ run make BOARD=YOUR BOARD for example: make BOARD=unexpectedmaker_feathers2
    • If you get errors, first try running make clean BOARD=YOUR BOARD.
    • If you still get errors double check all your setup steps (maybe you didn't install something) and if still stuck head over to (AdaFruit Discord)[] and the CircuitPython channel.
  • If your build completes without errors, you use the same flash commnds outlined above. Your file will be in a build-YOURBOARD folder and the file name is firmware.bin. example: build-unexpectedmaker_feathers2/firmware.bin
Copy link

fede2cr commented Jun 27, 2020

Some of us had problems with rw storage after loading cpy on the saolas. This has fixed in all cases so far:

import storage

Also, the way the Makefile is currently writen, it will only work on a Mac which sucks for the rest of us. @tannewt suggested detecting the port and adding "PORT="

make BOARD=espressif_saola_1_wrover PORT=/dev/on-my-os flash

(both are not bugs since uf2 is coming)

Copy link

UnexpectedMaker commented Aug 15, 2020

Hi folks! If you are trying to flash using the S2 CDC (internal S2 USB) and getting errors or timeouts, make sure you have --no-stubin your esptool args!

Example: --chip esp32s2 -p /dev/cu.usbmodem01 --no-stub -b 460800 --before=default_reset --after=hard_reset write_flash --flash_mode qio --flash_freq 40m --flash_size 16MB 0x0000 build-unexpectedmaker_feathers2/firmware.bin

Without the --no-stub, esptool expects a different response and will timeout waiting for it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment