ESP32 Digital Photo Frame

A DIY digital photo frame project using an ESP32 and an ILI9341 TFT display. This project features a dual SPI bus configuration to eliminate data interference and maximize image loading speeds. The repository also includes a custom PCB design, including all KiCad source and fabrication files. The board is production-ready and plug-and-play.

Key Features

• Dual SPI Architecture: Uses separate buses for the Display (VSPI) and the SD Card (HSPI) for stable, high-speed performance.
• Buffer-Optimized Rendering: Fast BMP processing using memory buffering.
• Random Start: Picks a completely random image from the SD card every time it boots up.
• Auto-Slideshow (Default): Advances to the next image every 5 seconds automatically.
• Manual Control: Dedicated buttons for "Next" and "Previous" navigation.
• Dynamic Mode Toggle: Switch between Manual and Auto modes by holding both buttons for 3 seconds.

Hardware Requirements

• ESP32 DevKit V1
• ILI9341 TFT Display (2.8" or 2.4" SPI)
• Micro SD Card Module
• 2x Push Buttons
• Lithium Battery, Charger Module (TP4056) and toggle button (Optional)

Wiring & Pinout

To avoid boot loops and "strapping pin" conflicts, the following pinout is used.

[!IMPORTANT] The display used for the proyect do not have a CS pin. All GND have to be connected to the same GND ESP32 pin. VERY CAREFULL with the polarity of the battery, charger pins and conexions with ESP32. Refer to the Schematics.pdf file in this repository for the full visual circuit diagram.

Component	Pin Name	ESP32 Pin	SPI Bus
Display	VCC	3v3	-
	CLK	GPIO 18	VSPI
	MOSI	GPIO 23	VSPI
	RES	GPIO 4	-
	DC	GPIO 2	-
	BLK	3v3	-
	MISO	GPIO 19	-
	GND	GND	-
SD Card	CS	GPIO 33	HSPI
	MOSI	GPIO 25	HSPI
	CLK	GPIO 22	HSPI
	MISO	GPIO 32	HSPI
	3V3	3v3	-
	GND	GND	-
Buttons	Next	GPIO 27	-
	Prev	GPIO 26	-
	GND	GND	-
Charger	Out+	VIN	-
	Out-	GND	-

Component	Pin Name	Charger Pin
Battery	RED	B+
	BLACK	B-

Image Preparation

To ensure the frame works correctly, your images must be formatted as follows:

• Format: BMP (Windows 24-bit / R8 G8 B8).
• Resolution: 320x240 pixels.
• Storage: Place images in the root directory of a FAT32 formatted Micro SD card.

Automated Image Batch Converter (Python Script)

To save time, an automated Python utility is provided in the tools/ directory to process images in bulk.

The script prompts you for the full path of your source image folder. It then automatically scales, converts, and exports all compatible files into a newly created Images-ready-to-use/ directory.

Important: The ESP32 firmware expects images to be in the root directory of the SD card. When moving the processed files, copy the contents of the Images-ready-to-use folder directly into the SD card, rather than copying the folder itself.

Prerequisites

Before running the script, you need to have Python 3 installed on your computer and install the required image libraries.

1. Install Python 3: Ensure Python is installed and added to your system's PATH.
2. Install Libraries: Open your computer's terminal (Command Prompt, PowerShell, or Terminal) and run the following command to install the required dependencies:

pip install pillow pillow_heif

User Controls

• Manual Navigation: Press the "Next" (GPIO 27) or "Previous" (GPIO 26) button.
• Mode Switch: Press and hold both buttons simultaneously for 3 seconds.
  • Green Label: Auto-mode active.
  • Red Label: Manual mode active.
• On-off control: Press the toggle button conected to the battery.

PCB Design (Hardware)

This project includes the complete design of a production-ready custom carrier board. It is designed to be fully plug-and-play: you simply need to plug the ESP32 and the display into their respective sockets, with no manual soldering required.

Display Compatibility (Extra CS Pin)

The original design of this PCB is optimized for standard 8-pin displays. However, to maximize the project's compatibility, I have added an extra pin for displays that include a CS (Chip Select) pin.

At the hardware level, this additional control pin is physically routed to GPIO 15 on the ESP32.

Firmware Configuration:

If you are using an 8-pin display, you don't need to do anything (it works out of the box). But if your display requires the use of the CS pin, you must enable it in the software by following this simple step:

Go to the main code file (main) and locate line 10. You will need to change the disabled value (-1) to the corresponding pin (15).

// ❌ Default configuration (8-pin displays without CS):
#define TFT_CS -1

// ✅ Modified configuration (Displays with CS pin connected):
#define TFT_CS 15

Getting Started

1. Clone this repository.
2. Install Adafruit_ILI9341 and Adafruit_GFX libraries in your Arduino IDE.
3. Upload the main.ino sketch to your ESP32.
4. Check the Schematics.pdf for wiring details.

---

Code helped by AI Created by Pablo Vazquez