02 场景模块

miot/service/scene

场景相关服务, 包括定时,人工与自动场景（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
    - ~createScene(deviceID, sceneType, opt) ⇒ IScene
    - ~loadScenes(deviceID, sceneType, opt) ⇒ [ 'Promise' ].<IScene>

module.exports ⏏

Kind: Exported member
Export:

module.exports.IScene

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>

iScene.sceneID : `int`

场景id

Kind: instance property of IScene
Read only: true

iScene.isNew : `boolean`

是否是新的场景

Kind: instance property of IScene
Read only: true

iScene.createTime : `long`

场景的创建时间

Kind: instance property of IScene
Read only: true

iScene.status : `int`

场景是否开启

Kind: instance property of IScene
Read only: true

iScene.deviceID : `string`

定时场景的设备的did

Kind: instance property of IScene
Read only: true

iScene.name : `string`

场景名称

Kind: instance property of IScene

iScene.type : `SceneType`

场景类型，只读

Kind: instance property of IScene
Read only: true

iScene.isTimer : `boolean`

是否是定时场景，只读

Kind: instance property of IScene
Read only: true

iScene.isArtificial : `boolean`

是否是人工场景，只读

Kind: instance property of IScene
Read only: true

iScene.isAutomatic : `readonly`

是否是自动场景，只读

Kind: instance property of IScene
Read only: true

iScene.identify : `string`

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

Kind: instance property of IScene

iScene.setting : `json`

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

Kind: instance property of IScene

iScene.authorizedDeviceIDs : `[ 'Array' ].<String>`

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

Kind: instance property of IScene

iScene.save(opt) ⇒ `[ 'Promise' ].<IScene>`

保存场景 /scene/edit

Kind: instance method of IScene

Param	Type	Default	Description
opt	`json`		{authed:[...], name, identify, setting} 同上面的authed，name，identify，setting

Example

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

Example

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

iScene.reload() ⇒ `[ 'Promise' ].<IScene>`

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

Kind: instance method of IScene

iScene.start() ⇒ `[ 'Promise' ].<IScene>`

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

Kind: instance method of IScene

iScene.remove() ⇒ `[ 'Promise' ].<IScene>`

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

Kind: instance method of IScene

module.exports~IMiotScene

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>

iMiotScene.createScene(deviceID, sceneType, opt) ⇒ `IScene`

创建场景

Kind: instance method of IMiotScene

Param	Type	Description
deviceID	`string`	设备id
sceneType	`SceneType`	场景类型
opt	`object`	{identify, us_id, name, setting }
opt.identify	`string`
opt.us_id	`string`	场景的唯一标识。创建时传"0"
opt.name	`string`	场景名称
opt.setting	`object`	可参考createTimerScene

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=>{
  ...
})

iMiotScene.createTimerScene(deviceID, opt) ⇒ `IScene`

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

Kind: instance method of IMiotScene

Param	Type
deviceID	`string`
opt	`json`

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=>{
  ...
})

iMiotScene.createArtificialScene(设备id, opt) ⇒ `IScene`

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

Kind: instance method of IMiotScene

Param	Type	Description
设备id	`string`
opt	`json`	同上面opt

iMiotScene.createAutomaticScene(deviceID, opt) ⇒ `IScene`

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

Kind: instance method of IMiotScene

Param	Type	Description
deviceID	`string`	设备id
opt	`json`	同上面opt

iMiotScene.loadScenes(deviceID, sceneType, opt) ⇒ `[ 'Promise' ].<Array.<IScene>>`

获取场景列表 /scene/list

Kind: instance method of IMiotScene

Param	Type	Description
deviceID	`*`	设备id
sceneType	`*`	场景类型
opt	`json`	{identify,name}

iMiotScene.loadTimerScenes(deviceID, opt) ⇒ `[ 'Promise' ].<Array.<IScene>>`

加载定时场景 /scene/list

Kind: instance method of IMiotScene

Param	Type	Default	Description
deviceID	`*`		设备id
opt	`json`		{identify}

iMiotScene.loadArtificialScenes(deviceID, opt) ⇒ `[ 'Promise' ].<Array.<IScene>>`

加载人工场景 /scene/list

Kind: instance method of IMiotScene

Param	Type	Default	Description
deviceID	`*`		设备id
opt	`json`		{identify,name}

iMiotScene.loadAutomaticScenes(deviceID, opt) ⇒ `[ 'Promise' ].<Array.<IScene>>`

加载自动场景 /scene/list

Kind: instance method of IMiotScene

Param	Type	Default	Description
deviceID	`*`		设备id
opt	`json`		{identify,name}

iMiotScene.loadScenesHistoryForDevice(did, timestamp, limit)

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

Kind: instance method of IMiotScene
Since: 10010

Param	Type	Default	Description
did	`string`		拉取设备的did
timestamp	`long`		时间戳限制
limit	`int`	`50`	拉取日志数量限制，小于等于50

iMiotScene.deleteSceneRecords(params)

批量删除自动化、场景

Kind: instance method of IMiotScene

Param	Type	Description
params	`Array`	自动化、场景us_id数组

