Alexa.ThermostatControllerインターフェース



Alexa.ThermostatControllerインターフェース

サーモスタットは、温度を感知し、計測温度を設定値近くや、指定された温度範囲内に保持しようとするデバイスです。Alexa.ThermostatControllerインターフェースは、最大3つの設定値を使用するサーモスタットの制御や照会、サーモスタットモードの設定や照会、プログラムされたサーモスタットスケジュールの再開を目的として使用されるメッセージを記述します。

ThermostatControllerインターフェースでサポートされているロケールについては、機能インターフェースの一覧を参照してください。

発話

Alexa.ThermostatControllerインターフェースを使用する場合、音声対話モデルは既にビルドされています。以下に、ユーザーの発話の例を示します。

アレクサ、サーモスタットを20に設定して。
アレクサ、エアコンを24度に設定して。
アレクサ、エアコンを4時間、25度に設定して。
アレクサ、暖かくして。
アレクサ、涼しくして。
アレクサ、午後10時まで暖かくして。
アレクサ、サーモスタットを自動に設定して。
アレクサ、午後8時まで暖房をオフにして。
アレクサ、サーモスタットのスケジュールを再開して。

ユーザーがこのような発話をしたら、Alexaがそれに対応するディレクティブをスキルに送信します。

サーモスタットの設定値

Alexaは、1つ、2つ、3つのいずれかの温度値を設定できるサーモスタットをサポートします。

設定値が1つのサーモスタットは、音声またはAlexaアプリから制御できます。設定値が2つまたは3つの場合は、現在の設定に対して照会できます。

設定値が1つのサーモスタット

設定値が1つのサーモスタットは設定できる温度は1つで、温度をその設定に保持しようとします。たとえば、設定値が1つのサーモスタットでは次のことが可能です。

  • 温度が設定値よりも低くなると暖房をオンにし、温度が設定値よりも高くなるとオフにします。
  • 温度が設定値よりも高くなるとエアコンをオンにし、温度が設定値よりも低くなるとオフにします。
  • 温度が単一設定値の温度よりも高くなると、天井のファンをオンにします。
  • 温度が単一設定値の温度よりも低くなると、給湯器をオンにします。

設定値が2つのサーモスタット

設定値が2つのサーモスタットには、上限と下限の温度設定があります。たとえば、設定値が2つのサーモスタットでは次のことが可能です。

  • 室温が下限の設定値より低くなると暖房を自動でオンにし、上限の設定値より高くなるとエアコンをオンにします。
  • 下限の設定値と上限の設定値の範囲に室温を保つよう、暖房を自動でオン／オフします。
  • 下限の設定値と上限の設定値の範囲に室温を保つよう、冷房を自動でオン／オフします。
  • 室温が下限の設定値よりも低くなり、通風口温度が下限の設定値よりも高くなると、通気バッフルを開きます。
  • 室温が上限の設定値よりも高くなり、通風口温度が上限の設定値よりも低くなると、通気バッフルを開きます。
  • 温度が下限の設定値よりも低くなるとシーリングファンの風向きを自動で上に向け、上限の設定値よりも高くなると下に向けます。
  • 上限低の設定値と下限の設定値を使って2点方式の給湯器のヒーター部を制御し、省電力で最低温度を保持します。

設定値が3つのサーモスタット

設定値が3つのサーモスタットには、設定温度、下限温度、上限温度の3つの設定温度があります。

上限と下限の間の温度範囲内、および目標温度値に近い温度を保つサーモスタットに使用されるのが一般的です。

サーモスタットモード

ThermostatControllerインターフェースは、ThermostatModeプロパティを使ったサーモスタット操作モードの制御とレポートを行います。このプロパティは、サーモスタットで制御するシステムがオンかどうか、モードが暖房、冷房のどちらか、自動、省電力のどちらかを表します。詳細については、ThermostatModeを参照してください。

サーモスタットモードによって指定できる設定値の数が変わるため、モード設定は重要です。使用中のモードによっては、1つまたは2つの設定値のみをサポートし、1つ、2つ、3つの設定値とぞれぞれのサーモスタットモードのすべての組み合わせを使えない場合もあります。たとえば、空調システムを制御するサーモスタットがHEATモードおよびCOOLモードでは設定できる値は1つのみですが、AUTOモードおよびECOモードでは2つ設定できる場合があります。

保持時間のスケジューリング

