Smart Device Management(SDM)API では、Google Nest Thermostat のすべてのモデルがサポートされています。これらのデバイスは、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 Thermostat では、温度を摂氏または華氏のいずれかで表示できますが、SDM API で体重計を設定することはできません。ユーザーが現在設定されている温度スケールを確認するには、Settings トレイトを使用します。
モードを変更する
サーモスタットのモードは、ThermostatMode とThermostatEcoの 2 つの異なるトレイトで管理されます。
標準モード
サーモスタットのモードを HEAT、COOL、HEATCOOL に変更するには、The ThermostatMode トレイトの SetMode コマンドを使用します。
このコマンドは、サーモスタットのモードをオフに切り替える場合にも使用できます。エコモードをオンにするのには使用できません。たとえば、標準のサーモスタットモードのいずれかを変更するには:
リクエスト
POST /enterprises/project-id/devices/device-id:executeCommand
{
"command" : "sdm.devices.commands.ThermostatMode.SetMode
",
"params" : {
"mode" : "HEAT"
}
}
レスポンス
{}
エコモード
エコモードをオンにするには、The ThermostatEco トレイトの SetMode コマンドで、モードとして MANUAL_ECO を使用します。
リクエスト
POST /enterprises/project-id/devices/device-id:executeCommand
{
"command" : "sdm.devices.commands.ThermostatEco.SetMode
",
"params" : {
"mode" : "MANUAL_ECO"
}
}
レスポンス
{}
このコマンドは、エコモードの現在のステータスやエコモードの変更に基づいて、他のトレイトに影響します。
- エコモードがオフの場合、前回アクティブだった標準モード(暖房、冷房、HEATCOOL、オフ)がデフォルトで設定されます。
- エコモードが MANUAL_ECO の場合:
- ThermostatTemperatureSetpoint トレイトのコマンドは拒否されます。
- 温度設定値は、 ThermostatTemperatureSetpoint トレイトでは返されません。
設定温度を変更する
温度設定値を変更できるのは、サーモスタットが HEAT、COOL、HEATCOOL モードのいずれかで、許容される設定値がサーモスタットの現在のモードに対応している場合のみです。モードが OFF の場合やエコモードが MANUAL_ECO に設定されている場合、温度設定ポイントは変更できません。
設定温度を変更する前に、サーモスタットが、呼び出されたコマンドに対応するモードになっている必要があります。設定値を変更するためのコマンドとフィールドは、サーモスタットのモードによって異なります。
たとえば、SetHeat コマンドを発行するには、最初にサーモスタットを HEAT モードにする必要があります。
モード | コマンド | フィールド |
---|---|---|
暖房 | SetHeat | heatCelsius |
冷房 | SetCool | coolCelsius |
ヘイトコール | SetRange | heatCelsius 、coolCelsius |
setpoint コマンドではパラメータとして摂氏のみが使用されますが、Google Nest Thermostat では温度を摂氏または華氏のいずれかで表示できます。
たとえば、サーモスタットが HEAT モードのときに温度設定を変更するには、The 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 サービスが稼働していることを確認します。
イベントが有効になっている場合は、デバイスがオフラインになったことを示すリソース イベントも返されるはずです。
ペイロード
{
"eventId" : "23f0d97b-6cc0-412d-b9e9-206721c6f54f",
"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"
]
}
デバイスのイベントに反応する
トレイト フィールドが変更されると、イベントが生成されます。 たとえば、サーモスタットの暖房換気空調のステータスが「暖房」に変わった場合、次の resourceUpdate
イベントを受け取ります。
ペイロード
{
"eventId" : "15ad542b-59e9-4553-bd8a-7a73a1cb3f0e",
"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 トレイトによれば、一部のサーモスタット モデルでは、サーモスタット モードがオフのときにエコモードを変更できないことがあります。エコモードを変更する前に、サーモスタットのモードを HEAT、COOL、HEATCOOL のいずれかに変更する必要があります。 |
サーモスタットのファンは利用できません。 | FAILED_PRECONDITION |
サーモスタットにファン機能はありません。ファン関連のトレイトやコマンドは、このデバイスには使用できません。 |
サーモスタットが MANUAL_ECO モードの場合、コマンドは使用できません。 | FAILED_PRECONDITION |
サーモスタットが手動エコモードの場合、温度設定値は設定できません。 |
API エラーコードの完全なリストについては、API エラーコード リファレンスをご覧ください。