电功率测量 Cluster（ElectricalPowerMeasurement）

Cluster ID: 0x0090  |  所在 Endpoint: 电气设备功能端点

ElectricalPowerMeasurement 用于实时测量电气设备的电功率参数 —— 电压、电流、有功功率、无功功率、视在功率、频率、功率因数等。 它是 Matter 能源管理体系中的核心测量 Cluster，适用于智能插座、电表、充电桩、电力监控面板等需要精确电力数据的设备。

属性详解

ElectricalPowerMeasurement 共有 19 个应用属性，分为基本信息、实时测量值、RMS 测量值、谐波数据四组。 点击属性 ID 可跳转到对应分组的详细说明。

基本信息（0x0000 ~ 0x0003）

描述设备的供电模式、支持的测量类型数量、精度声明和历史测量范围。

↑ 返回属性列表

实时测量值（0x0004 ~ 0x000A）

设备当前的电压、电流和功率瞬时值。所有值均为 Nullable —— 返回 null 表示当前数据无效。

↑ 返回属性列表

RMS 测量值（0x000B ~ 0x000E）

交流电的 RMS（均方根）测量值 —— 交流电的有效值。对于纯正弦波，RMS 值 = 峰值 / √2。 这组属性全部需要 ALTC 特性。

↑ 返回属性列表

谐波与补充属性（0x000F ~ 0x0012）

谐波分析数据和功率因数、中性线电流。谐波属性需要 HARM 特性，功率因数需要 ALTC，中性线电流需要 POLY。

↑ 返回属性列表

枚举定义

PowerModeEnum（供电模式）

MeasurementTypeEnum（测量类型）

用于 Accuracy 和 Ranges 中标识具体的测量种类：

事件（Events）

ElectricalPowerMeasurement 定义了一个事件，用于周期性上报各测量类型在一段时间内的统计范围。 这是获取历史峰值、谷值数据的主要方式。

MeasurementPeriodRanges

优先级: INFO  |  触发时机: 设备完成一个测量周期后自动上报

事件包含一个 Ranges 字段，类型为 list<MeasurementRangeStruct>， 每个元素记录了某种测量类型在该周期内的最小值、最大值、起止时间戳等统计信息。

Feature 位图

ElectricalPowerMeasurement 通过 FeatureMap（0xFFFC）声明设备支持的电气测量能力。 不同 Feature 组合决定了哪些属性可用：

命令

ElectricalPowerMeasurement 是一个纯只读的 Server Cluster，没有任何命令。 设备负责采集电力数据并更新属性，App 端只需读取（Read）或订阅（Subscribe）即可获取数据。

示例数据

一个启用了 ALTC（交流电）特性的智能插座上报的电力数据：

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

  // --- 基本信息 ---
  "0x0000": 2,              // PowerMode = AC（交流电）
  "0x0001": 5,              // NumberOfMeasurementTypes = 5

  // --- 实时测量值 ---
  "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 测量值（交流电专用）---
  "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

  // --- 功率因数 ---
  "0x0011": 9960            // PowerFactor = 9960 → 99.60%
}

MeasurementPeriodRanges 事件示例 —— 设备在 1 小时周期内的电压和功率范围统计：

{
  // MeasurementPeriodRanges 事件
  // 设备在一个测量周期结束时上报，包含各测量类型的统计范围
  "MeasurementPeriodRanges": {
    "Ranges": [
      {
        "MeasurementType": 1,        // Voltage
        "Min": 218500,               // 最低 218.5 V
        "Max": 222100,               // 最高 222.1 V
        "StartTimestamp": 1695600000,
        "EndTimestamp": 1695603600
      },
      {
        "MeasurementType": 5,        // ActivePower
        "Min": 280000,               // 最低 280.0 W
        "Max": 350000,               // 最高 350.0 W
        "StartTimestamp": 1695600000,
        "EndTimestamp": 1695603600
      }
    ]
  }
}

{`// 设备返回值（int64, Nullable）
val voltageRaw: Long? = 220300     // mV
val powerRaw: Long? = 334856       // mW
val freqRaw: Long? = 50000         // mHz
val pfRaw: Long? = 9960            // 百分比 × 100

// 转换为可读值
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%

// 显示时处理 null
val display = voltageV?.let { String.format("%.1f V", it) } ?: "--"`}

常见场景