スマートホーム ColorSetting トレイトのスキーマ

action.devices.traits.ColorSetting - このトレイトは、色や色温度を変更できるスマートライトなどのデバイスに適用されます。このトレイトを持つデバイスは、RGB 値または HSV 値のフルスペクトル カラー、あるいはケルビン絶対温度の色温度、またはその両方をサポートします(ただし同時にではありません)。たとえば、ライトを同時に「緑色」と「9,000 ケルビン」の両方に設定することはできません。

RGB、HSV、色温度

RGB は、色を(赤、緑、青)からなる 3 つの値の組で表します。RGB がデフォルトのカラーモデルです。RGB は、3 つの 16 進値を連結した 16 進コードで表せます。たとえば、「青」は (0, 0, 255) と #0000FF のどちらでも表せます。RGB 色空間内の任意の値を使用できます。つまり、x、y、z が 0 以上、255 以下の RGB(x, y, z) です。

HSV は、色を(色相、彩度、明度)の 3 つの値の組で表します。HSV のどの色の値も RGB に変換でき、その逆も可能です。色相は、0 度以上、360 度未満の値で表されます(折り返して 0 度になるため、360 度は入りません)。彩度と明度は、0.0 以上、1.0 以下の浮動小数点数で表されます。

色温度は、一部の色をケルビン絶対温度の非負の 10 進数で表します。この属性は、「白い」光や「暖かい」光を、「cool white」や「overcast daylight」などの色の名前で表します。色温度をサポートするスマートライトは、通常 2,000 以上、9,000 以下のケルビン絶対温度をサポートします。これは、固定ケルビン絶対温度の従来のライトに対応します。色温度は線形スケールであり、RGB / HSV フルスペクトル カラーモデルのサブセットになっています。

デバイスの属性

属性 定義
colorModel

文字列。デバイスがフルスペクトル カラーモデルをサポートしている場合、必須。colorTemperatureRange 属性が設定されていない場合、必須。次のいずれか 1 つの値に設定する必要があります。

  • rgb デフォルト モデル。デバイスが RGB カラーモデルをサポートしている。
  • hsv デバイスが HSV カラーモデルをサポートしている。
colorTemperatureRange

オブジェクト。デバイスがケルビン絶対温度の色温度をサポートしている場合、必須。colorModel 属性が設定されていない場合、必須。デバイスでサポートされているケルビン絶対温度の最小値と最大値が含まれます。colorTemperatureRange は、デバイスが色温度とフルスペクトルのカラーモデルの両方をサポートしているなら、colorModelrgb あるいは hsv の場合も使用できます。

  • temperatureMinK 整数。デバイスでサポートされている最低色温度(ケルビン絶対温度)。
  • temperatureMaxK 整数。デバイスでサポートされている最高色温度(ケルビン絶対温度)。
commandOnlyColorSetting ブール値。デフォルトは false。デバイスがコマンドのみの実行をサポートしている場合、必須。この属性は、デバイスが一方向または双方向の通信をサポートしているかどうかを示します(たとえば、コントローラがリクエストの送信後に新しいステータスを通知する場合は双方向がサポートされています)。デバイスがステータスの通知を受けてリクエストの成功を確認できない場合は、true に設定する必要があります。

SYNC リクエストとレスポンスの例

リクエスト
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.SYNC"
    }]
}
Node.jsレスポンス
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onSync((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      agentUserId: '1836.15267389',
      devices: [{
        id: '123',
        type: 'action.devices.types.LIGHT',
        traits: [
          'action.devices.traits.ColorSetting'
        ],
        name: {
          defaultNames: ['AAA bulb A19 color hyperglow'],
          name: 'lamp1',
          nicknames: ['reading lamp']
        },
        willReportState: false,
        attributes: {
          colorModel: 'rgb',
          colorTemperatureRange: {
            temperatureMinK: 2000,
            temperatureMaxK: 9000
          },
          commandOnlyColorSetting: false
        },
        deviceInfo: {
          manufacturer: 'AAA',
          model: 'hg11',
          hwVersion: '1.2',
          swVersion: '5.4'
        },
        customData: {
          fooValue: 12,
          barValue: false,
          bazValue: 'dancing alpaca'
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
JSONレスポンス
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.ColorSetting"
        ],
        "name": {
          "defaultNames": [
            "AAA bulb A19 color hyperglow"
          ],
          "name": "lamp1",
          "nicknames": [
            "reading lamp"
          ]
        },
        "willReportState": false,
        "attributes": {
          "colorModel": "rgb",
          "colorTemperatureRange": {
            "temperatureMinK": 2000,
            "temperatureMaxK": 9000
          },
          "commandOnlyColorSetting": false
        },
        "deviceInfo": {
          "manufacturer": "AAA",
          "model": "hg11",
          "hwVersion": "1.2",
          "swVersion": "5.4"
        },
        "customData": {
          "fooValue": 12,
          "barValue": false,
          "bazValue": "dancing alpaca"
        }
      }
    ]
  }
}
検証ツール

デバイスのステータス

ステータス 定義
color

