# 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`](https://developers.home.google.com/cloud-to-cloud/intents/sync) operation. To learn
more about handling `SYNC` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/sync).

| 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. Value must be between `0` and `360`. |
| `rotationDegreesMax` | *Number* | **Required.** Maximum rotation in degrees. Value must be between `0` and `360`. |
| `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`](https://developers.home.google.com/cloud-to-cloud/intents/query) operation. To learn
more about handling `QUERY` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute).

| 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. Value must be between `0` and `100`. |
| `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. Value must be between `0` and `100`. |

#### 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`](https://developers.home.google.com/cloud-to-cloud/intents/execute) operation. To learn
more about handling `EXECUTE` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute#handle_execute_intents).

### `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. Value must be between `0` and `100`. |

#### 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
  }
}
```

#### Related errors

An error occurred setting the rotation of the device.

Supported values:

`deviceJammingDetected`

## Device ERRORS

See the full list of [errors and exceptions](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions).