Skip to content
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 [email protected]: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,过滤你们反馈上面的日志。

Clone this wiki locally