オブジェクト。現在の色設定。次のいずれかの 1 つのステータス(デバイスで現在使用されている方)を含める必要があります。

  • temperatureK 整数。ケルビン絶対温度の値。現在デバイスが色温度に設定されている場合に使用。たとえば、4,000K の「cool white」。
  • spectrumRgb 整数。colorModelrgb に設定されている場合に使用。RGB のスペクトル値(10 進整数に変換された 16 進値)。たとえば、16 進数の #0000FF で表される「青色」は、10 進整数の 255 に変換されます。
  • spectrumHsv オブジェクト。colorModelhsv に設定されている場合に使用。次の 3 つのパラメータを含める必要があります。
    • hue 色相を正の度数(たとえば、-60.0 度ではなく 300.0 度)で表す、0.0 以上、360.0 未満の浮動小数点数。
    • saturation 浮動小数点。0.0 以上、1.0 以下の彩度。
    • value 浮動小数点。0.0 以上、1.0 以下の明度。

次は spectrumHsv の色設定の例です。
"color": {
  "spectrumHsv": {
    "hue": 240.0,
    "saturation": 1.0,
    "value": 1.0
  }
}

QUERY リクエストとレスポンスの例

「電気スタンドは何色ですか?」

リクエスト
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": 'action.devices.QUERY',
    "payload": {
      "devices": [{
        "id": "123",
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "foo"
        }
      }]
    }
  }]
}
Node.jsレスポンス
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onQuery((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      devices: {
        123: {
          online: true,
          spectrumRgb: 16711935
        }
      }
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
JSONレスポンス
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "online": true,
        "spectrumRgb": 16711935
      }
    }
  }
}

デバイスのコマンド

コマンド パラメータ / 定義
action.devices.commands.ColorAbsolute

color オブジェクト。新しい色設定。

  • name 省略可。ユーザーのコマンドから解析された色名を表す文字列(「warm white」、「red」など)。常に利用できるとは限りません(たとえば「光を暖かくして」などの相対コマンド)。

color オブジェクトには、次のいずれか 1 つを含める必要があります。

  • temperature 整数。ケルビン絶対温度の色温度。colorTemperatureRange 属性が指定されている場合に送信される可能性があります。
  • spectrumRGB 整数。RGB のカラー値(10 進数に変換された 16 進値)。colorModelrgb の場合に送信される可能があります。
  • spectrumHSV オブジェクト。colorModelhsv の場合に送信される可能性があります。次の 3 つのパラメータを含める必要があります。
    • hue 色相を正の度数(たとえば、-60.0 度ではなく 300.0 度)で表す、0.0 以上、360.0 未満の浮動小数点数。
    • saturation 浮動小数点。0.0 以上、1.0 以下の彩度。
    • value 浮動小数点。0.0 以上、1.0 以下の明度。

パラメータ名は、コマンド パラメータとステータス パラメータでわずかに異なります。これにより、非推奨の ColorSpectrum トレイトおよび ColorTemperature トレイトを持つデバイスに送信されたコマンドに対する下位互換性が保証されます。

コマンド ステータス
temperature temperatureK
spectrumRGB spectrumRgb
spectrumHSV spectrumHsv

EXECUTE リクエストとレスポンスの例

「ライトをマゼンタにして」colorModel 属性は rgb に設定されている)

リクエスト
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "lambtwirl"
          }
        }],
        "execution": [{
          "command": "action.devices.commands.ColorAbsolute",
          "params": {
            "color": {
              "name": "magenta",
              "spectrumRGB": 16711935
            }
          }
        }]
      }]
    }
  }]
}
Node.jsレスポンス
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        status: 'SUCCESS',
        states: {
          online: true,
          color: {
            spectrumRgb: 16711935
          }
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
JSONレスポンス
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "color": {
            "spectrumRgb": 16711935
          }
        }
      }
    ]
  }
}

「キッチンランプを青にして」colorModel 属性は hsv に設定されている)

リクエスト
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "456",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "lambtwirl"
          }
        }],
        "execution": [{
          "command": "action.devices.commands.ColorAbsolute",
          "params": {
            "color": {
              "spectrumHSV": {
                "hue": 240.0,
                "saturation": 1.0,
                "value": 1.0
              }
            }
          }
        }]
      }]
    }
  }]
}
Node.jsレスポンス
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        status: 'SUCCESS',
        states: {
          online: true,
          color: {
            spectrumHsv: {
              hue: 240.0,
              saturation: 1.0,
              value: 1.0
            }
          }
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
JSONレスポンス
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "color": {
            "spectrumHsv": {
              "hue": 240,
              "saturation": 1,
              "value": 1
            }
          }
        }
      }
    ]
  }
}

「ランプをクールホワイトにして」colorTemperatureRange 属性が提供されている)

リクエスト
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "456",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "lambtwirl"
          }
        }],
        "execution": [{
          "command": "action.devices.commands.ColorAbsolute",
          "params": {
            "color": {
              "name": "warm white",
              "temperature": 4000
            }
          }
        }]
      }]
    }
  }]
}
Node.jsレスポンス
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        status: 'SUCCESS',
        states: {
          online: true,
          color: {
            temperatureK: 4000
          }
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
JSONレスポンス
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "color": {
            "temperatureK": 4000
          }
        }
      }
    ]
  }
}