米家 MIOT React Native 插件 SDK — 项目架构与插件设计说明SDK API_LEVEL: 10117 | 框架: React Native 0.61.0 React 16.9.0 React Navigation 2.x米家开发者平台https://iot.mi.com/一、项目整体架构miot-plugin-sdk/ ← 工作空间根目录不允许修改根 package.json ├── miot-sdk/ ← 核心 SDK只读引用不修改 │ ├── Device.js ← 设备入口WifiDevice / BluetoothLE │ ├── Service.js ← 服务层聚合spec / scene / smarthome / storage... │ ├── Package.js ← 插件包管理entry / entrance / exit │ ├── Host.js ← 宿主能力文件系统、系统信息、语言 │ ├── device/ ← 设备抽象 │ │ ├── BasicDevice.js ← 通用设备基类 │ │ ├── WifiDevice.js ← WiFi 设备subscribeMessages / loadProperties / callMethod │ │ └── bluetooth/ ← 蓝牙设备connect / discoverServices / write / setNotify │ ├── service/ │ │ ├── spec.js ← Spec 协议读写getPropertiesValue / setPropertiesValue / doAction │ │ ├── scene.js ← 场景/定时 │ │ ├── smarthome.js ← 智能家居通用接口 │ │ └── storage.js ← 本地存储 │ ├── ui/ ← 通用 UI 组件库 │ │ ├── NavigationBar ← 导航栏 │ │ ├── CommonSetting/ ← 通用设置分享、固件升级、更多 │ │ ├── ListItem, Card, Dialog, ColorPicker... ← 可复用 UI 原子 │ │ └── ... │ ├── resources/ ← SDK 内置多语言和样式 │ ├── hooks/ ← 内置 hooks │ └── utils/ ← 工具函数 │ ├── projects/ ← 所有设备插件项目每个独立 npm 包互不引用 │ └── com.xiaomi.fan/ ← 风扇示例 │ ├── bin/ ← CLI 工具 │ ├── createProject.js ← 创建项目 │ ├── runProject.js ← 启动调试 │ └── template/ ← 项目模板empty / common / wifi / ble ├── doc-md/ ← SDK 文档设备管理、蓝牙、功能接口、UI 组件 └── eslint-mihome-plugin/ ← 自定义 ESLint 规则核心约束规则说明根package.json不可修改修改会导致在线打包失败第三方库只能装在projects/xxx/下cd projects/xxx npm install --save xxx项目间不互相引用每个projects/下的项目是独立沙箱二、设备通信协议2.1 Spec vs ProfileProfile旧协议Spec / miot-spec新协议年代2019 年前的设备现在的主流设备属性标识字符串名power数字索引siid:2, piid:1读属性loadProperties(power, temperature)getPropertiesValue([{did, siid, piid}])写属性callMethod(set_power, [on])setPropertiesValue([{did, siid, piid, value}])订阅格式prop.powerprop.2.1方法调用callMethod(button_pressed)doAction({did, siid, aiid, in:[]})新设备统一用 Spec 协议Profile 仅作历史兼容。2.2 WiFi vs BLE 通信链路WiFi 设备— 服务端中转插件下发请求 → setPropertiesValue([{did, siid, piid, value}]) → 云端 → 设备 → 设备上报属性变更 → DeviceEvent.deviceReceivedMessages 回调 → 插件更新 UIBLE 设备— 直连蓝牙插件主动发起 → checkBluetooth → startScan → connect → discoverServices → discoverCharacteristics → setNotify(读特征) / write(写特征) → BluetoothEvent 各类事件回调 → 插件更新 UI三、插件项目的三层分层设计每个设备插件项目内部推荐拆为三层各层职责边界层只管什么不管什么通信层spec 协议读写、订阅/取消订阅、pending 防回退、错误码处理UI 长什么样UI 组件层渲染、手势、动画、局部交互数据从哪来、怎么发给设备调度层持有全局 state、组合通信层和 UI 层、处理跨组件逻辑模式切换缓存、禁启用联动具体某个属性的协议细节四、项目入口与路由4.1 标准入口链index.js → 配置 Package.disableAutoCheckUpgradeWiFi 自动检测固件升级 → 监听 PackageEvent.packageAuthorizationCancel用户撤销授权 → 清缓存 退出 → Package.entry(App) Appclass 组件 → 根据 Package.entrance 决定初始路由 • Entrance.Main → MainPage从设备列表点击进入 • Entrance.Scene → ScenePage从场景/自动化进入 → createStackNavigator 注册所有页面 → 统一 NavigationBar 配置title/left/right → 配置页面切换动画interpolator4.2 典型页面路由MainPage ─→ SettingPage 设置 ─→ ScenePage 场景 ─→ XiaoAiPage 小爱训练 SettingPage └── CommonSettingPage分享、固件升级、更多设置五、国际化i18n方案推荐方案简洁适合多数项目// utils/Strings.jsimportHostfrommiot/Host;constLANGUAGEHost.locale.language;// zh | enconstgetStrings(strings)strings[LANGUAGE]||strings.en;constStringsgetStrings({zh:{power:开关,setting:设置,...},en:{power:Power,setting:Settings,...},});exportdefaultStrings;// 使用Text{Strings.power}/Text支持占位符电量 {level}%→formatString(Strings.battery, {level: 80})→电量 80%模板方案多语言15种// resources/strings/index.jsimport{Resources}frommiot;import{Language}frommiot/resources;// switch-case 按语言加载对应 .js 文件六、新设备插件开发流程Step 1 — 创建项目npmrun create com.xxx.yyy.zzz-typewifi# WiFi 设备npmrun create com.xxx.yyy.zzz-typeble# BLE 设备npmrun create com.xxx.yyy.zzz-typecommon# 通用模板Step 2 — 定义 spec 属性映射在utils/constant.ts中定义// 1. ValueType 枚举exportconstValueType{bool:0,uint8:1,uint16:3,uint32:5,...};// 2. AttrKey — 属性映射从设备 spec 文档获取 siid/piid/typeexportconstAttrKey{power:{key:power,siid:2,piid:1,type:ValueType.bool},// ... 按设备 spec 逐个添加};// 3. FormatPropsKey — 上报格式转换exportconstFormatPropsKey{prop.2.1:AttrKey.power.key,// ...};// 4. Attr — 属性枚举值exportconstAttr{light:{off:0,on:1,...},// ...};Step 3 — 搭建 MainPage调度层复用自定义通信层骨架Step 4 — 开发 UI 组件按设备功能拆分 Presentational 组件每个组件只接收 props数据 回调不 import AttrKey 或 Service.spec可复用 SDK 内置 UIListItem, Card, ColorPicker…Step 5 — 配置路由和入口project.json— 设置min_sdk_api_levelindex.js—Package.entry(App)App— 注册路由、配置入口分发SettingPage— 配置 CommonSetting分享、固件升级等Step 6 — 国际化utils/Strings.js— 中英文文案所有用户可见文字通过Strings.xxx引用不硬编码中文Step 7 — 调试与发布npmstart com.xxx.yyy.zzz# 启动调试米家 APP 扫码npmrun publish com.xxx.yyy.zzz# 发布构建七、快速参考常用 SDK APIimport{Package,Device,Service,Host,DeviceEvent}frommiot;import{PackageEvent,BluetoothEvent}frommiot;import{NavigationBar,CommonSettingPage,SETTING_KEYS}frommiot/ui;import{Resources,Styles}frommiot/resources;常用设备操作// WiFi Spec 设备Service.spec.getPropertiesValue([{did,siid,piid}])Service.spec.setPropertiesValue([{did,siid,piid,value}])Device.getDeviceWifi().subscribeMessages(prop.2.1,prop.3.1)// BLE 设备Bluetooth.checkBluetoothIsEnabled()Bluetooth.startScan(timeout,...serviceUUIDs)Device.getBluetoothLE(peripheralUUID).connect()bleDevice.getService(uuid).getCharacteristic(uuid).setNotify(true)bleDevice.getService(uuid).getCharacteristic(uuid).write(value)// 通用Device.name/Device.model/Device.deviceID/Device.isOnline/Device.isOwner Host.locale.language Package.exit()
