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 operation. To learn more about handling SYNC intents, see Intent fulfillment.

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 operation. To learn more about handling QUERY intents, see Intent fulfillment.

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 operation. To learn more about handling EXECUTE intents, see Intent fulfillment.

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.

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