Smart Home Rotation Trait Schema

action.devices.traits.Rotation - This trait belongs to devices that support rotation.

The rotation can be specified in either percent or degrees and if the device supports rotation by degrees, the default direction of rotation is clockwise.

Device ATTRIBUTES

Devices with this trait may report the following attributes as part of the SYNC operation. To learn more about handling SYNC intents, see Intent fulfillment.

Attributes Type Description
supportsDegrees Boolean

Required.

Set to true if the device allows rotation by degree.
supportsPercent Boolean

Required.

Set to true if device allows rotation by percent
rotationDegreesRange Object

Represent the range in degrees that a device can rotate.
rotationDegreesMin Number

Required.

Minimum rotation in degrees.
rotationDegreesMax Number

Required.

Maximum rotation in degrees.
supportsContinuousRotation Boolean

(Default: false)

Set to true if the device allows continuous rotation. When given a relative query, the RotateAbsolute command will wrap around the supported rotation range.
commandOnlyRotation Boolean

(Default: false)

Indicates if the device supports using one-way (true) or two-way (false) communication. Set this attribute to true if the device cannot respond to a QUERY intent or Report State for this trait.

Examples

Device that supports both rotation in percent and degrees.

{
  "supportsDegrees": true,
  "supportsPercent": true,
  "rotationDegreesRange": {
    "rotationDegreesMin": 0,
    "rotationDegreesMax": 180
  }
}

Device that only supports rotation in degrees.

{
  "supportsDegrees": true,
  "supportsPercent": false,
  "rotationDegreesRange": {
    "rotationDegreesMin": 0,
    "rotationDegreesMax": 90
  }
}

Device that only supports continuous rotation commands.

{
  "supportsDegrees": true,
  "supportsPercent": true,
  "rotationDegreesRange": {
    "rotationDegreesMin": 0,
    "rotationDegreesMax": 360
  },
  "supportsContinuousRotation": true,
  "commandOnlyRotation": true
}

Device STATES

Entities with this trait may report the following states as part of the QUERY operation. To learn more about handling QUERY intents, see Intent fulfillment.

States Type Description
rotationDegrees Number

Current level within rotationDegreesRange that indicates how many degrees the device is rotated. This value should always be relative to the clockwise rotation.
rotationPercent Number

Current level that indicates what percent the device is currently rotated. 0.0 corresponds to closed and 100.0 to open.
targetRotationPercent Number

Level indicating the rotation percent where the device will go or is moving to as a result of an ongoing change in rotation.

Examples

How much is the device rotated? (percent and degrees).

{
  "rotationDegrees": 45,
  "rotationPercent": 25
}

How much is the device rotated? (only degrees).

{
  "rotationDegrees": 45
}

How much is the device rotated? (continous).

{
  "rotationDegrees": 270,
  "rotationPercent": 75
}

A device currently rotating to a new position (percent).

{
  "rotationPercent": 75,
  "targetRotationPercent": 100
}

Device COMMANDS

Devices with this trait may respond to the following commands as part of the EXECUTE operation. To learn more about handling EXECUTE intents, see Intent fulfillment.

action.devices.commands.RotateAbsolute

Set the absolute rotation of the device.

Parameters

The payload contains one of the following:

Set the absolute rotation in degrees.

Parameters Type Description
rotationDegrees Number

Required.

An absolute value, in degrees, that specifies the final clockwise rotation of the device. Value must fall within rotationDegreesRange attribute.

Set the absolute rotation in percentage.

Parameters Type Description
rotationPercent Number

Required.

An absolute value, in percentage, that specifies the final rotation of the device.

Examples

Tilt the device to 50 percent.

{
  "command": "action.devices.commands.RotateAbsolute",
  "params": {
    "rotationPercent": 50
  }
}

Rotate the device by 15 degrees counter-clockwise (rotationDegrees: 45).

{
  "command": "action.devices.commands.RotateAbsolute",
  "params": {
    "rotationDegrees": 30
  }
}

Rotate the device by 100 degrees clockwise (supportsContinuousRotation: true, rotationDegrees: 270).

{
  "command": "action.devices.commands.RotateAbsolute",
  "params": {
    "rotationDegrees": 10
  }
}

An error occurred setting the rotation of the device.

Supported values:

deviceJammingDetected

Device ERRORS

See the full list of errors and exceptions.