# 红外遥控类设备MSDK 应用接口说明

本文档针对红外遥控类设备MSDK的应用开发接口进行说明，包括应用接口定义和使用说明，适用于基于MSDK进行开发和测试的相关人员。

# 数据类型说明

本章将介绍接口所涉及到的数据类型。

# 1. 枚举

枚举类型包括ms_sdk_result_t、ms_sdk_msg_t和ms_sdk_errcode_t。

# 1.1 ms_sdk_result_t

该枚举定义了MSDK的返回值类型，具体如下：

typedef enum

{

MS_SDK_SUCCESS = 0x00, //成功

MS_SDK_INIT_FAIL = 0x01, //初始化失败

MS_SDK_DEINIT_FAIL = 0x02, //反初始化失败

MS_SDK_LOGOUT = 0x03, //设备离线

MS_SDK_INVALID_PARAM = 0x04, //无效入参

MS_SDK_NO_MEM = 0x05, //内存不足

MS_SDK_SEND_FAIL = 0x06, //发送失败

MS_SDK_UNBIND = 0x07, //未绑定

MS_SDK_RESET_FAIL = 0x08, //重置失败

MS_SDK_REBOOT_FAIL = 0x08, //重启失败

} ms_sdk_result_t;

# 1.2 ms_sdk_msg_t

该枚举定义了MSDK的消息类型，具体如下：

typedef enum

{

MS_SDK_MSG_CONNECTING = 0x01, //联网中

MS_SDK_MSG_LOGIN_SUCCESSFUL = 0x02, //登录IoT云端成功

MS_SDK_MSG_LOGOUT = 0x03, //设备从IoT云端离线

MS_SDK_MSG_STATUS_UNBIND = 0x04, //设备未绑定

MS_SDK_MSG_STATUS_BIND = 0x05, //设备已绑定

MS_SDK_MSG_STATUS_AUTH = 0x06, //确权

MS_SDK_MSG_CMD_ACK = 0x07, //串口指令回复

MS_SDK_MSG_CMD_SEND = 0x08, //发送/回复串口指令

MS_SDK_MSG_NEED_UPGRADE = 0x09, //有固件可升级

MS_SDK_MSG_TRANS_FIRMWARE = 0x0A, //传输电控固件

} ms_sdk_msg_t;

# 2. 结构体

目前定义的结构体为ms_sdk_data_frame_t。

# 2.1 ms_sdk_data_frame_t

该结构体定义了应用需要MSDK发送数据或者MSDK接收数据后传递给应用时的内容格式，具体定义如下：

typedef struct ms_sdk_data_frame

{

uint8_t sub_devId[6]; //小端模式。子设备美的标识，非0代表子设备

uint16_t cmd; //通用命令标识，如0x00D0、0x80D0等

uint16_t subcmd; //子命令标识

uint8_t version; //协议版本号

uint8_t need_reply; //是否需要回复。0：不需要；1：需要

uint8_t *data; //发送或者接收数据的内容

uint16_t size; //发送或者接收数据的长度，最大不超过60000字节

}ms_sdk_data_frame_t;

# 3. 接口概述

# 3.1 头文件

应用需要包含头文件“ms_sdk.h”，才可以正常调用所有接口。

# 3.2 接口列表

本文涉及的接口如下表1所示：

序号	接口名称	接口含义	调用方向	参考章节
1	ms_sdk_event_cb	事件的回调	SDK ->应用	4.2
2	ms_sdk_data_recv_cb	数据接收的回调	SDK ->应用	4.3
3	ms_sdk_init	MSDK初始化	应用-> SDK	4.4
4	ms_sdk_deinit	MSDK反初始化	应用-> SDK	4.5
5	ms_sdk_send_data	数据发送	应用-> SDK	4.6
7	ms_sdk_reboot	MSDK重启	应用-> SDK	4.7
8	ms_sdk_reset	MSDK重置	应用-> SDK	4.8
9	ms_sdk_cmd_process	MSDK处理串口指令	应用-> SDK	4.9

各接口原型如下：

1）int ms_sdk_event_cb(ms_sdk_msg_t message, uint8_t *data, uint16_t data_len)

