Step 04 of 13

Plugging in the board and finding the port

Two things go wrong here and only here: the wrong USB socket, and permissions on /dev/ttyACM0. Both take one minute to settle before you build anything.

Use the native USB port

Plug the cable into the port wired to the chip's built-in USB-Serial-JTAG controller, usually labelled USB. Boards that also carry a separate CH343/CP210x bridge label that one UART. The native port is the one that gives you the console and the JTAG debugger over the same cable, so prefer it.

Find the device node

ls /dev/ttyACM*        # usually /dev/ttyACM0

Nothing there? Check dmesg | tail right after plugging in. A silent dmesg means the cable is charge-only or the socket is the wrong one.

Grant yourself access, once

sudo usermod -aG dialout $USER          # then LOG OUT and back in

The log-out is not optional — group membership is established at login. Until then you will get Permission denied on /dev/ttyACM0 and be tempted to run the flasher under sudo, which works but leaves root-owned build artifacts behind.

Forcing download mode

The flasher resets the board into the ROM download loader for you, by pulsing DTR and RTS. Occasionally — a wedged application, a board mid-deep-sleep — that does not take. Do it by hand:

1. Hold BOOT.
2. Tap RESET.
3. Release BOOT.

The board is now sitting in the ROM loader waiting for a flash command, and will stay there until you reset it again.

Reading the console

Any serial terminal at 115200 8N1 works. The ./x monitor command in the next step picks one for you, but if you would rather drive it yourself:

screen /dev/ttyACM0 115200                 # quit: Ctrl-A then K
# or:  python3 -m serial.tools.miniterm /dev/ttyACM0 115200
# or:  cat /dev/ttyACM0

Set ESPPORT in your environment and every command in this guide will pick it up, so you can drop the -p flag: export ESPPORT=/dev/ttyACM0.