I want to use LVGL to create an application similar to a photo album, but images cannot be displayed whether I use the official LVGL tool to convert them into RGB565 .bin files or use Sipeed’s tool to convert them into EZIP .bin files. However, using C arrays works fine.
The key code for displaying images is as follows:
void image_show_update_image_bin(const void *bin_data)
{
lv_img_set_src(main_obj->img, bin_data);
lv_img_header_t header;
lv_res_t res = lv_img_decoder_get_info(bin_data, &header);
if (res == LV_RES_OK)
{
printf("Image width: %d\n", header.w);
printf("Image height: %d\n", header.h);
printf("Color format: %d\n", header.cf);
}
else
{
printf("Failed to get image info\n");
}
}
The command used for EZIP conversion is:
E:\Users\chen\Pictures\bmp\sdcard\Bin\1>ezip -convert 45.png -rgb565 -binfile 2 -lvgl_version 8
ezip version: 2.3.4_2025_07_04 Support_c_file
------------- ezip convert begin: ezip -convert 45.png color RGB565 -------------
Output:
next file:C:pictures/45.bin
Failed to get image info
"Failed to get image info"is printed from the code above — this means EZIP’s binary format cannot be parsed by LVGL.
Another case:
prev file:C:pictures/test.bin
Image width: 355
Image height: 502
Color format: 4
This
.binfile was generated using the official LVGL converter (RGB565 true color). The image header is correctly recognized (color format 4 =LV_IMG_CF_TRUE_COLOR), but the image displays as a black screen.
No matter what I try, the image won’t display properly. I’m not sure where the problem lies.
Possible Causes and Solutions:
1. Ensure Image Data Is Properly Loaded into Memory
- If loading from external storage (e.g., SD card), confirm that:
- The file is successfully read.
- The buffer holding the
.bindata is valid and remains in scope. - There are no alignment or caching issues (especially on MCUs like ESP32).
- Example check:
uint8_t* img_buf = read_file_from_sd("45.bin"); if (img_buf) { image_show_update_image_bin(img_buf); }
2. Correct Image Format Flag in Conversion
- When using the LVGL Image Converter, make sure:
- Target format is set to RGB565 (with/without alpha).
- Output format is
.bin. - LVGL version matches (v8.0+).
- For Sipeed EZIP, note:
- EZIP uses a custom compression format; you must register a custom decoder in LVGL to handle
.ezipor-binfile 2outputs. -binfile 2generates compressed binary, which standard LVGL decoders cannot parse directly.
- EZIP uses a custom compression format; you must register a custom decoder in LVGL to handle
Fix for EZIP: You need to integrate the EZIP decoder into your project and register it with lv_img_decoder_set_info_cb() and lv_img_decoder_set_open_cb().
3. Black Screen with Valid Header (Official .bin)
- Header is read correctly → LVGL recognizes the image.
- But black screen usually means:
- Byte order (endianness) issue: RGB565 pixels may be swapped.
- Try enabling
LV_COLOR_16_SWAPinlv_conf.h:#define LV_COLOR_16_SWAP 1 - Especially important on STM32, ESP32, etc.
- Try enabling
- Incorrect pixel data: Verify the original PNG has no transparency issues or unsupported features.
- Partial load or corruption: Double-check file reading logic.
- Byte order (endianness) issue: RGB565 pixels may be swapped.
4. Memory Lifetime Issue
- If the image buffer is allocated on the stack or freed too early:
void load_image() { uint8_t data[1024]; read_sd(data, ...); lv_img_set_src(img, data); // ❌ `data` may be gone when LVGL tries to draw } Fix: Use lv_img_set_src(img, &my_img_dsc)wheremy_img_dscis a global/staticlv_img_dsc_t.
5. Recommended Workflow
Use official LVGL converter → generate .bin → read file from SD card → assign via lv_img_set_src.
Ensure lv_conf.h includes:
#define LV_COLOR_DEPTH 16
#define LV_COLOR_16_SWAP 1 // Critical for RGB565 on most MCUs
#define LV_IMG_CACHE_DEF_SIZE 1
And when setting source:
lv_img_set_src(img, "S:/45.bin"); // Use path syntax if file system driver registered
Or:
extern const unsigned char my_img_bin[];
lv_img_set_src(img, my_img_bin); // Only works for embedded C arrays
For external .bin files, you must use a file system driver (lv_fs_...) so LVGL can open and stream the image.
Final Recommendations:
- Avoid EZIP unless you’ve added its decoder — stick with official LVGL
.binfor now. - Enable
LV_COLOR_16_SWAP 1inlv_conf.h. - Register a file system driver (e.g., FatFS) so LVGL can directly open
"B:/test.bin". - Verify full file read — print first few bytes of
.binto ensure correct data. - Test with a small known-good image (e.g., 10x10 red square).
With these fixes, RGB565 .bin files should display correctly.
