ESP32-S3-WROOM CAM — 40-pin

Twenty pins a side, a DVP camera connector on the front, a microSD slot on the back, and two USB-C sockets. The camera claims fourteen of the thirty-six GPIO pads, the card claims three more, and the octal PSRAM claims three that are printed on the header and look free. What is left is seven pins.

That arithmetic is the whole story of this board. It also means the Arduino defaults for Wire and SPI land squarely on camera data lines, and that the single most common failure — "the camera does not initialise" — is almost never the camera.

• reference/board-hardware.md — the board: the full 40-pin header table with every alternate function, the camera and SDMMC maps traced to the vendor's own code, the PSRAM and strapping pins, the two USB routes, the power tree, the flash/partition layout — plus a development guide (§8 toolchain, §9 platformio.ini, §10 flashing and recovery, §11 symptom → cause → fix table).
• reference/esp32s3-soc.md — the silicon: which GPIOs do not exist, strapping semantics from the datasheet's own tables, ADC1/ADC2 and touch maps, the LCD_CAM DVP controller, power-up glitches, memory map and PSRAM addressing, deep sleep and RTC wake pins.
• reference/esp32-family.md — the rest of the family, for "should this be a different ESP32?" questions: what does and does not port between chips, radio and USB capability per chip, the RMT generation table (WS2812 under Wi-Fi load), deep-sleep memory and ULP/LP-core availability, and a chip-selection table.
• reference/recipes.md — code that compiles: platformio.ini, camera init and capture, SDMMC, camera → SD, an MJPEG web server, moving the console to native USB, I2C and SPI on the pins that are actually free, ADC, WS2812, deep sleep.
• template/ — a project that builds clean, in two variants, plus a scaffold script. See template/README.md.

Confirm the board first

Several ESP32-S3 camera boards exist and their pin maps are mutually incompatible. This skill is for the 40-pin one. Check three things before writing any pin:

	This board	Not this board
Header	20 + 20 pins, 3V3 RST 4 5 6 7 15 16 17 18 8 3 46 9 10 11 12 13 14 5V down one side	44-pin DevKitC-1 (no camera), 21-pin XIAO S3 Sense, ESP32-S3-EYE (no header)
Camera	24-pin FPC on the top face, XCLK on GPIO15	ESP32-S3-CAM-LCD boards use XCLK GPIO40; XIAO S3 Sense uses XCLK GPIO10
microSD	slot on the back, SDMMC on GPIO39/38/40	XIAO S3 Sense: SPI on GPIO7/8/9; LCD boards: GPIO47/48/...

The camera pin map is byte-for-byte CAMERA_MODEL_ESP32S3_EYE in the Arduino core's camera_pins.h. Use that macro, not CAMERA_MODEL_ESP32S3_CAM_LCD and not CAMERA_MODEL_XIAO_ESP32S3 — both compile and both give you a sensor that never answers on SCCB.

If the user is unsure, flash template/ --minimal and read the report: it prints flash size, PSRAM size and chip revision, which identifies the module.

Orientation

