BooleanState Cluster

Cluster ID: 0x0045  |  Endpoint: Typically on Endpoint 1 (application endpoint)  |  Role: Server (read-only, no commands)

BooleanState is one of the simplest Clusters in Matter — it has only 1 attribute, 0 commands, and 1 event. It reports a generic boolean (true/false) state, and is typically used by devices that only need to express a two-state condition, such as contact sensors, water leak detectors, and smoke alarms.

This Cluster is purely read-only — the app can only read the state and subscribe to changes; it cannot send any commands to the device to change the state. State changes are driven entirely by the device's physical sensors.

What Do true and false Actually Mean?

BooleanState itself does not define the specific meaning of true/false — the semantics are determined by the associated Device Type. This is the most common pitfall in development.

For example, for a ContactSensor (contact sensor, Device Type 0x0015):

  • true = door/window is closed (normal, contact closed)
  • false = door/window is open (alert, contact broken)

This may be counter-intuitive — many people assume true = open. The Matter design logic is: true represents the "normal/safe" state, and false represents the "attention needed" state. Always interpret values according to the specific Device Type specification, and never assume.

Attributes

BooleanState has only one attribute, and it is mandatory.

ID Name Type Access Description
0x00 StateValue bool Read-only Current boolean state

StateValue (Current State)

The device's current boolean state value. Read-only — it cannot be changed by writing the attribute or sending a command. Only a trigger from the device's physical sensor updates this value.

ValueGeneric MeaningContactSensor Meaning
true Normal / Safe Door/window is closed (contact closed)
false Abnormal / Attention needed Door/window is open (contact broken)
Developer Advice

Do not hard-code if (stateValue) "Closed" in your code. Instead, determine the display text based on the device's Device Type (obtained from the Descriptor Cluster's DeviceTypeList). Future Device Types may reuse BooleanState, and the meaning of true/false could be entirely different.

↑ Back to Attributes

Events

BooleanState defines one event, which the device proactively reports when StateValue changes. Subscribing to events is the recommended approach for monitoring state changes, rather than polling the attribute.

ID Name Priority Description
0x00 StateChange Info Triggered when StateValue changes

StateChange — State Change Event (0x00)

When the device's physical state changes (e.g., a door is opened, a water leak is detected), the device emits this event. The event data carries the new StateValue after the change.

FieldIDTypeDescription
StateValue 0x00 bool The new state value after the change

Event report example:

{
  "eventReports": [{
    "eventData": {
      "path": {
        "endpointId": 1,
        "clusterId": "0x0045",
        "eventId": "0x00"       // StateChange
      },
      "eventNumber": 42,
      "priority": "INFO",
      "data": {
        "0": false              // StateValue = false (state changed: e.g., door opened)
      }
    }
  }]
}
Subscribe vs. Poll

For devices like contact sensors, state changes are typically sudden and infrequent. It is recommended to use Subscribe to subscribe to both the StateValue attribute and the StateChange event, so you can immediately obtain the current state when the connection is established, and also receive real-time change notifications.

Subscription request example:

{
  "subscribeRequests": [{
    "attributeRequests": [{
      "endpointId": 1,
      "clusterId": "0x0045",
      "attributeId": "0x00"     // StateValue
    }],
    "eventRequests": [{
      "endpointId": 1,
      "clusterId": "0x0045",
      "eventId": "0x00"         // StateChange
    }]
  }],
  "minIntervalFloor": 0,        // Minimum reporting interval (seconds)
  "maxIntervalCeiling": 300     // Maximum reporting interval (seconds)
}

↑ Back to Events

Example Data

Reading the BooleanState Cluster attributes of a contact sensor:

{
  // --- Attributes ---
  "0x0": true          // StateValue = true (normal state, e.g., door closed, no water leak)
}

Common Scenarios

Scenario 1: Contact Sensor (ContactSensor)

The most common use case. A contact sensor consists of a magnet and a reed switch; when the door is closed, the magnet approaches the reed switch and the contact closes.

  1. Confirm the Device Type is 0x0015 (ContactSensor) from the Descriptor Cluster
  2. Subscribe to BooleanState's StateValue attribute and StateChange event
  3. Receive true → display "Door Closed" (green safe state)
  4. Receive false → display "Door Open" (yellow alert state)
  5. Can be combined with automation: if the door is open for more than 5 minutes → send a reminder notification
Scenario 2: Water Leak Detector

A water leak detector is placed in locations prone to leaks (beside the washing machine, under the water heater) and triggers an alert when water is detected.

  1. Subscribe to the StateChange event
  2. Receive true → normal, no water leak
  3. Receive false → water leak detected, trigger an urgent notification
  4. Recommended to combine with automation rules: when a leak is detected, automatically shut off the smart water valve in the corresponding area
Scenario 3: Generic Contact Sensor

BooleanState is not limited to doors/windows and water leaks — any sensor that needs a binary state can reuse it.

  • Refrigerator door sensor — false when the door is open, with a timed reminder
  • Mailbox sensor — triggers a notification when the mailbox is opened
  • Drawer/cabinet door sensor — security scenario, alert when opened unexpectedly

The key is to read the Device Type from the Descriptor Cluster and determine the UI text and icon based on the specific type, rather than assuming all BooleanState instances are contact sensors.