サーモスタット

Smart Device Management（SDM）API では、Google Nest Thermostat のすべてのモデルがサポートされています。これらのデバイスは THERMOSTAT デバイスタイプを返します。

sdm.devices.types.THERMOSTAT

トレイト

リファレンス

このグループに関連する特性、コマンド、イベントは次のとおりです。

トレイト説明コマンド
接続このトレイトは、接続情報を持つデバイスに使用します。
ファンこのトレイトは、ファンを制御するシステム機能を備えたデバイスに使用します。SetTimer
湿度このトレイトは、湿度を測定するセンサーを備えたデバイスに使用します。
情報このトレイトは、デバイス関連の情報を提供するデバイスに使用します。
設定このトレイトは、デバイス関連の設定情報を提供するデバイスに使用します。
温度このトレイトは、温度を測定するセンサーを備えたデバイスに使用します。
ThermostatEcoこのトレイトは、ECO モードをサポートする THERMOSTAT のデバイスタイプに属します。SetMode
ThermostatHvacこのトレイトは、HVAC の詳細を報告できる THERMOSTAT のデバイスタイプに属します。
ThermostatModeこのトレイトは、さまざまなサーモスタット モードをサポートする THERMOSTAT のデバイスタイプに属します。SetMode
ThermostatTemperatureSetpointこのトレイトは、目標温度と温度範囲の設定に対応する THERMOSTAT のデバイスタイプに属します。SetHeat
SetCool
SetRange

JSON

GET レスポンスにトレイトがない場合は、そのトレイトまたは機能が現在デバイスで利用できないことを示します。詳細については、デバイスタイプをご覧ください。

{
  "type" : "sdm.devices.types.THERMOSTAT",
  "traits" : {
    "sdm.devices.traits.Connectivity" : {
      "status" : "ONLINE"
    },
    "sdm.devices.traits.Fan" : {
      "timerMode" : "ON",
      "timerTimeout" : "2019-05-10T03:22:54Z"
    },
    "sdm.devices.traits.Humidity" : {
      "ambientHumidityPercent" : 35.0
    },
    "sdm.devices.traits.Info" : {
      "customName" : "My device"
    },
    "sdm.devices.traits.Settings" : {
      "temperatureScale" : "CELSIUS"
    },
    "sdm.devices.traits.Temperature" : {
      "ambientTemperatureCelsius" : 23.0
    },
    "sdm.devices.traits.ThermostatEco" : {
      "availableModes" : ["MANUAL_ECO", "OFF"],
      "mode" : "MANUAL_ECO",
      "heatCelsius" : 20.0,
      "coolCelsius" : 22.0
    },
    "sdm.devices.traits.ThermostatHvac" : {
      "status" : "HEATING"
    },
    "sdm.devices.traits.ThermostatMode" : {
      "availableModes" : ["HEAT", "COOL", "HEATCOOL", "OFF"],
      "mode" : "COOL"
    },
    "sdm.devices.traits.ThermostatTemperatureSetpoint" : {
      "heatCelsius" : 20.0,
      "coolCelsius" : 22.0
    }
  }
}

温度と湿度

サーモスタットの周囲温度を読み取るには、Temperature トレイトを使用します。周囲温度はデバイスで測定されます。

サーモスタットの周囲の湿度を読み取るには、Humidity トレイトを使用します。周囲の湿度はデバイスで測定されます。

温度目盛り

Google Nest サーモスタットでは、温度を摂氏または華氏で表示できますが、SDM API で目盛りを設定することはできません。ユーザーが現在設定している温度スケールを特定するには、Settings トレイトを使用します。

モードを変更する

サーモスタットのモードは、ThermostatMode とThermostatEcoの 2 つの異なるトレイトによって管理されます。

標準モード

サーモスタットのモードを HEAT、COOL、HEATCOOL に変更するには、ThermostatMode トレイトの SetMode コマンドを使用します。

このコマンドは、サーモスタットのモードをオフにするためにも使用できます。エコモードをオンにするために使用することはできません。

たとえば、標準のサーモスタット モードの 1 つを変更するには:

リクエスト

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatMode.SetMode",
  "params" : {
    "mode" : "HEAT"
  }
}

レスポンス

{}

エコモード

エコモードをオンにするには、ThermostatEco トレイトの SetMode コマンドでモードとして MANUAL_ECO を使用します。

リクエスト

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatEco.SetMode",
  "params" : {
    "mode" : "MANUAL_ECO"
  }
}

レスポンス

{}

このコマンドは、エコモードの現在のステータスまたは変更に基づいて、他のトレイトに影響します。

  • エコモードがオフの場合、サーモスタット モードは、最後に有効だった標準モード（HEAT、COOL、HEATCOOL、OFF）にデフォルト設定されます。
  • エコモードが MANUAL_ECO の場合:

設定温度を変更する

