# 1. 硬件产品接入流程
# 1. 概述
美的IoT平台提供两种硬件接入方式：标准模组和模组SDK，支持各种IoT硬件产品完成智能化升级，开发者可结合产品的情况选择合适的接入方式。
| 接入方式 | 描述 | 接入难度 |
|---|---|---|
| 标准模组 | 美的现成的标准模组，开发者可购买并集成到产品中，通过美的电控串口协议控制模组，实现设备接入美的云 | 简单 |
| 模组SDK | 由美的提供模组SDK，开发者移植模组SDK到自己的MCU中，通过API接口控制模组SDK，实现设备接入美的云 | 较难 |
- 标准模组，提供多种模组型号，选型表及用法见“基于标准模组接入”章节。
- 模组SDK，包含3个类型：WIFI_SDK、蜂窝SDK、BLE_SDK，功能说明见“基于模组SDK接入”章节。
标准模组接入拓扑图：
模组SD接入拓扑图 (以WIFI_SDK为例)：
# 2. 接入前准备工作
由于选择的硬件接入方式不同，准备工作也不一样。开发者可根据接入方式章节（基于标准模组接入、基于模组SDK接入）的指引，选择性阅读该章节内容。
接入前准备工作列表：（*号表示相关）
| 序号 | 准备工作 | 描述 | 标准模组接入方式 | 模组SDK接入方式 |
|---|---|---|---|---|
| 1 | 平台产品信息配置 | 在开发者平台创建产品和配置产品信息 | * | * |
| 2 | 申请SN | SN作为设备唯一标识，由开发者平台生成，模组/SDK需要设置SN才能正常运行 | * | * |
| 3 | 申请License | License用于鉴别美的产品和安全需要 ，(由美的对接人申请) | * | |
| 4 | 申请固件标识码 | 固件标识码用于构建固件版本号，用于模组OTA，(由美的对接人申请) | * | |
| 5 | 申请模组SDK | 填写SDK申请表并在开发者平台提交工单 | * | |
| 6 | 家电端通信协议 | 美的M-Smart物联网家电中所使用的模组与家电端的通信协议 | * | * |
说明：标准模组出厂前已烧录指定版本固件和License，因此不需要此类准备工作。
# 2.1. 平台产品信息配置
无论采用哪种硬件接入方式，均需在开发者平台配置产品信息，完成产品创建，配网指引配置等操作。
2.1.1. 创建产品
登录开发者平台 (opens new window)，若尚未注册账户，则参考链接成为开发者 (opens new window)注册账号，建议注册后进行企业认证，以获得更好的服务。
在开发者平台的
工作台页面创建智能产品，并根据创建指引完成产品创建，操作方法见：创建智能产品
2.1.2. 云端配置
在开发者平台设置配网指引，美居APP在配网过程中会根据配网指引执行特定操作，设置方法见： 设置配网指引 [TODO] -待平台同事添加
# 2.2. 申请SN
SN是美的IoT云为每台设备分配的唯一身份识别，无论是产品开发、测试还是量产，都需要先将SN烧录到设备电控中，以便和云端交互
SN的生成步骤如下：
(1) 选择一个产品
(2) 进入SN管理
(3) 申请新的SN
(4) 根据业务理解填写申请信息
(5) SN生成成功，点击下载
# 2.3. 申请License
基于安全考虑，美的IoT模组规定需要烧录License。
美的IoT生产管理平台，又名License系统，可通过此系统申请到MAC地址及对应的License，已有MAC地址或IMEI也可通过此系统申请到对应的License。
需要生产IoT模组的事业部或模组供应商（后文都称为模组厂）需指派一个接口人对接License系统，其他人统一通过接口人申请License。
License系统管理员: lijm37@midea.com，可通过美信或邮件咨询License相关事宜。
# 2.4. 申请固件标识码
模组固件标识码是固件版本号的一部分，用于模组OTA，标准模组/SDK上传版本号给云端，由云端判断固件是否有更新。
注意，申请人需是美的员工，通常由产品经理或项目负责人申请，新固件标识码通过美的内部MIP系统发放给申请人。
2.4.1. 申请步骤
下载固件标识码申请表： 事业部固件标识码申请表.xlsx (opens new window)
填写申请表中的
事业部申请信息栏，其中家电品类项推荐写法"品类码-产品名称"；若有多个产品固件版本需求，则按顺序添加到表格。
通过邮件提交申请表，收件人：maill@midea.com，抄送：yech3@midea.com，fengxm6@midea.com
新固件标识码分配好后，通MIP系统发放，其中申请人参与审批流程，请及时审批。
2.4.2. 固件版本号格式说明
固定标识码作为固件版本号的前缀，用于区分不同产品固件，避免开发者平台上出现固件版本号重叠的情况。
完整的固件版本号如下图所示，开发者拿到新的固件标识码后，通过下面规则，定义固件版本号。
Byte[0~2]: 对应固件标识码，此字段由美的AIRC管控，固件标识码相同，则表明软件可以互相替代，不影响基本功能与性能；
Byte[3-5]: 对应软件版本，开发者根据版本规则自行定义，比如若发布软件功能需要迭代升级，版本号在byte[3]字节上加1，初始版本从0x01开始累加；
Byte[6-8]: 对应开发记录小版本号，开发时用于标识不同代码版本，此字段不被云端OTA识别记录，即OTA服务器不会判断该字段以判断固件新旧，但是串口和网络端指令支持读取此信息；
2.4.3. OTA固件打包工具
在使用模组OTA功能时，新固件需先使用美的专用的固件打包工具打包后，再上传到开发者平台中。
工具由美的内部对接人提供。
# 2.5. 申请模组SDK
当采用基于模组SDK接入方式时，需要填写SDK申请表，并在开发者平台提交工单，下面是详细操作步骤。
2.5.1. 填写申请表
详细填写申请表中的项目信息，选择SDK方案并勾选想要的功能，填写步骤如下：(下面以WIFI_SDK方案为例，实际SDK申请表会不定时更新，截图供参考）
- 填写
基本信息页面，该页面通常由产品经理/项目负责人填写，在方案列表下拉框中勾选想要的方案，各项内容需详细填写（如产品名称、价值描述、需求时间）
- 填写
- 填写方案页面，根据前面勾选的方案，填写相应的方案页面。填写前请仔细阅读示例和说明，特别是编译选项和编译参数的说明。最后在功能定制表中选择需要的功能，若无明确的特殊功能要求，请勾选默认值，默认值选择的是SDK基础功能，满足大部分产品要求。
2.5.2. 提交工单
在开发者平台填写并提交模组SDK申请工单，平台详细操作请参考： 如何提交工单 (opens new window) 。在填写信息页面中，填写详细的项目背景、芯片型号等信息，并把SDK申请表添加到附件。
2.5.3. 获取SDK及使用说明
SDK制作完成后，SDK和使用说明书等资料，将通过邮件发给该项目的事业部对接人。
# 2.6. 家电端通信协议
《家电端通信协议》又称为电控串口协议，规定美的M-Smart物联网家电中所使用的模组与家电端的通信协议，家电开发人员按此文档开发通讯接口与模组进行通讯。
M-Smart串口调试工具，一款PC工具软件，支持《家电端通信协议》，用于把电脑模拟成家电电控，通过串口连接/控制美的IoT模组，可快速验证模组基础功能。
拓扑图（以标准模组/WIFI_SDK/蜂窝SDK为例，BLE_SDK不适用）
2.6.1. 下载协议和工具
由美的内部对接人提供。
2.6.2. 串口调试工具使用方法
用USB转串口工具把IoT模组连接到电脑
打开M-smart串口调试工具
选择串口号，波特率默认9600
点击"打开串口'"，通常能收到模组上报的“SN请求”帧。
发送命令：遵循《家电端通信协议》完成填写设备类型、消息类型、消息体，点击"计算"，然后点击"发送"
2.6.3. 常用指令及用法示例
常用指令列表：
| 指令 | 指令码 | 用法示例 |
|---|---|---|
| 云端透传控制指令 | 0x02 | |
| 云端透传查询指令 | 0x03 | |
| 家电运行参数上报（无应答） | 0x04 | |
| 家电运行参数上报（需应答） | 0x05 | |
| 家电设备SN获取 | 0x07 | 上电后模组/SDK主动向电控请求SN |
| 模组联网状态通知 | 0x0D | 实时上报连蓝牙、连路由、连云端等状态，含连接过程错误码 |
| 模组入网方法切换 | 0x64 | 进入配网模式，起AP/BLE热点 |
| 模组重新启动 | 0x82 | |
| 模组恢复出厂设置 | 0x83 | |
| 家电型号及基本信息查询 | 0xA0 | |
| 家电网络功能查询 | 0xE1 |
更多命令请参考M-Smart串口调试工具包中的《参考脚本.json》，或按照《家电端通信协议》构建。
用法示例： （后面将“模组/SDK”简称为“SDK”）
模组/SDK上电后与家电端的指令交互流程：
07-请求SN指令：设备上电后，SDK开始运行，SDK周期性自动发送
07-请求SN指令给电控，并等待电控应答SN后，SDK才能继续执行之后的流程（流程阻塞）。SDK连续发送多次07指令后，若都没收到电控的应答，则调用适配层reboot接口来重启设备，以此往复，直到收到有效的应答帧。
指令示例：
SDK->家电：0xAA, 0x0B, 0xFF, 0xF4, 0x00, 0x00, 0x01, 0x00, 0x00, 0x07, 0x00, 0xFA 家电->SDK(应答): 0xAA, 0x2A, 0xFC, 0xD6, 0x00, 0x00, 0x00, 0x00, 0x00, 0x07, 0x30, 0x30, 0x30, 0x30, 0x46, 0x43, 0x32, 0x31, 0x31, 0x31, 0x38, 0x32, 0x37, 0x33, 0x36, 0x34, 0x35, 0x31, 0x37, 0x35, 0x30, 0x37, 0x32, 0x39, 0x42, 0x4B, 0x30, 0x36, 0x30, 0x30, 0x30, 0x30, 0x5AA0-家电型号及基本信息查询指令：SDK收到
07-请求SN应答后，继续发送A0-家电型号及基本信息查询指令，查询家电的基本信息。SDK连续发送3次后，若都没有收到电控的回复，则按SDK内部默认值继续执行其他流程。
指令示例：
SDK->家电：0xAA, 0x1E, 0xFC, 0xE2, 0x00, 0x00, 0x00, 0x00, 0x00, 0xA0, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x64 家电->SDK(应答): 0xaa, 0x25, 0xfc, 0xd9, 0x00, 0x00, 0x00, 0x00, 0x02, 0xa0, 0x00, 0xfc, 0x08, 0x00, 0x16, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x4a0D-模组联网状态通知指令：这是一条很实用的指令，当网络状态发送变化时，SDK主动发起0D指令通知家电端，比如蜂窝链路建立成功或失败、是否连上美的云服务中心及连接失败的原因、信号强度变化等；
家电端需根据返回状态做相应的处理，比如收到
已连接美的云服务中心状态，此后，家电可以使用数据上报指令如04/05指令，将家电数据发送给云端/美居APP。指令示例：
SDK->家电：AA 1E AC B2 00 00 08 00 00 0D 01 03 00 01 01 A8 C0 00 01 01 00 00 00 00 00 00 01 00 00 00 FE 家电->SDK: 无应答
数据透传：
当SDK连接云端后，家电与云端/美居APP之间可通过SDK的数据透传相关指令交换数据，家电端可以主动发送数据帧给云端/美居APP，也可能收云端/美居APP主动发来的数据帧，且需要应答。
根据发起方不同，指令可分为2类：
- 由云端/美居APP主动发起的：
02-云端透传控制指令（需应答）、03-云端透传查询指令（需应答）。
举例：用户在美居APP的空调页面上执行
打开空调，美居APP/云端将相关指令帧发送给SDK，SDK转发02-云端透传控制指令给家电空调，家电端解析和处理该指令并应答SDK，SDK转发应答帧给云端/美居APP，美居APP提示用户空调打开成功或失败。- 由家电端主动发起的：
04-家电运行参数上报（无应答）、05-家电运行参数上报（需应答）、06-家电异常事件上报（无应答）。
其用法跟第1类类似，仅是发起方不同。
- 由云端/美居APP主动发起的：
SDK仅负责转发透传帧，不解析其内容。各家电实际控制协议（如开关机控制）、格式（lua、json、物模型）等内容均与SDK无关，由开发者自行开发。
# 3. 基于标准模组接入
本章节主要介绍模组端标准模组的接入流程，云端和APP端涉及开发工作请参考开发者平台相关资料，这里不做详细描述。
标准模组基础功能验证，比如AP/BLE配网、连云、绑定等功能，需要云端和APP端配合，因此模组使用前需确保以下工作已完成。
- 云端：正确配置平台产品信息，确保APP端能找到该产品信息和配网指引，操作方法见 [平台产品信息配置](2.1. 平台产品信息配置) 章节。
- APP端：下载美居APP/SmartHome，完成插件页开发，详见开发者平台相关章节内容。
# 3.1. 接入流程图
# 3.2. 模组选型及购买
标准模组型号表：
| 标准模组型号 | 通讯类型 |
|---|---|
| MWB-S-WB01 | WiFi4+BLE5.1 |
| MWB-S-F13 | WiFi4+BLE5.2 |
| MWB-S-WB02-3 | WiFi6+BLE5.2 |
| MWB-S-WM01 | WiFi4+BLE5.2 |
购买方式：
由美的内部对接人提供购买联系方式。
# 3.3. 申请SN
SN作为设备唯一标识，由开发者平台生成，模组/SDK需要设置SN才能正常运行，详细操作见 “[申请SN](#2.2. 申请SN)” 章节。
# 3.4. 业务开发、联合调试
开发人员在电控端实现《家电端通信协议》，通过串口发送控制指令给标准模组，比如发送SN、起配网热点、复位模组、透传数据等。
详细操作参考链接：[家电端通信协议](#2.6. 家电端通信协议) 。
电控端完成业务开发，并配合云端和APP端联合调试，调试前，云端需完成产品创建、配置配网指引等工作，APP端需完成插件页开发工作。具体操作方法参考云端/APP端相关页面。
产品测试通过后，根据开发者平台相关的产品发布指引，上线产品。
# 4. 基于模组SDK接入
本章节主要介绍模组端SDK的接入流程，云端和APP端涉及开发工作请参考开发者平台相关资料，这里不做详细描述。
模组SDK基础功能验证，比如AP/BLE配网、连云、绑定等功能，需要云端和APP端配合，因此使用模组前需确保以下工作已完成。
- 云端：正确配置平台产品信息，确保APP端能找到该产品信息和配网指引，操作方法见 [平台产品信息配置](#2.1. 平台产品信息配置) 章节。
- APP端：下载美居APP/SmartHome，完成插件页开发，详见开发者平台相关章节内容。
# 4.1. 接入流程图
# 4.2. 选择SDK类型
模组SDK包含3个类型，根据产品需求，选择相应的SDK类型。
| SDK类型 | 描述 | 注意 |
|---|---|---|
| WIFI_SDK | 用于WIFI+BLE产品，支持AP配网、BLE配网、连美的云、数据透传、OTA等功能。 | |
| 蜂窝SDK | 用于蜂窝/4G网产品，支持扫码绑定、连美的云、数据透传、OTA等功能。 | |
| BLE_SDK | 用于单蓝牙产品，支持美居绑定、数据透传、OTA等功能 |
不同类型SDK对芯片资源有最低要求，申请SDK前，需评估所选芯片资源是否满足要求，及时调整方案。
WIFI_SDK资源要求
| 评估检查项 | 要求 | 是否必须满足 |
|---|---|---|
| MCU速率 | 主频大于100MHz | 否 |
| FLASH空间 | 预留给SDK的空间需大于512KB | 是 |
| RAM空间 | 预留给SDK的空间需大于128KB | 是 |
| 编译环境 | Linux | 是 |
蜂窝SDK资源要求
| 评估检查项 | 要求 | 是否必须满足 |
|---|---|---|
| MCU速率 | 主频大于100MHz | 否 |
| FLASH空间 | 预留给SDK的空间需大于512KB | 是 |
| RAM空间 | 预留给SDK的空间需大于128KB | 是 |
| 编译环境 | Linux | 是 |
BLE_SDK资源要求
| 评估检查项 | 要求 | 是否必须满足 |
|---|---|---|
| MCU速率 | 主频大于32MHz | 否 |
| FLASH空间 | 预留给SDK的空间需大于25KB | 是 |
| RAM空间 | 预留给SDK的空间需大于10KB | 是 |
| 编译环境 | Linux/KEIL | 是 |
| 蓝牙协议版本 | Bluetooth 4.2及以上 | 是 |
| 安全要求 | 蓝牙芯片底层提供ECDH-secp256r1接口 | 是 |
# 4.3. 申请SDK、SN、License、固件标识码
申请SDK下载并填写SDK申请表，提交申请工单，详细操作见 “[申请模组SDK](#2.5. 申请模组SDK)” 章节。
申请SNSN作为设备唯一标识，由开发者平台生成，模组/SDK需要设置SN才能正常运行，详细操作见 “[申请SN](#2.2. 申请SN)” 章节。
申请LicenseLicense用于鉴别美的产品和安全需要，每个模组均有唯一License，SDK适配层接口需要用到，详细操作见 “[申请License](#2.3. 申请License)” 章节。
申请固件标识码固件标识码用于构建固件版本号，用于模组OTA，详细操作见 “[申请固件标识码](#2.4. 申请固件标识码)” 章节。
注意：项目未正式确认方案，不要申请固件标识码
在项目初期，由于各种因素影响容易导致芯片方案变更、项目终止等风险(特别是预研类项目)，而固件标识码数量有限，为避免浪费，建议在SDK基础功能(如配网、连云)验证成功后（SDK固件标识码不影响基础功能验证），再申请新的固件标识码，验证OTA功能。
# 4.4. 移植SDK
开发阶段，优先推荐在Sit环境下，使用其他已发布产品的SN来做测试，确保云端配置和插件页可靠，完成SDK基础功能验证后，再切换到新产品SN。
SDK申请成功后，开发者拿到的资料如下：
| SDK类型 | 资料包 | 作用 | 示例 |
|---|---|---|---|
| WIFI_SDK | MSDK包及说明书 | 支持AP配网、BLE配网、连美的云、数据透传、OTA等功能。 | standard_msdk_芯片型号_xxxx_日期.zip |
| XTS_SDK包及说明书 | XTS工具包，用于验证MSDK适配层接口 | mxts_芯片型号_xxxx_日期.zip | |
| 蜂窝SDK | MSDK包及说明书 | 支持扫码绑定、连美的云、数据透传、OTA等功能。 | standard_msdk_芯片型号_xxxx_日期.zip |
| XTS_SDK包及说明书 | XTS工具包，用于验证MSDK适配层接口 | mxts_芯片型号_xxxx_日期.zip | |
| BLE_SDK | MSDK包及说明书 | 支持美居绑定、数据透传、OTA等功能 | msdk_芯片型号_xxxx_日期.zip |
注意：若资料包包含XTS_SDK，则开发者需先适配XTS_SDK。
开发应避免直接移植MSDK，由于适配层接口由MSDK静态库调用，若适配层接口出现问题，开发者很难定位，难以排查。
而XTS_SDK，包含测试用例源代码，开发者编写完适配层接口代码后，逐个运行测试用例，验证接口功能是否符合要求，用例源码可帮助快速定位问题。验证通过再移植MSDK即可。
开发者根据资料包中的SDK使用说明书，完成MSDK适配，实现配网、连云、绑定、数据透传等基础功能。
其中数据透传功能，即MSDK为开发者提供的业务数据传输通道，用于开发具体业务功能。
工具推荐：串口调试工具，工具下载及操作说明见链接：[家电端通信协议](#2.6. 家电端通信协议)
串口调试工具，一款PC软件，实现美的的《家电端通信协议》，用于模拟真实电控，通过串口与模组/SDK通信，比如模拟电控给SDK发送SN、起热点、复位、透传数据等指令
该工具支持移植了
WIFI_SDK或蜂窝SDK的产品使用，不支持BLE_SDK。
# 4.5. 业务开发、联合调试
基于MSDK提供的功能完成模组端业务开发，并配合云端和APP端联合调试，调试前，云端需完成产品创建、配置配网指引等工作，APP端需完成插件页开发工作，具体操作方法参考云端/APP端相关页面。
产品测试通过后，根据开发者平台相关的产品发布指引，上线产品。