Alexa.ThermostatController.Scheduleインターフェース3.2

Alexa.ThermostatController.Scheduleインターフェース3.2

ユーザーがサーモスタットのスケジュールを定義できるようにするには、AlexaスキルにAlexa.ThermostatController.Scheduleインターフェースを実装します。ユーザーは、デバイスまたはAlexaアプリから、温度のスケジュールを設定できます。

通常、Alexa.ThermostatController.Scheduleインターフェースは、Alexa.ThermostatControllerインターフェース、Alexa.TemperatureSensorインターフェースと併せて使用します。

Alexa.ThermostatController.Scheduleインターフェースがサポートするロケールについては、Alexaインターフェースとサポートしている言語の一覧を参照してください。メッセージプロパティの定義については、Alexaインターフェースのメッセージとプロパティを参照してください。

発話

Alexa.ThermostatController.Scheduleインターフェースは、ほかのAlexaインターフェースとは異なります。スキルは、Alexaとユーザーとの音声対話を直接サポートしません。その代わり、Alexaがスキルと通信して、サーモスタットのスケジュールの設定と取得を行います。このインターフェースにはユーザー発話はありません。

プロパティとオブジェクト

Alexa.ThermostatController.Scheduleインターフェースには、次のプロパティとオブジェクトが含まれます。

出力可能なプロパティ

以下の表は、Alexa.ThermostatController.Scheduleインターフェースが定義するプロパティの一覧です。検出応答で、サポートするプロパティを指定します。すべてのプロパティはオプションです。サーモスタットデバイスの機能に対応するプロパティのみを含めてください。

プロパティ 説明 型

adaptiveRecoveryEnabled

スケジュール内の予熱および予冷を有効／無効にする場合に使用します。たとえば、次のスケジュールが開始する前に、暖房、換気、エアコン（HVAC）システムの暖房をオンにし、次のスケジュール開始時に目標温度に達するようにします。

ブール値

scheduleEnabled

サーモスタットのスケジュールを有効／無効にする場合に使用します。

ブール値

WeeklyScheduleオブジェクト

WeeklyScheduleオブジェクトは、サーモスタットデバイスのスケジュールを定義します。

プロパティ 説明 型 必須

temperatureScale

サーモスタットに設定する温度単位です。この値は通常、Alexa.ThermostatController.ConfigurationインターフェースのtemperatureScaleプロパティと同じです。

文字列

◯

Monday

月曜日のスケジュールを指定します。

ScheduleEntryオブジェクトの配列

◯

Tuesday

火曜日のスケジュールを指定します。

ScheduleEntryオブジェクトの配列

◯

Wednesday

水曜日のスケジュールを指定します。

ScheduleEntryオブジェクトの配列

◯

Thursday

木曜日のスケジュールを指定します。

ScheduleEntryオブジェクトの配列

◯

Friday

金曜日のスケジュールを指定します。

ScheduleEntryオブジェクトの配列

◯

Saturday

土曜日のスケジュールを指定します。

ScheduleEntryオブジェクトの配列

◯

Sunday

日曜日のスケジュールを指定します。

ScheduleEntryオブジェクトの配列

◯

ScheduleEntryオブジェクト

ScheduleEntryオブジェクトは、特定の曜日のサーモスタット温度設定の詳細を定義します。スケジュールエントリに終了時間は含まれません。次のスケジュールエントリが開始するときに終了します。

プロパティ 説明 型 必須

startTimeInMinutes

温度変更の開始時間を、日付が変わってからの分数で指定します。たとえば、午前5時は300分と指定します。有効な値： 0～1439。

整数

◯

setpoints

次のスケジュールエントリまでに到達および維持したい、生活空間の目標温度を定義します。

SetPointsオブジェクト

◯

fanSetting

ファンの運転設定を指定します。

FanSettingオブジェクト

✕

activityType

温度変更の原因となるアクティビティの種類を指定します。

ActivityTypeオブジェクト

✕

SetPointsオブジェクト

SetPointsオブジェクトは、生活空間の目標温度を定義します。

プロパティ 説明 型

upperSetpoint

このプロパティに温度を指定すると、サーモスタットは温度をこの設定値よりも下に維持しようとします。

Temperature

lowerSetpoint

このプロパティに温度を指定すると、サーモスタットは温度をこの設定値よりも上に維持しようとします。

Temperature

FanSettingオブジェクト

FanSettingオブジェクトはファンの運転モードを定義します。

プロパティ 説明 型

mode

ファンの運転設定を指定します。たとえば、CIRCULATEを指定すると、ファンはランダムな間隔で運転します。
モードを指定しない場合、HVACシステムはメーカーのデフォルト設定を使用します。
有効な値： ON、AUTO、CIRCULATE。

