智能家居计时器特征架构

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

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

设备属性

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

属性 类型 说明
maxTimerLimitSec 整数

必填。

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

（默认值：false）

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

示例

具有 2 小时计时器限制的设备。

{
  "maxTimerLimitSec": 7200
}

设备状态

具有此特征的实体可能会在 QUERY 操作过程中报告以下状态。如需详细了解如何处理 QUERY intent，请参阅 intent 执行方式。

州 类型 说明
timerRemainingSec 整数

必填。

当前剩余时间（以秒为单位）、-1 或 [0, maxTimerLimitSec]。设置为 -1 表示没有计时器在运行。
timerPaused Boolean

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

示例

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

{
  "timerRemainingSec": -1
}

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

{
  "timerRemainingSec": 60
}

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

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

设备命令

具有此特征的设备可能会在 EXECUTE 操作过程中响应以下命令。如需详细了解如何处理 EXECUTE intent，请参阅 intent 执行方式。

action.devices.commands.TimerStart

启动一个新的计时器。

参数

参数 类型 说明
timerTimeSec 整数

必填。

计时器的时长（以秒为单位）；必须在 [1, maxTimerLimitSec] 以内。

示例

让设备计时器运行 5 分钟。

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

启动计时器时出错。

支持的值：

noTimerExists
timerValueOutOfRange
aboveMaximumTimerDuration
belowMinimumTimerDuration

action.devices.commands.TimerAdjust

调整计时器时长。

参数

参数 类型 说明
timerTimeSec 整数

必填。

对计时器的正/负调整（以秒为单位）；该值必须在 [-maxTimerLimitSec, maxTimerLimitSec] 的范围内。

示例

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

{
  "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

设备出错

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