ESP MMAP ASSETS

[中文]

This module is mainly used to package resources (such as images, fonts, etc.) and map them directly for user access. At the same time, it also integrates rich image preprocessing functions.

Features

Adding Import File Types

Support for various file formats such as .bin, .jpg, .ttf, etc.

Enable Split JPG

Need to use SJPG to parse. Refer to the LVGL SJPG.

Enable Split PNG

Need to use SPNG to parse. See the component esp_lv_decoder.

Set Split Height

Set the split height, depends on MMAP_SUPPORT_SJPG, MMAP_SUPPORT_SPNG or MMAP_SUPPORT_SQOI.

Support QOI

Supports converting images from JPG and PNG formats to QOI.
Supports split qoi, which requires the use of esp_lv_decoder for parsing.

Supporting multiple partitions

The spiffs_create_partition_assets function allows you to mount multiple partitions, each with its own processing logic.

Supporting LVGL Image Converter

By enabling MMAP_SUPPORT_RAW and related configurations, JPG and PNG can be converted to Bin so that they can be used in LVGL.

CMake Options

The following options are supported. These options allow you to configure various aspects of image handling.

set(options
    FLASH_IN_PROJECT,
    FLASH_APPEND_APP,
    MMAP_SUPPORT_SJPG,
    MMAP_SUPPORT_SPNG,
    MMAP_SUPPORT_QOI,
    MMAP_SUPPORT_SQOI,
    MMAP_SUPPORT_RAW,
    MMAP_RAW_DITHER,
    MMAP_RAW_BGR_MODE)

set(one_value_args
    MMAP_FILE_SUPPORT_FORMAT,
    MMAP_SPLIT_HEIGHT,
    MMAP_RAW_FILE_FORMAT)

Option Explanations

General Options

FLASH_IN_PROJECT: Users can opt to have the image automatically flashed together with the app binaries, partition tables, etc. on idf.py flash.

FLASH_APPEND_APP: Enables appending binary data (bin) to the application binary (app_bin).

MMAP_FILE_SUPPORT_FORMAT: Specifies supported file formats (e.g., .png, .jpg, .ttf).

MMAP_SPLIT_HEIGHT: Defines height for image splitting to reduce memory usage. Depends on:

MMAP_SUPPORT_SJPG

MMAP_SUPPORT_SPNG

MMAP_SUPPORT_SQOI

General demo

spiffs_create_partition_assets(
   my_spiffs_partition
   my_folder
   FLASH_IN_PROJECT
   MMAP_FILE_SUPPORT_FORMAT ".jpg,.png,.ttf"
)

Supported Image Formats

MMAP_SUPPORT_SJPG: Enables support for SJPG format.

MMAP_SUPPORT_SPNG: Enables support for SPNG format.

MMAP_SUPPORT_QOI: Enables support for QOI format.

MMAP_SUPPORT_SQOI: Enables support for SQOI format. Depends on:

MMAP_SUPPORT_QOI

Image Splitting Demo

spiffs_create_partition_assets(
   my_spiffs_partition
   my_folder
   FLASH_IN_PROJECT
   MMAP_FILE_SUPPORT_FORMAT ".jpg"
   MMAP_SUPPORT_SJPG
   MMAP_SPLIT_HEIGHT 16
)

LVGL Bin Support

MMAP_SUPPORT_RAW: Converts images to LVGL-supported Binary data.

References:

LVGL v8: Use detailed reference

LVGL v9: Use detailed reference

MMAP_RAW_FILE_FORMAT: Specifies file format for RAW images.

LVGL v8: {true_color, true_color_alpha, true_color_chroma, indexed_1, indexed_2, indexed_4, indexed_8, alpha_1, alpha_2, alpha_4, alpha_8, raw, raw_alpha, raw_chroma}

LVGL v9: Not used.

MMAP_RAW_COLOR_FORMAT: Specifies color format for RAW images.

LVGL v8: {RGB332, RGB565, RGB565SWAP, RGB888}

LVGL v9: {L8, I1, I2, I4, I8, A1, A2, A4, A8, ARGB8888, XRGB8888, RGB565, RGB565A8, ARGB8565, RGB888, AUTO, RAW, RAW_ALPHA}

MMAP_RAW_DITHER: Enables dithering for RAW images.

LVGL v8: Requires dithering.

LVGL v9: Not used.

MMAP_RAW_BGR_MODE: Enables BGR mode for RAW images.

LVGL v8: Not used.

LVGL v9: Not used.

LVGL v9 demo

spiffs_create_partition_assets(
    .........
    MMAP_FILE_SUPPORT_FORMAT ".png"
    MMAP_SUPPORT_RAW
    MMAP_RAW_COLOR_FORMAT "ARGB8888"
)

LVGL v8 demo

spiffs_create_partition_assets(
    .........
    MMAP_FILE_SUPPORT_FORMAT ".png"
    MMAP_SUPPORT_RAW
    MMAP_RAW_FILE_FORMAT "true_color_alpha"
    MMAP_RAW_COLOR_FORMAT "RGB565SWAP"
)

Application Examples

Generate Header(mmap_generate_my_spiffs_partition.h)

This header file is automatically generated and includes essential definitions for memory-mapped assets.

#include "mmap_generate_my_spiffs_partition.h"

#define TOTAL_MMAP_FILES      2
#define MMAP_CHECKSUM         0xB043

enum MMAP_FILES {
   MMAP_JPG_JPG = 0,   /*!< jpg.jpg */
   MMAP_PNG_PNG = 1,   /*!< png.png */
};

Create Assets Handle

The assets config ensures consistency with mmap_generate_my_spiffs_partition.h. It sets the max_files and checksum, verifying the header and memory-mapped binary file.

mmap_assets_handle_t asset_handle;

const mmap_assets_config_t config = {
   .partition_label = "my_spiffs_partition",
   .max_files = MMAP_MY_FOLDER_FILES, //Get it from the compiled .h
   .checksum = MMAP_MY_FOLDER_CHECKSUM, //Get it from the compiled .h
   .flags = {
      .mmap_enable = true,
      .app_bin_check = true,
   }
};

ESP_ERROR_CHECK(mmap_assets_new(&config, &asset_handle));

Assets Usage

You can use the enum defined in mmap_generate_my_spiffs_partition.h to get asset information.

const char *name = mmap_assets_get_name(asset_handle, MMAP_JPG_JPG);
const void *mem = mmap_assets_get_mem(asset_handle, MMAP_JPG_JPG);
int size = mmap_assets_get_size(asset_handle, MMAP_JPG_JPG);
int width = mmap_assets_get_width(asset_handle, MMAP_JPG_JPG);
int height = mmap_assets_get_height(asset_handle, MMAP_JPG_JPG);

ESP_LOGI(TAG, "Name:[%s], Mem:[%p], Size:[%d bytes], Width:[%d px], Height:[%d px]", name, mem, size, width, height);

API Reference

Header File

components/display/tools/esp_mmap_assets/include/esp_mmap_assets.h

Functions

esp_err_t mmap_assets_new(const mmap_assets_config_t *config, mmap_assets_handle_t *ret_item)

Create a new asset instance.

Parameters

config – [in] Pointer to the asset configuration structure.
ret_item – [out] Pointer to the handle of the newly created asset instance.

Returns

ESP_OK: Success
ESP_ERR_NO_MEM: Insufficient memory
ESP_ERR_NOT_FOUND: Can’t find partition
ESP_ERR_INVALID_SIZE: File num mismatch
ESP_ERR_INVALID_CRC: Checksum mismatch

esp_err_t mmap_assets_del(mmap_assets_handle_t handle)

Delete an asset instance.

Parameters

handle – [in] Asset instance handle.

Returns

ESP_OK: Success
ESP_ERR_INVALID_ARG: Invalid argument

const uint8_t *mmap_assets_get_mem(mmap_assets_handle_t handle, int index)

Get the memory of the asset at the specified index.

Parameters

handle – [in] Asset instance handle.
index – [in] Index of the asset.

Returns

Pointer to the asset memory, or NULL if index is invalid.

size_t mmap_assets_copy_mem(mmap_assets_handle_t handle, size_t offset, void *dest_buffer, size_t size)

Copy a portion of an asset’s memory to a destination buffer.

Parameters

handle – [in] Asset instance handle.
offset – [in] Offset within the asset’s memory from which to start copying.
dest_buffer – [out] Pointer to the destination buffer where the memory will be copied.
size – [in] Number of bytes to copy from the asset’s memory to the destination buffer.

Returns

The actual number of bytes copied, or 0 if the operation fails.

const char *mmap_assets_get_name(mmap_assets_handle_t handle, int index)

Get the name of the asset at the specified index.

Parameters

handle – [in] Asset instance handle.
index – [in] Index of the asset.

Returns

Pointer to the asset name, or NULL if index is invalid.

int mmap_assets_get_size(mmap_assets_handle_t handle, int index)

Get the size of the asset at the specified index.

Parameters

handle – [in] Asset instance handle.
index – [in] Index of the asset.

Returns

Size of the asset, or -1 if index is invalid.

int mmap_assets_get_width(mmap_assets_handle_t handle, int index)

Get the width of the asset at the specified index.

Parameters

handle – [in] Asset instance handle.
index – [in] Index of the asset.

Returns

Width of the asset, or -1 if index is invalid.

int mmap_assets_get_height(mmap_assets_handle_t handle, int index)

Get the height of the asset at the specified index.

Parameters

handle – [in] Asset instance handle.
index – [in] Index of the asset.

Returns

Height of the asset, or -1 if index is invalid.

int mmap_assets_get_stored_files(mmap_assets_handle_t handle)

Get the number of stored files in the memory-mapped asset.

This function returns the total number of assets stored in the memory-mapped file associated with the given handle. This can be useful for iterating over all assets or validating the file contents.

Parameters: handle – [in] Asset instance handle. This handle is used to identify the memory-mapped file instance containing the assets.
Returns: The number of stored assets. Returns the total count of assets if the handle is valid, otherwise returns 0.

Structures

struct mmap_assets_config_t

Asset configuration structure, contains the asset table and other configuration information.

Public Members

const char *partition_label: Label of the partition containing the assets

int max_files: Maximum number of assets supported

uint32_t checksum: Checksum of the asset table for integrity verification

unsigned int mmap_enable: Flag to indicate if memory-mapped I/O is enabled

unsigned int app_bin_check: Flag to enable app header and bin file consistency check

unsigned int full_check: Flag to enable self-consistency check

unsigned int metadata_check: Flag to enable metadata verification

unsigned int reserved: Reserved for future use

struct mmap_assets_config_t::[anonymous] flags: Configuration flags

Type Definitions

typedef struct mmap_assets_t *mmap_assets_handle_t

Asset handle type, points to the asset.

Type of asset handle

Provide feedback about this document