Module	ESP32-S3-WROOM-1 N8R8 or N16R8. ESP32-S3, Xtensa LX7 dual-core @ 240 MHz
Memory	8 or 16 MB quad SPI flash · 8 MB OCTAL SPI PSRAM · 512 KB SRAM (~320 KB linkable) · 8 KB RTC FAST + 8 KB RTC SLOW
Header	40 pins, 20 a side. 36 GPIO pads, plus 3V3, 5V, GND, EN
Camera	24-pin DVP FPC. OV2640 (2 MP) on most batches, OV3660 or GC2145 on some. PWDN/RESET not wired — must be -1
Camera pins	XCLK 15 · SIOD 4 · SIOC 5 · VSYNC 6 · HREF 7 · PCLK 13 · D0-D7 = 11, 9, 8, 10, 12, 18, 17, 16
microSD	SDMMC host, 1-bit only (D1/D2/D3 not routed). CLK 39 · CMD 38 · D0 40
LEDs	plain LED on GPIO2, active high · WS2812 on GPIO48 (one pixel, GRB) · power/TX/RX LEDs not on a GPIO
Buttons	BOOT = GPIO0, pressed low, internal pull-up · EN/RST acts on CHIP_PU, not readable
USB	two USB-C. One is a WCH CH343 bridge on UART0 (GPIO43/44) with DTR/RTS auto-reset; the other is the S3's native USB on GPIO19/20 (USB-Serial-JTAG + OTG)
Console	UART0 @ 115200 by default. Serial moves to native USB only with -DARDUINO_USB_CDC_ON_BOOT=1
Unusable	35, 36, 37 — octal PSRAM, on the header and fatal to touch · 26-32 flash bus, not brought out · 22-25 do not exist on the S3
Strapping	0 (boot) · 45 (VDD_SPI voltage) · 46 (boot + ROM log) · 3 (JTAG source, floating, no internal pull)
Free with camera + SD	1, 2, 14, 21, 41, 42, 47 — and 19/20 or 43/44 if you give up a USB route
Analog	ADC1 = GPIO1-10, ADC2 = GPIO11-20. With the camera wired the only free ADC1 channels are GPIO1, 2, 3
Radio	Wi-Fi b/g/n + Bluetooth 5 LE, PCB antenna
Toolchain	PlatformIO 6.1.19 + platform-espressif32 7.0.1 + Arduino core 2.0.17, board = esp32-s3-devkitc-1

Rules that prevent the expensive mistakes

Each of these produces a failure that looks like something else.

1. board_build.arduino.memory_type = qio_opi and -DBOARD_HAS_PSRAM, or nothing works. The esp32-s3-devkitc-1 board definition is an N8 with no PSRAM; its default memory type is qio_qspi. Leave it and the 8 MB octal PSRAM is never mapped: psramFound() returns false and esp_camera_init() fails with ESP_ERR_NO_MEM (0x101) — or, worse, succeeds at QVGA and then dies the first time you raise the frame size. There is no message saying "PSRAM missing"; check psramFound() first, always.

2. GPIO35, 36 and 37 are printed on the header and are the PSRAM bus. On any R8 or R16V module the datasheet's own footnote reads: "pins IO35, IO36, and IO37 are connected to the Octal SPI PSRAM and are not available for other uses". Driving one is not a soft failure — it corrupts the bus the CPU is reading its cached data from, and the board reboots with Cache disabled but cached memory region accessed or a LoadProhibited panic that points anywhere but the pin you touched.

3. Wire.begin() and SPI.begin() with no arguments land on camera data lines. The ESP32-S3 Arduino variant defaults to SDA = 8, SCL = 9 and MOSI = 11, MISO = 13, SCK = 12, SS = 10. On this board those are camera D2, D1, D0, PCLK, D4, D3. The symptom is not an I2C error: the camera starts returning torn or all-green frames the moment your sensor library initialises. Always pass explicit pins — Wire.begin(SDA_PIN, SCL_PIN) — and pick them from the free list.

4. The camera's SIOD/SIOC on GPIO4/5 is an SCCB bus owned by the camera driver, not a general I2C bus. Hanging your own I2C devices there works until the driver reprograms the sensor and the transaction collides. Give other I2C devices their own pins.

5. SD_MMC.setPins(39, 38, 40) must be called before SD_MMC.begin(). In the other order setPins() returns true, changes nothing, and begin() uses the S3's default SDMMC pins — which on an R8 module overlap the PSRAM pins of rule 2 and put the board into a reboot loop. And pass mode1bit = true: D1/D2/D3 are not routed on this board, so 4-bit mode cannot work.

6. Mounting the card kills pad-JTAG. GPIO39 is MTCK and GPIO40 is MTDO. Once the SD driver owns them an external JTAG probe is gone. Use the built-in USB-Serial-JTAG on the native USB-C instead — it needs no pins and works while the card is mounted.

7. Serial goes to UART0 (GPIO43/44), not to the native USB port. Plugging into the wrong USB-C gives you a device that enumerates and prints nothing. The CH343 bridge shows up as wchusbserial/ttyACM; the native port as usbmodem with VID 303A. To put the console on native USB add -DARDUINO_USB_CDC_ON_BOOT=1 — and accept that you then lose the first ~1.5 s of boot output while the host enumerates.

