# Smart Home EnergyStorage Trait Schema

`action.devices.traits.EnergyStorage` - This trait belongs to devices that can store energy in a battery and potentially recharge, or devices that can charge another device.

## 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 |
|---|---|---|
| `queryOnlyEnergyStorage` | *Boolean* | **Required.** True if this device only supports queries about the stored energy levels and, optionally, active charging state (dependent on `isRechargeable` attribute), but does not support starting and stopping charging. |
| `energyStorageDistanceUnitForUX` | *String* | (Default: `"KILOMETERS"`) Will be used in responses to the user. Supported values: `KILOMETERS` `MILES` |
| `isRechargeable` | *Boolean* | (Default: `false`) Set to true if this device is rechargeable. This indicates the device may report `capacityUntilFull`, `isCharging`, and optionally `isPluggedIn` state, and can accept the `Charge` command. |

#### Examples

*Rechargeable device*

```
{
  "isRechargeable": true,
  "queryOnlyEnergyStorage": false
}
```

*Rechargeable device that displays current charge level in miles*

```
{
  "isRechargeable": true,
  "energyStorageDistanceUnitForUX": "MILES",
  "queryOnlyEnergyStorage": false
}
```

*Non-rechargable device that only support reporting current charge level*

```
{
  "isRechargeable": false,
  "queryOnlyEnergyStorage": 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 |
|---|---|---|
| `descriptiveCapacityRemaining` | *String* | **Required.** A qualitative description of the energy capacity level. Note this is for when there's no numeric capacity data. If numeric capacity data is also available, it will be preferred over descriptive when possible. Supported values: `CRITICALLY_LOW` `LOW` `MEDIUM` `HIGH` `FULL` |
| `capacityRemaining` | *Array* | Array of unit/value pairs that hold information on the energy capacity the device currently holds. For example: *How many miles does my \<device\> currently have* or *What percentage charge does my \<device\> have* |
| `[*item, ...*]` | *Object* | Remaining capacity in unit and value pair. |
| `rawValue` | *Integer* | **Required.** The capacity value. |
| `unit` | *String* | **Required.** The capacity unit. Supported values: `SECONDS` `MILES` `KILOMETERS` `PERCENTAGE` `KILOWATT_HOURS` |
| `capacityUntilFull` | *Array* | Array of unit/value pairs that hold information on the capacity until the device is fully charged. For example: *How much time until \<device\> is fully charged*. |
| `[*item, ...*]` | *Object* | Capacity until charged. |
| `rawValue` | *Integer* | **Required.** The capacity value. |
| `unit` | *String* | **Required.** The capacity unit. Supported values: `SECONDS` `MILES` `KILOMETERS` `PERCENTAGE` `KILOWATT_HOURS` |
| `isCharging` | *Boolean* | Whether the device is currently charging. |
| `isPluggedIn` | *Boolean* | Whether the device is currently plugged in. The device can be plugged in, but not actively charging. |

#### Examples

*Rechargeable device*

```
{
  "descriptiveCapacityRemaining": "HIGH",
  "capacityRemaining": [
    {
      "rawValue": 36000,
      "unit": "SECONDS"
    },
    {
      "rawValue": 90,
      "unit": "PERCENTAGE"
    }
  ],
  "capacityUntilFull": [
    {
      "rawValue": 120,
      "unit": "SECONDS"
    }
  ],
  "isCharging": true,
  "isPluggedIn": true
}
```

*Rechargeable device that displays current charge level in miles*

```
{
  "descriptiveCapacityRemaining": "CRITICALLY_LOW",
  "capacityRemaining": [
    {
      "rawValue": 12,
      "unit": "MILES"
    }
  ],
  "capacityUntilFull": [
    {
      "rawValue": 6000,
      "unit": "SECONDS"
    }
  ],
  "isCharging": true,
  "isPluggedIn": true
}
```

*Non-rechargable device that only supports reporting the current charge level*

```
{
  "descriptiveCapacityRemaining": "LOW"
}
```

## 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.Charge`

Start or stop charging.
This command requires the following attributes:

```
{
  "isRechargeable": true
}
```

#### Parameters

| Parameters | Type | Description |
|---|---|---|
| `charge` | *Boolean* | **Required.** True to start charging, false to stop charging. |

#### Examples

*Start charging command*

```
{
  "command": "action.devices.commands.Charge",
  "params": {
    "charge": true
  }
}
```

*Stop charging command*

```
{
  "command": "action.devices.commands.Charge",
  "params": {
    "charge": false
  }
}
```

## Device ERRORS

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

`deviceUnplugged`: The user tried to charge a device that is not plugged in.