サーモスタットの保持時間は任意で設定できます。たとえば「アレクサ、エアコンを4時間、22度のままにして」のように、ユーザーが温度制御のリクエストに時間制限を追加することができます。
エンドポイントの検出応答のコンフィギュレーションオブジェクトを使用して、エンドポイントが保持時間のスケジューリングをサポートしていることを示します。その後、エンドポイントがscheduleオブジェクトを含む制御ディレクティブを受け取ると、指定された時間をすぐにリクエストに適用します。

現時点では、未来の時間に特定の温度または温度モードに設定するリクエスト（たとえば、 「アレクサ、午後4時に20度に設定して」など）はサポートされていません。

検出

サーモスタットは、最大3つの設定値、温度モード、保持時間のスケジューリングをサポートできます。サーモスタットが検出応答でサポートするプロパティを指定します。任意で、スケジューリングをサポートするかどうかを表すコンフィギュレーションオブジェクトや、サポートされるサーモスタットモードのリストを含めることもできます。詳細については、プロパティを参照してください。

検出応答を返す場合、以下のように記載したフィールドを含むコンフィギュレーションオブジェクトを含める必要があります。

プロパティ 説明 タイプ 必須
supportsScheduling このエンドポイントに対する制御リクエストでscheduleオブジェクトを送信できる場合はtrue、それ以外はfalseです。 ブール値 ✕
supportedModes このエンドポイントでサポートされる温度モードを指定します。 ThermostatMode値の配列 ✕

エンドポイントの説明にコンフィギュレーションオブジェクトが含まれないか、コンフィギュレーションにsupportsSchedulingフィールドが含まれない場合、サーモスタットがスケジューリングをサポートしておらず、制御リクエストにスケジューリング情報が含まれないと考えられます。

以下は、設定値が3つで、3つのサーモスタットモードの設定が可能な空調デバイスで、それらの情報をコンフィギュレーションオブジェクトでレポートする場合のサンプルコードです。この例のエンドポイントはスケジューリングをサポートしません。

デバイスの検出メッセージの詳細については、Alexa.Discoveryを参照してください。

空調デバイスの検出応答の例

 {
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<メッセージID>"
    },
    "payload": {
      "endpoints": [{
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "<エンドポイントのメーカー名>",
          "modelName": "<エンドポイントのモデル名>",
          "friendlyName": "廊下のサーモスタット",
          "description": "<Alexaアプリに表示される説明>",
          "displayCategories": ["THERMOSTAT"],
        "cookie": {

          },
        "capabilities": [{
            "type": "AlexaInterface",
            "interface": "Alexa.ThermostatController",
            "version": "3",
            "properties": {
              "supported": [{
                  "name": "targetSetpoint"
                },
                {
                  "name": "lowerSetpoint"
                },
                {
                  "name": "upperSetpoint"
                },
                {
                  "name": "thermostatMode"
                }
              ],
              "proactivelyReported": true,
              "retrievable": true
            },
            "configuration": {
              "supportsScheduling": false,
              "supportedModes": [
                "HEAT",
                "COOL",
                "AUTO"
              ]
            }
          },
          {
              "type": "AlexaInterface",
              "interface": "Alexa.TemperatureSensor",
              "version": "3",
              "properties": {
                  "supported": [
                      {
                          "name": "temperature"
                      }
                  ],
                  "proactivelyReported": true,
                  "retrievable": true
              }
          }
        ]
      }]
    }
  }
 }

ディレクティブ

SetTargetTemperatureディレクティブ

エンドポイントの温度を設定するには、SetTargetTemperatureディレクティブを使用します。新しい設定の持続時間を指定するスケジュールを含めることができます。ユーザーは、温度設定が1つの場合は音声で、温度設定が1つ、2つ、3つの場合はAlexaアプリを使用して設定できます。

ユーザー発話のサンプル

ユーザー： アレクサ、寝室のサーモスタットを20に設定して
ユーザー： アレクサ、リビングのエアコンを24度に設定して
ユーザー： アレクサ、キッチンのエアコンを4時間、25度に設定して

SetTargetTemperatureディレクティブペイロードの詳細

