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.