Alexa.ContactSensorインターフェース

 

Alexa.ContactSensorインターフェース

2面間の接触を検出するデバイスには、AlexaスキルにAlexa.ContactSensorインターフェースを実装します。たとえば、接触センサーはドアや窓が開いているか閉まっているかをレポートできます。セキュリティスキルの詳細については、スマートホームセキュリティの概要を参照してください。

接触センサーが大規模なセキュリティシステムの一部である場合は、スキルにAlexa.MotionSensorインターフェースやAlexa.SecurityPanelControllerインターフェースを実装して、ユーザーエクスペリエンスに統一感を持たせることができます。

ContactSensorインターフェースがサポートする言語については、Alexaインターフェースとサポートしている言語の一覧を参照してください。

発話

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

Alexa, is the bedroom window open?

アレクサ、寝室の窓は開いてる?

ユーザーがこのような発話をすると、Alexaはそれに対応する状態レポートリクエストをスキルに送信します。

概要

接触センサーには通常2つのコンポーネントがあります。メインコンポーネントとマグネットコンポーネントです。コンポーネントが互いに接触していると、センサーはクローズになります。接触しなくなると、センサーはオープンになります。

以下の図は、窓の接触センサーのオープン状態とクローズ状態を表しています。

プロパティ

Alexa.ContactSensorインターフェースはプライマリプロパティとしてdetectionStateを使用します。detectionStateでは以下の値を使用できます。

説明
DETECTED センサーがオープンで、センサーの2つの部品が互いに接触していない状態を表します。たとえば、窓を開けた後の状態です。
NOT_DETECTED センサーが閉じていて、センサーの2つの部品が互いに接触している状態を表します。

検出

Alexa.ContactSensorをサポートするエンドポイントは、Alexa.Discoveryの標準検出メカニズムを使用して表します。

Alexaからの状態レポートリクエストに応じてスキルがレポートする場合は、プロパティのretrievableをtrueに設定します。変更レポートでAlexaにプロアクティブにレポートする場合はプロパティのproactivelyReportedをtrueに設定します。

表示カテゴリーにはCONTACT_SENSORを使用します。表示カテゴリーの一覧は、表示カテゴリーを参照してください。

応答例

以下は、Alexa.ContactSensorインターフェースをサポートする接触センサーのDiscover.Responseメッセージの例です。センサーには、endpoint healthインターフェースも実装する必要があります。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "エンドポイントの一意のID",
          "manufacturerName": "<エンドポイントのメーカー名>",
          "description": "センサーメーカーのスマートセンサー",
          "friendlyName": "寝室の窓",
          "displayCategories": ["CONTACT_SENSOR"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.ContactSensor",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "detectionState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name":"connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

状態レポート

ReportStateディレクティブをサポートすると、ユーザーは接触センサーの状態について質問できます。

以下に、ユーザーの発話の例を示します。

Alexa, is the bedroom window open?

Alexaはエンドポイントの状態についての情報をリクエストするために、ReportStateディレクティブを送信します。AlexaがReportStateディレクティブを送信したら、それに対する応答としてStateReportイベントを送信します。応答には、contextオブジェクトのすべてのretrievableプロパティの現在の状態を含めます。retrievableプロパティは検出応答で特定します。状態レポートの詳細については、状態および変更レポートについてを参照してください。

StateReport応答イベントの例

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ContactSensor",
        "name": "detectionState",
        "value": "NOT_DETECTED",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

変更レポート

エンドポイントの状態の変化をプロアクティブにレポートするために、ChangeReportイベントを送信します。プロアクティブにレポートするプロパティは検出応答で特定します。変更レポートの詳細については、状態および変更レポートについてを参照してください。

ChangeReportイベントの例

クリップボードにコピーされました。

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "エンドポイントID"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.ContactSensor",
            "name": "detectionState",
            "value": "DETECTED",
            "timeOfSample": "2018-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2018-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}