サーモスタット

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

sdm.devices.types.THERMOSTAT

トレイト

リファレンス

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

トレイト説明コマンド
接続このトレイトは、接続情報を持つデバイスに使用します。
ファンこのトレイトは、ファンを制御するシステム機能を持つデバイスに使用します。SetTimer
Humidityこのトレイトは、湿度を測定するセンサーを備えたデバイスに使用します。
情報このトレイトは、デバイス関連の情報を持つすべてのデバイスに使用します。
設定このトレイトは、デバイス関連の設定情報を持つデバイスに使用します。
温度このトレイトは、温度を測定するセンサーを備えたデバイスに使用します。
ThermostatEcoこのトレイトは、エコモードをサポートするサーモスタット デバイス タイプに使用します。SetMode
ThermostatHvacこのトレイトは、暖房換気空調システムの詳細を報告できるサーモスタット デバイス タイプに使用します。
ThermostatModeこのトレイトは、さまざまなサーモスタット モードをサポートするサーモスタットのデバイスタイプに使用します。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 Thermostat では温度を摂氏または華氏で表示できますが、SDM API で目盛りを設定することはできません。ユーザーが現在設定している温度スケールを特定するには、Settings トレイトを使用します。

モードを変更する

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

標準モード

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

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

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

リクエスト

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 の場合:

設定温度を変更する

設定温度は、サーモスタットが暖房モード、冷房モード、暖房・冷房モードのいずれかの場合のみ変更できます。許可される設定温度は、サーモスタットの現在のモードに対応しています。モードがオフの場合や、エコモードが MANUAL_ECO に設定されている場合は、温度設定ポイントを変更できません。

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

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

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

なお、設定温度コマンドでパラメータとして指定できるのは摂氏のみです。Google Nest Thermostat では、温度を摂氏または華氏のいずれかで表示できます。

たとえば、サーモスタットが暖房モードのときに設定温度を変更するには、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" : "66cc2182-9529-41f4-a8c9-4f5413c40bfd",
  "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" : "5cbd3f60-055f-4ed7-b92d-9ae3cfa3e1ff",
  "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 トラブルシューティング
冷房の値は暖房の値よりも大きくする必要があります。 INVALID_ARGUMENT コマンドの heatCelsius フィールドが coolCelsius フィールドより小さいことを確認します。
現在のサーモスタット モードではコマンドが許可されていません。 FAILED_PRECONDITION 一部のサーモスタット モデルでは、 ThermostatMode トレイトに従い、サーモスタット モードがオフのときにエコモードの変更がサポートされていません。エコモードを変更する前に、サーモスタットのモードを暖房、冷房、暖房 / 冷房に変更する必要があります。
サーモスタット ファンを使用できません。 FAILED_PRECONDITION サーモスタットにファン機能はありません。このデバイスでは、ファン関連の特徴とコマンドを使用できません。
サーモスタットが MANUAL_ECO モードの場合、コマンドが許可されません。 FAILED_PRECONDITION サーモスタットが手動エコモードの場合、設定温度は設定できません。

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