When the upload fails: manual download mode
"Failed to connect" means the chip was running your sketch when the IDE wanted to talk to its bootloader. Two buttons fix it, in an order that matters, because the chip looks at GPIO 9 exactly once.
What "Failed to connect" is telling you
Uploading does not talk to your sketch. It talks to a bootloader in the chip's ROM, and that bootloader only runs if the chip decided to run it — a decision made once, at the instant reset is released, by reading two pins.
GPIO 9 is the one you can press. High means "start the sketch in flash", and the board's pull-up gives you that by default. Low means "wait for an upload". GPIO 8 has to be high at the same moment, which the board also arranges.
Most of the time you never touch either. The IDE asks the chip's USB peripheral to perform the same sequence for you, which is why uploading normally is one button. When that automatic path fails — because the running sketch is busy, because it crashed, because it reconfigured the pin — the chip never enters download mode, esptool talks into a void, and you get a timeout.
The one instant that matters
Everything about the ritual follows from the dashed line. The chip reads GPIO 9 as reset rises and never looks again, so:
- Hold BOO and keep holding it.
- Press and release RST.
- Wait a second, or until the IDE prints
Connecting…. - Release BOO.
Letting go afterwards cannot undo it, which is why step 4 is safe. And pressing RST first cannot work, no matter how quickly you follow it with BOO, because by then the decision is a frame old and nothing is reading the pin.
Where it sits in the upload
Press Upload in the IDE first, then do the button sequence while it is
compiling or printing Connecting…. That order matters on this board more than
on most: the reset destroys the serial port, so the IDE needs to be looking for
the new port rather than holding the old one.
When the upload finishes, the chip is still in download mode. Press RST once and your sketch starts. A board that appears to ignore a successful upload has almost always just not been reset.
When to suspect the sketch instead
If manual mode works every time and automatic never does, the board is fine and
the sketch is in the way. Anything that reconfigures GPIO 8 or 9, or that blocks
for a long time early in setup(), can stop the automatic sequence from
landing. Erase the flash, upload a bare blink, and see whether normal uploading
comes back — that separates a board problem from a code problem in about a
minute, and it is nearly always the code.
When it does not work
Something is holding GPIO 8 or GPIO 9 at the wrong level, or the sketch already on the board is crashing early enough to interfere. Erase the flash and upload a bare blink; if automatic upload comes back, the sketch was the problem rather than the board.
It is meant to. The serial port on this board is created by the chip, so resetting the chip destroys it and entering download mode creates a different one. Press Upload first and start the button sequence while the IDE is printing "Connecting", so it is watching for the port that appears rather than the one that went.
Try another cable. A charge-only lead powers the board and presents no data pair, so the board looks alive and the IDE finds no port — and if some other device is on the same port name, close whatever is holding it. A serial monitor left open on another program will take the port and never give it back.
That is expected. Download mode ends at the next reset, so press RST once when the upload finishes and your new sketch starts. A board that seems to do nothing after a successful upload has usually just not been reset.
The first sketch that proves the screen is really there, and the one you will keep coming back to whenever a module goes quiet.
Scan the I²C bus →Edit this page — content/boards/c3-oled/manual-download-mode.mdx
Questions about this product
See what other owners have asked, and read their solutions.
ESP32-C3 OLED Development Board with Expansion Base
Loading discussions…
Discuss this article
Ask about this page. The answer stays here, on the page it belongs to, for whoever hits the same wall next.