ElectricalEnergyMeasurement Cluster

Cluster ID: 0x0091  |  Endpoint: Typically on an electrical device endpoint (e.g. smart plug, energy meter, EV charger)

ElectricalEnergyMeasurement is responsible for recording the cumulative energy consumption (or output) of a device over time. Unlike ElectricalPowerMeasurement (0x0090) which measures instantaneous power, this Cluster focuses on "how much total energy has been used" and "how much energy was used during this period". Both typically coexist on the same Endpoint — the former is like a speedometer, the latter like an odometer.

Data Structures

ElectricalEnergyMeasurement uses two core Structs to carry data. Understanding these two structures is fundamental to reading the entire Cluster.

EnergyMeasurementStruct (Energy Measurement Data)

Every energy reading is represented by this structure. It contains the energy value and the corresponding time range.

CumulativeEnergyResetStruct (Cumulative Reset Information)

Records the time when the cumulative energy value was last reset. Used to determine the starting point of the current cumulative reading.

↑ Back to Data Structures

Attributes

ElectricalEnergyMeasurement has 6 application-level attributes. Click an attribute ID to jump to its detailed description.

Accuracy (Measurement Accuracy)

Describes the measurement accuracy and range of this energy metering device. Uses the MeasurementAccuracyStruct structure, containing the measurement type (fixed to ElectricalEnergy), range limits, and accuracy descriptions for different intervals. This is the only mandatory attribute — all devices implementing this Cluster must report it.

• Type: MeasurementAccuracyStruct
• Access: Read-only
• Required: Yes

↑ Back to Attributes

CumulativeEnergyImported (Cumulative Imported Energy)

The total energy imported (consumed) by the device from the grid since metering started (or last reset). This is the everyday "total energy consumption," similar to a household utility meter reading. The value only increases, unless reset to zero.

• Type: EnergyMeasurementStruct, Nullable
• Required Features: IMPE (ImportedEnergy) + CUME (CumulativeEnergy)
• Conversion: energy / 1000 = Wh, energy / 1000000 = kWh

↑ Back to Attributes

CumulativeEnergyExported (Cumulative Exported Energy)

The cumulative total energy exported (fed back) by the device to the grid. Applicable to solar inverters, energy storage systems, and other devices capable of feeding power back to the grid. Ordinary household appliances do not report this attribute.

• Type: EnergyMeasurementStruct, Nullable
• Required Features: EXPE (ExportedEnergy) + CUME (CumulativeEnergy)

↑ Back to Attributes

PeriodicEnergyImported (Periodic Imported Energy)

The energy imported (consumed) by the device within the current measurement period. Automatically resets at the end of each period. Ideal for tracking "how much energy was used in the past hour" or "today's usage." The period length is determined by the device implementation and can be calculated from StartTimestamp / EndTimestamp.

• Type: EnergyMeasurementStruct, Nullable
• Required Features: IMPE (ImportedEnergy) + PERE (PeriodicEnergy)

↑ Back to Attributes

PeriodicEnergyExported (Periodic Exported Energy)

The energy exported (fed back) by the device to the grid within the current measurement period. Symmetric to PeriodicEnergyImported, used by devices with generation capability to track energy output per period.

• Type: EnergyMeasurementStruct, Nullable
• Required Features: EXPE (ExportedEnergy) + PERE (PeriodicEnergy)

↑ Back to Attributes

CumulativeEnergyReset (Cumulative Reset Information)

Records when the cumulative energy value was last reset. Through this attribute you can determine when CumulativeEnergyImported / CumulativeEnergyExported started accumulating. If the device has never been reset, this attribute is null.

• Type: CumulativeEnergyResetStruct, Nullable
• Required Features: CUME (CumulativeEnergy)

↑ Back to Attributes

Events

ElectricalEnergyMeasurement has no commands (read-only Cluster), but defines two important events. Devices proactively notify the app of energy data updates through events, which is more efficient than polling attributes on a timer — especially useful for scenarios that need to track energy consumption changes in real time.

