Mlink API¶

Mlink (MESH LAN communication protocol) is a solution for controlling ESP-WIFI-MESH network devices through APP, including: device discovery, control, upgrade, etc.

Application Examples¶

For Mlink examples, please refer to the directory development_kit, which includes:

Smart light: Mesh App can control the color of the lamp, distribution network, upgrade, etc.

Mlink¶

Header File¶

mlink/include/mlink.h

Macros¶

MDF_EVENT_MLINK_SYSTEM_RESET¶: < _cplusplus

MDF_EVENT_MLINK_SYSTEM_REBOOT¶

MDF_EVENT_MLINK_SET_STATUS¶

MDF_EVENT_MLINK_GET_STATUS¶

MDF_EVENT_MLINK_SET_TRIGGER¶

MDF_EVENT_MLINK_BUFFER_FULL¶

Enumerations¶

enum mlink_protocol¶

Type of protocol.

Values:

MLINK_PROTO_HTTPD = 0¶: Http protocol communication

MLINK_PROTO_NOTICE = 1¶: UDP protocol communication

Mlink Handle¶

Header File¶

mlink/include/mlink_handle.h

Functions¶

mdf_err_t mlink_add_device(uint32_t tid, const char *name, const char *version)¶

Configuring basic information about the device.

Return

ESP_OK
ESP_FAIL

Parameters

tid: Unique identifier for the device type
name: The name of device
version: The version of device

mdf_err_t mlink_device_set_name(const char *name)¶

Set device name.

Return

ESP_OK
ESP_FAIL

Parameters

name: The name of device

mdf_err_t mlink_device_set_position(const char *position)¶

Set device version.

Return

ESP_OK
ESP_FAIL

Parameters

position: The position of device

const char *mlink_device_get_name()¶

Get device name.

Return: Name of the device

const char *mlink_device_get_position()¶

Get device version.

Return: Version of the device

int mlink_device_get_tid()¶

Get device tid.

Return: Unique identifier for the device type

mdf_err_t mlink_add_characteristic(uint16_t cid, const char *name, characteristic_format_t format, characteristic_perms_t perms, int min, int max, uint16_t step)¶

Add device characteristic information.

Return

ESP_OK
ESP_FAIL

Parameters

cid: Unique identifier for the characteristic
name: The name of the characteristic
format: The format of the characteristic
perms: The permissions of the characteristic
min: The min of the characteristic
max: The max of the characteristic
step: The step of the characteristic

mdf_err_t mlink_add_characteristic_handle(mlink_characteristic_func_t get_value_func, mlink_characteristic_func_t set_value_func)¶

Increase the device’s characteristic handler.

Return

ESP_OK
ESP_FAIL

Parameters

get_value_func: [description]
set_value_func: [description]

mdf_err_t mlink_handle(const uint8_t *src_addr, const mlink_httpd_type_t *type, const void *data, size_t size)¶

Handling requests from the APP.

Note

This function is deprecated. Use ‘mlink_handle_request’ function

Return

ESP_OK
ESP_FAIL

Parameters

src_addr: Source address of the device
type: Type of data
data: Requested message
size: The length of the requested data

mdf_err_t mlink_set_handle(const char *name, const mlink_handle_func_t func)¶

Add or modify a request handler.

Return

ESP_OK
ESP_FAIL

Parameters

name: The name of the handler
func: The pointer of the handler

mdf_err_t mlink_handle_request(mlink_handle_data_t *handle_data)¶

Call the handler in the request list.

Return

ESP_OK
ESP_FAIL
MDF_ERR_NOT_SUPPORTED_cplusplus MLINK_HANDLE_H

Parameters

handle_data: The data type of the parameter of the handler

Structures¶

struct mlink_handle_data_t¶

The data type of the parameter of the handler.

Public Members

const char *req_data¶: Received request data

ssize_t req_size¶: The length of the received request data

mlink_httpd_format_t req_fromat¶: The format of the received request data

char *resp_data¶: Response data to be sent

ssize_t resp_size¶: The length of response data to be sent

mlink_httpd_format_t resp_fromat¶: The format of response data to be sent

Type Definitions¶

typedef mdf_err_t (*mlink_handle_func_t)(mlink_handle_data_t *data)¶: Type of request handler.

typedef mdf_err_t (*mlink_characteristic_func_t)(uint16_t cid, void *value)¶: Get the type of callback function that sets the characteristic value.

Enumerations¶

enum characteristic_perms_t¶