8. GPIO19 and GPIO20 are the native USB D-/D+. Using them as GPIO kills that port, which also removes USB-Serial-JTAG (rule 6) and the only debugger the board has. They are also ADC2_CH8/CH9, so "just use them for analog" costs the same.

9. GPIO45 high at reset sets VDD_SPI to 1.8 V and the flash stops reading. It has a weak pull-down and must stay low through reset. An LED to 3V3, a pull-up on a shared bus, or a peripheral idling the line high leaves a board that looks bricked and is fine as soon as the pull comes off. GPIO46 is the same shape of trap for boot mode.

10. GPIO0 is the BOOT button and a header pin. Anything holding it low at reset puts the board in download mode — which presents as "my firmware stopped running", not as a pin problem. If uploads start failing after you wire something, unplug GPIO0 first.

11. XCLK is generated by LEDC channel 0 / timer 0. analogWrite() on the Arduino core allocates LEDC channels from 0 upward, so the first analogWrite() in a camera sketch can retune the timer under the sensor. Frames go dark or tear and nothing reports an error. Give your PWM an explicit high channel with ledcSetup(4, ...) and up.

12. ADC2 is dead while Wi-Fi is running, and with the camera wired ADC2 is GPIO11-20 — all camera pins anyway. Your entire analog budget on a connected camera build is GPIO1, GPIO2 and GPIO3 on ADC1. Plan the pinout around that number.

13. Every esp_camera_fb_get() needs a matching esp_camera_fb_return(), on the error paths too. With fb_count = 2 two leaked buffers stall the driver permanently: the next fb_get() blocks forever and the watchdog resets the board, pointing at whatever task happened to be running.

14. A reset when Wi-Fi starts, or when the flash LED fires, is the supply. The S3 peaks at ~340 mA transmitting, the sensor adds its own, and a thin USB cable or a laptop hub will not hold 3V3. esp_reset_reason() returns ESP_RST_BROWNOUT; say that rather than reading the backtrace.

15. board_upload.flash_size must match the module. The N8R8 and N16R8 both exist on this footprint and nothing on the silkscreen distinguishes them. Set 8MB — it is correct on an N8R8 and merely wasteful on an N16R8. The reverse (16 MB set on an 8 MB part) writes a partition table off the end of the flash and boot-loops. esptool.py flash_id prints the real size.

16. Do not use huge_app.csv here. It is a 4 MB table: its coredump partition lands at 0x3F0000 and the upper half of an 8 MB flash is simply lost. The board's own default (default_8MB.csv) is a dual-OTA table that spends 3.1 MB on a second app slot. template/partitions.csv is a single-app 4 MB + 3.875 MB SPIFFS layout that keeps the same offsets on 8 MB and 16 MB parts.

When the task is choosing pins

Work outward from what is already taken. With the camera and the card both in use the header has seven free GPIOs:

GPIO	Note
1, 2, 3	ADC1_CH0/CH1/CH2, TOUCH1/2/3. GPIO2 also drives the plain LED; GPIO3 is the JTAG-source strap and floats — give it a defined level at reset
14	ADC2_CH3, TOUCH14. The cleanest single free pin on the board
21	plain GPIO, no strap, no analog
41, 42	MTDI / MTMS. Free unless you want pad-JTAG (which rule 6 already cost you)
47	plain GPIO. GPIO48 next to it is the WS2812

Then the ones you buy by giving something up:

• 19, 20 — cost you the native USB port and USB-Serial-JTAG (rule 8).
• 43, 44 — cost you the UART0 console; only sane together with rule 7.
• 45, 46 — usable after boot if their reset-time level is respected (rule 9).
• 4-13, 15-18 — camera. Free only in a build with no camera.
• 38, 39, 40 — microSD. Free only in a build with no card.

If seven is not enough, the answer is an I2C GPIO expander or a shift register on GPIO14/21, not one of the PSRAM pins. There is no ninth pin hiding on this header.

When the task is the camera

Start from template/src/camera.cpp — it is a working init for this exact board.

