Google IoT Communication Platform - Google Weave 소개

Google IoT Communication Platform: Goole Weave 소개

이 문서는 https://developers.google.com/weave/ 홈페이지 내용을 참고하여 작성하였다.

제 개인적인 의견으로는 Apple HomeKit에 비해 개념 정립이 아직 덜 된 느낌이 있으며, 지원하는 장치와 기능들이 제한적이다. 

 1. Weave란?

Weave는 OEM 제조사의 IoT 장치들을 Google Cloud Service에 연결할 수 있는 Weave Device SDK와 Weave Server가 포함된 Communications Platform이다.
  • Weave Device SDK(libiota) - Linux, Qualcomm QCA4010 및 Marvell MW302기반의 장치들을 Weave Server에 연결할 수 있도록 지원되는 Lightweight Device SDK
  • Weave Server - Cloud Service이며, 이 서비스는 안전한 장치등록, 명령전달, 상태저장 및 Google Assistant와 같은 Google Service들과 통합을 제공
Weave를 통해서 Google은 클라우드를 관리하고 Google Assistant 음성 명령과 같은 Google 서비스와 함께 작동하도록 모든 백엔드 작업을 수행한다.

Weave는 현재 HVAC 컨트롤러, 조명, 콘센트, TV 및 벽 스위치와 같은 장치 유형을 지원하며, 더 많은 장치 유형을 추가 할 예정이다.

Weave에 대해서 보다 자세하게 알아 보자.

1.1. Weave 개발자 기능들

Weave 개발자들은 다음과 같은 개발자 기능들을 사용할 수 있다.
  • IoT Developer Console - 모든 Weave 장치를 관리하고 장치 활성화 및 명령 사용에 대한 실시간 통계를 한 곳에서 모니터링
  • Weave Developer app - Android 또는 iOS 기기에서 모든 Weave장치를 제어할 수 있고,  장치등록, 상태 관리 및 명령 전달을 시험
  • Command-line tools and simulators - 장치 명령들을 테스트하고, 장치를 개발
  • OEM metrics - 배포된 장치들의 집계되고 익명화 된 측정 항목들을 수집

1.2. 상호연동

Weave는 공통 장치 및 장치 특성에 대한 정의를 제공하여 동일한 유형의 장치간에 일관성을 보장한다.

2. Weave 장치들

Weave 장치는 Weave Device SDK에 내장된 Weave Protocol을 지원하는 IoT Device이다. 이 장치는 구성 요소 및 특성을 사용하여 장치 기능들을 규정하는 Weave Protocol을 제공한다. 특정 장치를 설명하는 구성 요소 및 특성 집합들을 장치 스키마(device schema)라고 한다.

Weave Protocol은 디바이스가 지원하는 명령과 디바이스가 유지 보수 할 수 있는 상태 정보의 유형을 알아내기 위해 제공된 Device Schema를 사용한다.

2.1. 장치 특성 및 구성 요소(Device traits and components)

특성(trait)은 장치 내의 기능을 정의한다. 예를 들어 "onOff" 특성은 켜거나 끌 수있는 장치 기능을 설명하고, 이 기능에 대한 on/off 상태 및 명령을 정의한다.

구성 요소(component)는 각 특성의 현재 상태뿐만 아니라 장치를 구성하는 특성 간의 구성 또는 논리적 관계를 설명한다. 예를 들어 벽 스위치 장치는 장치의 전원 스위치를 나타내는 "powerSwitch" 구성 요소를 제공 할 수 있다. "powerSwitch"구성 요소는 on/off 명령과 현재 전원 스위치 상태를 관리하기 위해 "onOff" 특성(trait)을 사용한다.

Weave 장치는 장치와 장치 상태를 설명하는 구성 요소 목록을 규정해야 한다.

2.2. 장치 명령(Device Commands)

명령은 특정 작업을 수행하기 위해 장치에 명령을 보낼 수 있다. 명령에는 특성 정의들, 파라메타들 그리고 완료된 결과 값들을 기반한 상태 값들이 담겨져 있다.

2.3. 공용 장치 스키마(Common Device Schemas)

