サーモスタットや空調デバイス用のスマートホームスキルを作成する



サーモスタットや空調デバイス用のスマートホームスキルを作成する

空調デバイス用に作成したスマートホームスキルを使うと、ユーザーはサーモスタット、ヒーター、エアコン、ファンといった機器を音声で操作できるようになります。たとえば、ユーザーが「アレクサ、温度を上げて」と言うと、サーモスタットの設定温度が高くなります。また、このようなスキルを使って、Alexaアプリから現在の空調デバイスの状況を確認することもできます。

このドキュメントでは、空調デバイス用にスキルを開発するにあたって理解すべき考え方と、習得するインターフェースやエラーメッセージの概要を説明します。

スマートホームスキルを作成するには、Amazon開発者ポータルでコンフィギュレーション情報を指定し、コードを追加します。このコードはAWS Lambda関数(アマゾンウェブサービスの提供サービスのひとつ)としてホストされます。スキルがAlexaから送られてくるディレクティブに応答して、サーモスタットなどのコネクテッドデバイス(エンドポイントと呼ばれる)と通信し、応答イベントをAlexaに返します。

スマートホームスキルを作成するステップについて理解しておいてください。詳細については、次のページを参照してください。

設定値、温度、サーモスタットモード

Alexaでは、温度設定が1つ、2つ、3つのいずれかで、温度モード設定が1つの空調デバイスをサポートします。サーモスタットエンドポイントを指定する場合は、サポートする温度設定の数を設定値として記述します。

  • 設定値が1つのサーモスタット: このタイプのサーモスタットの設定値は1つで、サーモスタットはその温度を保持しようとします。たとえば、設定値が1つのサーモスタットは、温度が設定値よりも低くなると暖房をオンにし、温度が設定よりも高くなるとオフにします。このタイプのサーモスタットは、Alexaの音声やAlexaアプリから制御できます。

  • 設定値が2つのサーモスタット: このタイプのサーモスタットには、上限と下限の温度設定があります。たとえば、設定値が2つのサーモスタットの場合、室温が下限の設定値より低くなると暖房を自動でオンにし、上限の設定値より高くなるとエアコンをオンにします。ユーザーはAlexaアプリを使って、Alexaからこのタイプのサーモスタットの現在の設定を取得できます。

  • 設定値が3つのサーモスタット: このタイプのサーモスタットには、設定温度、下限温度、上限温度の3つの温度設定があります。通常、設定値が3つのサーモスタットは、Alexa音声では制御できません。ユーザーはAlexaアプリを使って、Alexaからこのタイプのサーモスタットの現在の設定を取得できます。

  • 温度: デバイスの温度は常に同じ尺度で表すようにしてください。つまり、デバイスを摂氏に設定している場合は、温度も摂氏で表す必要があります。同様に、デバイスを華氏に設定している場合は、Alexaにも華氏でレポートする必要があります。

  • サーモスタットモード:サーモスタットのモードは、エンドポイントの動作と、指定可能な設定値の数に影響します。モードによって、設定値を1つだけ指定できるものと、2つまたは3つの設定値を指定できるものがあります。たとえば、空調システムを制御するサーモスタットがHEATおよびCOOLモードでは設定値は1つしかサポートせず、AUTOおよびECOモードでは2つサポートする場合があります。

さまざまなサーモスタットのタイプの例については、ThermostatControllerを参照してください。

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

Alexaは、一定時間温度を保持するユーザーリクエストもサポートします。たとえば、ユーザーが「アレクサ、午後10時までここをもっと暖かくして」と言うと、Alexaは温度変更とその温度変更を適用する時間を含むディレクティブを送信します。

エンドポイントが保持時間のスケジューリングをサポートする場合は、検出応答のコンフィギュレーションオブジェクトにこの情報を指定する必要があります。

機能を選択する

サーモスタットデバイス設定のレポートや変更、ファンの制御といったユーザーリクエストに対応するには、正しい機能を選択する必要があります。空調デバイスの機能を記述する機能インターフェースを、次の表で説明します。

操作 機能インターフェース
温度設定の変更、温度保持の適用、プログラムしたスケジュールの再開、現在の設定の提供を行います。 Alexa.ThermostatController
現在の温度に関するリクエストに応答します。 Alexa.TemperatureSensor
ファンのオン/オフ、ファンの速度の制御を行います。 Alexa.PowerControllerAlexa.PercentageController

空調エンドポイントを識別する

スキルが有効になると、Alexaはまず検出リクエストを送信します。スキルは応答に空調エンドポイントを指定します。エンドポイントに関連する機能と、各機能でサポートするプロパティを指定します。サーモスタットの制御を行うエンドポイントに対しては、温度モードと、エンドポイントで保持のスケジューリングをサポートするかどうかを指定するコンフィギュレーションを指定することもできます(任意)。また、サーモスタットでは最大3つの設定値をサポートできるため、設定値をtargetSetpointlowerSetpointupperSetpointを使って検出応答に指定します。サーモスタット検出の詳細は、ThermostatControllerの検出についてのセクションを参照してください。

空調エンドポイントを有効にしてAlexaアプリに適切に表示されるようにするには、displayCategoryも指定する必要があります。空調デバイスは以下のいずれかになります。

  • TEMPERATURE_SENSOR - 温度のみをレポート/感知するエンドポイントです。
  • THERMOSTAT - 温度、直接温度制御が可能なスタンドアロンのエアコン、ヒーターを制御するエンドポイントです。

温度設定の制御と温度の感知が可能なエンドポイントについては、次のような表示カテゴリーを設定する必要があります。

"displayCategories":["THERMOSTAT", "TEMPERATURE_SENSOR" ]

以下は、設定値が3つ、複数のサーモスタットモード、保持時間のスケジューリングの設定が可能な空調デバイスを記述したコードの例です。

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

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

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
    },
    "payload": {
      "endpoints": [{
        "endpointId": "appliance-002",
        "friendlyName": "Hallway Thermostat",
        "description": "サンプルメーカーのスマートサーモスタット",
        "manufacturerName": "サンプルメーカー",
        "displayCategories": [
          "THERMOSTAT"
        ],
        "cookie": {  },
        "capabilities": [{
            "type": "AlexaInterface",
            "interface": "Alexa.ThermostatController",
            "version": "3",
            "properties": {
              "supported": [{
                  "name": "lowerSetpoint"
                },
                {
                  "name": "targetSetpoint"
                },
                {
                  "name": "upperSetpoint"
                },
                {
                  "name": "thermostatMode"
                }
              ],
              "proactivelyReported": true,
              "retrievable": true
            },
            "configuration": {
              "supportsScheduling": true,
              "supportedModes": [
                "HEAT",
                "COOL",
                "AUTO"
              ]
            }
          },

          {
            "type": "AlexaInterface",
            "interface": "Alexa.TemperatureSensor",
            "version": "3",
            "properties": {
              "supported": [{
                "name": "temperature"
              }],
              "proactivelyReported": true,
              "retrievable": true
            }
          }
        ]
      }]
    }
  }
}

エラーをレポートする

エラーが発生した場合は、エラーイベントを返します。以下の表は、エラーのシナリオと返すエラーのタイプです。

シナリオ エラーメッセージタイプ 備考
サーモスタットに設定可能な範囲以外の値がディレクティブに含まれている TEMPERATURE_VALUE_OUT_OF_RANGE このエラーは、Alexa名前空間にあり、minimumValuemaximumValueという2つのTemperatureオブジェクトを含むvalidRangeオブジェクトを含める必要があります。これらの値は、それぞれサーモスタットの最低温度および最高温度の設定を表します。
ディレクティブに含まれる設定値の値が近すぎて使用できない REQUESTED_SETPOINTS_TOO_CLOSE 2つの設定値の差として設定可能な最小値を表すTemperature型のminimumTemperatureDeltaフィールドが必要です。REQUESTED_SETPOINTS_TOO_CLOSEの例を参照してください。
サーモスタットがオフで、オンにできない THERMOSTAT_IS_OFF Alexa.ThermostatController名前空間で定義されます。
このエンドポイントではサポートされないモードをディレクティブがリクエストした UNSUPPORTED_THERMOSTAT_MODE Alexa.ThermostatController名前空間で定義されます。
エンドポイントは、現在のモードで2つの設定値をサポートしていない DUAL_SETPOINTS_UNSUPPORTED Alexa.ThermostatController名前空間で定義されます。
サーモスタットは、現在のモードで3つの設定値をサポートしていない TRIPLE_SETPOINTS_UNSUPPORTED Alexa.ThermostatController名前空間で定義されます。
リクエストされたスケジュールを設定できません。 UNWILLING_TO_SET_SCHEDULE Alexa.ThermostatController名前空間で定義されます。
デバイスや機器に損傷を与える恐れがあるため、リクエストされた値を設定できません。 UNWILLING_TO_SET_VALUE Alexa.ThermostatController名前空間で定義されます。

THERMOSTAT_IS_OFFの例

{
  "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": "サーモスタットはオフです。安全上の理由からオンにできません"
    }
  }
}

REQUESTED_SETPOINTS_TOO_CLOSEの例

{
  "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"
      }
    }
  }
}