Pm25ConcentrationMeasurement Cluster

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

Pm25ConcentrationMeasurement measures PM2.5 (fine particulate matter) concentration in the air. PM2.5 refers to particles with a diameter of 2.5 micrometers or less that can penetrate deep into the lungs, making it one of the most critical indicators of air quality. Commonly found in air quality sensors, air purifiers, fresh air systems, and smart environment panels. The device acts as a Server and passively reports concentration data; the App (Client) simply reads or subscribes.

Feature Bitmap

Pm25ConcentrationMeasurement declares its supported capabilities via FeatureMap (0xFFFC). Features determine which attributes are available — for example, a device without the PEA Feature will not report peak data. All Concentration Measurement Clusters share identical Feature definitions.

Attribute Overview

The Concentration Measurement Cluster has many attributes, but most are controlled by Features. The core attributes are MeasuredValue (requires MEA) and LevelValue (requires LEV). Click an attribute ID to jump to its detailed description.

Attributes

MeasuredValue (Current PM2.5 Concentration)

The most recent PM2.5 concentration reading from the sensor. This is the most important attribute of the entire Cluster, and the App relies on it primarily for displaying air quality.

• Type: float (single-precision floating point)
• Unit: Determined by MeasurementUnit; PM2.5 sensors typically use UGM3 (micrograms per cubic meter, μg/m³)
• Nullable: null indicates invalid sensor data or that measurement has not yet completed
• Feature: Requires MEA

↑ Back to Attributes

MinMeasuredValue (Minimum Measurable Concentration)

The lowest concentration the sensor can measure. Most PM2.5 sensors have a lower limit of 0.0.

• Type: float, Nullable
• Feature: Requires MEA
• Nullable: null indicates the device has not defined a lower limit

↑ Back to Attributes

MaxMeasuredValue (Maximum Measurable Concentration)

The highest concentration the sensor can measure. Consumer-grade PM2.5 sensors typically have an upper limit between 500 ~ 1000 μg/m³. When MeasuredValue approaches this upper limit, it indicates extremely poor air quality and the sensor may also be near saturation.

• Type: float, Nullable
• Feature: Requires MEA
• Nullable: null indicates the device has not defined an upper limit

↑ Back to Attributes

PeakMeasuredValue (Peak Concentration)

The highest concentration measured by the sensor within the time window specified by PeakMeasuredValueWindow. Useful for detecting short-term air quality deterioration events (such as momentary high concentrations from cooking or smoking).

• Type: float, Nullable
• Feature: Requires PEA

↑ Back to Attributes

PeakMeasuredValueWindow (Peak Measurement Window)

The time window for peak measurement, in seconds. For example, a value of 3600 means PeakMeasuredValue is the maximum over the past 1 hour.

• Type: uint32 (elapsed-s, elapsed seconds)
• Feature: Requires PEA
• Default: Determined by the device manufacturer

↑ Back to Attributes

AverageMeasuredValue (Average Concentration)

The average concentration value within the time window specified by AverageMeasuredValueWindow. Suitable for assessing long-term air quality trends, more stable than instantaneous values.

• Type: float, Nullable
• Feature: Requires AVG

↑ Back to Attributes

AverageMeasuredValueWindow (Average Measurement Window)

The time window for average measurement, in seconds. For example, a value of 86400 means AverageMeasuredValue is the average over the past 24 hours.

• Type: uint32 (elapsed-s, elapsed seconds)
• Feature: Requires AVG

↑ Back to Attributes

Uncertainty (Measurement Uncertainty)

The sensor's measurement uncertainty, using the same unit as MeasuredValue. For example, a value of 2.0 means the actual concentration is within the range of MeasuredValue ± 2.0 μg/m³. Uncertainty should be taken into account when making threshold-based decisions.

• Type: float
• Feature: Requires MEA (optional attribute)

↑ Back to Attributes

MeasurementUnit (Measurement Unit)

Indicates the unit used by MeasuredValue and related concentration attributes. PM2.5 sensors almost always use UGM3 (μg/m³). This attribute remains fixed throughout the device's lifetime.

• Type: MeasurementUnitEnum (see enum below)
• Feature: Requires MEA

↑ Back to Attributes

