Keyfob Board

ESP32-S3 SD + Mic + OV2640 Recorder

WARNING: This project writes audio/video files to the SD card. Back up your data before testing.

Records:

• Audio: WAV via I2S mic (ICS-43434), mic_0001.wav, mic_0002.wav, ...
• Contact audio: WAV via ES8388 contact mic board, CT0001.WAV, CT0002.WAV, ...
• Video: MJPEG via OV2640, VID0001.MJP, VID0002.MJP, ...

Core features:

• SDMMC FAT mount/unmount
• USB MSC to expose the SD card when idle
• SSD1306 I2C OLED status
• Button UI
• BLE scan trigger (advertisements) with timestamped filenames
• Simultaneous standard mic + contact mic recording to separate WAV files
• Boot-time ES8388 codec bring-up so contact recording does not reinitialize the codec on every session

Supports SD (SDSC, SDHC, SDXC) cards and eMMC.

Quick wiring map (ESP32-S3)

• SD card (SDMMC):
  • CLK: GPIO6
  • CMD: GPIO7
  • D0: GPIO5
  • D1: GPIO4
  • D2: GPIO16
  • D3: GPIO15
• Mic (I2S):
  • BCLK: GPIO38
  • LRCK/WS: GPIO40
  • DOUT -> ESP DIN: GPIO39
• OLED (I2C, addr 0x3C):
  • SDA: GPIO1
  • SCL: GPIO2
• Contact mic codec board (ES8388 + MCP6002):
  • I2C SDA: GPIO1
  • I2C SCL: GPIO2
  • MCLK: GPIO41
  • ASDOUT -> ESP DIN: GPIO42
  • SCLK/BCLK: GPIO43
  • LRCK/WS: GPIO44
• Button:
  • GPIO45
• Camera (OV2640):
  • SCCB SDA: GPIO18
  • SCCB SCL: GPIO17
  • XCLK: GPIO9 (10 MHz)
  • D0..D7: GPIO47, GPIO48, GPIO14, GPIO21, GPIO12, GPIO13, GPIO10, GPIO11
  • PCLK: GPIO46
  • VSYNC: GPIO3
  • HREF: GPIO8
  • PWDN/RESET: tied in hardware (disabled in software with -1)

Hardware

This project targets ESP32-S3 and uses an SD card breakout or slot, an I2S mic, an SSD1306 OLED, and an OV2640 camera.

Although it is possible to connect an SD card breakout adapter, keep in mind that connections using breakout cables are often unreliable and have poor signal integrity. You may need to use lower clock frequency when working with SD card breakout adapters.

This project doesn't utilize card detect (CD) and write protect (WP) signals from SD card slot.

Pin assignments for ESP32

On ESP32, SDMMC peripheral is connected to specific GPIO pins using the IO MUX. GPIO pins cannot be customized. Please see the table below for the pin connections.

When using an ESP-WROVER-KIT board, this example runs without any extra modifications required. Only an SD card needs to be inserted into the slot.

Pin assignments for ESP32-S3 (current project)

On ESP32-S3, SDMMC peripheral is connected to GPIO pins using GPIO matrix. This allows arbitrary GPIOs to be used to connect an SD card. In this example, GPIOs can be configured in two ways:

1. Using menuconfig: Run idf.py menuconfig in the project directory and open "SD/MMC Example Configuration" menu.
2. In the source code: See the initialization of sdmmc_slot_config_t slot_config structure in the example code.

The table below lists the default pin assignments.

When using an ESP32-S3-USB-OTG board, this example runs without any extra modifications required. Only an SD card needs to be inserted into the slot.

I2S mic (ICS-43434)

SEL/LR on the mic should be tied to 3.3V (right channel), which matches the code.

OLED (SSD1306, I2C)

I2C address is 0x3C.

Contact mic codec board (ES8388)

Current firmware behavior:

• The ES8388 codec is initialized once at boot.
• If codec init is slow, the OLED shows retry/progress messages during boot.
• Once the OLED shows codec ok, normal operation begins.
• Later recordings reuse the initialized codec instead of re-running full codec init every time.

