电能量测量 Cluster（ElectricalEnergyMeasurement）

Cluster ID: 0x0091  |  所在 Endpoint: 通常在电气设备端点（如智能插座、电能表、充电桩）

ElectricalEnergyMeasurement 负责记录设备随时间累积的电能消耗（或输出）。 与实时测量瞬时功率的 ElectricalPowerMeasurement（0x0090） 不同， 这个 Cluster 关注的是「一共用了多少电」和「这段时间用了多少电」。 两者通常共存于同一个 Endpoint，前者像车速表，后者像里程表。

数据结构

ElectricalEnergyMeasurement 使用两个核心 Struct 来承载数据。 理解这两个结构体是读懂整个 Cluster 的基础。

EnergyMeasurementStruct（电能测量数据）

每一次能量读数都用这个结构体表示。它包含能量值和对应的时间范围。

CumulativeEnergyResetStruct（累计重置信息）

记录累计电能值上次被重置的时间。用于判断当前累计读数的起算时间。

↑ 返回数据结构

属性详解

ElectricalEnergyMeasurement 共有 6 个应用属性。点击属性 ID 可跳转到详细说明。

Accuracy（测量精度）

描述这个电能计量设备的测量精度和量程范围。使用 MeasurementAccuracyStruct 结构体， 包含测量类型（固定为 ElectricalEnergy）、量程上下限、以及不同区间的精度描述。 这是唯一的必选属性，所有实现此 Cluster 的设备都必须上报。

• 类型: MeasurementAccuracyStruct
• 读写: 只读
• 必选: 是

↑ 返回属性列表

CumulativeEnergyImported（累计输入电能）

从设备开始计量（或上次重置）到现在，设备从电网输入（消耗）的总电能。 这就是日常所说的「总用电量」，类似家用电表的读数。值只增不减，除非通过重置操作归零。

• 类型: EnergyMeasurementStruct，Nullable
• 所需特性: IMPE（ImportedEnergy）+ CUME（CumulativeEnergy）
• 换算: energy / 1000 = Wh，energy / 1000000 = kWh

↑ 返回属性列表

CumulativeEnergyExported（累计输出电能）

设备向电网输出（反馈）的累计总电能。 适用于光伏逆变器、储能系统等能向电网回馈电力的设备。普通家用电器不会上报此属性。

• 类型: EnergyMeasurementStruct，Nullable
• 所需特性: EXPE（ExportedEnergy）+ CUME（CumulativeEnergy）

↑ 返回属性列表

PeriodicEnergyImported（周期输入电能）

当前测量周期内设备输入（消耗）的电能。每个周期结束后自动重置。 适合统计「过去一小时用了多少电」「今天用了多少电」等场景。 周期长度由设备实现决定，通过 StartTimestamp / EndTimestamp 可以计算。

• 类型: EnergyMeasurementStruct，Nullable
• 所需特性: IMPE（ImportedEnergy）+ PERE（PeriodicEnergy）

↑ 返回属性列表

PeriodicEnergyExported（周期输出电能）

当前测量周期内设备向电网输出（反馈）的电能。与 PeriodicEnergyImported 对称， 用于有发电能力的设备统计周期内的发电量。

• 类型: EnergyMeasurementStruct，Nullable
• 所需特性: EXPE（ExportedEnergy）+ PERE（PeriodicEnergy）

↑ 返回属性列表

CumulativeEnergyReset（累计重置信息）

记录累计电能值上次被重置的时间。通过这个属性可以知道 CumulativeEnergyImported / CumulativeEnergyExported 是从什么时候开始累计的。如果设备从未被重置过，此属性为 null。

• 类型: CumulativeEnergyResetStruct，Nullable
• 所需特性: CUME（CumulativeEnergy）

↑ 返回属性列表

事件（Events）

ElectricalEnergyMeasurement 没有命令（纯只读 Cluster），但定义了两个重要事件。 设备通过事件主动通知 App 电能数据的更新， 比定时轮询属性更高效，尤其适合需要实时跟踪用电量变化的场景。

CumulativeEnergyMeasured（累计电能更新事件）

当设备的累计电能值发生变化时触发。事件数据中包含最新的累计输入和/或输出电能。

↑ 返回事件列表

PeriodicEnergyMeasured（周期电能更新事件）

每个测量周期结束时触发。事件数据中包含该周期内的输入和/或输出电能。 适合 App 在收到此事件后将数据追加到历史记录中，形成用电曲线图。

↑ 返回事件列表

Feature 位图

ElectricalEnergyMeasurement 通过 FeatureMap（0xFFFC）声明设备支持哪些计量能力。 四个 Feature 两两组合，决定了设备能提供哪些属性和事件：

与 ElectricalPowerMeasurement 的关系

Matter 把电气测量拆成了两个 Cluster，各司其职：

两者通常共存于同一 Endpoint。App 界面上可以同时展示实时功率（来自 0x0090）和累计用电量（来自 0x0091）， 前者适合实时监控，后者适合用电统计和费用计算。

示例数据

一个支持 IMPE + CUME + PERE 特性的智能插座的 ElectricalEnergyMeasurement Cluster 读取结果：

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

  // --- 测量精度 ---
  "0x0000": {                    // Accuracy（MeasurementAccuracyStruct）
    "measurementType": 1,        // ElectricalEnergy
    "measured": true,
    "minMeasuredValue": 0,
    "maxMeasuredValue": 100000000000,  // 100,000 kWh
    "accuracyRanges": [{
      "rangeMin": 0,
      "rangeMax": 100000000000,
      "fixedMax": 5000           // 最大固定误差 5000 mWh = 5 Wh
    }]
  },

  // --- 累计电能（需要 IMPE + CUME 特性）---
  "0x0001": {                    // CumulativeEnergyImported
    "energy": 12345678,          // 12,345,678 mWh = 12,345.678 Wh ≈ 12.35 kWh
    "startTimestamp": 1700000000,// 2023-11-14T22:13:20Z（开始计量时间）
    "endTimestamp": 1700086400   // 2023-11-15T22:13:20Z（最新更新时间）
  },

  // --- 周期电能（需要 IMPE + PERE 特性）---
  "0x0003": {                    // PeriodicEnergyImported
    "energy": 543210,            // 543,210 mWh = 543.21 Wh ≈ 0.54 kWh（本周期用电）
    "startTimestamp": 1700082800,// 周期开始时间
    "endTimestamp": 1700086400   // 周期结束时间（1 小时周期）
  },

  // --- 累计重置信息（需要 CUME 特性）---
  "0x0005": {                    // CumulativeEnergyReset
    "importedResetTimestamp": 1700000000  // 上次重置累计值的时间
  }
}

CumulativeEnergyMeasured 事件数据示例：

{
  // CumulativeEnergyMeasured 事件 —— 累计电能更新通知
  "eventId": "0x00",
  "priority": "INFO",
  "data": {
    "energyImported": {
      "energy": 12345678,          // 12,345.678 Wh
      "startTimestamp": 1700000000,
      "endTimestamp": 1700086400
    }
    // energyExported 省略（此设备不支持反向输出）
  }
}

{`// 设备返回 energy = 12345678 (mWh)
val rawEnergy: Long? = 12345678    // Nullable，可能为 null
val wattHours = rawEnergy?.let { it / 1000.0 }     // → 12,345.678 Wh
val kilowattHours = rawEnergy?.let { it / 1_000_000.0 }  // → 12.346 kWh

// 显示时处理 null + 选择合适单位
val display = kilowattHours?.let {
    if (it < 1.0) String.format("%.1f Wh", it * 1000)  // 小于 1 kWh 显示 Wh
    else String.format("%.2f kWh", it)
} ?: "--"`}

常见场景