Mcommmon API¶
Mcommon
(Mesh common) is a module shared by all ESP-MDF components, and it features the followings:
- Memory Management: manages memory allocation and release, and can help find a memory leak;
- Error Codes: checks the error codes of all the modules, and therefore can help find out what could possibly go wrong;
- Event Loop: uses an identical function for all the modules to deal with an event.
- Data persistence: provide an API to save any type of data on Flash.
Memory Management¶
Header File¶
Functions¶
-
void
mdf_mem_add_record
(void *ptr, int size, const char *tag, int line)¶ Add to memory record.
- Parameters
ptr
: Memory pointersize
: Memory sizetag
: Description tagline
: Line number
-
void
mdf_mem_remove_record
(void *ptr, const char *tag, int line)¶ Remove from memory record.
- Parameters
ptr
: Memory pointertag
: Description tagline
: 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 blocksize
: Block memory size
-
MDF_REALLOC
(ptr, size)¶ Reallocate memory.
- Return
- valid pointer on success
- NULL when any errors
- Parameters
ptr
: Memory pointersize
: 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 pointersize
: Block memory size
-
MDF_FREE
(ptr)¶ Free memory.
- Parameters
ptr
: Memory pointer_cplusplus MDF_MEM_H
Error Codes¶
Header File¶
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 checksesp_err_t
value rather than abool
condition. If the argument ofMDF_ERROR_ASSERT
is not equalMDF_OK
, then an error message is printed on the console, andabort()
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
Event Loop¶
Header File¶
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 filectx
: 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 eventsctx
: 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 eventsctx
: Reserved for userdelay_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 filectx
: Reserved for user
Info Store¶
Header File¶
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 loadvalue
: The corresponding value of keylength
: The length of the value, Pointer type will return length
-
LENGTH_TYPE_POINTER
¶
-
mdf_info_load
(key, value, len)¶