IoT 장치의 공통적인 문제는 상호 운용성의 부족이다. 다른 제조업체들의 장치들은 기능이 다를 수도 있고, 동일한 기능일지라도 다르게 표현될수 있어서 여러 장치들을 아우려 사용하려는 응용 프로그램이나 사용자들에게 어려움을 준다.

Weave는 표준 장치 유형을 나타내는 공통 장치 스키마(개발자가 장치를 표현하는 데 사용할 수 있는) 및 특성 집합을 도입하여 상호 운용성 문제를 해결한다.  이러한 장치 유형들은 그 장치들에게 접속하려는 클라이언트들에 일관성있는 방법을 제공한다.

3. 표준 특성들(Traits)

특성이름설명
BrightnessBrightness trait.
Color ModeColor mode trait (temperature, XY, etc).
Color TemperatureColor temperature trait.
Color XYColor XY trait.
Humidity SensorHumidity sensor trait.
HVAC Subsystem ControllerHVAC subsystem controller trait.
On OffOn/off trait.
Temperature Range SettingTemperature range setting trait.
Temperature SensorTemperature sensor trait.
Temperature SettingTemperature setting trait.
Temperature Units SettingTemperature units setting trait.

3.1. Brightness Trait(Trait ID: 0x00010006)

1) States
StateTypeComments
brightnessFloat (0.0 - 1.0)Required

Current brightness of the light source.


2) Commands

  • SetConfig
Command ParameterTypeComments
brightnessFloat (0.0 - 1.0)Optional

Current brightness of the light source.

3) Errors
NumberErrorComments
1UNEXPECTED_ERRORAn unexpected error was encountered while changing the state.
2VALUE_OUT_OF_RANGEThe requested value was out of the expected range.

3.2. Color Mode Trait(Trait ID: 0x00010010)

1) States
StateTypeComments
modeColorModeEnumOptional

No description.


2) Enums
  • ColorModeEnum
NumberEnum fieldComments
0UNKNOWNThe value received is not defined in this enumeration.
1COLOR_XYColor mode based on the goog.ColorXy trait.
2COLOR_TEMPColor mode based on the goog.ColorTemp trait.


3.3. Color Temperature Trait(Trait ID: 0x00010009)

1) States
StateTypeComments
color_tempInt32Required

The current color setting in units of Mired Color Temperature (10^6/(Temp in Kelvin)) on the BlackBodyLine (BBL). 0 means not on BBL.
min_color_tempInt32Required

The min colorTemp, in Mired, the component can achieve.
max_color_tempInt32Required

The max colorTemp, in Mired, the component can achieve.

2) Commands
  • SetConfig
Command ParameterTypeComments
color_tempInt32Optional

The current color setting in units of Mired Color Temperature (10^6/(Temp in Kelvin)) on the BlackBodyLine (BBL). 0 means not on BBL.


2) Errors

NumberErrorComments
1UNEXPECTED_ERRORAn unexpected error was encountered while changing the state.
2VALUE_OUT_OF_RANGEThe requested value was out of the expected range.


3.4. Color XY Trait(Trait ID: 0x00010007)

1) States
StateTypeComments
color_cap_redColorCoordinateRequired

Color capability of light for maximum red in CIE xy.
color_cap_greenColorCoordinateRequired

Color capability of light for maximum green in CIE xy.
color_cap_blueColorCoordinateRequired

Color capability of light for maximum blue in CIE xy.
color_settingColorCoordinateRequired

The current color of the light in CIE xy.


2) Structs
  • ColorCoordinate struct
Struct fieldTypeComments
color_yFloat (0.0 - 1.0)Required

The Y component of the color.
color_xFloat (0.0 - 1.0)Required

The X component of the color.

3) Commands
  • SetConfig
Command ParameterTypeComments
color_settingColorCoordinateOptional

The current color of the light in CIE xy.

4) Errors

NumberErrorComments
1UNEXPECTED_ERRORAn unexpected error was encountered while changing the state.
2VALUE_OUT_OF_RANGEThe requested value was out of the expected range.

3.5. Humidity Sensor Trait(Trait ID: 0x0001000e)

