ESP MMAP ASSETS

[中文]

This module is primarily used for packaging assets (such as images, fonts, etc.) and directly mapping them for user access.

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. Refer to the component esp_lv_spng.

Set Split Height

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

CMake

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)

Application Examples

Generate Header(assets_generate.h)

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

#include "esp_mmap_assets.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 assets_generate.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 assets_generate.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

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.

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.

Structures

struct mmap_assets_config_t

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

Public Members

const char *partition_label

Configuration partition_label

int max_files

Number of assets

uint32_t checksum

Checksum of table

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