Matter Cluster 47 — Power Source Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 47 values in the device shadow use this format:

endpoint_id / 47 / attribute_id

Example:

{
  "0/47/0": 1
}

Cluster 47 Features

The FeatureMap attribute (0/47/65532) is a bitmap. Each bit set means the device implements that feature and the attributes and commands that depend on it.

Example: FeatureMap = 0 means no optional feature is enabled; 15 means every feature listed above is enabled.

Data Types

BatApprovedChemistryEnum

BatChargeFaultEnum

BatChargeLevelEnum

BatChargeStateEnum

BatCommonDesignationEnum

BatFaultEnum

BatReplaceabilityEnum

PowerSourceStatusEnum

WiredCurrentTypeEnum

WiredFaultEnum

Cluster 47 Attributes

Cluster 47 defines 32 attributes plus the global attributes. Conformance: M mandatory, O optional, a feature code means "mandatory when that feature is present", square brackets mean "optional when …".

Global attributes

Attribute Details

Attribute 0 / 0x0000 — Status

Path example:

0/47/0

Indicates the participation of this power source in providing power to the Node as specified in PowerSourceStatusEnum.

Values (PowerSourceStatusEnum):

Example:

{
  "0/47/0": 1
}

Attribute 1 / 0x0001 — Order

Path example:

0/47/1

Indicates the relative preference with which the Node will select this source to provide power. A source with a lower order is selected by the Node to provide power before any other source with a higher order, if the lower order source is available. Note, Order is read-only and therefore NOT intended to allow clients control over power source selection.

Example:

{
  "0/47/1": 1
}

Attribute 2 / 0x0002 — Description

Path example:

0/47/2

This attribute provides a user-facing description of this source, used to distinguish it from other power sources, e.g. "DC Power", "Primary Battery" or "Battery back-up". This attribute must NOT be used to convey information such as battery form factor, or chemistry.

Example:

{
  "0/47/2": "example"
}

Attribute 3 / 0x0003 — WiredAssessedInputVoltage

Path example:

0/47/3

Indicates the assessed RMS or DC voltage currently provided by the hard-wired source, in mV (millivolts). A value of null indicates the Node is currently unable to assess the value. If the wired source is not connected, but the Node is still able to assess a value, then the assessed value may be reported.

Example:

{
  "0/47/3": 1
}

Attribute 4 / 0x0004 — WiredAssessedInputFrequency

Path example:

0/47/4

Indicates the assessed frequency of the voltage, currently provided by the hard-wired source, in Hz. A value of null indicates the Node is currently unable to assess the value. If the wired source is not connected, but the Node is still able to assess a value, then the assessed value may be reported.

Example:

{
  "0/47/4": 1
}

Attribute 5 / 0x0005 — WiredCurrentType

Path example:

0/47/5

Indicates the type of current the Node expects to be provided by the hard-wired source as specified in WiredCurrentTypeEnum.

Values (WiredCurrentTypeEnum):

Example:

{
  "0/47/5": 0
}

Attribute 6 / 0x0006 — WiredAssessedCurrent

Path example:

0/47/6

Indicates the assessed instantaneous current draw of the Node on the hard-wired source, in mA (milliamps). A value of null indicates the Node is currently unable to assess the value. If the wired source is not connected, but the Node is still able to assess a value, then the assessed value may be reported.

Example:

{
  "0/47/6": 1
}

Attribute 7 / 0x0007 — WiredNominalVoltage

Path example:

0/47/7

Indicates the nominal voltage, printed as part of the Node's regulatory compliance label in mV (millivolts), expected to be provided by the hard-wired source.

Example:

{
  "0/47/7": 1
}

Attribute 8 / 0x0008 — WiredMaximumCurrent

Path example:

0/47/8

Indicates the maximum current, printed as part of the Node's regulatory compliance label in mA (milliamps), expected to be provided by the hard-wired source.

Example:

{
  "0/47/8": 1
}

Attribute 9 / 0x0009 — WiredPresent

Path example:

0/47/9

