Frequently Asked Questions

Which computers can run Pico Bay?

Windows, macOS, Linux, and Raspberry Pi OS with Node.js 20 or newer. Run npx @ctrlpi/pico-bay, connect your board with a USB data cable, and open http://localhost:7426.

What does Windows need?

Node.js 20 or newer and the .NET Framework v4 C# compiler (csc.exe). Pico Bay compiles its Windows serial helper automatically at startup. Check the terminal for compiler or serial errors.

How do I install firmware on an ESP32?

Choose Enter download mode… from the app menu. For manual entry, hold BOOT/IO0, press and release RESET/EN, hold BOOT for three seconds, then release. Scan and select the red DOWNLOAD pill. The app offers installation only for identified, supported chips without blocking flash security.

Erase and initialize storage is selected by default. Uncheck it before installation to preserve existing files.

How do I enable MCP?

Enable HTTP MCP in the app interface or start with --mcp-http. It is enabled by default on Raspberry Pi hosts. For a client that launches a local server, use --mcp-stdio; this mode does not start the browser or web server.

No board appears in the interface?

For file access, confirm that the board is running MicroPython or CircuitPython. Supported bootloader modes appear as red device pills instead. Use a USB data cable and check that its serial device appears under /dev on macOS/Linux or Ports (COM & LPT) in Windows Device Manager.

Why is my ESP32 not detected on Windows?

You may be missing its serial driver. Many ESP32 boards use a CP210x USB to UART bridge. Download the CP210x Universal Windows Driver, open Device Manager, find the unrecognized device, and update the driver.

Why does a command time out?

Startup code may be keeping the board busy or disabling interrupts. You can increase --hold when repeated operations collide with a slow main.py startup. Disconnect and reconnect the board to recover an unknown raw-REPL state.

Why does the program restart after file access?

This is expected. Raw-REPL access interrupts the program, and Pico Bay resets the board afterward so main.py can resume.