CumulativeEnergyMeasured (Cumulative Energy Update Event)

Triggered when the device's cumulative energy value changes. The event data contains the latest cumulative imported and/or exported energy.

↑ Back to Events

PeriodicEnergyMeasured (Periodic Energy Update Event)

Triggered at the end of each measurement period. The event data contains the imported and/or exported energy for that period. Ideal for apps to append data to historical records upon receiving this event, building energy consumption charts.

↑ Back to Events

Feature Bitmap

ElectricalEnergyMeasurement declares the device's metering capabilities through FeatureMap (0xFFFC). The four Features combine in pairs to determine which attributes and events the device can provide:

Relationship with ElectricalPowerMeasurement

Matter splits electrical measurement into two Clusters, each serving a distinct role:

Both Clusters typically coexist on the same Endpoint. The app UI can simultaneously display real-time power (from 0x0090) and cumulative energy consumption (from 0x0091); the former is suited for real-time monitoring, the latter for consumption statistics and cost calculation.

Example Data

Read result of the ElectricalEnergyMeasurement Cluster for a smart plug supporting IMPE + CUME + PERE features:

{
  // --- ElectricalEnergyMeasurement Cluster（Endpoint 1）---

  // --- Measurement Accuracy ---
  "0x0000": {                    // Accuracy（MeasurementAccuracyStruct）
    "measurementType": 1,        // ElectricalEnergy
    "measured": true,
    "minMeasuredValue": 0,
    "maxMeasuredValue": 100000000000,  // 100,000 kWh
    "accuracyRanges": [{
      "rangeMin": 0,
      "rangeMax": 100000000000,
      "fixedMax": 5000           // Maximum fixed error 5000 mWh = 5 Wh
    }]
  },

  // --- Cumulative Energy (requires IMPE + CUME features) ---
  "0x0001": {                    // CumulativeEnergyImported
    "energy": 12345678,          // 12,345,678 mWh = 12,345.678 Wh ≈ 12.35 kWh
    "startTimestamp": 1700000000,// 2023-11-14T22:13:20Z (metering start time)
    "endTimestamp": 1700086400   // 2023-11-15T22:13:20Z (latest update time)
  },

  // --- Periodic Energy (requires IMPE + PERE features) ---
  "0x0003": {                    // PeriodicEnergyImported
    "energy": 543210,            // 543,210 mWh = 543.21 Wh ≈ 0.54 kWh (this period consumption)
    "startTimestamp": 1700082800,// Period start time
    "endTimestamp": 1700086400   // Period end time (1-hour period)
  },

  // --- Cumulative Reset Info (requires CUME feature) ---
  "0x0005": {                    // CumulativeEnergyReset
    "importedResetTimestamp": 1700000000  // Time of last cumulative value reset
  }
}

CumulativeEnergyMeasured event data example:

{
  // CumulativeEnergyMeasured Event — cumulative energy update notification
  "eventId": "0x00",
  "priority": "INFO",
  "data": {
    "energyImported": {
      "energy": 12345678,          // 12,345.678 Wh
      "startTimestamp": 1700000000,
      "endTimestamp": 1700086400
    }
    // energyExported omitted (this device does not support reverse output)
  }
}

{`// Device returns energy = 12345678 (mWh)
val rawEnergy: Long? = 12345678    // Nullable, may be null
val wattHours = rawEnergy?.let { it / 1000.0 }     // → 12,345.678 Wh
val kilowattHours = rawEnergy?.let { it / 1_000_000.0 }  // → 12.346 kWh

// Handle null + choose appropriate unit for display
val display = kilowattHours?.let {
    if (it < 1.0) String.format("%.1f Wh", it * 1000)  // Show Wh if less than 1 kWh
    else String.format("%.2f kWh", it)
} ?: "--"`}

Common Scenarios