The mechanism worth knowing: the LCD_CAM peripheral clocks 8 parallel data bits in on every PCLK edge into a DMA ring, and the driver hands you whole frames out of PSRAM. So:

• Frame buffers live in PSRAM (fb_location = CAMERA_FB_IN_PSRAM). An SVGA JPEG with fb_count = 2 costs roughly 200 KB of the 8 MB. UXGA RGB565 is 3.8 MB per buffer — one buffer fits, two do not, and the failure is ESP_ERR_NO_MEM at init.
• PIXFORMAT_JPEG is the only format worth streaming. RGB565 at anything above QVGA saturates the PSRAM bandwidth before it saturates Wi-Fi; the frame rate you measure will be the memory bus, not the sensor.
• xclk_freq_hz = 20000000 is the usual figure; the vendor's own sketches ship 10 MHz. Torn frames, a green cast, or Camera capture failed on an otherwise correct configuration is the first thing 10 MHz fixes. It is a signal-integrity limit of the FPC and the batch, not a setting you can reason from the datasheet.
• grab_mode = CAMERA_GRAB_LATEST for a live stream, CAMERA_GRAB_WHEN_EMPTY for stills. The default drops you a frame behind.
• The sensor is mounted upside down relative to the silkscreen: set_vflip(s, 1) and set_hmirror(s, 1).
• ESP_ERR_NOT_FOUND (0x105) means no sensor answered on SCCB. In order: reseat the FPC (contacts face the PCB, latch fully down), confirm PWDN/RESET are -1, confirm the pin macro is CAMERA_MODEL_ESP32S3_EYE. It is a connector fault far more often than a code fault.

When the task is the microSD card

template/src/sdcard.cpp is the working version. The card is on the SDMMC host in 1-bit mode, not on SPI — do not reach for SD.h and a SPI bus here; SD_MMC.h with setPins() is the whole interface.

• Mount failures are, in order: no card, not FAT32, setPins() called too late (rule 5), or a card that needs SDMMC_FREQ_PROBING instead of SDMMC_FREQ_DEFAULT.
• Pass format_if_empty = false unless the user asked for the opposite. The Arduino signature is begin(mountpoint, mode1bit, format_if_empty, sdmmc_frequency, maxOpenFiles) and the vendor's example ships true in the third slot.
• Writing a JPEG per frame is bounded by the card, not the camera: a cheap class-10 card gives ~2-4 SVGA frames per second. Buffer in PSRAM if you need bursts.

When the task is "the board does not work"

Diagnose in this order — each stage only depends on the ones before it:

1. Does psramFound() return true? If not, stop: rule 1. Every camera symptom downstream of this is a consequence, not a cause.
2. Is anything wired to GPIO35/36/37, or to GPIO0 or GPIO45? Unplug them first (rules 2, 9, 10).
3. Which USB-C is the cable in? wchusbserial prints by default; usbmodem needs -DARDUINO_USB_CDC_ON_BOOT=1 (rule 7).
4. Does anything print at 115200? The ROM banner (ESP-ROM:esp32s3-...) comes out before any of your configuration applies. No banner ⇒ cable, port or bridge driver.
5. Does it boot-loop? Read the reset reason. ESP_RST_BROWNOUT ⇒ rule 14. Cache disabled but cached memory region accessed ⇒ rule 2. invalid header ⇒ esptool.py erase_flash and reflash --minimal.
6. Camera-specific: 0x101 = memory (rule 1 or a frame size too large), 0x105 = nothing on SCCB (reseat the FPC), init OK but frames are torn or green = XCLK, or rule 3, or rule 11.
7. Card-specific: mount failure ⇒ the list above. Mount OK but writes fail ⇒ the card is full or the FAT is damaged; try another card before another line of code.
8. Still lost? Flash --minimal for a baseline that touches only the toolchain, the flashing route, the console, two LEDs and the PSRAM mapping — then add one subsystem at a time.

template/src/board_report.cpp prints the PSRAM state, flash size, reset reason and the strapping levels, which answers most of steps 1-5 in one paste.

Starting a new project

Do not hand-assemble one — the platformio.ini has four settings that are wrong by default and silent when wrong. Scaffold from template/:

