Using the Moddable SDK with ESP32

Copyright 2016-2024 Moddable Tech, Inc.
Revised: September 13, 2024

This document provides a guide to building apps for the ESP32 line of SoCs from Espressif. The Moddable SDK supports ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, and ESP32-H2.

Overview
Platforms
Build Types
Setup instructions

• Installing
• Troubleshooting • Installing
• Troubleshooting • Installing
• Troubleshooting
Troubleshooting
Using USB on ESP32
- Multi-port devices
- Build configuration
- TinyUSB (esp32s2, esp32s3)
- Serial-JTAG (esp32s3, esp32c3, esp32c6, esp32h2)
Using ESP Registry components

Overview

Before you can build applications, you need to:

Install the Moddable SDK and build its tools
Install the required drivers and development tools for the ESP32 platform

The instructions below will have you verify your setup by running the helloworld example on your device using mcconfig, a command line tool that builds and runs Moddable applications.

See the Tools documentation for more information about mcconfig

When building with mcconfig, you specify your device target by providing the platform identifier of your development board to the -p argument. For example, use the following command to build for Moddable Two:

mcconfig -d -m -p esp32/moddable_two

A list of available ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6 and ESP32-H2 subplatforms and their platform identifiers is provided in the Platforms section below.

Platforms

ESP32

ESP32 has the following features:

240 MHz processor
Dual core
Wi-Fi
BLE
520 KB RAM
4 MB flash

The Moddable SDK supports many devices built on ESP32. The following table lists each device, its platform identifier, a list of key features specific to the device, and links to additional resources.

Name	Platform identifier	Key features	Links
Moddable Two	`esp32/moddable_two` `simulator/moddable_two`	2.4" IPS display 240 x 320 QVGA 16-bit color Capacitive touch 20 External pins	Moddable Two developer guide Moddable product page
Moddable Display 2	`esp32/moddable_display_2` `simulator/moddable_two`	2.4" IPS display 240 x 320 QVGA 16-bit color Capacitive touch 20 External pins	Moddable Display developer guide Moddable product page
Node MCU ESP32	`esp32/nodemcu`
M5Stack	`esp32/m5stack` `esp32/m5stack_core2`	1.8" LCD display 320 x 240 QVGA 16-bit color Audio playback Accelerometer NeoPixels	Product page
M5Stack Fire	`esp32/m5stack_fire`	1.8" LCD display 320 x 240 QVGA 16-bit color Audio playback Accelerometer NeoPixels	Product page
M5Stick C	`esp32/m5stick_c` `simulator/m5stick_c`	0.96" LCD display 80 x 160 16-bit color IMU Microphone	Product page
M5Stick C PLUS	`esp32/m5stick_cplus`	1.14" LCD display 135 x 240 16-bit color IMU Microphone	Product page
M5Atom	`esp32/m5atom_echo` `esp32/m5atom_lite` `esp32/m5atom_matrix`	5 x 5 RGB LED matrix panel MPU6886 Inertial Sensor 6 External Pins	Product page
M5AtomU	`esp32/m5atom_u`	Neopixel, 1 button Microphone 6 External Pins	Product page
M5 Paper	`esp32/m5paper` `simulator/m5paper`	960 x 540 ePaper touch screen Temperature sensor	Product page Moddable SDK docs
M5Core Ink	`esp32/m5core_ink`	200 x 200 ePaper display Buzzer Dial	Product page Moddable SDK docs
Heltec WiFi Kit 32	`esp32/heltec_wifi_kit_32`	128 x 64 OLED display	Product page
Wemos OLED Lolin32	`esp32/wemos_oled_lolin32`	128 x 64 OLED display No built-in LED's	Additional information
SparkFun Thing	`esp32/esp32_thing`		Product page
SparkFun Thing Plus	`esp32/esp32_thing_plus`		Product page
ESP32 WRover Kit	`esp32/wrover_kit`		Product page
Wireless Tag WT32-ETH01	`esp32/wt32_eth01`	Built-in Ethernet	Product page
Lilygo TTGO	`esp32/lilygo_ttgo`	135 x 240 IPS display Button	Product page
Moddable Zero	`esp32/moddable_zero`		Wiring guide

ESP32-S2

ESP32-S2 has the following features:

240 MHz processor
Wi-Fi
320 KB RAM
External SRAM support
4 MB flash on popular modules

The Moddable SDK supports two ESP32-S2 development kits from Espressif. The following table lists each device, its platform identifier, a list of key features specific to the device, and links to additional resources.

Name	Platform identifier	Key features	Links
Kaluga	`esp32/kaluga`	3.2" LCD display 320 x 240 QVGA 16-bit color 2 MB SRAM Speaker and Audio Playback Touch Pad Panel NeoPixel LED	Moddable blog post Product page
Saola (WROOM & WROVER versions)	`esp32/saola_wroom` `esp32/saola_wrover`	NeoPixel LED 2 MB SRAM (WROVER version only)	Moddable blog post Product page
Adafruit QT Py ESP32-S2	`esp32/qtpys2`	Neopixel, 1 button, STEMMA/QWIIC	Product page
ili9341	`esp32/qtpys2_ili9341`	ili9341 QVGA display 320 x 240 16-bit color	Wiring Guide
Lolin S2 Mini	`esp32/lolin_s2mini`	1 button	Product guide

ESP32-S3

ESP32-S3 is the successor to the original ESP32. It has the following features:

240 MHz processor (two cores)
Wi-Fi
BLE
512 KB RAM
External PSRAM support
8 MB flash on popular modules

The Moddable SDK supports devices built on ESP32-S3. The following table lists each device, its platform identifier, a list of key features specific to the device, and links to additional resources.