フィールド 説明 タイプ 必須
targetSetpoint デバイスに設定する温度を表します。1モードおよび3モードのサーモスタットに送信されます。 Temperature 〇（1モードおよび3モードの場合）
lowerSetpoint デバイスの下限の設定値を表します。2モードおよび3モードのサーモスタットに送信されます。 Temperature 〇（2モードおよび3モードの場合）
upperSetpoint デバイスの上限の設定値を表します。2モードおよび3モードのサーモスタットに送信されます。 Temperature 〇（2モードおよび3モードの場合）
schedule 温度変更のスケジューリングパラメーターを表します。温度変更はすぐに適用され、指定した時間その温度が保持される必要があります。 startとdurationのフィールドを含むTimeIntervalです。start値には常に現在時刻が入り、duration値にはユーザーがリクエストした保持時間が入ります。 ✕

SetTargetTemperatureディレクティブの例（1モードリクエスト）：


{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "targetSetpoint": {
        "value": 20.0,
        "scale": "CELSIUS"
      }
    }
  }
}

SetTargetTemperatureディレクティブの例（設定値が1つで、スケジュールオブジェクトを使用する場合）：

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "messageId": "[MessageID]",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "targetSetpoint": {
        "value": 25.0,
        "scale": "CELSIUS"
      },
      "schedule": {
        "start": "2017-06-22T21:35Z",
        "duration": "PT25M"
      }
    }
  }
}

SetTargetTemperatureディレクティブの例（2モードリクエスト）：

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "lowerSetpoint": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
      },
      "upperSetpoint": {
        "value": 78.0,
        "scale": "FAHRENHEIT"
      }
    }
  }
}

SetTargetTemperatureディレクティブの例（3モードリクエスト）：

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetTargetTemperature",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "targetSetpoint": {
        "value": 73,
        "scale": "FAHRENHEIT"
      },
      "lowerSetpoint": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
      },
      "upperSetpoint": {
        "value": 78.0,
        "scale": "FAHRENHEIT"
      }
    }
  }
}

AdjustTargetTemperatureディレクティブ

エンドポイントの温度を上下に調整するリクエストです。

ユーザー発話のサンプル

ユーザー： アレクサ、暖かくして
ユーザー： アレクサ、涼しくして

AdjustTargetTemperatureディレクティブペイロードの詳細

フィールド 説明 タイプ 必須
targetSetpointDelta 設定値が1つの場合の設定値に対する温度調整値と尺度を表します。正と負の温度値は、それぞれ温度設定値を増減するディレクティブを表します。 Temperature ◯

AdjustTargetTemperatureディレクティブの例（温度を上げる場合）：

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "AdjustTargetTemperature",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "targetSetpointDelta": {
        "value": -2.0,
        "scale": "FAHRENHEIT"
      }
    }
  }
}

SetThermostatModeディレクティブ

サーモスタットのモードを指定した値に設定するリクエストです。ユーザーは、「アレクサ、（ユーザーのサーモスタットデバイス名）を利用可能なモードにして」のように発話する必要があります。

ユーザー発話のサンプル

ユーザー： アレクサ、リビングのサーモスタットを自動に設定して

SetThermostatModeディレクティブペイロードの詳細

フィールド 説明 タイプ 必須
thermostatMode デバイスのサーモスタットモードを表します。 ThermostatModeオブジェクト ◯

SetThermostatModeディレクティブの例

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "SetThermostatMode",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "thermostatMode" : {
        "value": "COOL"
      }
    }
  }
}

ResumeScheduleディレクティブ

サーモスタットにプログラムした暖房または冷房のスケジュールを再開するリクエストです。

ユーザー発話のサンプル

ユーザー： アレクサ、リビングのサーモスタットのスケジュールを再開して

ResumeScheduleディレクティブペイロードの詳細

フィールド 説明 タイプ 必須
なし ペイロードに必須または任意のフィールドはありません。 なし なし

ResumeScheduleディレクティブの例

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "ResumeSchedule",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}

応答

ディレクティブを正しく処理したら、Responseイベントを使用して応答します。この機能については、同期的に応答する必要があります。つまり、Lambda関数からAlexaに応答を送信します。

応答のプロパティ

応答を送信する場合、メッセージのcontextにインターフェースのプロパティの状態を含めます。

プロパティ名 タイプ 説明
targetSetpoint Temperature 設定温度値です。1モードおよび3モードのサーモスタット値に使用します。
lowerSetpoint Temperature 下限の温度のしきい値です。2モードおよび3モードのサーモスタット値のレポートに使用します。
upperSetpoint Temperature 上限の温度のしきい値です。2モードおよび3モードのサーモスタット値のレポートに使用します。
thermostatMode ThermostatMode COOL、HEATなどのサーモスタットモードです。詳細については、ThermostatModeの値を参照してください。