Permissions for the characteristics.

< _cplusplus

Values:

CHARACTERISTIC_PERMS_READ = 1 << 0¶: The characteristic of the device are readable

CHARACTERISTIC_PERMS_WRITE = 1 << 1¶: The characteristic of the device are writable

CHARACTERISTIC_PERMS_TRIGGER = 1 << 2¶: The characteristic of the device can be triggered

CHARACTERISTIC_PERMS_RW = CHARACTERISTIC_PERMS_READ | CHARACTERISTIC_PERMS_WRITE¶: The characteristic of the device are readable & writable

CHARACTERISTIC_PERMS_RT = CHARACTERISTIC_PERMS_READ | CHARACTERISTIC_PERMS_TRIGGER¶: The characteristic of the device are readable & triggered

CHARACTERISTIC_PERMS_WT = CHARACTERISTIC_PERMS_WRITE | CHARACTERISTIC_PERMS_TRIGGER¶: The characteristic of the device are writable & triggered

CHARACTERISTIC_PERMS_RWT = CHARACTERISTIC_PERMS_RW | CHARACTERISTIC_PERMS_TRIGGER¶: The characteristic of the device are readable & writable & triggered

enum characteristic_format_t¶

Format for the characteristic.

Values:

CHARACTERISTIC_FORMAT_NONE¶: Invalid format

CHARACTERISTIC_FORMAT_INT¶: characteristic is a number format

CHARACTERISTIC_FORMAT_DOUBLE¶: characteristic is a double format

CHARACTERISTIC_FORMAT_STRING¶: characteristic is a string format

Mlink Httpd¶

Header File¶

mlink/include/mlink_httpd.h

Functions¶

mdf_err_t mlink_httpd_start(void)¶

Start http server.

Return

ESP_OK
ESP_FAIL

mdf_err_t mlink_httpd_stop(void)¶

Stop http server.

Return

ESP_OK
ESP_FAIL

mdf_err_t mlink_httpd_read(mlink_httpd_t **request, TickType_t wait_ticks)¶

Receive data from http server.

Return

ESP_OK
ESP_FAIL

Parameters

request: Request data
wait_ticks: Waiting timeout

mdf_err_t mlink_httpd_write(const mlink_httpd_t *response, TickType_t wait_ticks)¶

Send data to http server.

Return

ESP_OK
ESP_FAIL_cplusplus MLINK_HTTPD_H

Parameters

response: Response data
wait_ticks: Waiting timeout

Structures¶

struct mlink_httpd_type_t¶

Http server data type.

Public Members

uint16_t sockfd¶: File descriptor for tcp

uint8_t format¶: Http body data format

uint8_t from¶: Data request source

bool resp¶: Whether to respond to request data

uint16_t received¶: Received

struct mlink_httpd_t¶

Http server data.

Public Members

mlink_httpd_type_t type¶: Http server data type

bool group¶: Send a package as a group

size_t addrs_num¶: Number of addresses

uint8_t *addrs_list¶: List of addresses

size_t size¶: Length of data

char *data¶: Pointer of Data

Enumerations¶

enum mlink_httpd_from_t¶

Data request source.

< _cplusplus

Values:

MLINK_HTTPD_FROM_DEVICE = 1¶: Request from within the ESP-WIFI-MESH network

MLINK_HTTPD_FROM_SERVER = 2¶: Request from server

enum mlink_httpd_format_t¶

Http body data format.

Values:

MLINK_HTTPD_FORMAT_NONE¶: Invalid format

MLINK_HTTPD_FORMAT_HEX¶: data is a hex format

MLINK_HTTPD_FORMAT_JSON¶: data is a json format

MLINK_HTTPD_FORMAT_HTML¶: data is a html format

Mlink Notice¶

Header File¶

mlink/include/mlink_notice.h

Functions¶

mdf_err_t mlink_notice_init()¶

Initialize mlink mdns and udp.

< _cplusplus

Return

MDF_OK
MDF_FAIL

mdf_err_t mlink_notice_deinit()¶

Deinitialize mlink mdns and udp.

Return

MDF_OK
MDF_FAIL

mdf_err_t mlink_notice_write(const char *message, size_t size, const uint8_t *addr)¶

Inform Mesh-App to initiate a request.

Return

MDF_OK
MDF_ERR_INVALID_ARG
MDF_FAIL_cplusplus MLINK_NOTICE_H

Parameters