iMiotScene.openIftttAutoPage()

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

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

Service.scene.openIftttAutoPage()

iMiotScene.openIftttAutoPageWithDid()

打开特定设备的智能页面

Kind: instance method of IMiotScene
Since: 10045

iMiotScene.openTimerSettingPageWithOptions(options)

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

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

Param	Type	Description
options	`object`	配置信息
options.onMethod	`string`	配置定时开启的 method 名，同上面openTimerSettingPageWithVariousTypeParams的参数onMethod
options.onParam	`string`	配置定时开启的参数，同上面openTimerSettingPageWithVariousTypeParams的参数onParam
options.offMethod	`string`	配置定时关闭的 method 名，同上面openTimerSettingPageWithVariousTypeParams的参数offMethod
options.offParam	`string`	配置定时关闭的参数，同上面openTimerSettingPageWithVariousTypeParams的参数offParam
options.timerTitle	`string`	定时列表页自定义标题
options.displayName	`string`	配置场景日志显示的名称
options.identify	`string`	自定义定时Identifier
options.onTimerTips	`string`	定时列表页面、设置时间页面打开副标题（默认：开启时间）
options.offTimerTips	`string`	定时列表页面、设置时间页面关闭时间副标题（默认：关闭时间）
options.listTimerTips	`string`	定时列表页面定时时间段副标题（默认：开启时段）
options.bothTimerMustBeSet	`boolean`	是否强制要求设置时间段？ true: 强制设置时间段(默认：false)如果设置true,忽略下面三个参数
options.showOnTimerType	`boolean`	是否可以创建：定时开启？ true: 可以，false:不可以(默认：true)
options.showOffTimerType	`boolean`	是否可以创建：定时关闭？ true: 可以，false:不可以(默认：true)
options.showPeriodTimerType	`boolean`	是否可以创建：时间段定时？ true: 可以，false:不可以(默认：true)
options.did	`string`	设备did，可为空，@since 10045 注意：showOnTimerType、showOffTimerType、showPeriodTimerType三个参数至少有一个为true，才有效，否则三个中任意都会被忽略掉

Example

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

iMiotScene.openCountDownPage(isCountDownOn, setting)

开启倒计时界面

Kind: instance method of IMiotScene

Param	Type	Description
isCountDownOn	`Boolean`	设备的当前状态:YES 为开启，所以我们启动关闭倒计时; NO 为关闭，所以我们启动开启倒计时
setting	`object`	设置倒计时页面的属性
setting.onMethod	`string`	指硬件端，打开倒计时应该执行的方法，请咨询硬件工程师
setting.onParam	`string`	指硬件端，打开倒计时应该传入的参数，请咨询硬件工程师
setting.offMethod	`string`	指硬件端，关闭倒计时应该执行的方法，请咨询硬件工程师
setting.offParam	`string`	指硬件端，关闭倒计时应该传入的参数，请咨询硬件工程师
setting.identify	`string`	since 10021, 用于设置倒计时的identify
options.displayName	`string`	配置场景日志显示的名称：注意，不会更改倒计时页面的标题，只会上传到服务端

Example

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

iMiotScene.convertDateToCron(params) ⇒ `[ 'Promise' ].<object>`

将时和分转化为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

