Serial ports and drivers
COM4 or /dev/cu.usbserial-0001 is not a property of your board. It is your operating system naming a driver, which is why the number changes, why two ports appear, and why one board works on a friend's laptop and not on yours.
Where the name comes from
Your board has either a separate USB-to-serial chip on it, or a USB interface built into the ESP32 itself. Either way the operating system matches a USB vendor ID against a driver, and the driver creates the port. Nothing about the name is decided by the board.
Which one is on your board
Look next to the USB socket.
| What you see | What it is | Driver needed |
|---|---|---|
| A small 4×4 mm chip marked CP2102 | Silicon Labs bridge | Windows: yes. Mac and Linux: no |
| A chip marked CH340 or CH9102 | WCH bridge | Windows: yes. Older macOS: yes |
| No extra chip, two USB sockets, or a socket marked USB | Native USB in the ESP32 | None, ever |
The habit worth building
Never memorise a port name. Open the port list with the board unplugged, plug it in, and take the entry that appeared. It costs three seconds and it is right on every machine, every time — including the machine you have never seen, belonging to the person you are helping.
The code
The reliable way to identify a board when several are plugged in is to make it say who it is. Upload this once to each board with a different name.
void setup() {
Serial.begin(115200);
delay(1000); // native USB needs a moment to enrol
}
void loop() {
Serial.println("greenhouse sensor, board #2");
delay(1000);
}On a native-USB board you can also set the USB product name, and it then appears under that name in the port list instead of a generic one.
MicroPython gives you the chip's unique ID for free, which is a better label than a port name because it belongs to the board rather than to the computer.
import machine, ubinascii
uid = ubinascii.hexlify(machine.unique_id()).decode()
print("board", uid)machine.unique_id() is the MAC address of the Wi-Fi radio. It never changes, so it makes a good device name in MQTT topics too.
When it does not work
On macOS every serial device shows up twice, as /dev/tty.* and /dev/cu.*. Use the cu one. On Windows a Bluetooth adapter often adds phantom COM ports that never respond.
It belongs to the driver, not the board, so a different USB socket gives a different number. On Linux, a udev rule matching the chip's serial number gives you a stable name like /dev/esp-greenhouse.
Mismatched baud, or the wrong port of two. Also check that your sketch actually calls Serial.begin — a board that is running fine and never opened the port looks identical to a dead one.
That is native USB. The chip is the USB device, so its firmware crashing removes the device. Hold BOOT and tap EN to get the ROM's port back.
The port works. What to send down it, and how to read a stream of numbers as a shape rather than as a wall of text.
Printing, plotting and debugging →Edit this page — content/esp32/serial-ports-and-drivers.mdx
Discuss this article
Ask about this page. The answer stays here, on the page it belongs to, for whoever hits the same wall next.