米家扩展程序初始化超时_Home · MiEcosystem/miot-plugin-sdk Wiki · GitHub

米家扩展程序开发概述

概要

此项目为方便智能硬件接入小米米家 App( iOS & Android 版本)。基于此方案，智能硬件厂商需要开发自己的米家扩展程序，用户使用米家 App 连接硬件之后，会自动下载、使用扩展程序，获得与设备交互的能力与 UI。米家客户端的扩展程序基于 React Native 框架实现，可以实时动态更新，同时最大限度保留了原生 App 的体验。

兼容性

支持iOS & Android

示例代码

miot-plugin-sdk/projects 目录中包含一系列示例代码，开发者可作为参考：

蓝牙设备示例程序，SDK 目录中 com.xiaomi.bledemo

一个涵盖了所有SDK功能的引导Demo程序 com.xiaomi.demo 目录

开发环境

React Native(以下简称RN): RN 的安装过程参见该项目主页。注意 目前米家客户端中内置的 RN 引擎版本为 0.54.1。

miot-plugin-sdk: SDK可以通过 Github项目主页 下载。

iPhone真机 | Android真机、模拟器。

由于iOS要使用 Appstore 版本的米家APP进行调试(如果想获得调试便利，需要一个debug版本的米家ipa，RN 的调试选项在 release 模式下禁用了)，所以不能使用模拟器开发，必须使用一部 iOS 9.0 以上系统的 iPhone 真机。

扩展程序申请与创建

在 小米 IoT 开发者平台上注册一个开发者账号(智能设备硬件、iOS 扩展程序、Android 扩展程序使用同一个开发者账号)并等待审核通过。

按引导创建新硬件，审核完成后，按引导完成硬件的基础配置，注意配网方式一定要保证正确。

创建该智能硬件的扩展程序。

开始写扩展程序代码

初始化

1, 安装 node, 版本9.0+

2, 下载开发环境, 执行 git clone git@github.com:MiEcosystem/miot-plugin-sdk.git

3, 进入开发环境, 安装ReactNative基础库, 在根目录下执行 npm install

注意, 项目中如果需要使用第三方库(仅限于纯js实现), 请进入项目目录(如 projects/com.xiaomi.demo),

执行 npm install --save xxxx, 否则在打包发布时将因为找不到第三方库而失败

命令介绍

创建项目

npm run create -- --models xxx.xxx.x1|xxx.xxx.x2 xxx.yyy.zzz

注: xxx.xxx.x1~2为项目注册的model

xxx.yyy.zzz 为项目路径名

启动调试

npm start

发布项目

npm run publish xxx.yyy.zzz

注: 缺省的目标文件位于 projects/xxx.yyy.zzz/build/publish.mpkg, 可以通过 --target 指定任意目标文件

本地扩展程序包创建成功后，会在 projects 目录下生成一个 plugin_name 目录，其目录结构以及各文件的含义见相关章节。

plugin_name 目录下有个名为 project.json 的扩展程序包信息文件(注意 不要与 npm 的 package.json 混淆)。这个文件关系到程序包的打包和上传，创建本地程序包成功后，请用文本编辑器打开这个文件并编辑其中的内容：

{

"models":"xxx.xxx.x1|xxx.xxx.x2", //必填, 固件 model 列表, 多个用|隔开

"package_path":"xxx.yyy.zzz", //项目路径名

"min_sdk_api_level":10000, //支持运行的SDK API_LEVEL

}

min_sdk_api_level

米家JS_SDK的功能随着版本的变化也在发生变化，开放给扩展程序的 API 也在逐渐增加(极少数情况下也会废弃)，每一个版本都有一个 API Level，代表了SDK支持的 API 集合，随 API 的变动而递增。

每个模块或 API 的文档中标明了其引入时米家 JS_SDK 的 API Level，例如 AL[7,] 表示这个模块或 API 只有在运行的JS_SDK API Level >= 7 的情况下才可以使用，若project.json配置中标注的ApiLevel小于实际使用的APILevel则会引起错误。

扩展程序包的 min_sdk_api_level 为整个扩展程序中所使用的所有 API 中 API Level 最高的一个。API Level 低于 min_sdk_api_level 的米家APP将无法获取到此扩展程序，默认情况下 min_sdk_api_level 为当前 SDK 的 SDK_API_Level(该 SDK 中所有 API 里 API Level 最高的一个)。

综上所述：开发者需要注意，在 project.json 文件中，填入你当前扩展程序中所有使用了的 API 的 API Level 的最大值。假设你只使用了两个 API，分别为 api_a [100,] 和 api_b [101,] ，则 project.json 文件中的 min_sdk_api_level 值应为 101 ，则不会出现兼容性问题。

扩展程序目录结构及文件含义

本地扩展程序包目录下包含以下文件和目录：

min_sdk_api_level.json: 扩展程序包信息文件。

Main目录：扩展程序的页面，其中 MainPage.js 为插件主页，具体界面开发参见RN文档。设备功能开发参见”与设备和米家云端的交互“章节。

Resources目录：扩展程序包资源目录。所有扩展程序包用到的资源，例如图片、文本、声音等文件都要存储在这个目录下。

智能设备的发现与连接

在开发与调试之前，需要将设备连接到米家客户端中。目前支持使用以下几种设备进行扩展程序的开发和调试：

已经接入米家的智能设备(Android&iOS)

正在开发的米家设备开发板(Android&iOS)

小米智能设备Demo开发板(Android&iOS)

任意已经接入米家的其他设备(Android&iOS)

虚拟设备(iOS Only)

其中，3、4和5由于不具备待开发设备的相应功能，只能用来开发UI界面。

使用 1 ， 2 和 5 进行扩展程序开发时，需要确定已经在 IoT 平台完成该产品 model 的基础配置，不然无法在客户端的快连菜单和设备列表里看到设备。

使用米家开发者账号登陆 客户端。

点击客户端右上角的添加按钮，如果菜单中并未出现要连接的设备型号，请按如下步骤操作：

确认已按前述步骤2设置产品状态。

退出登录开发者账号、杀死客户端进程并重新使用开发者账号登陆。

在菜单中选择要连接的设备型号，按客户端提示进行连接。

如果连接失败。请按照指示灯的状态选择对应的模式再试一次，注意 部分设备不支持工作在 5G wifi 下。

当设备出现在设备列表以后，即可进行扩展程序的开发和调试工作。

虚拟设备的创建流程见下节。

调试本地扩展程序

！！！注意：再使用本地扩展程序调试时，请确认 测试设备已经在设备列表中，参考 上方 的说明，否则无法调试

扩展程序的测试和发布

扩展程序开发者应在开发环境下进行充分的代码测试；

上传扩展程序，在对应版本后点击 “白名单测试” 按钮， 则白名单内的用户能下载和测试扩展程序。注意云端一般会有几分钟的缓存刷新时间，可能无法立即生效。尤其用户第一次被添加入白名单时，最好重新登录账号并重启 App。厂商需要利用白名单测试做好上线前测试；

厂商测试完毕，在对应版本后点击“申请上线”按钮，提交测试报告，等待审核；

审核通过，正式上线。

发现问题怎么办

第一步：提交日志

如果在开发过程中，使用米家APP发现了一些与SDK有关的问题，那么应该在米家APP的

“我得--》帮助与反馈--》选择设备--》反馈问题--》添加问题的说明--》提交”，

注意：这里一定要勾选“发送问题日志”，便于我们排查问题

第二步：提issue

按照issue的模板提交上述发现问题的，并且附上当前用户的id，我们会通过该用户id，过滤你们反馈上面的日志。