2）int ms_sdk_data_recv_cb(ms_sdk_data_frame_t *p_frame, uint32_t msgId)

3）ms_sdk_result_t ms_sdk_init(ms_sdk_event_cb event_cb, ms_sdk_data_recv_cb recv_cb)

4）ms_sdk_result_t ms_sdk_deinit(void)

5）ms_sdk_result_t ms_sdk_send_data(uint8_t responseFlag, ms_sdk_data_frame_t *pFrame, uint32_t *msgId)

6）ms_sdk_result_t ms_sdk_reboot(void)

7）ms_sdk_result_t ms_sdk_reset(void)

8）ms_sdk_result_t ms_sdk_auth_privilege(void)

9）ms_sdk_result_t ms_sdk_cmd_process(uint8_t* indata, uint16_t indata_len, uint8_t* outdata, uint32_t* outdata_len)

后续章节将会对每个接口进行详细的描述。

# 3.3 线程安全

本文中的所有接口是线程安全的，注意需要在SDK初始化后才能调用。

# 4. ms_sdk_event_cb

接口原型	int ms_sdk_event_cb(ms_sdk_msg_t message, uint8_t *data, uint16_t data_len)
功能说明	MSDK事件回调处理
返回值	应用自行定义各种返回值
输入参数	备注：该接口内的所有指针变量由MSDK申请和释放（回调返回后释放）
message	3.1.2节中定义的各类消息，具体含义参考4.2.1-4.2.5中对各事件的说明
data	回调输入的数据。该地址由MSDK申请和释放（回调接口返回后释放）
data_len	回调输入的数据长度，单位为字节

应用在初始化MSDK时需要设置该回调接口。

下面将分别描述在该回调接口里需要处理的7个事件。

# 4.1 MS_SDK_MSG_WAIT_CONNECT

此事件代表MSDK正处于待配网状态。

MSDK通过回调触发此事件时，入参如下：

message	MS_SDK_MSG_WAIT_CONNECT
data	NULL
data_len	0

# 4.2 MS_SDK_MSG_CONNECTING

此事件代表MSDK正在联网。

MSDK通过回调触发此事件时，入参如下：

message	MS_SDK_MSG_CONNECTING
data	NULL
data_len	0

此事件代表MSDK登录美的IoT云端成功，且每次登录成功都会触发此事件。如果设备的状态为已绑定，则收到此事件时说明数据通道可正常使用。

MSDK通过回调触发此事件时，入参如下：

message	MS_SDK_MSG_LOGIN_SUCCESSFUL
data	设备的美的标识（devId），小端模式
data_len	6

应用收到此事件1分钟后进行发送一次0x90-0x07指令触发电控升级检测，之后每12小时检测一次。

# 4.4 MS_SDK_MSG_LOGOUT

此事件代表设备从美的IoT云端离线，从在线变为离线时会触发此事件。此时数据收发通道不可用。

MSDK通过回调触发此事件时，入参如下：

message	MS_SDK_MSG_LOGOUT
data	NULL
data_len	0

# 4.5 MS_SDK_MSG_STATUS_BIND

此事件代表设备在美的IoT云端上的状态为已绑定，在设备发起绑定请求并成功绑定后会触发此事件（重复登录时不会触发）。此状态下可以正常收发数据。

MSDK通过回调触发此事件时，入参如下：

message	MS_SDK_MSG_STATUS_BIND
data	NULL
data_len	0

应用收到此事件后需要进行状态保存，以便后续MSDK重新登录成功后（MSDK会触发MS_SDK_MSG_LOGIN_SUCCESSFUL事件回调，参考4.2.2节）用于判断是否可以正常收发数据。

# 4.6 MS_SDK_MSG_STATUS_UNBIND

此事件代表设备在美的IoT云端上的状态为未绑定，在操作设备解绑后或者发起绑定请求但绑定失败时会触发此事件。此时MSDK会清除除了设备基础身份信息以外的其他入网参数、从IoT云端主动离线，数据通道不可用。应用收到此事件后需要进行状态保存。

MSDK通过回调触发此事件时，入参如下：

message	MS_SDK_MSG_STATUS_UNBIND
data	NULL
data_len	0

