hackshopStart a build

Free tool · ESP32

ESP32 not showing up? Find your serial port

Start with the cable: a charge-only USB cable powers the board but carries no data, so no port appears. With a data cable, native USB boards (ESP32-S3, C5, C6) show up as /dev/cu.usbmodem* on a Mac and /dev/ttyACM* on Linux. Boards with a CH340 chip show up as /dev/cu.usbserial-* or /dev/ttyUSB*. On Windows it's a COM port.

Pick your computer and board for the exact command and a checklist when nothing appears.

Your computer

Not sure

1. Run this

List serial ports

ls /dev/cu.*

2. Look for

  • /dev/cu.usbmodem*
  • /dev/cu.usbserial-*
  • /dev/cu.wchusbserial*

Look for a name with usbmodem (native USB) or usbserial (a USB bridge chip).

Not showing up? Check these in order

  1. Use a USB cable that carries data

    A charge-only cable powers the board but carries no data, so no port appears. Swap in a cable you know moves files, or test yours on another device. Muse's SDK lists a data cable as a requirement.

    Source: Use a USB cable that carries data

  2. Find the port by unplugging

    Run ls /dev/cu.* with the board unplugged, plug it in, and run it again. The new name is your board.

    ls /dev/cu.*
    Source: Find the port by unplugging

  3. Put the board in download mode

    If the port shows up but flashing can't connect: hold BOOT, tap RESET, let go of BOOT, and try again.

    Source: Put the board in download mode

  4. Close anything that has the port open

    A serial monitor, the Arduino IDE, another terminal or a modem manager can hold the port. Close them and try again, and check you passed the right port.

    Source: Close anything that has the port open

  5. Rule out the baud rate

    If it connects but fails partway, try a slow speed such as -b 9600 to rule out the baud rate.

    Source: Rule out the baud rate

  6. Bare module? Check the power

    ESP chips draw up to 70 mA, with 200-300 mA peaks. The 3.3 V pin on an FTDI adapter or an Arduino can't supply that. This mostly matters when you power a bare module from an adapter.

    Source: Bare module? Check the power

How this works

An ESP32 talks to your computer one of two ways. Most newer boards use the chip's own USB port (native USB), which shows up as a modem-style port. Others put a USB bridge chip such as a CH340 between the USB socket and the ESP32, which shows up as a serial adapter. The port name tells you which one you have.

The finder looks up your board's connection type from the Muse Gadgets SDK docs, then gives you the command for your computer, the name to look for, and the board's own flash command. The checklist runs from the most common fix to the rarest.

Port names by chip

ESP32 serial port names by USB chip and computer
ConnectionmacOSLinuxWindows
Native USB (ESP32-S3, C5 and C6 boards, StickS3, Waveshare, AIPI Lite, Voice PE)/dev/cu.usbmodem*/dev/ttyACM*COM port
CH340 bridge (ideaspark, SenseCAP Indicator, reTerminal E1001 and E1002)/dev/cu.usbserial-* or /dev/cu.wchusbserial*/dev/ttyUSB*COM port
CH342 bridge (SenseCAP Watcher)Two /dev/cu.usbmodem* ports. Use the one ending in 3Two ports. Use the second oneTwo COM ports
CH9102 bridge (M5Stack StickC Plus2)/dev/cu.usbserial-*/dev/ttyACM*COM port

On Linux, lsusb shows native USB as 303a:1001 and a CH340 as 1a86:7523.

Questions people ask

Why is my ESP32 not showing up?

Start with the cable. A charge-only USB cable powers the board but carries no data, so no port appears. Try a cable you know moves files, or test yours on another device. Muse's ESP32 SDK lists a data cable as a requirement.

What is the ESP32 port name on a Mac?

Run ls /dev/cu.* to list ports. Native USB boards (ESP32-S3, C5, C6) show up as /dev/cu.usbmodem followed by a number. Boards with a CH340 chip show up as /dev/cu.usbserial-* or /dev/cu.wchusbserial*.

How do I fix Permission denied on /dev/ttyUSB0 or /dev/ttyACM0?

Add yourself to the dialout group with sudo usermod -a -G dialout $USER (uucp on Arch), then log out and back in so the change takes effect.

What does holding BOOT and pressing RESET do?

It puts the chip in download mode so the flasher can connect. Hold BOOT, tap RESET, let go of BOOT, then flash again. Reflashing Muse keeps pairing and Wi-Fi settings; only erase-flash wipes them.

Which port do I use on the SenseCAP Watcher?

Its bottom USB-C port has a CH342 bridge that shows up as two ports. The ESP32-S3 console is the second one, ending in 3; the first is the Himax camera chip. Flash it with tools/muse/board.sh flash watcher and wait about three minutes.

Do I need a driver?

Espressif says the CP210x and FTDI drivers should come with your operating system, and the Watcher's CH342 works with macOS's built-in driver. On Windows, if the board shows up under Other devices with a warning sign, install the driver from the bridge chip's maker.

Does my board run Muse?Check your board and get its build command.Safe flashing checklistBack up first and know how to recover.Brick-risk field guideWhen a failed flash is fixable and when it isn't.

Board connected? Build the gadget.

Start a build to get the steps for your board, or hand it to your agent with the build plan.

Start a buildSee Muse boards

Sources