サーモスタット

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

sdm.devices.types.THERMOSTAT

トレイト

リファレンス

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

トレイト説明コマンド
通信方式このトレイトは、接続情報を持つデバイスに使用します。
ファンこのトレイトは、ファンを制御するシステム機能を備えたデバイスに使用します。SetTimer
湿度このトレイトは、湿度を測定するセンサーを備えたデバイスに使用します。
情報このトレイトは、デバイス関連の情報に使用します。
設定このトレイトは、デバイス関連の設定情報に使用します。
温度このトレイトは、温度を測定するセンサーを備えたデバイスに使用します。
ThermostatEcoこのトレイトは、エコモードをサポートする THERMOSTAT デバイスタイプに使用します。SetMode
ThermostatHvacこのトレイトは、暖房換気空調システムの詳細を報告できる 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 コマンドを使用します。

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

たとえば、標準のサーモスタット モードのいずれかを変更するには、次のようにします。

リクエスト

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 に設定されている場合は、温度設定値を変更できません。

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

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

モード コマンド フィールド
暖房 SetHeat heatCelsius
COOL SetCool coolCelsius
暖房・冷房 SetRange heatCelsius、coolCelsius

Google Nest サーモスタットでは温度を摂氏または華氏で表示できますが、設定値コマンドではパラメータとして摂氏のみを使用します。

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

リクエスト

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 ステータスになっていないか確認します。デバイスがインターネットに接続されていることを確認し、Nest サービスが起動していることを確認します。

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

ペイロード

{
  "eventId" : "6ac04910-dab8-40c0-8d16-63645e9b801c",
  "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"
  ]
}

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

トレイト フィールドが変更されると、イベントが生成されます。 たとえば、サーモスタットの暖房換気空調ステータスが HEATING に変更された場合は、次の resourceUpdate イベントを受信します。

ペイロード

{
  "eventId" : "1dc5ae6d-7334-4a71-8bb1-3e50d452a322",
  "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 トレイトの変更がシステムが実際にオンになると、別の イベントとして後で送信されます。暖房換気空調システムのオンに遅延がなかった場合は、 3 つのイベントがすべて同時に送信されます。

エラー

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

エラー メッセージ RPC トラブルシューティング
Cool value must be greater than heat value. INVALID_ARGUMENT コマンドの heatCelsius フィールドが coolCelsius フィールドより小さいことを確認してください。
Command not allowed in current thermostat mode. FAILED_PRECONDITION 一部のサーモスタット モデルでは、ThermostatMode トレイトに従って、サーモスタット モードが OFF のときにエコモードを変更することはできません。 エコモードを変更する前に、サーモスタット モードを HEAT、COOL、HEATCOOL に変更する必要があります。
Thermostat fan unavailable. FAILED_PRECONDITION サーモスタットにファン機能はありません。 このデバイスでは、ファン関連のトレイトとコマンドを使用できません。
Command not allowed when thermostat in MANUAL_ECO mode. FAILED_PRECONDITION サーモスタットが手動エコモードの場合、温度設定値を設定できません。

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