Frequently Asked Questions
Which computers can run Pico Bay?
Windows, macOS, Linux, and Raspberry Pi OS with Node.js 20 or newer. Run npx 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 turn a board into a ctrlPi agent?
With the board on USB and running MicroPython, choose Install ctrlPi API in the top-right menu. Enter your Wi-Fi details and, optionally, an API key and a name, and Pico Bay installs the latest pico-gpio-api (Pico W, Pico 2 W) or esp32-gpio-api (any ESP32; the ESP32, ESP32-C3 and ESP32-S3 are supported), then resets the board. On a Pico without Wi-Fi or a board running CircuitPython, the menu item is greyed out with the reason.
How do I configure MCP with stdio?
Use stdio when your MCP client (such as Claude Desktop or Claude Code) launches Pico Bay directly as a local subprocess. In this mode, no browser window opens and no network port is held.
In Claude Desktop, open Settings → Developer → Edit Config (claude_desktop_config.json) and add Pico Bay under mcpServers:
{
"mcpServers": {
"pico-bay": {
"command": "npx",
"args": ["-y", "pico-bay", "--mcp-stdio"]
}
}
}Restart Claude Desktop, and your connected USB boards will be accessible directly in conversation.
How do I configure MCP with HTTP?
Use Streamable HTTP when you want the MCP server to run alongside the web interface, or when Claude connects over your local network (for example, to a Raspberry Pi host).
Start Pico Bay with the --mcp-http flag (or toggle HTTP MCP in the app interface):
npx pico-bay --mcp-http
The MCP endpoint is served at http://localhost:7426/mcp (or http://PI_ADDRESS:7426/mcp). In Claude Desktop, connect using mcp-remote:
{
"mcpServers": {
"pico-bay": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:7426/mcp"]
}
}
}Or in Claude Code, connect directly via the HTTP transport:
claude mcp add pico-bay --transport http http://localhost:7426/mcp
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.