IlluminanceMeasurement Cluster

Cluster ID: 0x0400  |  Endpoint: Typically on Endpoint 1+ (application endpoint)

IlluminanceMeasurement reports the ambient light intensity (in lux). This is a read-only Server Cluster — it has no Commands, only 5 Attributes. Commonly found on light sensors, multi-function environmental sensors, and smart curtain controllers.

Attribute Overview

IlluminanceMeasurement has 5 Attributes, of which MeasuredValue is the most important. Click an Attribute ID to jump to its detailed description.

Attributes

MeasuredValue (Current Illuminance)

The most recently measured light intensity from the sensor, encoded on a logarithmic scale. This is the most important Attribute of the entire Cluster.

• Type: uint16, Nullable
• Valid range: 1 to 65534 (corresponding to approximately 1 lux to 3.5 × 10⁶ lux)
• Special values: 0 = illuminance below the measurable minimum; null = data invalid or measurement not completed
• Conversion: lux = 10(MeasuredValue - 1) / 10000

{`// Device returns MeasuredValue
val rawValue: Int? = 10001    // Nullable, may be null
val lux = when {
    rawValue == null -> null           // Sensor not ready
    rawValue == 0    -> 0.0            // Below measurable minimum
    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

// Handle null and precision when displaying
val display = lux?.let { String.format("%.0f lux", it) } ?: "--"`}

↑ Back to Attributes

MinMeasuredValue (Minimum Measurable Illuminance)

The minimum illuminance value the sensor can measure (logarithmic scale encoded). When MeasuredValue is 0, it indicates the actual illuminance is below this lower limit.

• Type: uint16, Nullable
• Range: 1 to 65533
• Nullable: null indicates the device has not defined a lower limit

↑ Back to Attributes

MaxMeasuredValue (Maximum Measurable Illuminance)

The maximum illuminance value the sensor can measure (logarithmic scale encoded). MeasuredValue will not exceed this value.

• Type: uint16, Nullable
• Range: 2 to 65534, and must be greater than MinMeasuredValue
• Nullable: null indicates the device has not defined an upper limit

↑ Back to Attributes

Tolerance (Measurement Tolerance)

The measurement tolerance of the sensor, also on a logarithmic scale. This is an optional Attribute and not all devices report it.

• Type: uint16 (unsigned)
• Range: 0 to 2048

↑ Back to Attributes

LightSensorType (Sensor Type)

Describes the type of light sensor used by the device. Different sensor types have varying spectral responses and sensitivities. A value of null indicates the sensor type is unknown.

LightSensorTypeEnum Enum Values

↑ Back to Attributes

Commands

IlluminanceMeasurement is a read-only Server Cluster with no Commands. The device is responsible for collecting light data and updating Attributes; the App only needs to Read or Subscribe to obtain data.

Example Data

Reading the IlluminanceMeasurement Cluster Attributes from a light sensor:

{
  // --- IlluminanceMeasurement Cluster (Endpoint 1) ---
  "0x0":  10001,       // MeasuredValue = 10001 → 10 lux (typical hallway illuminance)
  "0x1":  1,           // MinMeasuredValue = 1 → 1 lux
  "0x2":  50001,       // MaxMeasuredValue = 50001 → 100000 lux
  "0x3":  0,           // Tolerance = 0 (tolerance not reported)
  "0x4":  0            // LightSensorType = Photodiode
}

Subscribe to illuminance changes — track light level updates in real time:

{
  // Subscribe to illuminance changes (report every 10 seconds to 2 minutes)
  "subscribeRequests": [{
    "attributePath": {
      "endpointId": 1,
      "clusterId": "0x0400",
      "attributeId": "0x00"        // MeasuredValue
    },
    "minIntervalFloor": 10,        // Report at least every 10 seconds
    "maxIntervalCeiling": 120      // Report at most every 2 minutes
  }]
}

Common Scenarios