1) States
StateTypeComments
valueFloat (0.0 - 1.0)Required

Current relative humidity reading normalized from 0 to 1.

3.6. HAVC Subsystem Controller Trait(Trait ID: 0x0001000d)

1) States
StateTypeComments
controller_modeControllerModeRequired

The controller mode, as requested by the user.
subsystem_stateSubsystemStateRequired

The current state of the subsystem, as determined by the controller.
supports_mode_disabledBoolRequired

This controller supports CONTROLLER_MODE_DISABLED.
supports_mode_always_onBoolRequired

This controller supports CONTROLLER_MODE_ALWAYS_ON.
supports_mode_autoBoolRequired

This controller supports CONTROLLER_MODE_AUTO.


2) Enums
  • ControllerMode
NumberEnum fieldComments
0UNKNOWNThe value received is not defined in this enumeration.
1DISABLEDThe subsystem should transisition to the OFF state and stay there.
2ALWAYS_ONThe subsystem should transisition to the ON state and stay there. This may not be supported by all controllers.
3AUTOThe controller should place the subsystem under automatic control.
  • SubsystemState
NumberEnum fieldComments
0UNKNOWNThe value received is not defined in this enumeration.
1OFFThe subsystem is currently off.
2ONThe subsystem is currently on.

2) Commands
  • SetConfig
Command ParameterTypeComments
controller_modeControllerModeOptional

The controller mode, as requested by the user.

3) Errors
NumberErrorComments
1UNEXPECTED_ERRORAn unexpected error was encountered while changing the state.
3INVALID_VALUEThe requested value is invalid.
4INVALID_STATEThe combination of values provided is not valid.

3.6. On Off Trait(Trait ID: 0x00010005)

1) States
StateTypeComments
stateOnOffStateRequired

The power state of the device.

2) Enums
  • OnOffState
NumberEnum fieldComments
0UNKNOWNThe value received is not defined in this enumeration.
1ONThe device is on.
2OFFThe device is off.


3) Commands
  • SetConfig
Command ParameterTypeComments
stateOnOffStateOptional

The power state of the device.

4) Errors
NumberErrorComments
1UNEXPECTED_ERRORAn unexpected error was encountered while changing the state.
3INVALID_VALUEThe requested value is invalid.

3.7. Temperature Range Setting Trait(Trait ID: 0x0001000f)

3.8. Temperature Sensor(Trait ID: 0x0001000a)

3.9. Temperature Setting(Trait ID: 0x0001000b)

3.10. Temperature Units Setting(Trait ID: 0x0001000c)


4. Device Schemas

아래 나열된 문서는 표준 Weave Device에 대한 참조 스키마를 제공한다. 각 문서는 특정 장치 유형을 대상으로 한다. Google은 현재 이 장치 유형에 대해서만 인증하고 있으며, 매 분기마다 더 많은 장치 유형을 추가 할 예정이라고 한다.
Device Type SchemaDescription
LightLight 장치들에 대한 표준 명령들과 특성들
Outlet콘센트 정치들에 대한 표준 명령들과 특성들
HVAC ControllerHAVC 제어 장치들에 대한 표준 명령들과 특성들
Wall Switch스위치 장치들에 대한 표준 명령들과 특성들

4.1. Light (Interface ID: 0x00018006)

  • 구성 요소들
Component NameTraitComments
power_switchOnOffRequired

The main power switch for this light.
dimmerBrightnessOptional

An optional dimmer control for this light.
color_xyColorXyOptional

An optional color setting using the XY color space.
color_tempColorTempOptional

An optional color setting in degrees Kelvin.
color_modeColorModeOptional

If this light supports both ColorXy and ColorTemp, then this component reflects current mode, otherwise this component should not be present.

  • JSON example for a light device
{
  "colorTemp": {
    "traits": [
      "colorTemp"
    ]
  },
  "colorMode": {
    "traits": [
      "colorMode"
    ]
  },
  "powerSwitch": {
    "traits": [
      "onOff"
    ]
  },
  "colorXy": {
    "traits": [
      "colorXy"
    ]
  },
  "dimmer": {
    "traits": [
      "brightness"
    ]
  }
}

