Skip to content

Home

Jump to bottom
Xiaomi-Yule edited this page Apr 9, 2021 · 11 revisions

米家扩展程序开发概述

概要

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

兼容性

支持iOS & Android

示例代码

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

  • 蓝牙设备示例程序，SDK 目录中 com.xiaomi.bledemo
  • 一个涵盖了所有SDK功能的引导Demo程序 com.xiaomi.demo 目录

开发环境

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

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

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

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

扩展程序申请与创建

  1. 在 小米 IoT 开发者平台 上注册一个开发者账号（智能设备硬件、iOS 扩展程序、Android 扩展程序使用同一个开发者账号）并等待审核通过。
  2. 按引导创建新硬件，审核完成后，按引导完成硬件的基础配置，注意配网方式一定要保证正确。
  3. 创建该智能硬件的扩展程序。

开始写扩展程序代码

  1. 初始化

    1, 安装 node, 版本12.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, 否则在打包发布时将因为找不到第三方库而失败

  1. 命令介绍

    创建项目
 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 指定任意目标文件

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

  3. 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

  1. 米家JS_SDK的功能随着版本的变化也在发生变化，开放给扩展程序的 API 也在逐渐增加（极少数情况下也会废弃），每一个版本都有一个 API Level，代表了SDK支持的 API 集合，随 API 的变动而递增。
  2. 每个模块或 API 的文档中标明了其引入时米家 JS_SDK 的 API Level，例如 AL[7,] 表示这个模块或 API 只有在运行的JS_SDK API Level >= 7 的情况下才可以使用，若project.json配置中标注的ApiLevel小于实际使用的APILevel则会引起错误。
  3. 扩展程序包的 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 最高的一个）。
  4. 综上所述：开发者需要注意，在 project.json 文件中，填入你当前扩展程序中所有使用了的 API 的 API Level 的最大值。假设你只使用了两个 API，分别为 api_a [100,] 和 api_b [101,] ，则 project.json 文件中的 min_sdk_api_level 值应为 101 ，则不会出现兼容性问题。

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

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

  1. min_sdk_api_level.json: 扩展程序包信息文件。
  2. Main目录：扩展程序的页面，其中 MainPage.js 为插件主页，具体界面开发参见RN文档。设备功能开发参见”与设备和米家云端的交互“章节。
  3. Resources目录：扩展程序包资源目录。所有扩展程序包用到的资源，例如图片、文本、声音等文件都要存储在这个目录下。

智能设备的发现与连接

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

    1. 已经接入米家的智能设备(Android&iOS)
    2. 正在开发的米家设备开发板(Android&iOS)
    3. 小米智能设备Demo开发板(Android&iOS)
    4. 任意已经接入米家的其他设备(Android&iOS)
    5. 虚拟设备(iOS Only)

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

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

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

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

    1. 确认已按前述步骤2设置产品状态。
    2. 退出登录开发者账号、杀死客户端进程并重新使用开发者账号登陆。

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

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

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

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

调试本地扩展程序

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

调试本地扩展程序

扩展程序的测试和发布

  1. 扩展程序开发者应在开发环境下进行充分的代码测试；
  2. 上传扩展程序，在对应版本后点击 “白名单测试” 按钮， 则白名单内的用户能下载和测试扩展程序。注意云端一般会有几分钟的缓存刷新时间，可能无法立即生效。尤其用户第一次被添加入白名单时，最好重新登录账号并重启 App。厂商需要利用白名单测试做好上线前测试；
  3. 厂商测试完毕，在对应版本后点击“申请上线”按钮，提交测试报告，等待审核；
  4. 审核通过，正式上线。

发现问题怎么办

  • 第一步：提交日志

    如果在开发过程中，使用米家APP发现了一些与SDK有关的问题，那么应该在米家APP的 “我得--》帮助与反馈--》选择设备--》反馈问题--》添加问题的说明--》提交”，

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

  • 第二步：提issue

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

Home

API文档

迁移文档

RN版本升级54-61

iOS 旧版本迁移

Clone this wiki locally