Name	Platform identifier	Key features	Links
Moddable Six	`esp32/moddable_six` `esp32/moddable_six_cdc` `simulator/moddable_six`	2.4" IPS display 240 x 320 QVGA 16-bit color 8-bit parallel display bus Capacitive touch Neopixel Qwiic connector Optional speaker 20 External pins	Moddable Six developer guide Moddable product page
Moddable Display 2	`esp32/moddable_display_6` `simulator/moddable_six`	2.4" IPS display 240 x 320 QVGA 16-bit color 8-bit parallel display bus Capacitive touch Neopixel Qwiic connector Optional speaker 20 External pins	Moddable Display developer guide Moddable product page
ESP32-S3-DevKitC-1-N8	`esp32/esp32s3`		Product page
Adafruit QT Py ESP32-S3	`esp32/qtpys3`	Neopixel, 1 button, STEMMA/QWIIC	Product page
Adafruit ESP32-S3 TFT Feather	`esp32/feather_s3_tft`	1.14" TFT display 240 x 135 16-bit color	Product page
AtomS3	`esp32/m5atom_s3`	0.85" IPS display 128 x 128 16-bit color 1 button IMU	Product page
AtomS3 Lite	`esp32/m5atom_s3_lite`	Neopixel, 1 button	Product page
M5Dial	`esp32/m5dial`	1.28" IPS 240×240 Round Display, Touch, 1 button,Rotary Encoder, RTC	Product page
M5Stamp S3	`esp32/m5stamp_s3`	Neopixel, 1 button	Product page
Lilygo T-QT ESP32-S3	`esp32/lilygo_t_qt`	0.85" LCD display 128 x 128 16 bit color 2 buttons Qwiic connector	Product page
Lilygo T-Display-S3	`esp32/lilygo_tdisplay_s3`	1.9" LCD display 170 x 320 16 bit color 8-bit parallel display Touch 2 buttons Qwiic connector	Product page
Seeed Studio XIAO ESP32S3	`esp32/xiao_esp32s3`	1 button	Product page
ili9341	`esp32/qtpys3_ili9341` `esp32/xiao_esp32s3_ili9341`	ili9341 QVGA display 320 x 240 16-bit color	Wiring Guide

ESP32-C3

ESP32-C3 has the following features:

160 MHz RISC-V MCU
Wi-Fi
BLE
400 KB RAM
4 MB flash on popular modules

The Moddable SDK supports three ESP32-C3 development kits:

Name	Platform identifier	Key features	Links
ESP32-C3-DevKitM-1	`esp32/esp32c3`		Product page
ESP32 C3 DevKit clone	`esp32/esp32c3_cdc`		Product page
ESP32-C3-DevKit-RUST-1	`esp32/c3_devkit_rust`		Product page
Seeed Studio XIAO ESP32C3	`esp32/xiao_esp32c3`	1 button	Product page
Adafruit QT Py ESP32-C3	`esp32/qtpyc3`	Neopixel, 1 button, STEMMA/QWIIC	Product page
AI Thinker ESP-C3-32S-Kit (1 MB and 2 MB versions)	`esp32/c3_32s_kit` `esp32/c3_32s_kit_2m`	RGB LED	Product specification
ili9341	`esp32/qtpyc3_ili9341` `esp32/xiao_esp32c3_ili9341`	ili9341 QVGA display 320 x 240 16-bit color	Wiring Guide
Lolin C3 Mini	`esp32/lolin_c3mini`	1 button	Product guide
Lolin C3 Pico	`esp32/lolin_c3pico`	Neopixel, 1 button	Product guide

ESP32-C6

ESP32-C6 has the following features:

160 MHz RISC-V MCU
Wi-Fi
BLE
512 KB RAM
4 MB flash on popular modules

The Moddable SDK supports three ESP32-C6 development kits:

Name	Platform identifier	Key features	Links
ESP32-C6-DevKitC-1	`esp32/esp32c6`	NeoPixel, Button	Product page
M5NanoC6	`esp32/m5nanoc6`	LED, NeoPixel, Button	Product page

ESP32-H2

ESP32-H2 has the following features:

96 MHz RISC-V MCU
BLE
320 KB RAM
4 MB flash on popular modules

The Moddable SDK supports three ESP32-H2 development kits:

Name	Platform identifier	Key features	Links
ESP32-H2-DevKitM-1	`esp32/esp32h2`	NeoPixel, Button	Product page

Specifying ESP32 Subclass in Manifest

The target ESP32 subclass for a build is specified using the ESP32_SUBCLASS property in the build section of the manifest. This is usually set by the manifest for the target build device. The following example shows how to set the subclass to ESP32-S2.

"build":{
	"ESP32_SUBCLASS": "esp32s2"
},

`ESP32_SUBCLASS`	Device
`esp32` or not set	ESP32
`esp32s2`	ESP32-S2
`esp32s3`	ESP32-S3
`esp32c3`	ESP32-C3
`esp32c6`	ESP32-C6
`esp32h2`	ESP32-H2

Build Types

The ESP32 supports three kinds of builds: debug, instrumented, and release. Each is appropriate for different stages in the product development process. You select which kind of build you want from the command line.

Debug

A debug build is used for debugging JavaScript. In a debug build, the ESP-IDF logging is disabled and the GDB stub is not present.

The -d option on the mcconfig command line selects a debug build.

Instrumented

A debug build is used for debugging native code. In an instrumented build, the ESP-IDF logging is enabled and the GDB stub is present. The JavaScript debugger is disabled. The instrumentation data usually available in xsbug is output to the serial console once a second.

The -i option on the mcconfig command line selects an instrumented build.

Release