MeasurementMedium (Measurement Medium)

Indicates the target medium the sensor measures. For PM2.5 sensors, this value is fixed at Air. This attribute is common across the Concentration Measurement family — some water quality sensors use Water.

• Type: MeasurementMediumEnum (see enum below)
• Feature: No requirement (available on all devices)

↑ Back to Attributes

LevelValue (Concentration Level)

The device's graded assessment of the current concentration. Different manufacturers may use different grading thresholds, but the enum values are standardized. This attribute is mandatory when the LEV Feature is supported. Suitable for displaying air quality with color labels in the UI (green / yellow / orange / red).

• Type: LevelValueEnum (see enum below)
• Feature: Requires LEV

↑ Back to Attributes

Commands

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

Enum Definitions

The following three enum groups are shared by all Concentration Measurement Clusters — CO2, PM2.5, PM10, Formaldehyde, TVOC, and other Clusters all use identical enum definitions.

MeasurementUnitEnum (Measurement Unit)

MeasurementMediumEnum (Measurement Medium)

LevelValueEnum (Concentration Level)

PM2.5 and AQI Reference Table

PM2.5 concentration is one of the core indicators for calculating the AQI (Air Quality Index). The following is the US EPA standard (24-hour average) PM2.5 concentration to AQI level mapping, which is the most commonly used reference worldwide:

Example Data

Reading Pm25ConcentrationMeasurement Cluster attributes from an indoor air quality sensor (PM2.5 approximately 25 μg/m³):

{
  // --- Pm25ConcentrationMeasurement Cluster (Endpoint 1) ---
  // Scenario: Indoor air quality sensor, current PM2.5 approximately 25 μg/m³

  "0x0000": 25.0,         // MeasuredValue = 25.0 μg/m³ (current concentration)
  "0x0001": 0.0,          // MinMeasuredValue = 0.0 μg/m³
  "0x0002": 500.0,        // MaxMeasuredValue = 500.0 μg/m³
  "0x0003": 28.0,         // PeakMeasuredValue = 28.0 μg/m³ (peak)
  "0x0005": 22.5,         // AverageMeasuredValue = 22.5 μg/m³ (average)
  "0x0007": 2.0,          // Uncertainty = 2.0 (measurement uncertainty ±2 μg/m³)
  "0x0008": 4,            // MeasurementUnit = UGM3 (micrograms per cubic meter)
  "0x0009": 0,            // MeasurementMedium = Air
  "0x000A": 1             // LevelValue = Low (concentration level: low)
}

Read request example — read all Cluster attributes at once:

{
  // Read all attributes from the PM2.5 sensor
  "readRequests": [{
    "attributePath": {
      "endpointId": 1,
      "clusterId": "0x042A"
      // No attributeId specified → reads all Cluster attributes
    }
  }]
}

Subscribe to PM2.5 concentration changes — track air quality in real time:

{
  // Subscribe to PM2.5 concentration changes (reports every 30 seconds to 5 minutes)
  "subscribeRequests": [{
    "attributePath": {
      "endpointId": 1,
      "clusterId": "0x042A",
      "attributeId": "0x0000"      // MeasuredValue
    },
    "minIntervalFloor": 30,        // Report at least every 30 seconds
    "maxIntervalCeiling": 300      // Report at most every 5 minutes
  }]
}

{`// Device returns MeasuredValue = 25.0 (μg/m³)
val rawValue: Float? = 25.0f    // Nullable, may be null
val pm25 = rawValue ?: run {
    // null → sensor data invalid, show "--"
    showPlaceholder(); return
}

// Map to AQI level
val aqiLevel = when {
    pm25 <= 12.0f  -> "Good"                        // Green
    pm25 <= 35.4f  -> "Moderate"                     // Yellow
    pm25 <= 55.4f  -> "Unhealthy for Sensitive"      // Orange
    pm25 <= 150.4f -> "Unhealthy"                    // Red
    pm25 <= 250.4f -> "Very Unhealthy"               // Purple
    else           -> "Hazardous"                    // Maroon
}

// Can also use the device's LevelValue directly (if LEV Feature is supported)
val level: Int? = readAttribute(0x000A)  // LevelValueEnum`}

Common Scenarios