{
  "colorTemp": {
    "traits": [
      "colorTemp"
    ]
  },
  "colorMode": {
    "traits": [
      "colorMode"
    ]
  },
  "powerSwitch": {
    "traits": [
      "onOff"
    ]
  },
  "colorXy": {
    "traits": [
      "colorXy"
    ]
  },
  "dimmer": {
    "traits": [
      "brightness"
    ]
  }
}

4.2. Outlet(Interface ID: 0x00018007)

  • 구성 요소들
Component NameTraitComments
power_switchOnOffRequired

No description.
dimmerBrightnessOptional

No description.
  • JSON example for a light device

4.3. HAVC Controller(Interface ID: 0x00018008)

  • 구성 요소들
Component NameTraitComments
heat_subsystemHvacSubsystemControllerOptional

If this controller is present and AUTO mode is supported, then setting the controller to AUTO will cause heating subsystem to turn on when the current_temperature is lower than the heat_setting.

When this controller is in AUTO, the cool_subsystem and heat_cool_subsystemcomponents should both transition to the DISABLED state.

This controller MUST NOT support the ALWAYS_ON mode.
heat_settingTempSettingOptional

If this setting is present it is the temperature setting for the heat_subsystem.
cool_subsystemHvacSubsystemControllerOptional

If this controller is present and AUTO mode is supported, then setting the controller to AUTO will cause cooling subsystem to turn on when the current_temperature is higher than the cool_setting.

When this controller is in AUTO, the heat_subsystem and heat_cool_subsystemcomponents should both transition to the DISABLED state.

This controller MUST NOT support the ALWAYS_ON mode.
cool_settingTempSettingOptional

If this setting is present it is the temperature setting for the cool_subsystem.
heat_cool_subsystemHvacSubsystemControllerOptional

If this controller is present, then setting it to AUTO will cause the heating subsystem to turn on when the current_temperature is lower than the low_set_point_c, and the cooling subsystem to turn on when the current_temperature is above high_set_point_c.

When this controller is set to AUTO, the heat_subsystemand cool_subsystem should both transition to DISABLED. However, the subsystem_state values should continue to represent the current state of the heat and cool subsystems.

This controller MUST NOT support the ALWAYS_ON mode.
heat_cool_settingTempRangeSettingOptional

If this setting is present it is the temperature range setting for the heat_cool_subsystem.
fan_subsystemHvacSubsystemControllerOptional

If this controller is present and AUTO mode is supported, then setting the controller to AUTO will turn the fan on when either heating or cooling is active. If ALWAYS_ON mode is supported and enabled, then the fan will run regardless of the state of the heating and cooling subsystems.

This controller MUST NOT support the OFF mode.
ambient_air_temperatureTempSensorOptional

The current ambient air temperature as measured at or near the HVAC controller.
ambient_air_humidityHumiditySensorOptional

The current relative humidity of the air as measured at or near the HVAC controller.
display_unitsTempUnitsSettingOptional

The desired temperature display units.

4.3. WallSwitch(Interface ID: 0x00018009)

일반적으로 건물 벽에 설치되는 것으로 조광기(dimmer)는 옵션인 스위치

  • 구성 요소들
Component NameTraitComments
power_switchOnOffRequired

No description.
dimmerBrightnessOptional

No description.

5. REST API

Weave Companion API는 Weave 사용자들이 장치들을 프로그램적으로 관리할 수 있도록 한다.

모든 REST API의 URI는 https://weavecompanion.googleapis.com 에서 제공된다.

  • Collection: v1.devices
