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

Optionally, users can opt to have the image automatically flashed together with the app binaries, partition tables, etc. on idf.py flash by specifying FLASH_IN_PROJECT. For example:

/* partitions.csv
 * -----------------------------------------------------------------------
 * | Name                | Type | SubType | Offset | Size  | Flags     |
 * --------------------------------------------------------
 * | my_spiffs_partition | data | spiffs  |        | 6000K |           |
 * -----------------------------------------------------------------------
 */
 spiffs_create_partition_assets(
     my_spiffs_partition
     my_folder
     FLASH_IN_PROJECT
     MMAP_FILE_SUPPORT_FORMAT ".png")

The component also supports the following options, which allow you to enable various pre-processing of the image at compile time.

set(options FLASH_IN_PROJECT,           // Defines storage type (flash in project)
             MMAP_SUPPORT_SJPG,         // Enable support for SJPG format
             MMAP_SUPPORT_SPNG,         // Enable support for SPNG format
             MMAP_SUPPORT_QOI,          // Enable support for QOI format
             MMAP_SUPPORT_SQOI,         // Enable support for SQOI format
             MMAP_SUPPORT_RAW,          // Enable support for RAW format (LVGL conversion only)
             MMAP_RAW_DITHER,           // Enable dithering for RAW images (LVGL conversion only)
             MMAP_RAW_BGR_MODE)         // Enable BGR mode for RAW images (LVGL conversion only)

 set(one_value_args MMAP_FILE_SUPPORT_FORMAT,    // Specify supported file format (e.g., .png, .jpg)
                MMAP_SPLIT_HEIGHT,               // Define the height for image splitting
                MMAP_RAW_FILE_FORMAT)            // Specify the file format for RAW images (LVGL conversion only)

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 = TOTAL_MMAP_FILES,
   .checksum = MMAP_CHECKSUM,
};

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