Camera (OV2640, Waveshare) — read this first

This project uses OV2640 over SCCB (I2C). The camera is sensitive to pin choice and initial frames are often corrupted.

Current working pin map (ESP32-S3 custom board):

PWDN and RESET are tied in hardware (PWDN -> GND, RESET -> 3.3V). In software, they are disabled (set to -1).

What was broken and how it was fixed:

• Camera capture initially failed because of a real solder bridge between VSYNC and PCLK. Fix: remove the bridge; camera now initializes and produces frames.
• OLED instability was partly caused by a pin conflict: OLED SCL and the buzzer both used GPIO2. Fix: remove all buzzer code so GPIO2 is dedicated to OLED SCL.
• Mic audio was silent with one mic connected because the code was reading the wrong I2S slot. Fix: switch the mic capture to the right channel and wire the mic SEL/LR pin high.
• FATFS without LFN rejects long filenames. Fix: keep video filenames 8.3-safe as VID0001.MJP and BLE timestamped names as MMDDHHMM.MJP / MMDDHHMM.WAV.

Playback note: VIDxxxx.MJP is a raw MJPEG stream (not a container). VLC can play it; for QuickTime, convert to AVI/MP4.

Current camera behavior:

• Video recording is capped in software at 10 FPS to reduce camera/SD load and improve stability.

BLE trigger and timestamped filenames

The device scans BLE advertisements and uses a UUID-encoded timestamp to name files:

• Video: MMDDHHMM.MJP
• Audio: MMDDHHMM.WAV
• Contact audio: a contact-mic WAV derived from the same BLE timestamp, with the first timestamp character replaced by C to stay 8.3-safe

If no valid BLE timestamp is seen, it falls back to the index names:

• VID0001.MJP
• mic_0001.wav
• CT0001.WAV

UUID format (128-bit): 00000000-0000-0000-TT00-YYMMDDHHMMSS

• Prefix is fixed: all zeroes (00 00 00 00 00 00 00 00)
• TT = 01 short press, 02 long press
• YYMMDDHHMMSS are BCD digits (base-10 nibbles)
• Filenames use MMDDHHMM to stay 8.3-safe

Current BLE scan behavior:

• BLE trigger scanning is enabled.
• Scanning is passive with duplicate filtering disabled.
• Scan duty cycle was reduced from continuous 10 ms / 10 ms (~100%) to 5 ms / 80 ms (~6.25%) to reduce radio and power load while keeping start/stop trigger support during recording.

Button

Pin assignments for ESP32-P4

On ESP32-P4, Slot 1 of the SDMMC peripheral is connected to GPIO pins using GPIO matrix. This allows arbitrary GPIOs to be used to connect an SD card. In this example, GPIOs can be configured in two ways:

1. Using menuconfig: Run idf.py menuconfig in the project directory and open SD/MMC Example Configuration menu.
2. In the source code: See the initialization of sdmmc_slot_config_t slot_config structure in the example code.

The table below lists the default pin assignments.

Default dedicated pins on ESP32-P4 are able to connect to an ultra high-speed SD card (UHS-I) which requires 1.8V switching (instead of the regular 3.3V). This means the user has to provide an external LDO power supply to use them, or to enable and configure an internal LDO via idf.py menuconfig -> SD/MMC Example Configuration -> SD power supply comes from internal LDO IO.

When using different GPIO pins this is not required and SD power supply comes from internal LDO IO setting can be disabled.

4-line and 1-line SD modes

By default, this example uses 4 line SD mode, utilizing 6 pins: CLK, CMD, D0 - D3. It is possible to use 1-line mode (CLK, CMD, D0) by changing "SD/MMC bus width" in the example configuration menu (see CONFIG_EXAMPLE_SDMMC_BUS_WIDTH_1).

Note that even if card's D3 line is not connected to the ESP chip, it still has to be pulled up, otherwise the card will go into SPI protocol mode.

Note about GPIO2 (ESP32 only)

