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 Handle¶
Header File¶
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 typename
: The name of deviceversion
: 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 characteristicname
: The name of the characteristicformat
: The format of the characteristicperms
: The permissions of the characteristicmin
: The min of the characteristicmax
: The max of the characteristicstep
: 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 devicetype
: Type of datadata
: Requested messagesize
: 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 handlerfunc
: 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
-
const char *
Type Definitions¶
-
typedef mdf_err_t (*
mlink_handle_func_t
)(mlink_handle_data_t *data)¶ Type of request handler.
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¶
Functions¶
-
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 datawait_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 datawait_ticks
: Waiting timeout
Structures¶
-
struct
mlink_httpd_type_t
¶ Http server data type.
-
struct
mlink_httpd_t
¶ Http server data.
Mlink Notice¶
Header File¶
Functions¶
-
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 requestedsize
: Length of the messageaddr
: Address of the device to be requested
Mlink Utils¶
Header File¶
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 macmac_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 macmac_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 formatsta_mac
: Station address in hexadecimal format
- MAC for STA:
-
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 formatsta_mac
: Station address in hexadecimal format
Mlink Json¶
Header File¶
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 parsedkey
: Build value pairsvalue
: You must ensure that the incoming type is consistent with the post-resolution typevalue_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 stringkey
: Build value pairsvalue
: 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 stringkey
: Build value pairsvalue
: The value to be stored
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
-