~/.claude/skills/esp32s3-cam-40pin/template/variants/new-project.sh <target-dir> [--full|--minimal]
cd <target-dir> && pio run

• --minimal — LED + WS2812 blink, console heartbeat, PSRAM check. 280,785 B flash, 19,052 B RAM. Flash this first on a board you have not used before: its outputs fail independently, so it separates "wrong USB port" from "no PSRAM" from "clone without the GPIO2 LED" without any guessing.
• --full (default) — board self-test: report, microSD over SDMMC, camera init, and a JPEG onto the card on every BOOT press. 425,641 B flash, 24,008 B RAM. The camera's frame buffers are PSRAM and do not appear in that RAM figure.

Both build as-is with Arduino core 2.0.17 (verified, zero warnings). Nothing is generated and no paths are embedded, so copying template/ by hand works identically. template/README.md maps files to subsystems so a --full scaffold can be stripped back.

When the user already has a project, prefer bringing their platformio.ini and include/board.h in line with the template over rewriting their sketch.

ESP-IDF is a reasonable alternative and every pin rule above applies unchanged; add espressif/esp32-camera as a managed component and set CONFIG_SPIRAM_MODE_OCT=y, CONFIG_SPIRAM_SPEED_80M=y. The Arduino core bundles the same camera driver, which is why the template uses it.

Flashing

pio run -t upload -t monitor

The CH343 bridge drives EN and GPIO0 through the auto-reset circuit, so no buttons are needed on the UART port. Ports:

Socket	Enumerates as	Notes
CH343 bridge	/dev/cu.wchusbserial*, /dev/ttyACM*, a COM port	flashes and prints out of the box; needs the WCH driver on older macOS
native USB	/dev/cu.usbmodem*, VID 303A PID 1001	flashes too, and carries USB-Serial-JTAG for debugging; prints only with -DARDUINO_USB_CDC_ON_BOOT=1

When upload fails with Wrong boot mode detected or No serial data received, check GPIO0 before the cable (rule 10). Then the manual sequence: hold BOOT → tap EN/RST → release BOOT → upload. If 921600 is unreliable, drop upload_speed to 460800.

Bad firmware cannot brick this board. The ROM bootloader always answers that sequence:

esptool.py --chip esp32s3 -p <port> flash_id      # tells you 8 MB vs 16 MB (rule 15)
esptool.py --chip esp32s3 -p <port> erase_flash   # ~15 s for 8 MB

The one genuinely unrecoverable mistake is burning the VDD_SPI eFuse to 1.8 V on a 3.3 V module. eFuses are one-time. Do not run espefuse.py on this board.

Reporting

Say what is verified and what is derived.

Primary-source, high confidence: the module pin table, the "IO35/36/37 are the octal PSRAM and not available" footnote, the strapping tables (GPIO0/3/45/46), the power-up glitch list and the ADC/touch channel maps in reference/ are transcribed from the Espressif ESP32-S3-WROOM-1/1U Datasheet v1.8 and ESP32-S3 Series Datasheet v2.2.

Vendor-source, high confidence: the camera and SDMMC pin maps, the WS2812 on GPIO48 and the LED on GPIO2 come from Freenove's own published sketches for this board (camera_pins.h → CAMERA_MODEL_ESP32S3_EYE, SD_MMC_CLK 39 / CMD 38 / D0 40, marked "Please do not modify it") and from their published pinout drawing. The clones copy this layout, but a clone is still a clone.

Verified on this machine: both template variants build clean with PlatformIO 6.1.19 / platform-espressif32 7.0.1 / Arduino core 2.0.17, zero warnings, at the flash and RAM figures quoted above. Every recipe in reference/recipes.md was compiled in that project.

Not verified on hardware: nothing here was run on a physical board in this session — no photo was captured, no card was mounted, no frame rate was measured. Details that vary by vendor and batch (which sensor is fitted, whether the GPIO2 LED is populated, whether 20 MHz XCLK is stable, N8R8 vs N16R8) must be confirmed with --minimal on the user's actual board. Say so rather than presenting them as certain.