智慧型住宅計時器特徵結構定義

action.devices.traits.Timer - Timer 特徵代表裝置上的計時器。

舉例來說，智慧灑水控制器或智慧燈具開關可能內建計時器。這項特徵可用於控制裝置的內建計時器，例如啟動新計時器、暫停及取消執行中的計時器，以及詢問剩餘時間。

裝置屬性

具有這項特徵的裝置可能會回報下列屬性，做為 SYNC 作業的一部分。如要進一步瞭解如何處理 SYNC 意圖，請參閱「意圖完成」。

屬性 類型 說明
maxTimerLimitSec 整數

必要。

表示裝置可設定的最長計時器時間 (以秒為單位)。

最小值：1。
commandOnlyTimer 布林值

(預設值：false)

指出裝置是否支援單向 (true) 或雙向 (false) 通訊。如果裝置無法回應這項特徵的 QUERY 意圖或回報狀態，請將這個屬性設為 true。

範例

裝置的計時器限制為兩小時。

{
  "maxTimerLimitSec": 7200
}

裝置狀態

具有這項特徵的實體可能會回報下列狀態，做為 QUERY 作業的一部分。如要進一步瞭解如何處理 QUERY 意圖，請參閱「意圖完成」。

州 類型 說明
timerRemainingSec 整數

必要。

以秒為單位的剩餘時間、-1 或 [0, maxTimerLimitSec]。設為 -1 表示沒有計時器正在執行。
timerPaused 布林值

如果目前有暫停中的有效計時器，則為 True。

範例

裝置計時器還剩多少時間？(未執行)。

{
  "timerRemainingSec": -1
}

裝置計時器還剩多少時間？(正在執行)。

{
  "timerRemainingSec": 60
}

裝置計時器還剩多少時間？(已暫停)。

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

裝置指令

具有這項特徵的裝置可能會在 EXECUTE 作業中回應下列指令。如要進一步瞭解如何處理 EXECUTE 意圖，請參閱「意圖完成」。

action.devices.commands.TimerStart

啟動新的計時器。

參數

參數 類型 說明
timerTimeSec 整數

必要。

計時器時間長度 (以秒為單位)，必須介於 [1, maxTimerLimitSec]。

最小值：1。

範例

將裝置計時器設為五分鐘。

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

裝置錯誤

請參閱「錯誤和例外狀況」的完整清單。