Mcommmon API

Mcommon (Mesh common) is a module shared by all ESP-MDF components, and it features the followings:

1. Memory Management: manages memory allocation and release, and can help find a memory leak;
2. Error Codes: checks the error codes of all the modules, and therefore can help find out what could possibly go wrong;
3. Event Loop: uses an identical function for all the modules to deal with an event.
4. Data persistence: provide an API to save any type of data on Flash.

Memory Management

Header File

• mcommon/include/mdf_mem.h

Functions

void mdf_mem_add_record(void *ptr, int size, const char *tag, int line)

Add to memory record.

Parameters

• ptr: Memory pointer
• size: Memory size
• tag: Description tag
• line: Line number

void mdf_mem_remove_record(void *ptr, const char *tag, int line)

Remove from memory record.

Parameters

• ptr: Memory pointer
• tag: Description tag
• line: Line number

void mdf_mem_print_record(void)

Print the all allocation but not released memory.

Attention

Must configure CONFIG_MDF_MEM_DEBUG == y annd esp_log_level_set(mdf_mem, ESP_LOG_INFO);

void mdf_mem_print_heap(void)

Print memory and free space on the stack.

void mdf_mem_print_task(void)

Print the state of tasks in the system.

Macros

MDF_MEM_DEBUG

< _cplusplus CONFIG_MDF_MEM_DEBUG

CONFIG_MDF_MEM_DBG_INFO_MAX

CONFIG_MDF_MEM_DBG_INFO_MAX

MDF_MEM_DBG_INFO_MAX

MALLOC_CAP_INDICATE

MDF_MALLOC(size)

Malloc memory.

Return

• valid pointer on success
• NULL when any errors

Parameters

• size: Memory size

MDF_CALLOC(n, size)

Calloc memory.

Return

• valid pointer on success
• NULL when any errors

Parameters

• n: Number of block
• size: Block memory size

MDF_REALLOC(ptr, size)

Reallocate memory.

Return

• valid pointer on success
• NULL when any errors

Parameters

• ptr: Memory pointer
• size: Block memory size

MDF_REALLOC_RETRY(ptr, size)

Reallocate memory, If it fails, it will retry until it succeeds.

Return

• valid pointer on success
• NULL when any errors

Parameters

• ptr: Memory pointer
• size: Block memory size

MDF_FREE(ptr)

Free memory.

Parameters

• ptr: Memory pointer_cplusplus MDF_MEM_H

Error Codes

Header File

• mcommon/include/mdf_err.h

Functions

const char *mdf_err_to_name(mdf_err_t code)

Returns string for mdf_err_t error codes.

This function finds the error code in a pre-generated lookup-table and returns its string representation.

The function is generated by the Python script tools/gen_mdf_err_to_name.py which should be run each time an mdf_err_t error is modified, created or removed from the IDF project.

Return

string error message

Parameters

• code: mdf_err_t error code

Macros

MDF_OK

mdf_err_t value indicating success (no error)

MDF_FAIL

Generic mdf_err_t code indicating failure

MDF_ERR_NO_MEM

Out of memory

MDF_ERR_INVALID_ARG

Invalid argument

MDF_ERR_INVALID_STATE

Invalid state

MDF_ERR_INVALID_SIZE

Invalid size

MDF_ERR_NOT_FOUND

Requested resource not found

MDF_ERR_NOT_SUPPORTED

Operation or feature not supported

MDF_ERR_TIMEOUT

Operation timed out

MDF_ERR_INVALID_RESPONSE

Received response was invalid

MDF_ERR_INVALID_CRC

CRC or checksum was invalid

MDF_ERR_INVALID_VERSION

Version was invalid

MDF_ERR_INVALID_MAC

MAC address was invalid

MDF_ERR_NOT_INIT

MAC address was invalid

MDF_ERR_BUF

The buffer is too small

MDF_ERR_MWIFI_BASE

Starting number of MWIFI error codes

MDF_ERR_MESPNOW_BASE

Starting number of MESPNOW error codes

MDF_ERR_MCONFIG_BASE

Starting number of MCONFIG error codes

MDF_ERR_MUPGRADE_BASE

Starting number of MUPGRADE error codes

MDF_ERR_MDEBUG_BASE

Starting number of MDEBUG error codes

MDF_ERR_MLINK_BASE

Starting number of MLINK error codes

MDF_ERR_CUSTOM_BASE

Starting number of COUSTOM error codes

CONFIG_MDF_LOG_LEVEL

CONFIG_MDF_LOG_LEVEL

MDF_LOG_LEVEL

MDF_LOG_FORMAT(letter, format)

MDF_LOGE(format, ...)

MDF_LOGW(format, ...)

MDF_LOGI(format, ...)

MDF_LOGD(format, ...)

MDF_LOGV(format, ...)

MDF_ERROR_CHECK(con, err, format, ...)

Macro which can be used to check the error code, and terminate the program in case the code is not MDF_OK. Prints the error code, error location, and the failed statement to serial output.

Disabled if assertions are disabled.

MDF_ERROR_ASSERT(err)

Macro serves similar purpose as assert, except that it checks esp_err_t value rather than a bool condition. If the argument of MDF_ERROR_ASSERT is not equal MDF_OK, then an error message is printed on the console, and abort() is called.

Note

If IDF monitor is used, addresses in the backtrace will be converted to file names and line numbers.

Return

[description]

Parameters

• err: [description]

MDF_ERROR_GOTO(con, lable, format, ...)

MDF_ERROR_CONTINUE(con, format, ...)

MDF_ERROR_BREAK(con, format, ...)

MDF_PARAM_CHECK(con)

_cplusplus MDF_ERR_H

Type Definitions

typedef int mdf_err_t

< _cplusplus

Event Loop

Header File

• mcommon/include/mdf_event_loop.h

Functions

mdf_err_t mdf_event_loop_init(mdf_event_loop_cb_t cb)

Initialize event loop, create the event handler and task.

Attention

Because all the callbacks are dispatched from the same task, it is recommended to only do the minimal possible amount of work from the callback itself, posting an event to a lower priority task using a queue instead.

Return

• MDF_OK
• MDF_FAIL

Parameters

• cb: Application specified event callback, it can be modified by call mdf_event_loop_set

mdf_err_t mdf_event_loop_deinit()

Deinitialize event loop, delete the event handler and task.

Return

• MDF_OK
• MDF_FAIL

mdf_err_t mdf_event_loop(mdf_event_loop_t event, void *ctx)

Call event callback function directly.

Return

• MDF_OK
• MDF_FAIL

Parameters

• event: Event type defined in this file
• ctx: Reserved for user

mdf_event_loop_cb_t mdf_event_loop_set(mdf_event_loop_cb_t cb)

Set event loop callback function.

Return

• MDF_OK
• MDF_FAIL

Parameters

• cb: Set application event callback

mdf_err_t mdf_event_loop_send(mdf_event_loop_t event, void *ctx)

Send the event to the event handler.

Return

• MDF_OK
• MDF_FAIL

Parameters

• event: Generated events
• ctx: Reserved for user

mdf_err_t mdf_event_loop_delay_send(mdf_event_loop_t event, void *ctx, TickType_t delay_ticks)

Delay send the event to the event handler.

Return

• MDF_OK
• MDF_FAIL

Parameters

• event: Generated events
• ctx: Reserved for user
• delay_ticks: Delay time

Macros

CONFIG_EVENT_QUEUE_NUM

CONFIG_EVENT_QUEUE_NUM

EVENT_QUEUE_NUM

CONFIG_MDF_EVENT_TASK_NAME

CONFIG_MDF_EVENT_TASK_NAME

MDF_EVENT_TASK_NAME

CONFIG_MDF_EVENT_TASK_STACK_SIZE

CONFIG_MDF_EVENT_TASK_STACK

MDF_EVENT_TASK_STACK

CONFIG_MDF_EVENT_TASK_PRIOTY

CONFIG_MDF_EVENT_TASK_PRIOTY

MDF_EVENT_TASK_PRIOTY

MDF_EVENT_MWIFI_BASE

MDF_EVENT_MESPNOW_BASE

MDF_EVENT_MCONFIG_BASE

MDF_EVENT_MUPGRADE_BASE

MDF_EVENT_MDEBUG_BASE

MDF_EVENT_MLINK_BASE

MDF_EVENT_CUSTOM_BASE

Type Definitions

typedef uint32_t mdf_event_loop_t

typedef mdf_err_t (*mdf_event_loop_cb_t)(mdf_event_loop_t event, void *ctx)

Application specified event callback function.

Return

• MDF_OK
• MDF_FAIL

Parameters

• event: Event type defined in this file
• ctx: Reserved for user

Info Store

Header File

• mcommon/include/mdf_info_store.h

Functions

esp_err_t mdf_info_init(void)

Initialize the default NVS partition.

Return

• ESP_FAIL
• ESP_OK

esp_err_t mdf_info_save(const char *key, const void *value, size_t length)

save the information with given key

Return

• ESP_FAIL
• ESP_OK

Parameters

• key: Key name. Maximal length is 15 characters. Shouldn’t be empty.
• value: The value to set.
• length: length of binary value to set, in bytes; Maximum length is 1984 bytes (508000 bytes or (97.6% of the partition size - 4000) bytes whichever is lower, in case multi-page blob support is enabled).

esp_err_t __mdf_info_load(const char *key, void *value, size_t len, uint32_t type)

esp_err_t mdf_info_erase(const char *key)

Macros

MDF_SPACE_NAME

LENGTH_TYPE_NUMBER

Load the information, esp_err_t mdf_info_load(const char *key, void *value, size_t *length); esp_err_t mdf_info_load(const char *key, void *value, size_t length);.

Attention

The interface of this api supports size_t and size_t * types. When the length parameter of the pass is size_t, it is only the length of the value. When the length parameter of the pass is size_t *, the length of the saved information can be obtained.

Return

• ESP_FAIL
• ESP_OK

Parameters

• key: The corresponding key of the information that want to load
• value: The corresponding value of key
• length: The length of the value, Pointer type will return length

LENGTH_TYPE_POINTER

mdf_info_load(key, value, len)