# 4.7 MS_SDK_MSG_STATUS_AUTH

模组进入待确权、待确权超时或确权成功时会触发此事件。

MSDK通过回调触发此事件时，入参如下：

message	MS_SDK_MSG_STATUS_AUTH
data	完整的0E串口指令消息体，确权状态：0x00:确权成功，0x01:进入待确权，0x02:待确权超时
data_len	消息体长度

应用收到此事件进入待确权状态后，按按键进行确权并发送0x64指令给MSDK，MSDK串口指令封装参照《家电端通信协议（基础功能版本）20241012.pdf》。

# 4.8 MS_SDK_MSG_CMD_SEND

MSDK回复应用的串口指令或直接向应用发送串口指令时会触发此事件，串口指令封装参照《家电端通信协议（基础功能版本）20241012.pdf》。

MSDK通过回调触发此事件时，入参如下：

message	MS_SDK_MSG_STATUS_UNBIND
data	NULL
data_len	0

串口指令封装参照《家电端通信协议（基础功能版本）20241012.pdf》。

# 4.9 MS_SDK_MSG_NEED_UPGRADE

MSDK有电控固件可升级时会触发此事件.

MSDK通过回调触发此事件时，入参如下：

message	MS_SDK_MSG_NEED_UPGRADE
data	NULL
data_len	0

# 4.10 MS_SDK_MSG_TRANS_FIRMWARE

此事件代表电控OTA固件传输。

MSDK通过回调触发此事件时，入参如下：

message	MS_SDK_MSG_TRANS_FIRMWARE
data	帧数据
data_len	帧长度

应用收到此事件存储数据帧内容，并在传输完成后向MSDK发送0x90-0x04电控指令，通知模组下载成功。串口指令封装参照《家电端通信协议（基础功能版本）20241012.pdf》

# 5. ms_sdk_data_recv_cb

接口原型	int ms_sdk_data_recv_cb(ms_sdk_data_frame_t *pFrame, uint32_t msgId)
功能说明	MSDK接收数据的回调处理
返回值	应用自行定义各种返回值
输入参数	备注：该接口内的所有指针变量由MSDK申请和释放（回调返回后释放）
pPrame	接收数据的内容，具体参考3.2.1节定义
msgId	接收数据的消息Id

MSDK接收到云端下发的数据后会触发该回调接口。应用在该接口里需要根据pFrame里的各项参数进行处理，而且要根据msgId来匹配是否为之前某个请求消息的回复。

关于pFrame里cmd、sub_cmd、version、need_reply、data这些字段的解析规则，请参考IoT云端提供的相应说明文档。

# 6. ms_sdk_init

接口原型	ms_sdk_result_t ms_sdk_init(ms_sdk_event_cb event_cb, ms_sdk_data_recv_cb recv_cb)
功能说明	初始化MSDK，会创建MSDK线程
返回值
MS_SDK_SUCCESS	初始化成功
MS_SDK_INIT_FAIL	初始化失败
输入参数
event_cb	事件回调处理，定义参考4.2节
recv_cb	接收数据回调处理，定义参考4.3节

应用在启用MSDK功能前需要进行该接口调用，并传入对应的回调函数。如果初始化失败则MSDK功能不可用。MSDK内部会自行启动登录IoT云端，无须应用额外干预。初始化成功后，不管登录成功还是失败，都会通过ms_sdk_event_cb回调接口将对应事件进行回调，应用在回调里根据4.2中描述的各类事件进行处理即可。

# 7. ms_sdk_deinit

接口原型	ms_sdk_result_t ms_sdk_deinit(void)
功能说明	反初始化MSDK，会释放MSDK内部资源以及销毁线程
返回值
MS_SDK_SUCCESS	反初始化成功
MS_SDK_DEINIT_FAIL	反初始化失败
输入参数	无

应用需要停用MSDK功能时调用此接口。该接口调用之后数据通道不可用。

# 8. ms_sdk_send_data