GPIO2 pin is used as a bootstrapping pin, and should be low to enter UART download mode. One way to do this is to connect GPIO0 and GPIO2 using a jumper, and then the auto-reset circuit on most development boards will pull GPIO2 low along with GPIO0, when entering download mode.

• Some boards have pulldown and/or LED on GPIO2. LED is usually ok, but pulldown will interfere with D0 signals and must be removed. Check the schematic of your development board for anything connected to GPIO2.

Note about GPIO12 (ESP32 only)

GPIO12 is used as a bootstrapping pin to select output voltage of an internal regulator which powers the flash chip (VDD_SDIO). This pin has an internal pulldown so if left unconnected it will read low at reset (selecting default 3.3V operation). When adding a pullup to this pin for SD card operation, consider the following:

• For boards which don't use the internal regulator (VDD_SDIO) to power the flash, GPIO12 can be pulled high.
• For boards which use 1.8V flash chip, GPIO12 needs to be pulled high at reset. This is fully compatible with SD card operation.
• On boards which use the internal regulator and a 3.3V flash chip, GPIO12 must be low at reset. This is incompatible with SD card operation.
  • In most cases, external pullup can be omitted and an internal pullup can be enabled using a gpio_pullup_en(GPIO_NUM_12); call. Most SD cards work fine when an internal pullup on GPIO12 line is enabled. Note that if ESP32 experiences a power-on reset while the SD card is sending data, high level on GPIO12 can be latched into the bootstrapping register, and ESP32 will enter a boot loop until external reset with correct GPIO12 level is applied.
  • Another option is to burn the flash voltage selection efuses. This will permanently select 3.3V output voltage for the internal regulator, and GPIO12 will not be used as a bootstrapping pin. Then it is safe to connect a pullup resistor to GPIO12. This option is suggested for production use.

The following command can be used to program flash voltage selection efuses to 3.3V:

    espefuse.py set_flash_voltage 3.3V

This command will burn the XPD_SDIO_TIEH, XPD_SDIO_FORCE, and XPD_SDIO_REG efuses. With all three burned to value 1, the internal VDD_SDIO flash voltage regulator is permanently enabled at 3.3V. See the technical reference manual for more details.

espefuse.py has a --do-not-confirm option if running from an automated flashing script.

See the document about pullup requirements for more details about pullup support and compatibility of modules and development boards.

How to use

Build and flash

Build the project and flash it to the board, then run monitor tool to view serial output:

idf.py -p PORT flash monitor

(Replace PORT with serial port name.)

(To exit the serial monitor, type Ctrl-].)

Recording flow

1. Long press starts recording. USB MSC is stopped and the SD card is mounted to the app.
2. The normal I2S mic and the ES8388 contact mic are both recorded at the same time into separate WAV files.
3. Video is recorded in parallel if the camera is enabled and initialized.
4. Long press again stops recording, finalizes the WAV header(s), waits for the camera task to stop, and returns the SD card to USB MSC.
5. A later long press repeats the cycle with a new filename set.

Idle / post-record OLED messages

The OLED status is more specific than a generic Ready screen:

• Clean success: Recorded Xs at + the standard mic filename
• Standard mic file exists even if the task reported a higher-level failure: Mic file saved
• Standard mic saved but contact mic failed: Mic saved; c fail
• Startup codec bring-up: retry/progress messages followed by codec ok

Short press toggles pause/resume during recording.

SD card mount warnings

If SD mounting fails or is not ready, the OLED shows a warning:

• SD init failed
• SD mount failed
• SD not ready

When these appear, re-seat the SD card and try again. Also wait for the Exposing SD card over USB log before unplugging or copying files.

See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.

USB mass storage

When idle, the SD card is exposed over USB MSC for file access from your computer. During recording, USB MSC is stopped and the SD card is mounted to the application. After recording finishes, USB MSC is restarted and the card is visible again on the host.

Example output

Here is an example console output. In this case a 128MB SDSC card was connected, and EXAMPLE_FORMAT_IF_MOUNT_FAILED menuconfig option enabled. Card was unformatted, so the initial mount has failed. Card was then partitioned, formatted, and mounted again.