応答の例

設定値が1つでHEATモードの場合の応答の例

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.ThermostatController",
      "name": "targetSetpoint",
      "value": {
        "value": 25,
        "scale": "CELSIUS"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    }, {
      "namespace": "Alexa.ThermostatController",
      "name": "thermostatMode",
      "value": "HEAT",
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

設定値が2つでAUTOモードの場合の応答の例

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.ThermostatController",
      "name": "lowerSetpoint",
      "value": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    }, {
      "namespace": "Alexa.ThermostatController",
      "name": "upperSetpoint",
      "value": {
        "value": 74.0,
        "scale": "FAHRENHEIT"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    }, {
      "namespace": "Alexa.ThermostatController",
      "name": "thermostatMode",
      "value": "AUTO",
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

設定値が3つでAUTOモードの場合の応答の例

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.ThermostatController",
      "name": "lowerSetpoint",
      "value": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    }, {
      "namespace": "Alexa.ThermostatController",
      "name": "targetSetpoint",
      "value": {
        "value": 72.0,
        "scale": "FAHRENHEIT"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    }, {
      "namespace": "Alexa.ThermostatController",
      "name": "upperSetpoint",
      "value": {
        "value": 76.0,
        "scale": "FAHRENHEIT"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    }, {
      "namespace": "Alexa.ThermostatController",
      "name": "thermostatMode",
      "value": "AUTO",
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

エラー処理

エラーが発生した場合、ErrorResponseイベントを使用して応答します。詳細については、Alexa.ErrorResponseインターフェースを参照してください。

エラー応答のペイロードの詳細

Payload.Typeの値 説明 追加のペイロード
TEMPERATURE_VALUE_OUT_OF_RANGE 温度の値が許容範囲外であることを表します。エラーは、Alexa名前空間にあります。詳細については、TEMPERATURE_VALUE_OUT_OF_RANGEエラーの例を参照してください。 minimumValueとmaximumValueという2つのTemperatureオブジェクトを含むvalidRangeオブジェクトです。これらの値は、それぞれサーモスタットの最低温度および最高温度の設定を表します。
REQUESTED_SETPOINTS_TOO_CLOSE 2つの設定値の値が近すぎます。詳細については、REQUESTED_SETPOINTS_TOO_CLOSEを参照してください。 2つの温度設定値の差として設定可能な最小値を表すminimumTemperatureDeltaというTemperatureオブジェクトです。
THERMOSTAT_IS_OFF サーモスタットがオフで、オンにできません。 なし
UNSUPPORTED_THERMOSTAT_MODE サーモスタットは指定されたモードをサポートしていません。 なし
DUAL_SETPOINTS_UNSUPPORTED サーモスタットは、現在のモードで2つの設定値をサポートしていません。 なし
TRIPLE_SETPOINTS_UNSUPPORTED サーモスタットは、現在のモードで3つの設定値をサポートしていません。 なし
UNWILLING_TO_SET_SCHEDULE リクエストされたスケジュールを設定できません。 なし
UNWILLING_TO_SET_VALUE デバイスや機器に損傷を与える恐れがあるため、リクエストされた値を設定できません。 なし

サーモスタットがオフの場合のエラー応答の例

{
  "event": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "ErrorResponse",
      "messageId": "d3c5828a-df17-4396-a64c-1a3bd172abbd",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "payload": {
      "type": "THERMOSTAT_IS_OFF",
      "message": "サーモスタットはオフです。安全上の理由からオンにできません"
    }
  }
}

設定値が互いに近すぎる場合のエラー応答の例

{
  "event": {
    "header": {
      "namespace": "Alexa.ThermostatController",
      "name": "ErrorResponse",
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "payloadVersion": "3"
    },
     "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {
      "type": "REQUESTED_SETPOINTS_TOO_CLOSE",
      "message": "リクエストされた温度設定の値が近すぎます",
      "minimumTemperatureDelta": {
          "value": 2.0,
          "scale": "CELSIUS"
      }
    }
  }
}

その他のサンプルコード

リクエストと応答のサンプルについては、以下のAlexaスマートホームのGitHubリポジトリを参照してください。

ThermostatController

インターフェース 説明
Alexa.TemperatureSensor サーモスタットエンドポイントの設定変更に関連するディレクティブとイベントについて説明しています。
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment