ElectricalPowerMeasurement Cluster

Cluster ID: 0x0090  |  Endpoint: Electrical device function endpoint

ElectricalPowerMeasurement is used for real-time measurement of electrical power parameters — voltage, current, active power, reactive power, apparent power, frequency, power factor, and more. It is a core measurement Cluster in the Matter energy management ecosystem, suitable for smart plugs, power meters, EV chargers, power monitoring panels, and other devices requiring precise electrical data.

Attributes

ElectricalPowerMeasurement has 19 application-level attributes, organized into four groups: basic information, real-time measurements, RMS measurements, and harmonics data. Click an attribute ID to jump to the detailed description for its group.

Basic Information (0x0000 ~ 0x0003)

Describes the device's power mode, number of supported measurement types, accuracy declarations, and historical measurement ranges.

↑ Back to Attributes

Real-time Measurements (0x0004 ~ 0x000A)

Instantaneous voltage, current, and power values from the device. All values are Nullable — a null return means the data is currently invalid.

↑ Back to Attributes

RMS Measurements (0x000B ~ 0x000E)

RMS (Root Mean Square) measurements for AC power — the effective values of alternating current. For a pure sine wave, RMS value = peak value / √2. All attributes in this group require the ALTC feature.

↑ Back to Attributes

Harmonics & Supplementary Attributes (0x000F ~ 0x0012)

Harmonic analysis data, power factor, and neutral current. Harmonic attributes require the HARM feature, power factor requires ALTC, and neutral current requires POLY.

↑ Back to Attributes

Enum Definitions

PowerModeEnum (Power Mode)

MeasurementTypeEnum (Measurement Type)

Used in Accuracy and Ranges to identify the specific measurement type:

Events

ElectricalPowerMeasurement defines one event, used for periodically reporting the statistical range of each measurement type over a time period. This is the primary way to obtain historical peak and valley data.

MeasurementPeriodRanges

Priority: INFO  |  Trigger: Automatically reported when the device completes a measurement period

The event contains a Ranges field of type list<MeasurementRangeStruct>, where each element records the minimum value, maximum value, start/end timestamps, and other statistics for a measurement type within that period.

Feature Bitmap

ElectricalPowerMeasurement declares the device's electrical measurement capabilities through FeatureMap (0xFFFC). Different Feature combinations determine which attributes are available:

Commands

ElectricalPowerMeasurement is a read-only Server Cluster with no commands. The device is responsible for collecting electrical data and updating attributes; the app only needs to Read or Subscribe to obtain data.

Example Data

Electrical data reported by a smart plug with the ALTC (AC) feature enabled:

{
  // --- ElectricalPowerMeasurement Cluster (Endpoint 1) ---

  // --- Basic Information ---
  "0x0000": 2,              // PowerMode = AC (Alternating Current)
  "0x0001": 5,              // NumberOfMeasurementTypes = 5

  // --- Real-time Measurements ---
  "0x0004": 220300,         // Voltage = 220300 mV → 220.3 V
  "0x0005": 1520,           // ActiveCurrent = 1520 mA → 1.52 A
  "0x0008": 334856,         // ActivePower = 334856 mW → 334.856 W
  "0x0009": 28700,          // ReactivePower = 28700 mW → 28.7 VAR
  "0x000A": 336100,         // ApparentPower = 336100 mW → 336.1 VA

  // --- RMS Measurements (AC only) ---
  "0x000B": 219800,         // RMSVoltage = 219800 mV → 219.8 V
  "0x000C": 1530,           // RMSCurrent = 1530 mA → 1.53 A
  "0x000D": 335200,         // RMSPower = 335200 mW → 335.2 W
  "0x000E": 50000,          // Frequency = 50000 mHz → 50.0 Hz

  // --- Power Factor ---
  "0x0011": 9960            // PowerFactor = 9960 → 99.60%
}

MeasurementPeriodRanges event example — voltage and power range statistics over a 1-hour period:

{
  // MeasurementPeriodRanges Event
  // Reported when the device completes a measurement period, containing statistical ranges for each measurement type
  "MeasurementPeriodRanges": {
    "Ranges": [
      {
        "MeasurementType": 1,        // Voltage
        "Min": 218500,               // Minimum 218.5 V
        "Max": 222100,               // Maximum 222.1 V
        "StartTimestamp": 1695600000,
        "EndTimestamp": 1695603600
      },
      {
        "MeasurementType": 5,        // ActivePower
        "Min": 280000,               // Minimum 280.0 W
        "Max": 350000,               // Maximum 350.0 W
        "StartTimestamp": 1695600000,
        "EndTimestamp": 1695603600
      }
    ]
  }
}

{`// Device return values (int64, Nullable)
val voltageRaw: Long? = 220300     // mV
val powerRaw: Long? = 334856       // mW
val freqRaw: Long? = 50000         // mHz
val pfRaw: Long? = 9960            // percentage x 100

// Convert to human-readable values
val voltageV = voltageRaw?.let { it / 1000.0 }    // → 220.3 V
val powerW = powerRaw?.let { it / 1000.0 }         // → 334.856 W
val freqHz = freqRaw?.let { it / 1000.0 }          // → 50.0 Hz
val powerFactor = pfRaw?.let { it / 100.0 }         // → 99.60%

// Handle null when displaying
val display = voltageV?.let { String.format("%.1f V", it) } ?: "--"`}

Common Scenarios