光照度测量 Cluster（IlluminanceMeasurement）

Cluster ID: 0x0400  |  所在 Endpoint: 通常在 Endpoint 1+（功能端点）

IlluminanceMeasurement 用于上报环境光照强度（单位 lux）。 这是一个纯只读的 Server Cluster —— 没有任何命令，只有 5 个属性。 光照传感器、多合一环境传感器、智能窗帘控制器等设备会用到它。

属性总览

IlluminanceMeasurement 有 5 个属性，其中 MeasuredValue 是最核心的。点击属性 ID 可跳转到详细说明。

属性详解

MeasuredValue（当前光照度）

传感器最近一次测量到的光照强度，采用对数刻度编码。这是整个 Cluster 最核心的属性。

• 类型: uint16，Nullable
• 有效范围: 1 ~ 65534（对应约 1 lux ~ 3.5 × 10⁶ lux）
• 特殊值: 0 = 光照低于可测下限；null = 数据无效或未完成测量
• 换算: lux = 10(MeasuredValue - 1) / 10000

{`// 设备返回 MeasuredValue
val rawValue: Int? = 10001    // Nullable，可能为 null
val lux = when {
    rawValue == null -> null           // 传感器未就绪
    rawValue == 0    -> 0.0            // 低于可测下限
    else -> Math.pow(10.0, (rawValue - 1).toDouble() / 10000.0)
}
// rawValue = 10001 → lux = 10.0
// rawValue = 20001 → lux = 100.0
// rawValue = 30001 → lux = 1000.0

// 显示时处理 null 和精度
val display = lux?.let { String.format("%.0f lux", it) } ?: "--"`}

↑ 返回属性列表

MinMeasuredValue（可测最低光照度）

传感器能够测量的最低光照度值（对数刻度编码）。当 MeasuredValue 为 0 时， 表示实际光照低于此下限。

• 类型: uint16，Nullable
• 范围: 1 ~ 65533
• Nullable: 为 null 时表示设备未定义下限

↑ 返回属性列表

MaxMeasuredValue（可测最高光照度）

传感器能够测量的最高光照度值（对数刻度编码）。 MeasuredValue 不会超过此值。

• 类型: uint16，Nullable
• 范围: 2 ~ 65534，且必须大于 MinMeasuredValue
• Nullable: 为 null 时表示设备未定义上限

↑ 返回属性列表

Tolerance（测量容差）

传感器的测量精度容差，同样采用对数刻度。这是可选属性，不是所有设备都上报。

• 类型: uint16（无符号）
• 范围: 0 ~ 2048

↑ 返回属性列表

LightSensorType（传感器类型）

描述设备使用的光照传感器类型。不同传感器类型在光谱响应和灵敏度上有差异。 值为 null 表示传感器类型未知。

LightSensorTypeEnum 枚举值

↑ 返回属性列表

命令

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

示例数据

读取一个光照传感器的 IlluminanceMeasurement Cluster 属性：

{
  // --- IlluminanceMeasurement Cluster（Endpoint 1）---
  "0x0":  10001,       // MeasuredValue = 10001 → 10 lux（普通走廊照度）
  "0x1":  1,           // MinMeasuredValue = 1 → 1 lux
  "0x2":  50001,       // MaxMeasuredValue = 50001 → 100000 lux
  "0x3":  0,           // Tolerance = 0（未上报容差）
  "0x4":  0            // LightSensorType = Photodiode
}

订阅光照变化 —— 实时跟踪光照更新：

{
  // 订阅光照变化（每 10 秒~2 分钟上报一次）
  "subscribeRequests": [{
    "attributePath": {
      "endpointId": 1,
      "clusterId": "0x0400",
      "attributeId": "0x00"        // MeasuredValue
    },
    "minIntervalFloor": 10,        // 最少 10 秒上报一次
    "maxIntervalCeiling": 120      // 最多 2 分钟上报一次
  }]
}

常见场景