message: Type of message requested
size: Length of the message
addr: Address of the device to be requested

Mlink Utils¶

Header File¶

mlink/include/mlink_utils.h

Functions¶

uint8_t *mlink_mac_str2hex(const char *mac_str, uint8_t *mac_hex)¶

Convert mac from string format to hex.

< _cplusplus

Return

MDF_OK
MDF_ERR_INVALID_ARG
MDF_FAIL

Parameters

mac_str: String format mac
mac_hex: Hex format mac

char *mlink_mac_hex2str(const uint8_t *mac_hex, char *mac_str)¶

Convert mac from hex format to string.

Return

MDF_OK
MDF_ERR_INVALID_ARG
MDF_FAIL

Parameters

mac_hex: Hex format mac
mac_str: String format mac

uint8_t *mlink_mac_ap2sta(const uint8_t *ap_mac, uint8_t *sta_mac)¶

Convert mac address from ap to sta.

Each ESP32 chip has MAC addresses for Station (STA), Access Point (AP), Bluetooth low energy (BT) and Local Area Network (LAN). Their address values are incremented by one, i.e. LAN Mac = BT Mac + 1 = AP Mac + 2 = STA Mac + 3.

For example:

MAC for STA: xx:xx:xx:xx:xx:00
MAC for AP : xx:xx:xx:xx:xx:01
MAC for BT : xx:xx:xx:xx:xx:02
MAC for LAN: xx:xx:xx:xx:xx:03

The device’s STA address is used For ESP-WIFI-MESH communication.

Return

MDF_OK
MDF_ERR_INVALID_ARG
MDF_FAIL

Parameters

ap_mac: Access Point address in hexadecimal format
sta_mac: Station address in hexadecimal format

uint8_t *mlink_mac_bt2sta(const uint8_t *bt_mac, uint8_t *sta_mac)¶

Convert mac address from bt to sta.

Return

MDF_OK
MDF_ERR_INVALID_ARG
MDF_FAIL_cplusplus MLINK_UTILS_H

Parameters

bt_mac: Access Point address in hexadecimal format
sta_mac: Station address in hexadecimal format

Mlink Json¶

Header File¶

mlink/include/mlink_json.h

Functions¶

esp_err_t __mlink_json_parse(const char *json_str, const char *key, void *value, int value_type)¶

esp_err_t mlink_json_parse( const char *json_str, const char *key, void *value) Parse the json formatted string

Note

does not support the analysis of array types

Return

ESP_OK
ESP_FAIL

Parameters

json_str: The string pointer to be parsed
key: Build value pairs
value: You must ensure that the incoming type is consistent with the post-resolution type
value_type: Type of parameter

esp_err_t __mlink_json_pack(char **json_str, const char *key, int value, int value_type)¶

mlink_json_pack(char *json_str, const char *key, int/double/char value); Create a json string

Note

if the value is double or float type only retains the integer part, requires complete data calling mlink_json_pack_double()

Return

lenght: generates the length of the json string
ESP_FAIL

Parameters

json_str: Save the generated json string
key: Build value pairs
value: This is a generic, support long / int / float / char / char* / char []
value_type: Type of parameter

ssize_t mlink_json_pack_double(char **json_ptr, const char *key, double value)¶

Create a double type json string, Make up for the lack of mdf_json_pack()

Return

lenght: generates the length of the json string
ESP_FAIL_cplusplus MLINK_JOSN_H

Parameters

json_ptr: Save the generated json string
key: Build value pairs
value: The value to be stored

Macros¶

mlink_json_parse(json_str, key, value)¶

mlink_json_pack(json_str, key, value)¶

Enumerations¶

enum mlink_json_type¶

The type of the parameter.

< _cplusplus

Values:

MLINK_JSON_TYPE_NONE = 0¶: Invalid parameter type

MLINK_JSON_TYPE_INT8 = 1¶: The type of the parameter is int8_t / uint8_t

MLINK_JSON_TYPE_INT16 = 10¶: The type of the parameter is int16_t / uint16_t

MLINK_JSON_TYPE_INT32 = 100¶: The type of the parameter is int32_t / uint32_t

MLINK_JSON_TYPE_FLOAT = 1000¶: The type of the parameter is float

MLINK_JSON_TYPE_DOUBLE = 10000¶: The type of the parameter is double

MLINK_JSON_TYPE_STRING = 100000¶: The type of the parameter is string

MLINK_JSON_TYPE_POINTER = 1000000¶: The type of the parameter is point