{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"settings":"","params":[]},"next":{"description":"","pages":[]},"title":"Light Messages","type":"basic","slug":"light-messages","excerpt":"","body":"Light messages control and acquire the state of a specific type of device, such as a lightbulb.  The state is comprised of the [label](doc:device-messages#section-label), [power level](doc:device-messages#section-power-level) and [color](#section-hsbk).\n\nThere are a duplicate set of __device__ power related messages, [Device::GetPower](doc:device-messages#section-getpower-20), [Device::StatePower](doc:device-messages#section-statepower-22) and [Device::SetPower](doc:device-messages#section-setpower-21), which are extended for lights by adding a _duration_ field to [Light::SetPower](#section-setpower-117).\n\nThe [Protocol header](doc:header-description#protocol-header) _message type_ field value (decimal) appears after each message name in this document. Each section below describes the _payload_ that is appended to the [message header](doc:header-description). Some messages do not require a payload.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Message Field Data Types\"\n}\n[/block]\n### HSBK\n\nHSBK is used to represent the _color_ and _color_ temperature of a light.\n\nThe _color_ is represented as an HSB ([Hue, Saturation, Brightness](http://en.wikipedia.org/wiki/HSL_and_HSV)) value.\n\nThe _color temperature_ is represented in K ([Kelvin](http://en.wikipedia.org/wiki/Color_temperature)) and is used to adjust the warmness / coolness of a white light, which is most obvious when saturation is close zero.\n\n* Hue: range 0 to 65535\n* Saturation: range 0 to 65535\n* Brightness: range 0 to 65535\n* Kelvin: range 2500° (warm) to 9000° (cool)\n\n| Field | Type |\n|-------|------|\n| hue | unsigned 16-bit integer |\n| saturation | unsigned 16-bit integer |\n| brightness | unsigned 16-bit integer |\n| kelvin | unsigned 16-bit integer |\n\nFor user interface purposes, the hue is typically scaled to between 0° and 360°. Saturation and brightness are typically scaled to between 0% and 100%.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Light Messages\"\n}\n[/block]\n### Get - 101\n\nSent by a client to obtain the light state. No payload required. Causes the device to transmit a [State](#section-state-107) message.\n\n### SetColor - 102\n\nSent by a client to change the light state.\n\n| Field | Type |\n|-------|------|\n| reserved | unsigned 8-bit integer |\n| color | HSBK |\n| duration | unsigned 32-bit integer |\n\nThe _duration_ is the color transition time in milliseconds.\n\nIf the [Frame Address](doc:header-description#frame-address) *res\\_required* field is set to one (1) then the device will transmit a [State](#section-state-107) message.\n\n### SetWaveform - 103\n\nApply an effect to the bulb.\n\nThis message will be replied to with a State message.\n\n| Field | Type | Purpose |\n|-------|------|---------|\n| reserved | unsigned 8-bit integer | |\n| transient | 8-bit integer as 0 or 1 | Color does not persist. |\n| color | Hsbk | Light end color. |\n| period | unsigned 32-bit integer | Duration of a cycle in milliseconds. |\n| cycles | 32-bit float | Number of cycles. |\n| skew_ratio | signed 16-bit integer | Waveform Skew, [-32768, 32767] scaled to [0, 1]. |\n| waveform | unsigned 8-bit integer | Waveform to use for transition. |\n\nSee [Waveforms](doc:waveforms) for more information.\n\n### SetWaveformOptional - 119\n\nOptionally set effect parameters. Same as SetWaveform but allows some parameters to be set from the current value on device.\n\nThis message will be replied to with a State message.\n\n| Field | Type |\n|-------|------|\n| reserved | unsigned 8-bit integer |\n| transient | boolean |\n| color | Hsbk |\n| period | unsigned 32-bit integer |\n| cycles | 32-bit float |\n| skew_ratio | signed 16-bit integer |\n| waveform | unsigned 8-bit integer |\n| set_hue | 8-bit integer as 0 or 1 |\n| set_saturation | 8-bit integer as 0 or 1 |\n| set_brightness | 8-bit integer as 0 or 1 |\n| set_kelvin | 8-bit integer as 0 or 1 |\n\nSee [Waveforms](doc:waveforms) for more information.\n\n### State - 107\n\nSent by a device to provide the current light state.\n\n| Field | Type |\n|-------|------|\n| color | HSBK |\n| reserved | signed 16-bit integer |\n| power | unsigned 16-bit integer |\n| label | string, size: 32 bytes |\n| reserved | unsigned 64-bit integer |\n\nSee [color](#section-hsbk), [label](doc:device-messages#section-label) and [power level](doc:device-messages#section-power-level).\n\n### GetPower - 116\n\nSent by a client to obtain the [power level](doc:device-messages#section-power-level). No payload required. Causes the device to transmit a [StatePower](#section-statepower-118) message.\n\n### SetPower - 117\n\nSent by a client to change the light [power level](doc:device-messages#section-power-level).\n\n| Field | Type |\n|-------|------|\n| level | unsigned 16-bit integer |\n| duration | unsigned 32-bit integer |\n\nThe [power level](doc:device-messages#section-power-level) must be either 0 or 65535.\n\nThe _duration_ is the _power level_ transition time in milliseconds.\n\nIf the [Frame Address](doc:header-description#frame-address) *res\\_required* field is set to one (1) then the device will transmit a [StatePower](#section-statepower-118) message.\n\n### StatePower - 118\n\nSent by a device to provide the current [power level](doc:device-messages#section-power-level).\n\n| Field | Type |\n|-------|------|\n| level | unsigned 16-bit integer |\n\n### GetInfrared - 120\n\nGets the current maximum power level of the Infrared channel. If the [Frame Address](doc:header-description#frame-address) *res_required* field is set to one (1) then the device will transmit a [StateInfrared](#section-stateinfrared-121) message.\n\nNo payload is required\n\n### StateInfrared - 121\n\nThis message is returned from a [GetInfrared](#section-getinfrared-120) message. It indicates the current maximum setting for the infrared channel.\n\n| Field | Type |\n|-------|------|\n| brightness | unsigned 16-bit integer |\n\n### SetInfrared - 122\n\nSend this message to alter the current maximum brightness for the infrared channel.\n\nIf the [Frame Address](doc:header-description#frame-address) *res_required* field is set to one (1) then the device will transmit a [StateInfrared](#section-stateinfrared-121) message.\n\n| Field | Type |\n|-------|------|\n| brightness | unsigned 16-bit integer |","updates":["5be297a0ab8dc900298a7d07"],"order":3,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"57fdb17c4defec0e00642294","githubsync":"","createdAt":"2015-06-18T03:19:08.438Z","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Protocol Messages","slug":"message-types","order":3,"from_sync":false,"reference":false,"_id":"57fdb17c4defec0e0064228e","project":"5581248904ae5b0d0026289a","__v":0,"version":"57fdb17c4defec0e0064228b","createdAt":"2015-06-18T03:15:52.144Z"},"parentDoc":null,"user":"557e2561eb75d80d00af3dab","version":{"version":"2.0","version_clean":"2.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["57fdb17c4defec0e0064228c","57fdb17c4defec0e0064228d","57fdb17c4defec0e0064228e","57fdb520bcc07b0e00d1ef41"],"_id":"57fdb17c4defec0e0064228b","project":"5581248904ae5b0d0026289a","__v":2,"createdAt":"2016-10-12T03:43:56.009Z","releaseDate":"2016-10-12T03:43:56.009Z"},"__v":2,"project":"5581248904ae5b0d0026289a"}