Light Trait
API Service: LightApi
Control the light output of a device. Brightness values should be normalised to 0-100 as a percentage, though the device may not support all steps within. See BrightnessSupport for step values of the device.
| Method | Request Type | Response Type | Description |
|---|---|---|---|
| UpdateBrightness | UpdateBrightnessRequest | Brightness | request that the brightness be changed |
| GetBrightness | GetBrightnessRequest | Brightness | get the current value of the range |
| PullBrightness | PullBrightnessRequest | PullBrightnessResponse stream | request updates to changes in the range value |
Info Service: LightInfo
Describes the capabilities of a specific named device with respect to this trait.
| Method | Request Type | Response Type | Description |
|---|---|---|---|
| DescribeBrightness | DescribeBrightnessRequest | BrightnessSupport | Get information about how a named device implements Brightness features |
Brightness
Brightness represent the light level that is being emitted. It represents the output level as either a percentage or a preset. Both percentage and preset can be present on read if the device supports exposing a presets underlying value, e.g. Full (100%). Off (0%) cannot be distinguished from Off (not present), this is by design as the alternative would complicate the type use for all other cases.
If the output level is transitioning towards a value then target_level_percent or target_preset may be present on read to indicate what the final state will be. The level_percent and preset value always represent the current value.
| Field Name | Type | Description |
|---|---|---|
| level_percent | float | A level that the device is set to. [0-100] as a percentage. A zero value will be ignored iff preset is present. On write only one of level_percent or preset should be set. |
| preset | LightPreset | A preset that the device is using |
| brightness_tween | smartcore.types.Tween | How the brightness changes or should change over time. On write only duration should be set. |
| target_level_percent | float | The target level_percent. Ignored on write. On read zero values should be ignored iff target_preset is present. |
| target_preset | LightPreset | The target preset. Ignored on write. If present ignore target_level_percent |
LightPreset
| Field Name | Type | Description |
|---|---|---|
| name | string | |
| title | string |
BrightnessSupport
BrightnessSupport describes the capabilities of devices implementing this trait
| Field Name | Type | Description |
|---|---|---|
| resource_support | smartcore.types.ResourceSupport | How a named device supports read/write/pull apis |
| brightness_attributes | smartcore.types.Int32Attributes | control how the brightness can be controlled. The range of these attributes is fixed at 0-100 as a percentage |
| presets | repeated LightPreset | A description of the supported presets, none means no presets |
UpdateBrightnessRequest
A request to update the value of a brightness
| Field Name | Type | Description |
|---|---|---|
| name | string | The name of the device to update |
| brightness | Brightness | The new value for the brightness. Supply ramp to transition |
| delta | bool | if true, then the values in the brightness represent deltas from the current value and not absolute values |
| update_mask | google.protobuf.FieldMask | The state fields to update |
GetBrightnessRequest
A request to get the current value of a brightness
| Field Name | Type | Description |
|---|---|---|
| name | string | The name of the device to get the value for |
| read_mask | google.protobuf.FieldMask | The state fields to fetch |
PullBrightnessRequest
Request to begin a subscription for brightness values
| Field Name | Type | Description |
|---|---|---|
| name | string | The name of the device we want events from |
| exclude_ramping | bool | Indicate whether we want to be notified of values while ramping or not. The device may ignore this depending on capabilities |
| read_mask | google.protobuf.FieldMask | The state fields to fetch |
| updates_only | bool | When true the device will only send changes to the resource value. The default behaviour is to send the current value immediately followed by any updates as they happen. |
PullBrightnessResponse
A response as part of the stream of changes to the brightness value
| Field Name | Type | Description |
|---|---|---|
| changes | repeated PullBrightnessResponse.Change | The list of changes |
PullBrightnessResponse.Change
A change to a single devices brightness value
| Field Name | Type | Description |
|---|---|---|
| name | string | name for the device that issued the change |
| change_time | google.protobuf.Timestamp | when the change occurred |
| brightness | Brightness | The new value for the brightness |
DescribeBrightnessRequest
| Field Name | Type | Description |
|---|---|---|
| name | string | The name of the device |