Skip to content
Handsy AI · ESP32 iPhone Agent

"Failed to connect with the device" when installing firmware

Hold BOOT while you plug the board in, then click Connect board again. That fixes this error in almost every case.

Why it happens

Section titled “Why it happens”

The installer talks to the board over a USB serial port. A blank XIAO ESP32S3 offers one, so the first install just works. Once Handsy firmware is running, the board’s USB port acts as the iPhone’s keyboard and mouse, and it may not offer a serial port the installer can use. The installer then fails with:

Couldn't install.
Details: Failed to connect with the device

You may also see Timed out waiting for packet header or a board that never shows up in the picker. Same cause, same fix.

Fix: put the board in install mode

Section titled “Fix: put the board in install mode”
  1. Unplug the board from the computer.
  2. Press and hold the BOOT button. It is the small button next to the USB-C port.
  3. Keep holding it and plug the board back in. Release the button after a second.
  4. On the install page, click Connect board and pick the port that just appeared. It is usually called USB JTAG/serial debug unit.
  5. When it says Installed, unplug the board and plug it in again so it starts the new firmware.

Your board isn’t harmed by a failed attempt. Trying again is safe.

Still failing?

Section titled “Still failing?”
  • Use a data cable. Many USB-C cables only charge. Try the cable you use for file transfer.
  • Plug in directly. Skip hubs and docks, or try another port on the computer.
  • Close other apps using the board. A serial monitor, Arduino IDE, PlatformIO, or another installer tab holds the port.
  • Use Chrome or Edge on a computer. Safari, Firefox, and phones can’t open USB serial ports.
  • Check the board. The installer is made for the standard XIAO ESP32S3 (8 MB flash, 8 MB PSRAM). See Hardware.

Updating a board that already works

Section titled “Updating a board that already works”

You don’t need the computer for this. When the board is plugged into your iPhone, the ESP32 Agent app offers firmware updates over Wi-Fi. See Update ESP32 Agent firmware.

Still stuck? Click Download log under the error and send the file to [email protected]. The log stays in your browser until you send it. More answers: FAQ and Debugging & logs.