I (336) example: Initializing SD card
I (336) example: Using SDMMC peripheral
I (420) example: Mounting filesystem
I (538) mic: Waiting for long press
I (1840) button: Recording started
I (1841) mic: Recording started
I (9620) mic: Stop requested
I (9622) mic: Captured 7 sec to /sdcard/mic_0001.wav
I (9660) example: Card unmounted

Troubleshooting

Failure to download the example

Connecting........_____....._____....._____....._____....._____....._____....._____

A fatal error occurred: Failed to connect to Espressif device: Invalid head of packet (0x34)

Disconnect the SD card D0/MISO line from GPIO2 and try uploading again. Read "Note about GPIO2" above.

Card fails to initialize with sdmmc_init_sd_scr: send_scr (1) returned 0x107 error

Check connections between the card and the ESP32. For example, if you have disconnected GPIO2 to work around the flashing issue, connect it back and reset the ESP32 (using a button on the development board, or by pressing Ctrl-T Ctrl-R in IDF Monitor).

Card fails to initialize with sdmmc_check_scr: send_scr returned 0xffffffff error

Connections between the card and the ESP32 are too long for the frequency used. Try using shorter connections, or try reducing the clock speed of SD interface.

Failure to mount filesystem

example: Failed to mount filesystem. If you want the card to be formatted, set the EXAMPLE_FORMAT_IF_MOUNT_FAILED menuconfig option.

The example will be able to mount only cards formatted using FAT32 filesystem. If the card is formatted as exFAT or some other filesystem, you have an option to format it in the example code. Enable the EXAMPLE_FORMAT_IF_MOUNT_FAILED menuconfig option, then build and flash the example.

Debug SD connections and pullup strength

If the initialization of the SD card fails, initially follow the above options. If the issue persists, confirm the connection of pullups to the SD pins. To do this, enable the Debug sd pin connections and pullup strength option from menuconfig and rerun the code. This will provide the following result:

**** PIN recovery time ****

PIN 14 CLK  10044 cycles
PIN 15 CMD  10034 cycles
PIN  2  D0  10034 cycles
PIN  4  D1  10034 cycles
PIN 12  D2  10034 cycles
PIN 13  D3  10034 cycles

**** PIN recovery time with weak pullup ****

PIN 14 CLK  100 cycles
PIN 15 CMD  100 cycles
PIN  2  D0  100 cycles
PIN  4  D1  100 cycles
PIN 12  D2  100 cycles
PIN 13  D3  100 cycles

**** PIN voltage levels ****

PIN 14 CLK  0.6V
PIN 15 CMD  0.3V
PIN  2  D0  0.8V
PIN  4  D1  0.6V

In the absence of connected pullups and having the weak pullups enabled, you can assess the pullup connections by comparing PIN recovery time measured in CPU cycles. To check pullup connections, configure the pin as open drain, set it to low state, and count the cpu cycles consumed before returning to high state. If a pullup is connected, the pin will get back to high state after reasonably small cycle count, typically around 50-300 cycles, depending on pullup strength. If no pullup is connected, the PIN stays low and the measurement times out after 10000 cycles.

It will also provide the voltage levels at the corresponding SD pins. By default, this information is provided for ESP32 chip only, and for other chipsets, verify the availability of ADC pins for the respective GPIO using this and configure ADC mapped pins using menuconfig. Then test the voltage levels accordingly.

You can monitor the voltage levels of individual pins using PIN voltage levels and PIN voltage levels with weak pullup. However, if one pin being pulled low and experiencing interference with another pin, you can detect it through PIN cross-talk and PIN cross-talk with weak pullup. In the absence of pullups, voltage levels at each pin should range from 0 to 0.3V. With 10k pullups connected, the voltage will be between 3.1V to 3.3V, contingent on the connection between ADC pins and SD pins, and with weak pullups connected, it can fluctuate between 0.8V to 1.2V, depending on pullup strength.

207d2c1 (Initial commit)