Indicates if the Node detects that the hard-wired power source is properly connected.

Example:

{
  "0/47/9": true
}

Attribute 10 / 0x000A — ActiveWiredFaults

Path example:

0/47/10

Indicates the set of wired faults currently detected by the Node on this power source. This set is represented as a list of WiredFaultEnum. When the Node detects a fault has been raised, the appropriate WiredFaultEnum value is added to this list, provided it is not already present. This list must NOT contain more than one instance of a specific WiredFaultEnum value.

Example:

{
  "0/47/10": []
}

Attribute 11 / 0x000B — BatVoltage

Path example:

0/47/11

Indicates the currently measured output voltage of the battery in mV (millivolts). A value of null indicates the Node is currently unable to assess the value.

Example:

{
  "0/47/11": 1
}

Attribute 12 / 0x000C — BatPercentRemaining

Path example:

0/47/12

Indicates the estimated percentage of battery charge remaining until the battery will no longer be able to provide power to the Node. Values are expressed in half percent units, ranging from 0 to 200. E.g. a value of 48 is equivalent to 24%. A value of null indicates the Node is currently unable to assess the value.

Example:

{
  "0/47/12": 1
}

Attribute 13 / 0x000D — BatTimeRemaining

Path example:

0/47/13

Indicates the estimated time in seconds before the battery will no longer be able to provide power to the Node. A value of null indicates the Node is currently unable to assess the value. Changes to this attribute only be marked as reportable in the following cases: - At most once every 10 seconds, or - When it changes from null to any other value and vice versa. Since reporting consumes power, devices should be careful not to over-report.

Example:

{
  "0/47/13": 0
}

Attribute 14 / 0x000E — BatChargeLevel

Path example:

0/47/14

Indicates a coarse ranking of the charge level of the battery, used to indicate when intervention is required as specified in BatChargeLevelEnum.

Values (BatChargeLevelEnum):

Example:

{
  "0/47/14": 0
}

Attribute 15 / 0x000F — BatReplacementNeeded

Path example:

0/47/15

Indicates if the battery needs to be replaced. Replacement may be simple routine maintenance, such as with a single use, non-rechargeable cell. Replacement, however, may also indicate end of life, or serious fault with a rechargeable or even non-replaceable cell.

Example:

{
  "0/47/15": true
}

Attribute 16 / 0x0010 — BatReplaceability

Path example:

0/47/16

Indicates the replaceability of the battery as specified in BatReplaceabilityEnum.

Values (BatReplaceabilityEnum):

Example:

{
  "0/47/16": 1
}

Attribute 17 / 0x0011 — BatPresent

Path example:

0/47/17

Indicates whether the Node detects that the batteries are properly installed.

Example:

{
  "0/47/17": true
}

Attribute 18 / 0x0012 — ActiveBatFaults

Path example:

0/47/18

Indicates the set of battery faults currently detected by the Node on this power source. This set is represented as a list of BatFaultEnum. When the Node detects a fault has been raised, the appropriate BatFaultEnum value is added to this list, provided it is not already present. This list must NOT contain more than one instance of a specific BatFaultEnum value.

Example:

{
  "0/47/18": []
}

Attribute 19 / 0x0013 — BatReplacementDescription

Path example:

0/47/19

This attribute provides a user-facing description of this battery, which should contain information required to identify a replacement, such as form factor, chemistry or preferred manufacturer.

Example:

{
  "0/47/19": "example"
}

Attribute 20 / 0x0014 — BatCommonDesignation

Path example:

0/47/20

Indicates the ID of the common or colloquial designation of the battery, as specified in BatCommonDesignationEnum.

Values (BatCommonDesignationEnum):

Example:

{
  "0/47/20": 1
}

Attribute 21 / 0x0015 — BatANSIDesignation

Path example:

0/47/21

No condensed specification text is available for BatANSIDesignation; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/47/21": "example"
}

Attribute 22 / 0x0016 — BatIECDesignation

Path example:

0/47/22

