02 场景模块 - MiEcosystem/miot-plugin-sdk GitHub Wiki

场景相关服务, 包括定时,人工与自动场景（SceneType 类中） 定时场景：是指设备的有关倒计时或设置时间触发设备执行某一动作的智能自动化； 例如米家app中 “智能”->“+”->“定时” 创建的自动化或通过openTimerSettingPageWithOptions或openCountDownPage 提供的API 创建的智能自动化都属于定时场景。 人工场景：是指需要手动执行的智能自动化； 例如米家app中 “智能”->“+”->“手动执行” 创建的自动化属于人工场景 自动场景：主要是指设备之间相互关联的能够自动促发的智能自动化； 例如米家app中 “智能”->“+”-> 选择某一设备 创建的智能自动化, 通常有 if...then... 的执行过程。

更多详细介绍可以参考：https://iot.mi.com/new/doc/extension-development/topics/automation-develop

Export: public
Doc_name: 场景模块
Doc_index: 2
Doc_directory: service
Example

import {Service, Device, SceneType} from 'miot';
  //加载此设备所有的定时场景
  Service.scene.loadScenes(Device.deviceID, SceneType.Timer)
  .then((sceneArr) => {
     if(sceneArr.length > 0){
        const scene = sceneArr[0];
        scene.setting.enable_push = 1;
        ...
        scene.save().then((res)=>{
           console.log(res)
        });
     }
 });

Example

//加载此设备名称为name，类别为identify的所有人工场景
   ** 注意：name字段慎用，后台有如此判断逻辑：if(req.name != "") req.did=req.identify... 。这个会导致请求接口提示have no device permit。**
   Service.scene.loadArtificialScenes(Device.deviceID, {name:'...', identify:'...'})
   .then(arr=>{...}).catch(err=>{...})

Example

//加载此设备的所有定时场景
  Device.loadTimerScenes().then((sceneArr) => {
    ...
  })
  .catch(err=>{
     console.log(err)
  })

• miot/service/scene
  • module.exports ⏏
    • static
      • .IScene
        • .sceneID : int
        • .isNew : boolean
        • .createTime : long
        • .status : int
        • .deviceID : string
        • .name : string
        • .type : SceneType
        • .isTimer : boolean
        • .isArtificial : boolean
        • .isAutomatic : readonly
        • .identify : string
        • .setting : json
        • .authorizedDeviceIDs : [ 'Array' ].<String>
        • .save(opt) ⇒ [ 'Promise' ].<IScene>
        • .reload() ⇒ [ 'Promise' ].<IScene>
        • .start() ⇒ [ 'Promise' ].<IScene>
        • .remove() ⇒ [ 'Promise' ].<IScene>
    • inner
      • ~IMiotScene
        • .createScene(deviceID, sceneType, opt) ⇒ IScene
        • .createTimerScene(deviceID, opt) ⇒ IScene
        • .createArtificialScene(设备id, opt) ⇒ IScene
        • .createAutomaticScene(deviceID, opt) ⇒ IScene
        • .loadScenes(deviceID, sceneType, opt) ⇒ [ 'Promise' ].<Array.<IScene>>
        • .loadTimerScenes(deviceID, opt) ⇒ [ 'Promise' ].<Array.<IScene>>
        • .loadArtificialScenes(deviceID, opt) ⇒ [ 'Promise' ].<Array.<IScene>>
        • .loadAutomaticScenes(deviceID, opt) ⇒ [ 'Promise' ].<Array.<IScene>>
        • .loadScenesHistoryForDevice(did, timestamp, limit)
        • .deleteSceneRecords(params)
        • .openIftttAutoPage()
        • .openIftttAutoPageWithDid()
        • .openTimerSettingPageWithOptions(options)
        • .openCountDownPage(isCountDownOn, setting)
        • .convertDateToCron(params) ⇒ [ 'Promise' ].<object>
        • .convertCronToDate(params) ⇒ [ 'Promise' ].<object>
      • ~SceneType : object
        • .Timer
        • .Artificial
        • .Automatic
      • ~createScene(deviceID, sceneType, opt) ⇒ IScene
      • ~loadScenes(deviceID, sceneType, opt) ⇒ [ 'Promise' ].<IScene>

Kind: Exported member
Export:

Kind: static interface of module.exports

• .IScene
  • .sceneID : int
  • .isNew : boolean
  • .createTime : long
  • .status : int
  • .deviceID : string
  • .name : string
  • .type : SceneType
  • .isTimer : boolean
  • .isArtificial : boolean
  • .isAutomatic : readonly
  • .identify : string
  • .setting : json
  • .authorizedDeviceIDs : [ 'Array' ].<String>
  • .save(opt) ⇒ [ 'Promise' ].<IScene>
  • .reload() ⇒ [ 'Promise' ].<IScene>
  • .start() ⇒ [ 'Promise' ].<IScene>
  • .remove() ⇒ [ 'Promise' ].<IScene>

场景id

Kind: instance property of IScene
Read only: true

是否是新的场景

Kind: instance property of IScene
Read only: true

场景的创建时间

Kind: instance property of IScene
Read only: true

场景是否开启

Kind: instance property of IScene
Read only: true

定时场景的设备的did

Kind: instance property of IScene
Read only: true

场景名称

Kind: instance property of IScene

场景类型，只读

Kind: instance property of IScene
Read only: true

是否是定时场景，只读

Kind: instance property of IScene
Read only: true

是否是人工场景，只读

Kind: instance property of IScene
Read only: true

是否是自动场景，只读

Kind: instance property of IScene
Read only: true

代表场景的分类，创建场景时可自定义此参数；如果获取场景的时候传入identify，表示获取identify类场景列表；如果不需要对场景分类，此参数可忽略。

Kind: instance property of IScene

场景的更多属性，详见 module:miot/service/scene/createTimerScene

Kind: instance property of IScene

授权设备列表，指场景关联的那些设备的deviceID

Kind: instance property of IScene

保存场景 /scene/edit

Kind: instance method of IScene

Example

scene.save({setting:{...}}).then(scene=>{...})

Example

scene.save().then(scene=>{...}).catch(err=>{...})

重新加载场景数据 /scene/get 用法：scene.reload();

Kind: instance method of IScene

启动场景 /scene/start 用法：scene.start();

Kind: instance method of IScene

删除场景 /scene/delete 用法：scene.remove();

Kind: instance method of IScene

Kind: inner class of module.exports
Export:

• ~IMiotScene
  • .createScene(deviceID, sceneType, opt) ⇒ IScene
  • .createTimerScene(deviceID, opt) ⇒ IScene
  • .createArtificialScene(设备id, opt) ⇒ IScene
  • .createAutomaticScene(deviceID, opt) ⇒ IScene
  • .loadScenes(deviceID, sceneType, opt) ⇒ [ 'Promise' ].<Array.<IScene>>
  • .loadTimerScenes(deviceID, opt) ⇒ [ 'Promise' ].<Array.<IScene>>
  • .loadArtificialScenes(deviceID, opt) ⇒ [ 'Promise' ].<Array.<IScene>>
  • .loadAutomaticScenes(deviceID, opt) ⇒ [ 'Promise' ].<Array.<IScene>>
  • .loadScenesHistoryForDevice(did, timestamp, limit)
  • .deleteSceneRecords(params)
  • .openIftttAutoPage()
  • .openIftttAutoPageWithDid()
  • .openTimerSettingPageWithOptions(options)
  • .openCountDownPage(isCountDownOn, setting)
  • .convertDateToCron(params) ⇒ [ 'Promise' ].<object>
  • .convertCronToDate(params) ⇒ [ 'Promise' ].<object>

创建场景

Kind: instance method of IMiotScene

Example

import {Service, Device, SceneType} from 'miot'
const scene = Service.scene.createScene(Device.deviceID, SceneType.Timer, {
     identify:'identify',
     name:'myTimer',
     setting:{...}
});

scene.save().then(scene=>{
  ...
})

创建定时场景 用法同上面的 createScene(deviceID, SceneType.Timer, opt); 定时中的 crontab string 详见 Linux crontab命令

Kind: instance method of IMiotScene

Example

import {Service, Device, SceneType} from 'miot'
const settinig = {
enable_timer_on: true, //是否开启定时打开。如果enable_timer设置为false，此属性不会起作用
on_time: * * * * *, //crontab string, minute hour day month week。如：59 11 21 3 * 指3月21号11点59分定时开
off_time: * * * * *, //crontab string，同上。
enable_timer_off: true,//是否开启定时关闭。如果enable_timer设置为false，此属性不会起作用
on_method: 'method_name', //咨询硬件工程师,指硬件端，打开开关的方法。miot-spec下，一般为：set_properties
on_param: 'param', //咨询硬件工程师，指硬件端，打开开关应该传入的参数。miot-spec下，一般为：[{did,siid,piid,value}]
off_method: 'method_name', //咨询硬件工程师，指硬件端，关闭开关的方法。miot-spec下，一般为：set_properties
off_param: 'param', //咨询硬件工程师，关闭开关应该传入的参数。 miot-spec下，一般为：[{did,siid,piid,value}]
enable_timer: true, //是否开启此定时器，后续打开，关闭定时器，可以设置此属性
timer_type: "0",//用来区分普通定时和倒计时，为空（或者为"0"）表示普通定时，为"1"表示倒计时
on_filter: "cn_workday" // 后台用来过滤日期,目前只在大陆地区生效：cn_workday 表示工作日，cn_freeday 表示节假日
off_filter:"cn_freeday" // 后台用来过滤日期,目前只在大陆地区生效：cn_workday 表示工作日，cn_freeday 表示节假日
     //
}

const scene = Service.scene.createTimerScene(Device.deviceID, {
     identify:'identify',//同上面的identify
     name:'myTimer',//同上面的名称
     setting:settinig
});

scene.save().then(scene=>{
  ...
})

创建人工场景 same as createScene(deviceID, SceneType.Timer, opt);

Kind: instance method of IMiotScene

创建自动场景 same as createScene(deviceID, SceneType.Automatic, opt);

Kind: instance method of IMiotScene

获取场景列表 /scene/list

Kind: instance method of IMiotScene

加载定时场景 /scene/list

Kind: instance method of IMiotScene

加载人工场景 /scene/list

Kind: instance method of IMiotScene

加载自动场景 /scene/list

Kind: instance method of IMiotScene

获取指定设备的智能日志信息

Kind: instance method of IMiotScene
Since: 10010

批量删除自动化、场景

Kind: instance method of IMiotScene

打开添加智能的页面(米家APP实现)

Kind: instance method of IMiotScene
Since: 10032 ,SDKLevel 10032 开始提供使用,注意分享的用户无法打开
Example

Service.scene.openIftttAutoPage()

打开特定设备的智能页面

Kind: instance method of IMiotScene
Since: 10045

打开时间设置页面(米家APP实现)

Kind: instance method of IMiotScene
Since: 10032 ,SDKLevel 10032 开始提供使用

Example

Service.scene.openTimerSettingPageWithOptions({onMethod:"power_on", onParam: "on", offMethod: "power_off", offParam: "off", displayName:"设置xxx定时"，identify:"plug_usb_countdowm"})

开启倒计时界面

Kind: instance method of IMiotScene

Example

Service.scene.openCountDownPage(true, {onMethod:"power_on", offMethod:'power_off', onParam:'on', offParam:'off',displayName:"新名字"})

将时和分转化为cron表达式

Kind: instance method of IMiotScene
Returns: [ 'Promise' ].<object> - 成功时：{"data":"xxx","code":0} 例如：{"data":"16 30 18 18 1 * 2020","code":0} 失败时：{"code":xxx, "message":"xxx" }
Since: 10034

Example

可参考 com.xiaomi.demo 中的 SceneDemo.js

将cron表达式转化为时和分

Kind: instance method of IMiotScene
Returns: [ 'Promise' ].<object> - 成功时：{"data":{object},"code":0} 例如： { "data": { "weekday": [ true, true, false, false, true, true, true ], "timerOnDetail": "12:30", "repeatStr": "周日, 周一, 周四, 周五, 周六", "repeatType": 4, "minute": 30, "hour": 12 }, "code": 0 } 失败时：{"code":xxx, "message":"xxx" }
Since: 10034

Example

可参考 com.xiaomi.demo 中的 SceneDemo.js

场景类型

Kind: inner namespace of module.exports

• ~SceneType : object
  • .Timer
  • .Artificial
  • .Automatic

定时场景

Kind: static constant of SceneType

人工场景

Kind: static constant of SceneType

自动场景

Kind: static constant of SceneType

创建场景

Kind: inner method of module.exports

加载场景

Kind: inner method of module.exports