文字列

ActivityTypeオブジェクト

ActivityTypeオブジェクトにより、ユーザーはアクティビティの種類に基づいてスケジュールを設定できるようになります。

プロパティ 説明 型

type

アクティビティの種類を指定します。
有効な値： AWAY、HOME、SLEEP。

文字列

検出

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

Alexaからスキルに状態レポートリクエストが送信されたら、レポートするプロパティのretrievableをtrueに設定します。変更レポートでAlexaにプロアクティブにレポートするプロパティのproactivelyReportedをtrueに設定します。

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

configurationオブジェクト

Alexa.ThermostatController.Scheduleには、標準の検出応答フィールドのほかに、次のフィールドを含むconfigurationオブジェクトを含めます。

プロパティ 説明 型 必須

supportedFanModes

ファンのサポートされる運転モードを指定します。
有効な値： ON、AUTO、CIRCULATE。

文字列の配列

◯

supportsAdaptiveRecovery

予熱または予冷をサポートするかどうかを指定します。

ブール値

◯

maxEntryPerDay

各日のスケジュールエントリの最大数です。制限が複雑な場合、スキルまたはデバイスでスケジュールを検証できます。

整数

✕

検出応答の例

以下は、サーモスタットの設定を受け入れ、Alexa.ThermostatControllerインターフェースとAlexa.EndpointHealthインターフェースをサポートするAlexaスキルのDiscover.Responseメッセージの例です。この例のサーモスタットデバイスは、状況に応じた復旧をサポートします。

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

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "一意の識別子、バージョン4 UUIDが望ましい"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "エンドポイントの一意のID",
                "manufacturerName": "サンプルメーカー",
                "description": "Alexaアプリに表示される説明",
                "friendlyName": "Alexaアプリに表示されるデバイス名",
                "displayCategories": ["THERMOSTAT"],
                "additionalAttributes": {
                    "manufacturer": "サンプルメーカー",
                    "model": "サンプルモデル",
                    "serialNumber": "デバイスのシリアル番号",
                    "firmwareVersion": "デバイスのファームウェアバージョン",
                    "softwareVersion": "デバイスのソフトウェアバージョン",
                    "customIdentifier": "デバイスのカスタム識別子"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.ThermostatController",
                        "version": "3.2",
                        "properties": {
                            "supported": [
                                {
                                    "name": "thermostatMode"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportedModes": [
                                "HEAT",
                                "COOL",
                                "AUTO",
                                "OFF"
                            ],
                            "supportsScheduling": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.ThermostatController.Schedule",
                        "version": "3.2",
                        "properties": {
                            "supported": [{
                                    "name": "adaptiveRecoveryEnabled"
                                },
                                {
                                    "name": "scheduleEnabled"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportedFanModes": [
                                "ON",
                                "AUTO"
                            ],
                            "supportsAdaptiveRecovery": true,
                            "maxEntryPerDay": 4
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.1",
                        "properties": {
                            "supported": [{
                                "name": "connectivity"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

ディレクティブ

Alexaは次のAlexa.ThermostatController.Scheduleインターフェースディレクティブをスキルに送信します。

SetWeeklyScheduleディレクティブ

SetWeeklyScheduleディレクティブをサポートすると、サーモスタットのセットアップ中またはAlexaアプリで後からユーザーが設定したスケジュールを取得できます。

SetWeeklyScheduleディレクティブの例

以下は、Alexaがスキルに送信するSetWeeklyScheduleディレクティブの例です。

SetWeeklyScheduleディレクティブのペイロード

以下の表は、Alexaがスキルに送信するSetWeeklyScheduleディレクティブのペイロードの詳細です。

プロパティ 説明 型 必須

weeklySchedule

サーモスタットデバイスが各曜日に従うスケジュールを指定します。

WeeklyScheduleオブジェクト

✕

SetWeeklySchedule応答

SetWeeklyScheduleディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。

SetWeeklyScheduleディレクティブのエラー処理

SetWeeklyScheduleディレクティブを正常に処理できない場合、デバイスのスケジュールを変更せずに、Alexa.ThermostatController.Schedule.ErrorResponseイベントで応答します。サーモスタット固有のエラーではない場合は、汎用のAlexa.ErrorResponseイベントを使用して応答することもできます。

SetScheduleStateディレクティブ

SetScheduleStateディレクティブをサポートすると、ユーザーはサーモスタットのスケジュールを有効または無効にできます。ユーザーがスケジュールをもう一度有効にできるようにするには、以前に設定したスケジュールを保存しておく必要があります。

SetScheduleStateディレクティブの例

以下は、Alexaがスキルに送信するSetScheduleStateディレクティブの例です。

{
  "directive": {
    "header": {
      "namespace": "Alexa.ThermostatController.Schedule",
      "name": "SetScheduleState",
      "messageId": "一意のバージョン4 UUID",
      "correlationToken": "opaque相関トークン",
      "payloadVersion": "3.2"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2ベアラートークン"
      },
      "endpointId": "エンドポイントID",
      "cookie": {}
    },
    "payload": {
      "scheduleEnabled": true
    }
  }
}

SetScheduleStateディレクティブのペイロード

次の表は、SetScheduleStateイベントのペイロードの詳細を示しています。

プロパティ 説明 型 必須

scheduleEnabled

サーモスタットのスケジュールを有効（true）にするか、無効（false）にするかを指定します。

ブール値

◯

SetScheduleState応答

SetScheduleStateディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。

SetScheduleStateディレクティブのエラー処理

SetScheduleStateディレクティブを正しく処理できなかった場合は、Alexa.ThermostatController.Schedule.ErrorResponseイベントを使用して応答します。サーモスタット固有のエラーではない場合は、汎用のAlexa.ErrorResponseイベントを使用して応答することもできます。

SetAdaptiveRecoveryディレクティブ

デバイスが状況に応じた復旧をサポートする場合、AlexaはSetAdaptiveRecoveryディレクティブを送信して、ユーザーが予熱や予冷を有効／無効にできるようにします。

SetAdaptiveRecoveryディレクティブの例

以下は、Alexaがスキルに送信するSetAdaptiveRecoveryディレクティブの例です。

{
    "directive": {
        "header": {
            "namespace": "Alexa.ThermostatController.Schedule",
            "name": "SetAdaptiveRecovery",
            "messageId": "一意のバージョン4 UUID",
            "correlationToken": "opaque相関トークン",
            "payloadVersion": "3.2"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "OAuth2ベアラートークン"
            },
            "endpointId": "endpoint-id",
            "cookie": {}
        },
        "payload": {
            "adaptiveRecoveryEnabled": true
        }
    }
}

SetAdaptiveRecoveryディレクティブのペイロード

次の表は、SetAdaptiveRecoveryイベントのペイロードの詳細を示しています。

プロパティ 説明 型 必須

adaptiveRecoveryEnabled

状況に応じた復旧を有効（true）にするか、無効（false）にするかを指定します。

ブール値

◯

SetAdaptiveRecovery応答

SetAdaptiveRecoveryディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。

SetAdaptiveRecoveryディレクティブのエラー処理

SetAdaptiveRecoveryディレクティブを正しく処理できなかった場合は、Alexa.ThermostatController.Schedule.ErrorResponseイベントを使用して応答します。サーモスタット固有のエラーではない場合は、汎用のAlexa.ErrorResponseイベントを使用して応答することもできます。

状態レポート

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

StateReport応答の例

この例のサーモスタットデバイスは、setupStateとtemperatureScaleの両方をサポートします。

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

{
    "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.ThermostatController.Schedule",
                "name": "adaptiveRecoveryEnabled",
                "value": true,
                "timeOfSample": "2020-02-26T16:20:50Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.ThermostatController.Schedule",
                "name": "scheduleEnabled",
                "value": true,
                "timeOfSample": "2020-02-26T16:20:50Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "thermostatMode",
                "value": "HEAT",
                "timeOfSample": "2020-02-26T16: 20: 50Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2020-02-26T16: 20: 50Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

変更レポート

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

payloadには変更されたプロパティの値が含まれ、contextにはその他の関連プロパティの値が含まれます。

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.ThermostatController.Schedule",
                    "name": "scheduleEnabled",
                    "value": false,
                    "timeOfSample": "2020-02-26T16: 20: 50Z",
                    "uncertaintyInMilliseconds": 500
                }]
            }
        }
    },
    "context": {
        "properties": [{
                "namespace": "Alexa.ThermostatController.Schedule",
                "name": "adaptiveRecoveryEnabled",
                "value": true,
                "timeOfSample": "2020-02-26T16:20:50Z",
                "uncertaintyInMilliseconds": 1000
            },
            {
                "namespace": "Alexa.ThermostatController",
                "name": "thermostatMode",
                "value": "HEAT",
                "timeOfSample": "2020-02-26T16: 20: 50Z",
                "uncertaintyInMilliseconds": 500
            },
            {
                "namespace": "Alexa.EndpointHealth",
                "name": "connectivity",
                "value": {
                    "value": "OK"
                },
                "timeOfSample": "2020-02-26T16: 20: 50Z",
                "uncertaintyInMilliseconds": 0
            }
        ]
    }
}

このページは役に立ちましたか？

最終更新日: 2024 年 07 月 11 日