Param	Type	Description
params	`object`
params.hour	`int`	时
params.minute	`int`	分
params.on_filter	`string`	定时开启标识符中国大陆法定节假日 cn_freeday 中国大陆法定工作日 cn_workday 其他不填，为空
params.off_filter	`string`	定时关闭标识符中国大陆法定节假日 cn_freeday 中国大陆法定工作日 cn_workday 其他不填，为空
params.repeatType	`int`	重复类型 0: 执行一次 1: 每天 2 :中国大陆法定工作日 3：中国大陆法定节假日 4: 自定义
params.weekday	`array`	当repeatType为4的时候才有效，必须将七天的数据都带上 [true, // 代表周日被选中 true, // 代表周一被选中 false, // 代表周一未被选中 false, true, true, true]

Example

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

iMiotScene.convertCronToDate(params) ⇒ `[ 'Promise' ].<object>`

将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

Param	Type	Description
params	`Object`	{ "cron": "58 30 12 * * 0,1,2,3,4,5,6 *", "on_filter": "cn_workday", // 定时开启标识符这两个参数一般由服务端传回 "off_filter": "cn_workday", // 定时关闭标识符这两个参数一般由服务端传回 } 中国大陆法定节假日 cn_freeday 中国大陆法定工作日 cn_workday 其他不填，为空

Example

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

module.exports~SceneType : `object`

场景类型

Kind: inner namespace of module.exports

~SceneType : object

SceneType.Timer

定时场景

Kind: static constant of SceneType

SceneType.Artificial

人工场景

Kind: static constant of SceneType

SceneType.Automatic

自动场景

Kind: static constant of SceneType

module.exports~createScene(deviceID, sceneType, opt) ⇒ `IScene`

创建场景

Kind: inner method of module.exports

Param	Type	Description
deviceID	`string`	设备id
sceneType	`SceneType`	场景类型
opt	`object`	{identify, us_id, name, setting }
opt.identify	`string`
opt.us_id	`string`	场景的唯一标识。创建时传"0"
opt.name	`string`	场景名称
opt.setting	`object`	可参考createTimerScene

module.exports~loadScenes(deviceID, sceneType, opt) ⇒ `[ 'Promise' ].<IScene>`

加载场景

Kind: inner method of module.exports

Param	Type	Description
deviceID	`string`	设备id
sceneType	`SceneType`	场景类型
opt	`*`	{identify,name} 同上面的identify，name

02 场景模块

miot/service/scene

module.exports ⏏

module.exports.IScene

iScene.sceneID : int

iScene.isNew : boolean

iScene.createTime : long

iScene.status : int

iScene.deviceID : string

iScene.name : string

iScene.type : SceneType

iScene.isTimer : boolean

iScene.isArtificial : boolean

iScene.isAutomatic : readonly

iScene.identify : string

iScene.setting : json

iScene.authorizedDeviceIDs : [ 'Array' ].<String>

iScene.save(opt) ⇒ [ 'Promise' ].<IScene>

iScene.reload() ⇒ [ 'Promise' ].<IScene>

iScene.start() ⇒ [ 'Promise' ].<IScene>

iScene.remove() ⇒ [ 'Promise' ].<IScene>

module.exports~IMiotScene

iMiotScene.createScene(deviceID, sceneType, opt) ⇒ IScene

iMiotScene.createTimerScene(deviceID, opt) ⇒ IScene

iMiotScene.createArtificialScene(设备id, opt) ⇒ IScene

iMiotScene.createAutomaticScene(deviceID, opt) ⇒ IScene

iMiotScene.loadScenes(deviceID, sceneType, opt) ⇒ [ 'Promise' ].<Array.<IScene>>

iMiotScene.loadTimerScenes(deviceID, opt) ⇒ [ 'Promise' ].<Array.<IScene>>

iMiotScene.loadArtificialScenes(deviceID, opt) ⇒ [ 'Promise' ].<Array.<IScene>>

iMiotScene.loadAutomaticScenes(deviceID, opt) ⇒ [ 'Promise' ].<Array.<IScene>>

iMiotScene.loadScenesHistoryForDevice(did, timestamp, limit)

iMiotScene.deleteSceneRecords(params)

iMiotScene.openIftttAutoPage()

iMiotScene.openIftttAutoPageWithDid()

iMiotScene.openTimerSettingPageWithOptions(options)

iMiotScene.openCountDownPage(isCountDownOn, setting)

iMiotScene.convertDateToCron(params) ⇒ [ 'Promise' ].<object>

iMiotScene.convertCronToDate(params) ⇒ [ 'Promise' ].<object>

module.exports~SceneType : object

SceneType.Timer

SceneType.Artificial

SceneType.Automatic

module.exports~createScene(deviceID, sceneType, opt) ⇒ IScene

module.exports~loadScenes(deviceID, sceneType, opt) ⇒ [ 'Promise' ].<IScene>

Home

API文档

迁移文档

RN版本升级54-61

iOS 旧版本迁移

Clone this wiki locally

iScene.sceneID : `int`

iScene.isNew : `boolean`

iScene.createTime : `long`

iScene.status : `int`

iScene.deviceID : `string`

iScene.name : `string`

iScene.type : `SceneType`

iScene.isTimer : `boolean`

iScene.isArtificial : `boolean`

iScene.isAutomatic : `readonly`

iScene.identify : `string`

iScene.setting : `json`

iScene.authorizedDeviceIDs : `[ 'Array' ].<String>`

iScene.save(opt) ⇒ `[ 'Promise' ].<IScene>`

iScene.reload() ⇒ `[ 'Promise' ].<IScene>`

iScene.start() ⇒ `[ 'Promise' ].<IScene>`

iScene.remove() ⇒ `[ 'Promise' ].<IScene>`

iMiotScene.createScene(deviceID, sceneType, opt) ⇒ `IScene`

iMiotScene.createTimerScene(deviceID, opt) ⇒ `IScene`

iMiotScene.createArtificialScene(设备id, opt) ⇒ `IScene`

iMiotScene.createAutomaticScene(deviceID, opt) ⇒ `IScene`

iMiotScene.loadScenes(deviceID, sceneType, opt) ⇒ `[ 'Promise' ].<Array.<IScene>>`

iMiotScene.loadTimerScenes(deviceID, opt) ⇒ `[ 'Promise' ].<Array.<IScene>>`

iMiotScene.loadArtificialScenes(deviceID, opt) ⇒ `[ 'Promise' ].<Array.<IScene>>`

iMiotScene.loadAutomaticScenes(deviceID, opt) ⇒ `[ 'Promise' ].<Array.<IScene>>`

iMiotScene.convertDateToCron(params) ⇒ `[ 'Promise' ].<object>`

iMiotScene.convertCronToDate(params) ⇒ `[ 'Promise' ].<object>`

module.exports~SceneType : `object`

module.exports~createScene(deviceID, sceneType, opt) ⇒ `IScene`

module.exports~loadScenes(deviceID, sceneType, opt) ⇒ `[ 'Promise' ].<IScene>`