A release build is for production. In a release build, the ESP-IDF logging is disabled, the GDB stub is not present, the JavaScript debugger is disabled, instrumentation statistics are not collected, and serial console output is suppressed.

Omitting the -d and -i options on the mcconfig command line selects a release. Note that -r specifies rotation rather than selecting a release build.

macOS

The Moddable SDK build for ESP32 currently uses ESP-IDF v5.3 (commit e0991fac) and the CMake option of Espressif's idf.py tool.

Installing

Install the Moddable SDK tools by following the instructions in the Getting Started document.
Create an esp32 directory in your home directory at ~/esp32 for required third party SDKs and tools.
If you are running macOS 10.15 (Catalina) or earlier, download and install the Silicon Labs CP210x USB to UART VCP driver.

If you run macOS Catalina, an extra step is required to enable the VCP driver. If you see a popup that says "System Extension Blocked" during installation, follow the instructions in the dialog to enable the extension in Security & Privacy System Preferences.

If you are using macOS 10.16 (Big Sur) or later, you do not need to install the VCP driver.
If this is your first install, clone the ESP-IDF GitHub repository into your ~/esp32 directory. Make sure to specify the --recursive option. Be sure to checkout the v5.3 tag:
```
cd ~/esp32
git clone -b v5.3 --recursive https://github.com/espressif/esp-idf.git esp-idf-v5.3
```
(Optional) Update homebrew and then install Python, cmake, ninja, the pip package management system, and pyserial. Also run a brew upgrade on those packages, in case you already had older versions installed:
```
brew update
brew install python3 cmake ninja dfu-util
brew upgrade python3 cmake ninja dfu-util
pip install pyserial
```
Connect the ESP32 device to your macOS host with a USB cable.
Open your shell startup/initialization file.

For macOS Mojave and earlier, the default shell is bash, so you should open ~/.profile.
```
open ~/.profile
```
Starting with macOS Catalina, the default shell is zsh, so you should open ~/.zshrc.
```
open ~/.zshrc
```
Add the following line to the file you just opened and save. This sets the IDF_PATH environment variable to point at your ESP-IDF directory.
```
export IDF_PATH=$HOME/esp32/esp-idf-v5.3
```
There is one optional environment variables for advanced users: UPLOAD_PORT.

The ESP-IDF build/config tool idf.py automatically detects the serial port in most cases. If it does not, set the path of the port to use in the UPLOAD_PORT environment variable.
```
export UPLOAD_PORT=/dev/cu.SLAB_USBtoUART
```
To identify the proper serial port, examine the list of serial devices in macOS before and after plugging in your ESP32 device and note the new serial port that shows up. To see a list of serial device files, use the following command in Terminal:
```
ls /dev/cu.*
```
The UPLOAD_PORT can also be specified on the mcconfig command line, which is useful when deploying to multiple ESP32 devices.
```
UPLOAD_PORT=/dev/cu.SLAB_USBtoUART mcconfig -d -m -p esp32
```
Adding the export statements to your ~/.profile or ~/.zshrc does not update the environment variables in active shell instances, so open a new shell instance (by opening a new tab/window) or manually run the export statement in your shell before proceeding.
Run the ESP-IDF install script. This will install the proper cross-compilation toolchain and utilities needed for the ESP-IDF build.
```
cd $IDF_PATH
./install.sh
```
If you are using a Mac with an M1 chip, you will have to take some additional steps before you can run the install script because the ESP-IDF does not yet have proper support for Darwin-arm64 hosts. This comment provides step by step instructions that you can follow to work around this issue.
Set up your build environment by sourcing the ESP-IDF export.sh script. This must be run every time you open a new shell instance, either manually or by a startup script.
```
source $IDF_PATH/export.sh
```
If you prefer to automate this process for new shell instances, follow the instructions from Steps 7-9 above and add the source command at the end of your shell startup/initialization script. Make sure it is after the export IDF_PATH command.
Verify the setup by building helloworld for your device target:
```
cd ${MODDABLE}/examples/helloworld
mcconfig -d -m -p esp32/<YOUR_SUBPLATFORM_HERE>
```
Note that the first time you build an application for the ESP32 target, the toolchain may prompt you to enter configuration options. If this happens, accept the defaults.

Troubleshooting

When you're trying to install applications, you may experience roadblocks in the form of errors or warnings; this section explains some common issues on macOS and how to resolve them.

For other issues that are common on macOS, Windows, and Linux, see the Troubleshooting section at the bottom of this document.

Device not connected/recognized

The following error messages mean that the device is not connected to your computer or the computer doesn't recognize the device.

error: cannot access /dev/cu.SLAB_USBtoUART
error: cannot access /dev/usbserial-0001

There are a few reasons this can happen:

Your device is not plugged into your computer. Make sure it's plugged in when you run the build commands.
You have a USB cable that is power only. Make sure you're using a data sync-capable USB cable.
A different application is connected to the serial port. For example, a serial monitor may have the port opened. Close the application or disconnect the device from the application.
The computer does not recognize your device. To fix this problem, follow the instructions below.

Unplug the device and enter the following command.

ls /dev/cu*

Then plug in the device and repeat the same command. If nothing new appears in the terminal output, the device isn't being recognized by your computer.

If you are running macOS 10.15 or earlier, make sure you have the correct VCP driver installed. If you are running macOS 10.16 or earlier, you do not need to install the VCP driver.

If it is recognized, you now have the device name and you need to edit the UPLOAD_PORT environment variable. Enter the following command, replacing /dev/cu.SLAB_USBtoUART with the name of the device on your system.

export UPLOAD_PORT=/dev/cu.SLAB_USBtoUART

SSL certificate errors

