智能家居计时器特征架构

action.devices.traits.Timer - Timer 特征表示设备上的计时器。

例如，智能洒水控制器或智能灯开关可能具有内置计时器。此特征可用于控制设备上的内置计时器，例如启动新计时器、暂停和取消正在运行的计时器，以及询问剩余时间。

设备属性

具有此特征的设备可能会在 SYNC 操作中报告以下属性。如需详细了解如何处理 SYNC intent，请参阅 Intent 实现。

属性 类型 说明
maxTimerLimitSec 整数

必填。

表示设备上可用的最长计时器设置（以秒为单位）。

最小值：1。
commandOnlyTimer 布尔值

（默认值：false）

指示设备是否支持单向 (true) 或双向 (false) 通信。如果设备无法响应此特征的 QUERY intent 或报告状态，请将此属性设置为 true。

示例

设备设置了 2 小时的计时器限制。

{
  "maxTimerLimitSec": 7200
}

设备状态

具有此特征的实体可能会报告以下状态作为 QUERY 操作的一部分。如需详细了解如何处理 QUERY intent，请参阅intent 执行。

州 类型 说明
timerRemainingSec 整数

必填。

以秒为单位的当前剩余时间，-1 或 [0, maxTimerLimitSec]。设置为 -1 表示没有正在运行的计时器。
timerPaused 布尔值

如果存在有效但目前处于暂停状态的计时器，则为 true。

示例

设备计时器还剩多长时间？（未运行）。

{
  "timerRemainingSec": -1
}

设备计时器还剩多长时间？（正在运行）。

{
  "timerRemainingSec": 60
}

设备计时器还剩多长时间？（已暂停）。

{
  "timerRemainingSec": 30,
  "timerPaused": true
}

设备命令

具有此特征的设备可能会响应以下命令，作为 EXECUTE 操作的一部分。如需详细了解如何处理 EXECUTE intent，请参阅 Intent 实现。

action.devices.commands.TimerStart

开始新的定时。

参数

参数 类型 说明
timerTimeSec 整数

必填。

计时器的时长（以秒为单位）；必须介于 [1, maxTimerLimitSec] 之间。

最小值：1。

示例

运行设备计时器 5 分钟。

{
  "command": "action.devices.commands.TimerStart",
  "params": {
    "timerTimeSec": 300
  }
}

启动计时器时出错。

支持的值：

noTimerExists
timerValueOutOfRange
aboveMaximumTimerDuration
belowMinimumTimerDuration

action.devices.commands.TimerAdjust

调整计时器时长。

参数

参数 类型 说明
timerTimeSec 整数

必填。

以秒为单位的正向或负向计时器调整值；必须介于 [-maxTimerLimitSec, maxTimerLimitSec] 之间。

示例

将设备计时器延长 1 分钟。

{
  "command": "action.devices.commands.TimerAdjust",
  "params": {
    "timerTimeSec": 60
  }
}

从设备计时器中减去 30 秒。

{
  "command": "action.devices.commands.TimerAdjust",
  "params": {
    "timerTimeSec": -30
  }
}

调整计时器时出错。

支持的值：

noTimerExists
timerValueOutOfRange
aboveMaximumTimerDuration
belowMinimumTimerDuration

action.devices.commands.TimerPause

暂停计时器。

参数

参数 类型 说明

没有属性

示例

暂停设备计时器。

{
  "command": "action.devices.commands.TimerPause",
  "params": {}
}

暂停计时器时出错。

支持的值：

noTimerExists

action.devices.commands.TimerResume

继续计时。

参数

参数 类型 说明

没有属性

示例

恢复设备计时器。

{
  "command": "action.devices.commands.TimerResume",
  "params": {}
}

恢复计时器时出错。

支持的值：

noTimerExists

action.devices.commands.TimerCancel

取消计时器。

参数

参数 类型 说明

没有属性

示例

停止设备计时器。

{
  "command": "action.devices.commands.TimerCancel",
  "params": {}
}

停止计时器时出错。

支持的值：

noTimerExists

设备错误

查看错误和异常的完整列表。