設定温度を変更できるのは、サーモスタットが HEAT、COOL、HEATCOOL のいずれかのモードになっている場合のみです。また、設定できる温度はサーモスタットの現在のモードに対応しています。モードが OFF の場合、またはエコモードが MANUAL_ECO に設定されている場合、温度設定値を変更することはできません。

温度設定値を変更する前に、サーモスタットが呼び出されるコマンドに対応するモードになっている必要があります。設定値を変更するコマンドとフィールドは、サーモスタットのモードによって異なります。

たとえば、SetHeat コマンドを発行するには、まずサーモスタットが HEAT モードになっている必要があります。

モード コマンド フィールド
暖房 SetHeat heatCelsius
涼しい SetCool coolCelsius
HEATCOOL SetRange heatCelsius、coolCelsius

Google Nest サーモスタットは温度を摂氏または華氏で表示できますが、設定温度コマンドのパラメータとして摂氏のみが使用されることに注意してください。

サーモスタットがエコモードの場合、

たとえば、サーモスタットが暖房モードのときに設定温度を変更するには、ThermostatTemperatureSetpoint トレイトの SetHeat コマンドを使用します。

リクエスト

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatTemperatureSetpoint.SetHeat",
  "params" : {
    "heatCelsius" : 22.0
  }
}

レスポンス

{}

エコモードの設定値

ThermostatEco トレイトから返される heatCelsius と coolCelsius の設定値はユーザーが設定したものであり、SDM API を介して変更することはできません。

扇風機をオンまたはオフにする

サーモスタットがファンをサポートしている場合は、Fan トレイトの SetTimer コマンドを使用してオンまたはオフにします。オンにする場合は、ファンを動作させる時間を秒単位で指定できます。

たとえば、ファンを 1 時間動作させるには:

リクエスト

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.Fan.SetTimer",
  "params" : {
    "timerMode" : "ON",
    "duration" : "3600s"
  }
}

レスポンス

{}

duration フィールドを省略すると、ファンはデフォルトの 15 分間動作します。

デバイスの接続を確認する

デバイスがコマンドに応答しない、イベントを送信しない、デバイスに関連する API からエラーが返される場合は、Connectivity トレイトを使用して、デバイスの接続ステータスが OFFLINE になっていないか確認します。デバイスのインターネット接続を確認し、Google Nest サービスが稼働していることを確認します。

イベントが有効になっている場合は、デバイスがオフラインになったことを示すリソース イベントも受信しているはずです。

ペイロード

{
  "eventId" : "c10c1ae5-2bf3-434b-a77f-42a2b94f689b",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.Connectivity" : {
        "status" : "OFFLINE"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

デバイス イベントに対応する

特性フィールドが変更されると、イベントが生成されます。 たとえば、サーモスタットの HVAC ステータスが HEATING に変更された場合、次のような resourceUpdate イベントが届きます。

ペイロード

{
  "eventId" : "880ace18-f08a-4703-8d46-ddba8a7c9542",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.ThermostatHvac" : {
        "status" : "HEATING"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

このデバイスタイプに関連付けられたすべてのトレイトに対してイベントがトリガーされます。統合の一部としてイベントに何らかの方法で対応する必要がある場合は、[イベントを有効にする] をオンにします。

イベントのタイミング

暖房換気空調ステータスの変更イベントは、サーモスタット モードの変更イベントと同時に配信されない場合があります。

たとえば、暖房換気空調システムを保護するために、サーモスタットの暖房モードまたは冷房モードの開始が遅れることがあります。このシナリオでは、サーモスタットのモードを変更すると、最初は ThermostatMode と ThermostatTemperatureSetpoint の特性変更のイベントのみが送信され、システムが実際にオンになると、 ThermostatHvac の特性変更が別のイベントとして後で送信されます。HVAC システムのオンに遅延がなかった場合、3 つのイベントはすべて同時に送信されます。

エラー

このデバイスに関連して、次のエラーコードが返されることがあります。

エラー メッセージ RPC トラブルシューティング
冷房の値は暖房の値よりも大きくする必要があります。 INVALID_ARGUMENT コマンドの heatCelsius フィールドが coolCelsius フィールドより小さいことを確認します。
現在のサーモスタット モードではコマンドが許可されていません。 FAILED_PRECONDITION ThermostatMode トレイトによると、サーモスタットのモードがオフの場合、一部のサーモスタット モデルではエコモードの変更がサポートされていません。エコモードを変更する前に、サーモスタットのモードを HEAT、COOL、HEATCOOL に変更する必要があります。
サーモスタットのファンを使用できません。 FAILED_PRECONDITION サーモスタットに送風機能がありません。このデバイスでは、ファン関連の特性とコマンドを使用できません。
サーモスタットが MANUAL_ECO モードの場合、コマンドは許可されません。 FAILED_PRECONDITION サーモスタットが手動エコモードの場合、設定温度を設定することはできません。

API エラーコードの一覧については、API エラーコードのリファレンスをご覧ください。