Espressif is encouraging moving to Python 3 as 2.7 is not recommended.

However, if you are using Python 2.7 and encounter SSL certificate errors while building the ESP-IDF, you may need to install Python 2.7 and the required packages manually. We've used brew and pip to install the additional components:

brew install python
brew install python@2
pip install future
pip install pyserial
pip install cryptography

Updating

This is a substantial update. We have found it best to start with a clean clone.

If you have the disk space, you may want to back up your old ESP-IDF.
```
cd ~/esp32/
mv esp-idf esp-idf.old
```

Remove the directory and clone the repository.

cd ~/esp32
rm -rf esp-idf
git clone -b v5.3 --recursive https://github.com/espressif/esp-idf.git

(Optional - you probably don't have to do this.) Update homebrew and then verify that you have all the necessary tools and that they are up to date:
```
brew update
brew install python cmake ninja
brew upgrade python cmake ninja
pip install pyserial
```
Verify the IDF_PATH environment variable is set correctly in your shell's user profile file (e.g. ~/.profile or ~/.zshrc, depending on your shell).
```
export IDF_PATH=$HOME/esp32/esp-idf
```
Run the ESP-IDF install script. This will install the proper cross-compilation toolchain and utilities needed for the ESP-IDF build.
```
cd $IDF_PATH
./install.sh
```
Set up your build environment by sourcing the ESP-IDF export.sh script. This must be run every time you open a new shell instance, either manually or by a startup script.
```
source $IDF_PATH/export.sh
```
If you prefer to automate this process for new shell instances, follow the instructions from Step 3 above and add the source command at the end of your shell startup/initialization script. Make sure it is after the export IDF_PATH command.

Windows

The Moddable SDK build for ESP32 currently uses ESP-IDF v5.3 (commit e0991fac) and the CMake option of Espressif's idf.py tool.

Installing

Install the Moddable SDK tools by following the instructions in the Getting Started document.
Download and install the Silicon Labs CP210x USB to UART VCP driver. The driver zip file contains x64 and x86 versions of the installer. Most modern PCs run 64-bit Windows and should use the x64 version of the VCP driver. If you run a 32-bit version of Windows, use the x86 version of the driver. (You can determine if your computer is running a 64-bit version of Windows by checking "About your PC" in System Settings.)
Download and run the Espressif ESP-IDF Windows Installer. This will install the ESP32 Xtensa gcc toolchain, Ninja Build, OpenOCD, and a KConfig Frontend. This tool will also set your PATH to include the newly downloaded tools, as necessary.

It is safe to accept all of the default options in the installer, or to change install locations as necessary.

If you do not already have CMake or Python, the installer will also prompt you to download and install those tools (you should do so if needed).

The installer will offer to clone the ESP-IDF git repository for you. If you choose this option, select the "v5.3(release version)" option and clone into a directory called esp32\esp-idf within your home folder.
If you did not clone the ESP-IDF using the ESP-IDF Windows Installer, create an esp32 directory in your home folder, either from File Explorer or a Command Prompt:
```
cd %USERPROFILE%
mkdir esp32
```
If you did not clone the ESP-IDF using the ESP-IDF Windows Installer, clone the ESP-IDF Github repository into your ~/esp32 directory. Make sure to specify the --recursive option. Then checkout the v5.3 tag:
```
cd %USERPROFILE%\esp32
git clone -b v5.3 --recursive https://github.com/espressif/esp-idf.git
```
If you already have a cloned copy of the ESP-IDF, the simplest way to do the update is to delete the existing esp-idf folder and clone it again. See Espressif's Get ESP-IDF
Connect the ESP32 device to your Windows host with a USB cable.
Open the "Environment Variables" dialog of the Control Panel app by following these instructions. From that dialog:
- Create a User Variable called IDF_PATH and set it to the directory where you cloned the ESP-IDF, e.g.:
  - Variable name: IDF_PATH
  - Variable value (Use the "Browse Directory..." button to make this selection): C:\Users\<user>\esp32\esp-idf
There is one optional environment variable for advanced users: UPLOAD_PORT.

The ESP-IDF build/config tool idf.py automatically detects the serial port in most cases. If it does not, set the path of the port to use in the UPLOAD_PORT environment variable following the same procedure as above.
- UPLOAD_PORT: the COM port for your device, e.g. COM3
To identify the correct serial port, launch the Windows Device Manager. Open the "Ports (COM & LPT)" section, verify the "Silicon Labs CP210x USB to UART Bridge" is displayed, and note the associated COM port (e.g. COM3).
Newly-set environment variables will not take effect in existing Command Prompt instances, so be sure to open a new Command Prompt instance after applying these changes.
Run the ESP-IDF install batch file. This will configure utilities used by the ESP-IDF build for your machine.
```
cd %IDF_PATH%
install.bat
```
The ESP-IDF Windows Installer provides a command prompt called "ESP-IDF 5.3 CMD" that automatically sets important environment variables and paths. We recommend building ESP32 projects with "ESP-IDF 5.3 CMD." In each new command prompt instance you will need to run the Visual Studio x86 initialization batch file manually. Adjust the path as necessary for your system.
```
"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars32.bat"
```
Note for experts: If you are comfortable editing Windows shortcuts, a convenient alternative to this manual process is to modify the "ESP-IDF 5.3 CMD" shortcut to initialize both the ESP-IDF environment and the Visual Studio x86 environment. To do this, right-click the "ESP-IDF 5.3 CMD" shortcut and select "Properties." In the "Target" field of the Properties window, you should see a command that looks like:
```
C:\WINDOWS\system32\cmd.exe /k "C:\Users\<username>\.espressif\idf_cmd_init.bat"
```
You can change the Target to include the path to vcvars32.bat as follows. Adjust the paths as necessary for your system.
```
%comspec% /k ""%ProgramFiles%\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars32.bat" && pushd %IDF_PATH% && "%IDF_TOOLS_PATH%\idf_cmd_init.bat" && popd"
```
It is also convenient to update the "Start in" field of the shortcut to %MODDABLE% to start your Command Prompt session in the Moddable SDK directory.

Note: These instructions assume you only have one copy of the ESP-IDF installed. idf_cmd_init.bat can also take an argument to specify a particular ESP-IDF installation, if necessary. This argument should be set up in the default "ESP-IDF 5.3 CMD" shortcut.
In the "ESP-IDF 5.3 CMD" command prompt, verify the setup by building helloworld for your device target:
```
cd %MODDABLE%\examples\helloworld
mcconfig -d -m -p esp32/<YOUR_SUBPLATFORM_HERE>
```

Troubleshooting

When you're trying to install applications, you may experience roadblocks in the form of errors or warnings; this section explains some common issues on Windows and how to resolve them.

For other issues that are common on macOS, Windows, and Linux, see the Troubleshooting section at the bottom of this document.

ESP-IDF Build is Extremely Slow

The built-in anti-virus software included with Windows 10 and 11 (Microsoft Defender, formerly Windows Defender) can significantly slow down ESP-IDF builds. Espressif's ESP-IDF Windows Installer includes an option to automatically configure Microsoft Defender with all the exclusions needed to bypass realtime scanning during builds. If your build is slow, try re-running the ESP-IDF Windows Installer to verify that that option is selected. You may also need to manually exclude your Moddable build folder or other custom build output directories by following these instructions.

Python Versions

Espressif recommends using Python 3.9 or later when building with ESP-IDF v5.3. Python 3.9 will be installed by the ESP-IDF Windows Installer.

If you had a previous version of Python (such as Python 2.7) installed on your system, you may need to remove it from the System PATH so that Python 3.9 is chosen by default. Look for entries like C:\Python27\ or C:\Python27\Scripts\ in your PATH and remove them if you encounter Python errors during the build process.

Python dependencies

If you get an error about Python dependencies not being installed, it means that the ESP-IDF installer failed to update Python. This usually happens due to permissions issues on your machine. To correct it, run python -m pip install -r %IDF_PATH%\requirements.txt from the "x86 Native Tools Command Prompt for VS 2022."

Device not connected/recognized

If a device is not connected, or the UPLOAD_PORT isn't set to the proper COM port, a number of error messages may appear after building. An error message similar to the following means that the device is not connected to your computer or the computer doesn't recognize the device. Note the could not open port 'COM3' message.

raise SerialException("could not open port {!r}: {!r}".format(self.portstr, ctypes.WinError()))
serial.serialutil.SerialException: could not open port 'COM3': FileNotFoundError(2, 'The system cannot find the file specified.', None, 2)

There are a few reasons this can happen:

Your device is not plugged into your computer. Make sure it's plugged in when you run the build commands.
You have a USB cable that is power only. Make sure you're using a data sync-capable USB cable.
The computer does not recognize your device. To fix this problem, follow the instructions below.

Check the list of USB devices in Device Manager. If your device shows up as an unknown device, make sure you have the correct VCP driver installed.

If your device shows up on a COM port other than COM3, you need to edit the UPLOAD_PORT environment variable. Enter the following command, replacing COM3 with the appropriate device COM port for your system.

set UPLOAD_PORT=COM5

Other Errors

Many ESP32 errors on Windows can be corrected by updating the Espressif tools. This is especially true of errors reported during initialization of the "ESP-IDF CMD" Command Prompt and Python version errors during builds.

To update the Espressif tools, download and run the most recent ESP-IDF Windows Installer. Do not use the tool to clone a new ESP-IDF tree if you already have one installed. Instead, choose the option to use an existing ESP-IDF tree and point it to %IDF_PATH%.

Updating

To ensure that your build environment is up to date, perform the following steps:

Download and run the Espressif ESP-IDF Windows Installer. This will update the ESP32 Xtensa gcc toolchain, Ninja Build, OpenOCD, and a KConfig Frontend. This tool will also set your PATH to include the newly downloaded tools, as necessary.

It is safe to accept all of the default options in the installer, or to change install locations as necessary.

If you do not already have CMake or Python, the installer will also prompt you to download and install those tools (you should do so if needed).

If you choose to clone the ESP-IDF, select the v5.3 (release version) of the esp-idf.

If you use the installer to clone the ESP-IDF, please follow the instructions in the next step to update to the v5.3 tag.
If you did not clone the ESP-IDF using the ESP-IDF Windows Installer, clone the ESP-IDF Github repository into your ~/esp32 directory. Make sure to specify the --recursive option and branch v5.3 tag:
```
cd %USERPROFILE%\esp32
git clone -b v5.3 --recursive https://github.com/espressif/esp-idf.git
```
Open the "Environment Variables" dialog of the Control Panel app by following these instructions. From that dialog, verify the IDF_PATH Windows environment variable is set correctly.
- IDF_PATH should have the value C:\Users\<user>\esp32\esp-idf
Run the ESP-IDF install batch file. This will configure utilities used by the ESP-IDF build for your machine.
```
cd %IDF_PATH%
install.bat
```

The ESP-IDF Windows Installer provides a command prompt called "ESP-IDF 5.1 CMD" that automatically sets important environment variables and paths. We recommend building ESP32 projects using "ESP-IDF 5.1 CMD." In each new command prompt instance you will need to run the Visual Studio x86 initialization batch file manually. Adjust the path as necessary for your system.
```
"C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars32.bat"
```
Note for experts: If you are comfortable editing Windows shortcuts, a convenient alternative to this manual process is to modify the "ESP-IDF 5.1 CMD" shortcut to initialize both the ESP-IDF environment and the Visual Studio x86 environment. To do this, right-click the "ESP-IDF 5.1 CMD" shortcut and select "Properties." In the "Target" field of the Properties window, you should see a command that looks like:
```
C:\WINDOWS\system32\cmd.exe /k "C:\Users\<username>\.espressif\idf_cmd_init.bat"
```
You can change the Target to include the path to vcvars32.bat as follows. Adjust the paths as necessary for your system.
```
%comspec% /k ""%ProgramFiles%\Microsoft Visual Studio\2022\Community\VC\Auxiliary\Build\vcvars32.bat" && pushd %IDF_PATH% && "%IDF_TOOLS_PATH%\idf_cmd_init.bat" && popd"
```
It is also convenient to update the "Start in" field of the shortcut to %MODDABLE% to start your Command Prompt session in the Moddable SDK directory.

Note: These instructions assume you only have one copy of the ESP-IDF installed. idf_cmd_init.bat can also take an argument to specify a particular ESP-IDF installation, if necessary. This argument should be set up in the default "ESP-IDF 5.1 CMD" shortcut.
In the "ESP-IDF 5.1 CMD" command prompt, verify the setup by building helloworld for your device target:
```
cd %MODDABLE%\examples\helloworld
mcconfig -d -m -p esp32/<YOUR_SUBPLATFORM_HERE>
```

Linux

The Moddable SDK build for ESP32 currently uses ESP-IDF v5.3 (commit e0991fac) and the CMake option of Espressif's idf.py tool.

Installing

Install the Moddable SDK tools by following the instructions in the Getting Started document.
Install the packages required to compile with the ESP-IDF.

For Ubuntu 20.04 or newer (and other Linux distributions that default to Python 3):
```
sudo apt-get update
sudo apt-get install git wget flex bison gperf python-is-python3 python3-pip python3-serial python-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util
```
For Ubuntu prior to 20.04 (and other Linux distributions that default to Python 2):
```
sudo apt-get update
sudo apt-get install git wget flex bison gperf python python-pip python-setuptools python-serial cmake ninja-build ccache libffi-dev libssl-dev dfu-util
```
Note: The ESP-IDF build recommends Python 3 and will soon stop supporting Python 2.7. If your distribution uses Python 2.7 by default, you can explicitly install Python 3 and set it as the default Python interpreter with these commands. Note that this is a system-wide change that will impact other applications that use Python.
```
sudo apt-get install python3 python3-pip python3-setuptools
sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 10
```
Create an esp32 directory in your home directory at ~/esp32 for required third party SDKs and tools.
If this is your first install, clone the ESP-IDF GitHub repository into your ~/esp32 directory. Make sure to specify the --recursive option. Then checkout the v5.3 tag:
```
cd ~/esp32
git clone -b v5.3 --recursive https://github.com/espressif/esp-idf.git esp-idf-v5.3
```
Connect the ESP32 device to your Linux host with a USB cable.
Open your shell startup/initialization file (e.g. ~/.bash_profile or ~/.zshrc, depending on your shell), add the following line to the file, and save. This sets the IDF_PATH environment variable to point at your ESP-IDF directory.
```
export IDF_PATH=$HOME/esp32/esp-idf
```
There is an optional environment variable for advanced users: UPLOAD_PORT.

The ESP-IDF build/config tool idf.py automatically detects the serial port in most cases. If it does not, set the path of the port to use in the UPLOAD_PORT environment variable.
```
export UPLOAD_PORT=/dev/ttyUSB0
```
To identify the proper serial port, examine the list of serial devices on your Linux host before and after plugging in your ESP32 device and note the new serial port that shows up. To see a list of serial device files, use the following command:
```
ls /dev/*
```
The UPLOAD_PORT can also be specified on the mcconfig command line, which is useful when deploying to multiple ESP32 devices.
```
UPLOAD_PORT=/dev/ttyUSB0 mcconfig -d -m -p esp32
```
Adding the export statements to your shell startup file does not update the environment variables in active shell instances, so open a new shell instance (by opening a new tab/window) or manually run the export statements in your shell before proceeding.
Run the ESP-IDF install script. This will install the proper cross-compilation toolchain and utilities needed for the ESP-IDF build.
```
cd $IDF_PATH
sh ./install.sh
```
Set up your build environment by sourcing the ESP-IDF export.sh script. This must be run every time you open a new shell instance, either manually or by a startup script.
```
source $IDF_PATH/export.sh
```
If you prefer to automate this process for new shell instances, follow the instructions from Steps 6-7 above and add the source command at the end of your shell startup/initialization script. Make sure it is after the export IDF_PATH command.
Verify the setup by building helloworld for your device target:
```
cd $MODDABLE/examples/helloworld
mcconfig -d -m -p esp32/<YOUR_SUBPLATFORM_HERE>
```
Note that the first time you build an application for the ESP32 target, the toolchain may prompt you to enter configuration options. If this happens, accept the defaults.

Troubleshooting

When you're trying to install applications, you may experience roadblocks in the form of errors or warnings; this section explains some common issues on Linux and how to resolve them.

For other issues that are common on macOS, Windows, and Linux, see the Troubleshooting section at the bottom of this document.

Permission denied

The ESP32 communicates with the Linux host via the ttyUSB0 device. On Ubuntu Linux the ttyUSB0 device is owned by the dialout group. If you get a permission denied error when flashing the ESP32, add your user to the dialout group:

sudo adduser <username> dialout 
sudo reboot

Device not connected/recognized

The following error messages mean that the device is not connected to your computer or the computer doesn't recognize the device.

error: cannot access /dev/ttyUSB0

There are a few reasons this can happen:

Your device is not plugged into your computer. Make sure it's plugged in when you run the build commands.
You have a USB cable that is power only. Make sure you're using a data sync-capable USB cable.
The computer does not recognize your device. To fix this problem, follow the instructions below.

Unplug the device and enter the following command.

ls /dev/cu*

Then plug in the device and repeat the same command. If nothing new appears in the terminal output, the device isn't being recognized by your computer.

If it is recognized, you now have the device name and you need to edit the UPLOAD_PORT environment variable. Enter the following command, replacing /dev/ttyUSB1 with the name of the device on your system.

export UPLOAD_PORT=/dev/ttyUSB1

Updating

This is a substantial update. We have found it best to start with a clean clone.

If you have the disk space, you may want to back up your old ESP-IDF.
```
cd ~/esp32/
mv esp-idf esp-idf.old
```

Remove the directory and clone the repository.

cd ~/esp32
rm -rf esp-idf
git clone -b v5.3 --recursive https://github.com/espressif/esp-idf.git

(optional) Update apt, then install any missing packages (and upgrade existing packages) required to compile with the ESP-IDF. The packages to install vary based on your distribution's default Python version.

For Ubuntu 20.04 or newer (and other Linux distributions that default to Python 3):
```
sudo apt-get update
sudo apt-get install git wget flex bison gperf python-is-python3 python3-pip python3-serial python-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util
```
For Ubuntu prior to 20.04 (and other Linux distributions that default to Python 2):
```
sudo apt-get update
sudo apt-get install git wget flex bison gperf python python-pip python-setuptools python-serial cmake ninja-build ccache libffi-dev libssl-dev dfu-util
```
Note: The ESP-IDF build recommends Python 3. If your distribution uses Python 2.7 by default, you can explicitly install Python 3 and set it as the default Python interpreter with these commands. Note that this is a system-wide change that will impact other applications that use Python.
```
sudo apt-get install python3 python3-pip python3-setuptools
sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 10
```
Verify the IDF_PATH environment variable is set correctly in your shell's user profile file (e.g. ~/.bash_profile or ~/.zshrc, depending on your shell).
```
export IDF_PATH=$HOME/esp32/esp-idf
```
Run the ESP-IDF install script. This will install the proper cross-compilation toolchain and utilities needed for the ESP-IDF build.
```
cd $IDF_PATH
./install.sh
```
Set up your build environment by sourcing the ESP-IDF export.sh script. This must be run every time you open a new shell instance, either manually or by a startup script.
```
source $IDF_PATH/export.sh
```
If you prefer to automate this process for new shell instances, follow the instructions from Step 3 above and add the source command at the end of your shell startup/initialization script. Make sure it is after the export IDF_PATH command.
If you have existing ESP32 build output in $MODDABLE/build/bin/esp32 or $MODDABLE/build/tmp/esp32, delete those directories:
```
cd $MODDABLE/build
rm -rf bin/esp32
rm -rf tmp/esp32
```
Verify the setup by building helloworld for your device target:
```
cd $MODDABLE/examples/helloworld
mcconfig -d -m -p esp32/<YOUR_SUBPLATFORM_HERE>
```
Note that the first time you build an application for the ESP32 target, the toolchain may prompt you to enter configuration options. If this happens, accept the defaults.

Troubleshooting

When you're trying to install applications, you may experience roadblocks in the form of errors or warnings; this section explains some common issues and how to resolve them.

Incompatible baud rate

The following warning message is normal and is no cause for concern.

warning: serialport_set_baudrate: baud rate 921600 may not work

However, sometimes the upload starts but does not complete. You can tell an upload is complete after the progress bar traced to the console goes to 100%. For example:

........................................................... [ 16% ]
........................................................... [ 33% ]
........................................................... [ 49% ]
........................................................... [ 66% ]
........................................................... [ 82% ]
........................................................... [ 99% ]
..                                                         [ 100% ]

There are a few reasons the upload may fail partway through:

You have a faulty USB cable.
You have a USB cable that does not support higher baud rates.
You're using a board that requires a lower baud rate than the default baud rate that the Moddable SDK uses.

To solve the last two problems above, you can change to a slower baud rate as follows:

Open $MODDABLE/tools/mcconfig/make.esp32.mk.
Find this line, which sets the upload speed to 921600:
```
UPLOAD_SPEED ?= 921600
```
Set the speed to a smaller number. For example:
```
UPLOAD_SPEED ?= 115200
```

Note: Instead of modifying the make.esp32.mk file, you can make a temporary change by setting the environment variable UPLOAD_SPEED.

ESP32 is not in bootloader mode

If an ESP32 is not in bootloader mode, you cannot flash the device. Most development boards built with the ESP32 include circuitry that automatically puts them into bootloader mode when you try to reflash the board. Some do not, and sometimes the auto programming will fail. This is most common on Windows machines.

When your ESP32 is not in bootloader mode, status messages stop being traced briefly when you attempt to flash the device, and after several seconds this error message is traced to the console:

A fatal error occurred: Failed to connect to ESP32: Timed out waiting for packet header

To manually put your ESP32 into bootloader mode, follow these steps:

Unplug the device.
Hold down the BOOT button.
Plug the device into your computer.
Enter the mcconfig command.
Wait a few seconds and release the BOOT button.

Using USB on ESP32

Originally, programming and debugging with the ESP32 was done over a serial or UART connection. Some devices contain an integrated serial-to-USB chip (UART), and some use an external programmer.

In newer devices, Espressif has added USB support. Starting with the ESP32-S2, TinyUSB support was added. TinyUSB support continued with ESP32-S3.

Starting with the ESP32-S3 and continuing with the ESP32-C3, ESP32-C6 and ESP32-H2, support for USB is integrated into the device with a USB Serial/JTAG driver. Using the Serial/JTAG driver is preferred as it uses the built-in driver which results in a smaller binary.

Multi-port devices

There are some development boards that include both the UART and USB connections.

On macOS, when plugged into the UART port, the device is enumerated as a /dev/cu.usbserial-##### device. When plugged into the USB port, the device is enumerated as a /dev/cu.usbmodem-##### device.

The Espressif IDF will install the app to whatever is connected. However, the xsbug connection will only work in the method that the application was built for. For example, building an app for the esp32/esp32s3 target will use the UART port to connect to the debugger. Building the app for esp32/esp32s3_cdc or esp32/esp32s3_usb will connect over the USB port.

Note: If you have built with USB configured and are connected to the UART port, xsbug will not be able to connect.

Build configuration

In a device's manifest.json file, the USE_USB build option specifies which USB implementation to use. The SDKCONFIGPATH is also specified to pick up the ESP-IDF config files specific to this device:

	"build": {
		"ESP32_SUBCLASS": "esp32s2",
		"USE_USB": "1",
		"SDKCONFIGPATH": "./sdkconfig"
		...

`USE_USB: 1` - TinyUSB

TinyUSB works with the ESP32-S2 and ESP32-S3 devices.

With TinyUSB, we need to set the UPLOAD_PORT. For example:

export UPLOAD_PORT=/dev/cu.usbmodem01

See the section for your build platform macOS, Windows, or Linux which describes how to find your device's UPLOAD_PORT.

Build your application:

mcconfig -d -m -p esp32/esp32s3_usb

Note: if your device is not in programming mode, there will be a notice in the build console:

# looking for UPLOAD_PORT: /dev/cu.usbmodem01
** Put device in programming mode **

When the console says Done, press the Reset button on the device.

Executing "ninja flash"...
Done

After you press Reset on the device, the device will restart and connect to xsbug.

These are some of the devices use this technique:

Platform	Device
`esp32/esp32s3_usb`	Espressif ESP32-S3-DevKitC
`esp32/m5atom_s3`	M5 Atom S3
`esp32/m5atom_s3_lite`	M5 Atom S3 Lite
`esp32/qtpys2`	Adafruit QT Py S2
`esp32/qtpys3`	Adafruit QT Py S3
`esp32/s2mini`	Lolin S2 mini
`esp32/s3_tft_feather`	Adafruit ESP32-S3 TFT Feather

Note: A quirk with this variant is that the device enumerates to a different /dev/cu.usbmodem-##### whether it is in programming mode or run mode.

For example, building for esp32/esp32s3_usb I see /dev/cu.usbmodem123401 in programming mode. In run-mode, I see /dev/cu.usbmodem1234561. So I set DEBUGGER_PORT=/dev/cu.usbmodem1234561 and UPLOAD_PORT=/dev/cu.usbmodem123401 to ensure the proper connections are made.

`USE_USB: 2` - SERIAL-JTAG

The built-in SERIAL-JTAG driver can be used with the ESP32-S3 and ESP32-C3 devices.

There is usually no need to set the UPLOAD_PORT, or press buttons on your device. However, if you have multiple devices connected simultaneously, you will have to use the UPLOAD_PORT to specify which one to use.

Build your application:

mcconfig -d -m -p esp32/esp32s3_cdc

These are some of the devices use this technique:

Platform	Device
`esp32/moddable_six_cdc`	Moddable Six
`esp32/c3_devkit_rust`	Espressif C3 DevKit Rust
`esp32/esp32c3_cdc`	Espressif C3 DevKitM
`esp32/esp32s3_cdc`	Espressif ESP32-S3-DevKitC
`esp32/qtpyc3`	Adafruit QT Py C3
`esp32/xiao_esp32c3`	Seeed Xiao ESP32C3

Using ESP Registry components

The ESP Component Registry contains many components and libraries for the Espressif devices.

You can write modules that expose the functionality of these components to your JavaScript modules.

Add a dependency property in the platforms:esp32 section of the manifest:

	"platforms": {
		"esp32": {
			"dependency": [
				{ "name": "onewire_bus", "version": "^1.0.2" }
			]
		}
	}

The library and include files from the dependencies will be loaded from the ESP Registry automatically and made available to your project. You can then write your module with a native part to interface with the component.

The onewire module demonstrates the use of dependency.

Files

esp32.md

Latest commit

History

esp32.md

File metadata and controls

Using the Moddable SDK with ESP32

Table of Contents

Overview

Platforms

ESP32

ESP32-S2

ESP32-S3

ESP32-C3

ESP32-C6

ESP32-H2

Specifying ESP32 Subclass in Manifest

Build Types

Debug

Instrumented

Release

macOS

Installing

Troubleshooting

Device not connected/recognized

SSL certificate errors

Updating

Windows

Installing

Troubleshooting

ESP-IDF Build is Extremely Slow

Python Versions

Python dependencies

Device not connected/recognized

Other Errors

Updating

Linux

Installing

Troubleshooting

Permission denied

Device not connected/recognized

Updating

Troubleshooting

Incompatible baud rate

ESP32 is not in bootloader mode

Using USB on ESP32

Multi-port devices

Build configuration

USE_USB: 1 - TinyUSB

USE_USB: 2 - SERIAL-JTAG

Using ESP Registry components

`USE_USB: 1` - TinyUSB

`USE_USB: 2` - SERIAL-JTAG