Introduction: ESP32 Photo Clock

This instructables show how to use ESP32 and LCD to make a photo clock. In Japanese, it is called BiJin ToKei(美人時計).

Step 1: What Is BiJin ToKei?

BiJin ToKei(美人時計)start from 2009, they find various beauty hold a time board report time every minute. BiJin ToKei provide web application and mobile app version. After these years, you can find many variant on the web now.


Step 2: Why ESP32?

BiJin ToKei originally provide web application and mobile app version. It is a beautiful clock, but it is very hard to dedicate a desktop screen or mobile phone as a clock in long term.

How about ESP32 and a tiny LCD, it only cost around 10 USD, this price is reasonably worth to make it.

Step 3: Preparation

ESP32 board

Any ESP32 development board with SPI breakout pins should be ok.


ESP32_TFT_Library can support ILI9341, ILI9488, ST7789V and ST7735. This time I am using a 2.4" ST7789V LCD, model number JLX240-00302-BN. This model is designed for SPI only, so it only have 10 pins (actually 9 pins). It can help the soldering work easier.

Update: I also tried a 3.2" LCD, model number JLX320-00202

Display Stand

You may reuse any old material in hand as a simple stand, e.g. a mobile stand. I have a broken name tag holder in hand, it is prefect to do this job!


A 10 Ohm resistor and some coated copper wire.

Step 4: Design

A photo clock require the ability to display photo. The photo at is in JPG format so I need a JPG decode and display library. I am looking for the related library a long times ago, until ESP32 become popular.

ESP32 is the first hobby chip that have complete solution for displaying JPG image (thanks loboris's effort). Before that, I can found some video in Youtube claimed can show JPG with ESP8266, but lack of source code.

So this project start from Loboris's ESP32_TFT_library.

Here is the program flow:

  1. Connect WiFi
  2. Get current time with NTP protocol
  3. Concat the hour and minute string to form the current time picture URL and then retrieve it from every minute
  4. Save the picture jpg file to SPIFFS
  5. Display jpg file
Update: the latest code also support direct decode JPG HTTP response to LCD, no need write to SPIFFS as a cache.

Design concerning details:

  1. WiFi and Internet connection are not 100% reliable and I don't want the clock freezes at a wrong time, so once encounter any error (e.g. DNS lookup fail, NTP fail, download fail) the program trigger restart and do it again.
  2. Every minute have a single time picture means 1440 pictures a day, ESP32 built-in flash cannot fit hundreds MB pictures. So the clock cannot prefetch all pictures, but it can retrieve the picture every time, display it and then clean it up.
  3. Flash worn out easy from subsequent overwrite, so the program rotate the cache files to avoid write to the same place every minute.
  4. The picture size is bigger than the LCD resolution, so it is required to shrink the picture to half size to display.
  5. The ESP-IDF built-in timezone adjustment not work as expected, so require adjust timezone with custom code.
  6. Download file time require 10-50 seconds (depends on file size and network), so I have advanced 20 seconds (configurable) from the real time to overcome this delay.

Step 5: Download, Compile, Flash and Run the Program

Setting Up ESP-IDF (if not yet):

Download the source code here:


make menuconfig
  • config serial port
    1. select "Serial Flasher Config"
    2. select "Default serial port"
    3. fill ESP32 board serial port, e.g. COM6 at Windows; /dev/cu.SLAB_USBtoUART at macOS
  • config WiFi
    1. select "BiJin Tokei Configuration"
    2. fill your own "WiFi SSID" and "WiFi Password"


Modified "partitions.csv", adjust the storage size. (maximum 0x100000 for 2M and 0x300000 for 4M)

storage,  data, spiffs,  0x100000, 0xF0000,

Modified "main/bijin_tokei.c"

  • define how many cache files will be use, depend on the SPIFFS storage size. Or set to 0 for direct decode JPG HTTP response on the fly:

#define CACHE_COUNT 0

  • Select and uncomment one of the TOKEI LIST URL or fill your own URL:

static const char *REQUEST_FORMAT = 

Compile, flash and run the program:

make flash monitor

Step 6: Soldering Work

Stick the ESP32 board on the LCD back and soldering with coated copper wire.

The connection is very simple but the LCD pins usually very thin, beware don't mesh it up.

Here is the connection summary:

ESP32 GND    -> LCD -ve
             -> LCD LED -ve
ESP32 3v3    -> LCD +ve
             -> 10 Ohm resistor -> LCD LED +ve

Tips: power line require thicker wire to fulfil the current flow but it require more effort to fix the position; other signal lines can use thinner wire and ease the soldering work.

Step 7: Check and Place LCD on the Stand

Check the program run correctly and then fix it on the stand.

Step 8: Happy Time!

It's time to place it on your desktop and show to your friend what your have done!

Step 9: What's Next?

  • Try other BiJin ToKei variation
  • Random rotate selected variations
  • Tailor made your own photos
  • Display time in large font size in case picture failed to load
  • Try larger screen, e.g. ili9488 (320 x 480)