接口原型	ms_sdk_result_t ms_sdk_send_data(ms_sdk_data_frame_t pFrame, uint32_t msgId)
功能说明	数据发送
返回值
MS_SDK_SUCCESS	发送成功
MS_SDK_ERR_INVALID_PARAM	入参错误
MS_SDK_NO_MEM	内存不足
MS_SDK_UNBIND	未绑定
MS_SDK_SEND_FAIL	其他原因的发送失败
输入参数	备注：该接口内的所有指针变量由调用者申请和释放
pFrame	发送数据的内容，具体参考3.2.1节定义
msgId	(1）应用主动发送给IoT云端的消息，msgId由SDK内部生成，发送成功后通过此参数返回给应用；(2）回复给IoT云端的消息，msgId由应用传递给SDK，其值跟从IoT云端收到的消息Id一致（即ms_sdk_data_recv_cb返回的msgId）

当应用需要向美的IoT云端发送数据时（主动发送或者是对云端的回复）调用此接口。发送成功只说明MSDK将数据成功发送到设备和云端的通道，不能说明云端一定收到。对于一定要收到云端回复的数据请求，则需要在应用层做其他自定义措施进行保证，比如超时重发等。另外，只有在设备已绑定的情况下才允许数据发送，否则会返回“MS_SDK_UNBIND“的错误。

发送成功后，MSDK会将消息Id赋值到参数msgId中返回给应用，应用需要进行保存，以便接收到云端回复时进行比对。

如果是对云端消息的回复，则应用需要将从ms_sdk_data_recv_cb获取到的的msgId通过此接口传递给SDK。

关于pFrame里cmd、sub_cmd、version、need_reply、data这些字段的填写规则，请参考IoT云端提供的相应说明文档。

# 9. ms_sdk_reboot

接口原型	ms_sdk_result_t ms_sdk_reboot(void)
功能说明	MSDK重启
返回值
MS_SDK_SUCCESS	成功
MS_SDK_REBOOT_FAIL	重启失败

应用需要重启SDK时，调用此接口。该接口会使设备重启。

# 10. ms_sdk_reset

接口原型	ms_sdk_result_t ms_sdk_reset(void)
功能说明	MSDK重置
返回值
MS_SDK_SUCCESS	成功
MS_SDK_REBOOT_FAIL	重置失败
输入参数	无

应用需要重置SDK时，调用此接口。该接口中会使设备从云端离线，并且清除设备基础身份信息以外的其他入网信息。

# 11. ms_sdk_cmd_process

接口原型	ms_sdk_result_t ms_sdk_cmd_process(uint8_t* indata, uint16_t indata_len)
功能说明	MSDK串口指令处理
返回值
MS_SDK_SUCCESS	成功
MS_SDK_SEND_FAIL	失败
输入参数
indata	发送串口指令消息体
indata_len	发送串口指令消息体长度

应用向SDK发送串口指令时，调用此接口。该接口会处理串口指令并返回。串口指令封装参照《家电端通信协议（基础功能版本）20241012.pdf》。

# 红外遥控类设备MSDK 应用接口说明

# 数据类型说明

# 1. 枚举

# 1.1 ms_sdk_result_t

# 1.2 ms_sdk_msg_t

# 2. 结构体

# 2.1 ms_sdk_data_frame_t

# 3. 接口概述

# 3.1 头文件

# 3.2 接口列表

# 3.3 线程安全

# 4. ms_sdk_event_cb

# 4.1 MS_SDK_MSG_WAIT_CONNECT

# 4.2 MS_SDK_MSG_CONNECTING

# 4.3 MS_SDK_MSG_LOGIN_SUCCESSFUL

# 4.4 MS_SDK_MSG_LOGOUT

# 4.5 MS_SDK_MSG_STATUS_BIND

# 4.6 MS_SDK_MSG_STATUS_UNBIND

# 4.7 MS_SDK_MSG_STATUS_AUTH

# 4.8 MS_SDK_MSG_CMD_SEND

# 4.9 MS_SDK_MSG_NEED_UPGRADE

# 4.10 MS_SDK_MSG_TRANS_FIRMWARE

# 5. ms_sdk_data_recv_cb

# 6. ms_sdk_init

# 7. ms_sdk_deinit

# 8. ms_sdk_send_data

# 9. ms_sdk_reboot

# 10. ms_sdk_reset

# 11. ms_sdk_cmd_process