サーモスタット

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

sdm.devices.types.THERMOSTAT

トレイト

リファレンス

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

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

モードを変更する

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

Standard モード

サーモスタットのモードを HEAT、COOL、または HEATCOOL に変更するには、サーモスタットモード トレイトの 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 ステータスかどうかを確認します。デバイスのインターネット接続を確認し、Nest Service が稼働していることを確認します。

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

ペイロード

{
  "eventId" : "366dcbfb-2b0d-4c8c-9ad9-2ff7434f1dc7",
  "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" : "1e9d0340-7543-4a6f-b498-7c12a77f0b27",
  "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 エラーコード リファレンスをご覧ください。