Fbs API Reference

The esp-dl model utilizes FlatBuffers to store information about parameters and the computation graph. Taking into account the encryption requirements of some models, this part has not been open-sourced. However, we provide a set of APIs to facilitate users in loading and parsing esp-dl models.

Header File

esp-dl/fbs_loader/include/fbs_loader.hpp

Classes

class FbsLoader

Class for parser the flatbuffers.

Public Functions

FbsLoader(const char *rodata_address_or_partition_label_or_path = nullptr, model_location_type_t location = MODEL_LOCATION_IN_FLASH_RODATA)

Construct a new FbsLoader object.

Parameters

rodata_address_or_partition_label_or_path – The address of model data while location is MODEL_LOCATION_IN_FLASH_RODATA. The label of partition while location is MODEL_LOCATION_IN_FLASH_PARTITION. The path of model while location is MODEL_LOCATION_IN_SDCARD.
location – The model location.

~FbsLoader(): Destroy the FbsLoader object.

FbsModel *load(const uint8_t *key = nullptr, bool param_copy = true)

Load the model. If there are multiple sub-models, the first sub-model will be loaded.

Parameters

key – NULL or a 128-bit AES key, like {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f}
param_copy – Set to false to avoid copy model parameters from FLASH to PSRAM. Only set this param to false when your PSRAM resource is very tight. This saves PSRAM and sacrifices the performance of model inference because the frequency of PSRAM is higher than FLASH. Only takes effect when MODEL_LOCATION_IN_FLASH_RODATA(CONFIG_SPIRAM_RODATA not set) or MODEL_LOCATION_IN_FLASH_PARTITION.

Returns

Return nullptr if loading fails. Otherwise return the pointer of FbsModel.

FbsModel *load(const int model_index, const uint8_t *key = nullptr, bool param_copy = true)

Load the model by model index.

Parameters

model_index – The index of model.
key – NULL or a 128-bit AES key, like {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f}.
param_copy – Set to false to avoid copy model parameters from FLASH to PSRAM. Only set this param to false when your PSRAM resource is very tight. This saves PSRAM and sacrifices the performance of model inference because the frequency of PSRAM is higher than FLASH. Only takes effect when MODEL_LOCATION_IN_FLASH_RODATA(CONFIG_SPIRAM_RODATA not set) or MODEL_LOCATION_IN_FLASH_PARTITION.

Returns

Return nullptr if loading fails. Otherwise return the pointer of FbsModel.

FbsModel *load(const char *model_name, const uint8_t *key = nullptr, bool param_copy = true)

Load the model by model name.

Parameters

model_name – The name of model.
key – NULL or a 128-bit AES key, like {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f}
param_copy – Set to false to avoid copy model parameters from FLASH to PSRAM. Only set this param to false when your PSRAM resource is very tight. This saves PSRAM and sacrifices the performance of model inference because the frequency of PSRAM is higher than FLASH. Only takes effect when MODEL_LOCATION_IN_FLASH_RODATA(CONFIG_SPIRAM_RODATA not set) or MODEL_LOCATION_IN_FLASH_PARTITION.

Returns

Return nullptr if loading fails. Otherwise return the pointer of FbsModel.

int get_model_num()

Get the number of models.

Returns: The number of models

void list_models(): List all model’s name.

const char *get_model_location_string()

Get the model location string.

Returns: The model location string.

Header File

esp-dl/fbs_loader/include/fbs_model.hpp

Classes

class FbsModel

Flatbuffer model object.

Public Functions

FbsModel(const void *data, size_t size, model_location_type_t location, bool encrypt, bool rodata_move, bool auto_free, bool param_copy)

Construct a new FbsModel object.

Parameters

data – The data of model flatbuffers.
size – The size of model flatbuffers in bytes.
location – The location of model flatbuffers.
encrypt – Whether the model flatbuffers is encrypted or not.
rodata_move – Whether the model flatbuffers is moved from FLASH rodata to PSRAM.
auto_free – Whether to free the model flatbuffers data when destroy this class instance.
param_copy – Whether to copy the parameter in flatbuffers.

~FbsModel(): Destroy the FbsModel object.

void print(): Print the model information.

std::vector<std::string> topological_sort()

Return vector of node name in the order of execution.

Returns: topological sort of node name.

esp_err_t get_operation_attribute(std::string node_name, std::string attribute_name, int &ret_value)

Get the attribute of node.

Parameters

node_name – The name of operation.
attribute_name – The name of attribute.
ret_value – The attribute value.

Returns