No condensed specification text is available for BatIECDesignation; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "0/47/22": "example"
}

Attribute 23 / 0x0017 — BatApprovedChemistry

Path example:

0/47/23

Indicates the ID of the preferred chemistry of the battery source as specified in BatApprovedChemistryEnum.

Values (BatApprovedChemistryEnum):

Example:

{
  "0/47/23": 1
}

Attribute 24 / 0x0018 — BatCapacity

Path example:

0/47/24

Indicates the preferred minimum charge capacity rating in mAh of individual, user- or factory-serviceable battery cells or packs in the battery source.

Example:

{
  "0/47/24": 1
}

Attribute 25 / 0x0019 — BatQuantity

Path example:

0/47/25

Indicates the quantity of individual, user- or factory-serviceable battery cells or packs in the battery source.

Example:

{
  "0/47/25": 1
}

Attribute 26 / 0x001A — BatChargeState

Path example:

0/47/26

Indicates the current state of the battery source with respect to charging as specified in BatChargeStateEnum.

Values (BatChargeStateEnum):

Example:

{
  "0/47/26": 1
}

Attribute 27 / 0x001B — BatTimeToFullCharge

Path example:

0/47/27

Indicates the estimated time in seconds before the battery source will be at full charge. A value of null indicates the Node is currently unable to assess the value. Changes to this attribute only be marked as reportable in the following cases: - At most once every 10 seconds, or - When it changes from null to any other value and vice versa. Since reporting consumes power, devices should be careful not to over-report.

Example:

{
  "0/47/27": 0
}

Attribute 28 / 0x001C — BatFunctionalWhileCharging

Path example:

0/47/28

Indicates whether the Node can remain operational while the battery source is charging.

Example:

{
  "0/47/28": true
}

Attribute 29 / 0x001D — BatChargingCurrent

Path example:

0/47/29

Indicates assessed current in mA (milliamps) presently supplied to charge the battery source. A value of null indicates the Node is currently unable to assess the value.

Example:

{
  "0/47/29": 1
}

Attribute 30 / 0x001E — ActiveBatChargeFaults

Path example:

0/47/30

Indicates the set of charge faults currently detected by the Node on this power source. This set is represented as a list of BatChargeFaultEnum. When the Node detects a fault has been raised, the appropriate BatChargeFaultEnum value is added to this list, provided it is not already present. This list must NOT contain more than one instance of a specific BatChargeFaultEnum value.

Example:

{
  "0/47/30": []
}

Attribute 31 / 0x001F — EndpointList

Path example:

0/47/31

Indicates a list of endpoints that are powered by the source defined by this cluster. Multiple instances of this cluster may list the same endpoint, because it is possible for power for an endpoint to come from multiple sources. In that case the Order attribute indicates their priority. For each power source on a node, there only be one instance of this cluster.

Example:

{
  "0/47/31": []
}

Cluster 47 Commands

Cluster 47 defines no commands. It is read (and, for writable attributes, written) through attribute access only.

Cluster 47 Events

Event 0 — WiredFaultChange

The WiredFaultChange Event is generated when the set of wired faults currently detected by the Node on this wired power source changes. This event must correspond to a change in value of ActiveWiredFaults.

Event 1 — BatFaultChange

The BatFaultChange Event is generated when the set of battery faults currently detected by the Node on this battery power source changes. This event must correspond to a change in value of ActiveBatFaults.

Event 2 — BatChargeFaultChange

The BatChargeFaultChange Event is generated when the set of charge faults currently detected by the Node on this battery power source changes. This event must correspond to a change in value of ActiveBatChargeFaults.

SmartphoneKey Notes

• Battery level (BatPercentRemaining, attribute 12, in half-percent units: 200 = 100 %) and BatChargeLevel (attribute 14) are the values surfaced for battery devices.
• Shadow paths follow endpoint/47/attribute; attribute values that the device reports as unreadable are written as n/a.
• Attribute IDs, command IDs and enum values on this page come from the CSA Matter 1.6.1 data model; descriptions are condensed from the specification text.