Introduction to the ESP32-S31 with Vision: Tooling: Getting started with ESP-Vision

Build vision applications fast

#

ESP-Vision is an open-source rapid-development environment for camera and edge-AI applications on Espressif hardware. It combines an ESP32 build of MicroPython with high-level camera, image, display, and inference modules.

In this assignment, you will flash ESP-Vision and connect the ESP32-S31-Korvo-1 to the ESP-Vision Web IDE. The first Python application comes after the LED Blink assignment.

How ESP-Vision works

#

ESP-Vision code runs on the SoC, not on your computer. It uses MicroPython, a compact implementation of Python designed for microcontrollers, rather than desktop CPython. Common Python syntax is available, but the standard library is intentionally smaller and selected at firmware build time. Desktop packages, native wheels, pip, and operating-system services are not available on the device.

The ESP32-S31 build provides these principal modules:

ImageIO is registered as part of the image public API. Access it as image.ImageIO; do not use import imageio, because the firmware does not provide a separate imageio module.

ESP-Vision also inherits a subset of MicroPython modules. The ESP32-S31 documentation indexes the following module groups:

To see the definitive module list for the firmware currently running on your board, enter this command in the REPL:

help("modules")

You can inspect a module’s available classes and functions in the same way:

import machine
help(machine)

The typical loop is:

graph TD
    Script[main.py] --> Sensor[sensor.snapshot]
    Sensor --> Image[Image in memory]
    Image --> Model[ESP-DL inference]
    Model --> Draw[Draw results]
    Draw --> LCD[image.flush]

Why start with ESP-Vision?

#

ESP-Vision and MicroPython shorten the development loop compared with a native ESP-IDF application:

The REPL is particularly useful during bring-up because it lets you check an import, inspect a module, capture one frame, or read a value without creating and rebuilding a complete application.

ESP-Vision is also an effective platform for evaluating compatible models. You can replace a model file, adjust score and NMS thresholds, and observe the results with the same camera and target hardware that the final application will use. This makes it easier to compare model behavior before integrating it into a larger native ESP-IDF project.

ESP-Vision does not replace ESP-IDF. Use ESP-IDF when the application needs lower-level peripheral control, custom native components, tighter memory and task management, or production-specific system integration. Assignments 6 and 7 introduce that workflow.

Scripts and model files are separate. Models used in this workshop are stored in the root directory of the internal flash filesystem. A FAT32 microSD card mounted at /sdcard is only needed for models that are too large for the available flash filesystem space.

Step 1: Flash ESP-Vision

#

1. Connect a data-capable USB Type-A to Type-A cable between your computer and the board’s USB Type-A USB CDC/JTAG/Debug port.
2. Open vision.espressif.com in a supported desktop browser.
3. Select Flash It Now.

4. Choose ESP32-S31-Korvo-1 and the current stable ESP-Vision firmware.
5. Under Flash Mode, select Full Install (blank board / recovery).

6. Select Connect Serial.
7. Choose the USB CDC/JTAG/Debug device associated with the ESP32-S31-Korvo-1, and then select Connect.

8. Start flashing and wait until the operation completes. Do not disconnect or power off the board while firmware is being written.

If the browser cannot start the download, put the board into download mode:

1. Hold Boot.
2. Press and release Reset.
3. Release Boot.
4. Retry the web flasher.

After ESP-Vision starts, the host computer detects the board as a removable disk. This disk exposes the files stored in the board’s internal flash filesystem. You can copy scripts, models, and other application files directly to its root directory.

Step 2: Connect to the board

#

Close serial monitors and other applications first; only one application can own the USB CDC/JTAG/Debug device at a time.

1. Open the Web IDE from vision.espressif.com.
2. Select Connect.
3. Choose the ESP32-S31-Korvo-1 USB CDC/JTAG/Debug device.

4. Stop any script that starts automatically.
5. Open the device REPL (Read-Evaluate-Print Loop). The REPL is MicroPython’s interactive console: it reads a command, evaluates it on the ESP32-S31, prints the result, and waits for the next command. It is useful for checking the connection, trying short API calls, and viewing script output or errors.

The connection is ready when the Web IDE reports the device as connected and the REPL displays the MicroPython prompt (>>>).

Step 3: Explore the development workflow

#

ESP-Vision applications normally follow this cycle:

1. Edit a script in the Web IDE.
2. Save it locally or to the device filesystem.
3. Run it and observe the preview and device output.
4. Stop it before replacing the file or opening another transport.
5. Review exceptions from the bottom upward; the final line gives the exception type and message.

Use main.py only when you want a script to run automatically at boot. During development, use a separate filename so a faulty infinite loop does not restart after every reset.

The Web IDE also provides access to bundled examples, the API library reference, and files on the mounted ESP-Vision flash disk.

Common problems

#

What you learned

#

In this section, you:

• Used ESP-Vision on the ESP32-S31-Korvo-1
• Learned the difference between device-side MicroPython and desktop Python
• Flashed the ESP-Vision firmware through the browser
• Connected to the board with the Web IDE
• Explored the edit, run, stop, preview, example, and device-file workflow

Next step

#

Tooling: Set up the ESP-Vision MCP server

Return to the workshop main page