Methods
deleteDELETE /v1/{name=devices/*}
Deletes a device.
getGET /v1/{name=devices/*}
Gets a device.
listGET /v1/devices
Lists devices.
provisionPOST /v1/devices:provision
Provision a device.

  • Collection: v1.devices.commands
Methods
createPOST /v1/{device=devices/*}/commands
Creates a command.
getGET /v1/{name=devices/*/commands/*}
Gets a command.
listGET /v1/{device=devices/*}/commands
Lists commands.


5.1. Method: device.delete

  • HTTP request
    • DELETE https://weavecompanion.googleapis.com/v1/{name=devices/*}

  • Path Parameters
Parameters
name
string
The name of the device to delete.
  • Request body
    • The request body must be empty.
  • Response body
    • If successful, the response body will be empty.
  • Authorization
    • Requires the following OAuth scope:
      • https://www.googleapis.com/auth/weave.app

5.2. Method: device.get

  • HTTP request
    • GET https://weavecompanion.googleapis.com/v1/{name=devices/*}

  • Path Parameters
Parameters
name
string
The resource name of the device.
  • Request body
    • The request body must be empty.
  • Response body
    • If successful, the response body will be empty.
  • Authorization
    • Requires the following OAuth scope:
      • https://www.googleapis.com/auth/weave.app

5.3. Method: device.list

  • HTTP request
    • GET https://weavecompanion.googleapis.com/v1/devices

  • Query Parameters
Parameters
pageSize
number
Requested page size. Server may return fewer devices than requested. If unspecified, server will pick an appropriate default.
pageToken
string
A token identifying a page of results the server should return.
  • Request body
    • The request body must be empty.
  • Response body
    • If successful, the response body contains data with the following structure:
      Response message for WeaveCompanionService.ListDevices.
JSON representation
{ "devices": [ { object(Device) } ], "nextPageToken": string, }







Fields
devices[]
object(Device)
The list of devices.
nextPageToken
string
A token to retrieve next page of results.
  • Authorization
    • Requires the following OAuth scope:
      • https://www.googleapis.com/auth/weave.app

5.4. Method: device.commands.create

  • HTTP request

  • Path Parameters
Parameters
device
string
The name of the device to create the command.
  • Query Parameters
Parameters
expireAfterTimeMs
number
Optional time in milliseconds that the command is expired after.
  • Request body
    • The request body contains an instance of Command.
  • Response body
    • If successful, the response body contains a newly created instance of Command.
  • Authorization
    • Requires the following OAuth scope:
      • https://www.googleapis.com/auth/weave.app

5.5. Collection: devices

  • Resource:Device
JSON representation
{ "name": string, "displayName": string, "description": string, "nicknames": [ string ], "serialNumber": string, "modelManifestId": string, "interfaceVersion": string, "firmwareVersion": string, "oemName": string, "modelName": string, "components": { object }, "traits": { object }, "deviceKind": enum(DeviceKind), "state": { object }, "connectionStatus": enum(ConnectionStatus), "createTime": string, "lastUpdateTime": string, "lastUseTime": string, "lastSeenTime": string, }
Fields
name
string
The resource name of the device. Device names have the form devices/{device_id}.
Note: This field is used in responses only. Any value specified here in a request is ignored.
displayName
string
Display name of the device.
description
string
Description of the device.
nicknames[]
string
Nicknames of the device.
serialNumber
string
Serial number of the device.
Note: This field is used in responses only. Any value specified here in a request is ignored.
modelManifestId
string
Model manifest ID of the device.
Note: This field is used in responses only. Any value specified here in a request is ignored.
interfaceVersion
string
Interface version of the device.
Note: This field is used in responses only. Any value specified here in a request is ignored.
firmwareVersion
string
Firmware version of the device.
Note: This field is used in responses only. Any value specified here in a request is ignored.
oemName
string
Name of device model manufacturer.
Note: This field is used in responses only. Any value specified here in a request is ignored.
modelName
string
Device model name.
Note: This field is used in responses only. Any value specified here in a request is ignored.
components
object (Struct format)
Components of the device model. { "powerSwitch": { "traits": [ {"trait": "onOff"} ] }, "dimmer": { "traits": [ {"trait": "brightness"} ] } }
Note: This field is used in responses only. Any value specified here in a request is ignored.
traits
object (Struct format)
Traits that the device model components use.
{ "onOff": { "commands": { "setConfig": { "parameters": { "state": { "type": "string", "enum": [ "on", "off" ] } } } }, "state": { "state": { "isRequired": true, "type": "string", "enum": [ "on", "off" ] } } }, "brightness": { ... } }
Note: This field is used in responses only. Any value specified here in a request is ignored.
deviceKind
enum(DeviceKind)
Device kind.
Note: This field is used in responses only. Any value specified here in a request is ignored.
state
object (Struct format)
Components state of the device. As an example, the state of a simple light device looks like this. { "powerSwitch": { "state": { "onOff": { "state": "on" } } }, "dimmer": { ... } }
Note: This field is used in responses only. Any value specified here in a request is ignored.
connectionStatus
The connection status for a device.
Note: This field is used in responses only. Any value specified here in a request is ignored.
createTime
string (Timestamp format)
Create time.
A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".
Note: This field is used in responses only. Any value specified here in a request is ignored.
lastUpdateTime
string (Timestamp format)
Last update time.
A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".
Note: This field is used in responses only. Any value specified here in a request is ignored.
lastUseTime
string (Timestamp format)
Last use time.
A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".
Note: This field is used in responses only. Any value specified here in a request is ignored.
lastSeenTime
string (Timestamp format)
Last seen time.
A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".
Note: This field is used in responses only. Any value specified here in a request is ignored.

  • DeviceKind
Enums
UNKNOWN_DEVICE_KINDUnknown device kind.
AC_HEATINGAir Conditioner.
LIGHTLight.
OUTLETOutlet.
SWITCHSwitch.
TVTV.

  • ConnectionStatus
Enums
CONNECTION_STATUS_UNSPECIFIEDConnection status unspecified.
ONLINEOnline status.
OFFLINEOffline status.
  • Methods

Methods

delete

Deletes a device.

get

Gets a device.

list

Lists devices.

provision

Provision a device.

5.6. Collection: devices.commands

  • Resource:Command

JSON representation
{ "name": string, "commandName": string, "state": enum(CommandState), "parameters": { object }, "results": { object }, "error": { object(ErrorData) }, "createTime": string, "expireTime": string, "lastUpdateTime": string, }
Fields
name
string
The resource name of the command. Command names have the form devices/{device_id}/commands/{command_id}.
Note: This field is used in responses only. Any value specified here in a request is ignored.
commandName
string
Full command name including component and trait.
state
Command state.
Note: This field is used in responses only. Any value specified here in a request is ignored.
parameters
object (Struct format)
Parameters object of the command. It's set by clients. It can be empty.
results
object (Struct format)
Results object of the command. It's set by devices when the command is completed successfully. It can be empty.
Note: This field is used in responses only. Any value specified here in a request is ignored.
error
object(ErrorData)
Command error. It's set by devices when the command is aborted.
Note: This field is used in responses only. Any value specified here in a request is ignored.
createTime
string (Timestamp format)
Creation time.
A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".
Note: This field is used in responses only. Any value specified here in a request is ignored.
expireTime
string (Timestamp format)
Expiration time.
A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".
Note: This field is used in responses only. Any value specified here in a request is ignored.
lastUpdateTime
string (Timestamp format)
Latest command update time.
A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".
Note: This field is used in responses only. Any value specified here in a request is ignored.
  • Command States
Enums
UNKNOWN_COMMAND_STATEUnknown command state.
QUEUEDCommand has been submitted.
ABORTEDExecution of the command was aborted by the device and cannot continue.
COMPLETEDCommand execution was successfully completed and all command results have been provided by the device.
EXPIREDDevice did not complete or abort the command before the expiration time-limit.
  • Error Data
JSON representation
{ "errorCode": string, "errorMessage": string, "arguments": { object }, }

Fields
errorCode
string
Status code indicating the type of error that occurred. This can be one of the standard set of codes, or a vendor-specific code.
errorMessage
string
User-visible error message format in English. Error translations should be provided in the model manifests.
arguments
object (Struct format)
Keyed error arguments used for error message formatting.
  • Methods

Methods

create

Creates a command.

get

Gets a command.

list

Lists commands.

댓글

이 블로그의 인기 게시물

macOS가 갑자기 부팅이 되지 않을 경우 데이터 복구 또는 백업 방법

C++로 프로그래밍할 때 인자 또는 리턴 값으로 std::vector 등 STL 데이터 타입 처리하는 좋은 방법

Git 저장소를 병합하는 방법(How to merge repositories in Git)