智能家居计时器特征架构

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] 的范围内。

示例

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

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

设备出错

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