Your Alexa Dashboards
Sign In
?
Sign In
Your Alexa Dashboards Support

Property Schemas for State Reporting

This document contains the schemas for property values that are used to indicate state changes.

Brightness

Indicates the brightness of an appliance such as a smart light bulb. Valid value is an integer from 0-100, inclusive.

Example brightness

{
  "name": "brightness",
  "value": 45
 }

Channel

Represents a channel as a number or call sign. It is a structure containing number, callSign and affiliateCallSign attributes. Only one of these attributes is required for the channel to be valid. Used by the ChannelController interface.

Field Description
number String representing a floating point number that identifies the channel such as 13.1.
callSign The call sign of the channel such as PBS.
affiliateCallSign The local affiliate call sign for the channel such as KBTC.

Example Channel

{
   "name":"channel",
   "value": {
    "number": "6",
    "callSign": "PBS",
    "affiliateCallSign": "KBTC"
  }
}

Color

Used for properties that represent the color of an endpoint. It is a structure containing hue, saturation and brightness fields, which are each double precision numbers. For use by endpoints that are able to change color.

Field/Value Description
hue Indicates the hue attribute of the color. A double that ranges from 0.0 to 360.0, inclusive.
saturation Indicates the saturation attribute of the color. A double that ranges from 0.0 to 1.0, inclusive.
brightness Indicates the brightness attribute of the color. A double that ranges from 0.0 to 1.0, inclusive.

Example color

{
    "name": "color",
    "value": {
        "hue": 350.5,
        "saturation": 0.7138,
        "brightness": 0.6524
    }
}

ColorTemperatureInKelvin

The ColorTemperature schema is used for properties that represent the color temperature of an endpoint. It an integer with a valid range from 1000 to 10000 inclusive, indicating the color temperature in degrees Kelvin. Used by endpoints that support tunable white light.

Some example customer requests and resulting kelvin values:

Shades of White colorTemperatureInKelvin value
warm, warm white 2200
incandescent, soft white 2700
white 4000
daylight, daylight white 5500
cool, cool white 7000

Example colorTemperatureInKelvin

{
    "name": "colorTemperatureInKelvin",
    "value": 7500
}

Connectivity

Represents the connectivity state of an endpoint. Used by the EndpointHealth interface.

Field/Value Description
value Indicates the status of the endpoint. One of the following values: OK, UNREACHABLE

Example Connectivity

{
    "name": "connectivity",
    "value": 
     {
      "value" : "UNREACHABLE"
     }
}

Input

Represents the input state of an audio video endpoint. Its value is a single string that indicates the input device. Used by the InputController interface.

Example Input

{
    "name": "input",
    "value": "HDMI1"
}

LockState

The LockState schema is used for properties that represent the state of a lock. It is a string with the following valid values:

Field/Value Description
LOCKED Indicates that the appliance is currently locked.
UNLOCKED Indicates that the appliances is currently unlocked.
JAMMED Indicates that the lock cannot complete its transition to “LOCKED” or “UNLOCKED” because the locking mechanism is jammed.

Example lockState

{
  "name": "lockState",
  "value": "LOCKED"
}

MuteState

Represents the mute state of an audio device. A single boolean value where true indicates the device is muted and false indicates the device is not muted. Used by the Speaker interface

Example MuteState

{
    "name": "muted",
    "value": false
}

Percentage

Represent a percentage value. Integer with a valid range of 0-100.

Example percentage

{
 "name": "percentage",
  "value": 74
}

PowerState

Represents the power state of a device. Two valid string values:

  • “ON”
  • “OFF”

Example powerState

{
  "name": "powerState",
  "value": "OFF"
}

Temperature

A structure that contains a value and a scale that is used for properties that represent a temperature.

Field/Value Description
value An double representing the numerical temperature value in the scale specified.
scale String either “CELSIUS”, “FAHRENHEIT” or “KELVIN”

Example lowerSetpoint temperature

{
    "name": "lowerSetpoint",
    "value": {
        "value": 68.0,
        "scale": "FAHRENHEIT"
    }
}

ThermostatMode

Used for properties that represent the mode of a thermostat. Valid values are strings, and listed in the table that follows. When ThermostatMode is “CUSTOM”, you must provide an addition field, customName.

Field/Value Description
AUTO Automatic heat or cool selection based on the temperature reading and the setpoint
COOL cooling mode
HEAT heating mode
ECO economical mode
OFF heating/cooling is turned off, but the device may still have power
CUSTOM A custom mode specified by an additional field customName
customName String indicating a custom mode or friendly name specific to the endpoint or manufacturer.

The customName attribute specifies a friendly name for the custom temperature mode. The value for this field is specific to your implementation/device and you must contact Amazon to provide a custom name.

customName is required when value is set to CUSTOM, optional otherwise. When used with a predefined mode such as AUTO, the customName specifies a manufacturer’s preferred name for the mode. When used with the CUSTOM mode, customName specifies a manufacturer’s custom mode for the thermostat that is not already represented by other modes.

Example

{
    "name": "thermostatMode",
    "value": "AUTO"
}

Example customName with Predefined Mode:

{
    "name": "thermostatMode",
    "value": "AUTO",
    "customName": "VENDOR_HEAT_COOL"
}

Example with CUSTOM, customName:

{
    "name": "thermostatMode",
    "value": "CUSTOM",
    "customName" : "VENDOR_HEAT_COOL"
}

VolumeLevel

Used for properties that represent the audio volume level on a scale from 0 to 100. Its value is a single integer ranging from 0-100. Used by the Speaker interface.

Example VolumeLevel

{
   "name":"volume",
   "value":"50"
}