src/app/clusters/power-source-server/README.md - third_party/github/project-chip/connectedhomeip - Git at Google

 # Power Source Cluster

 The Power Source cluster is used to monitor and report the state of a power
 source. A power source can be either a battery or a wired power source.

 ## Overview

 This directory contains an implementation of Matter Power Source cluster. This
 implementation does not handle the persistence of the `Order` attribute. Because
 the `Order` attribute is read-only, only the direct user of the cluster can
 change it, so it is expected of them to handle the persistence of the attribute.
 This implementation also doesn't handle the storage of fixed string attributes
 and the attribute `endpointList`. This implementation notifies the data model
 when an attribute changes in the way that the spec mandates.

 ## Usage

 The cluster needs to be created manually and registered directly using
 `CodeDrivenDataModelProvider`. Creation can be done using
 `RegisteredServerCluster` and `LazyRegisteredServerCluster` in
 `src/app/server-cluster/SingleEndpointServerClusterRegistry.h`.

 ### How does the cluster work

 Because of flash considerations the implementation is a template based on the
 feature set and attribute set for things that the user wants to be supported.
 This will be made more clear using examples

 ### Examples

 -   ## Configuration for a wired power source besides mandatory attributes.

     This cluster supports `WiredAssessedInputVoltage` and `WiredNominalVoltage`
     optional attributes

     ```cpp
     #include <app/clusters/power-source-server/PowerSourceCluster.h>
     #include <app/server-cluster/SingleEndpointServerClusterRegistry.h>
     #include <data-model-providers/codedriven/CodeDrivenDataModelProvider.h>

     using namespace app;
     using namespace app::Clusters;

     constexpr EndpointId powerSourceEndpointId = 1;
     ```

     Define the template specialization to be used

     ```cpp
     // this is the "more correct" way to do this :)
     constexpr uint32_t GetOptionalAttributeBits()
     {
         PowerSource::PowerSourceOptionalAttributeSet optAttributes{};
         optAttributes.Set<PowerSource::Attributes::WiredAssessedInputVoltage::Id>();
         optAttributes.Set<PowerSource::Attributes::WiredNominalVoltage::Id>();
         return optAttributes.Raw();
     }

     constexpr uint32_t optionalAttributeBits = GetOptionalAttributeBits();

     // -- OR --

     constexpr uint32_t optionalAttributeBits = OptionalAttributeSet<
         PowerSource::Attributes::WiredAssessedInputVoltage::Id,
         PowerSource::Attributes::WiredNominalVoltage::Id>::All();

     constexpr uint32_t featureBits = BitFlags<PowerSource::Feature>(PowerSource::Feature::kWired).Raw();

     using MyWiredPowerSourceCluster = PowerSourceCluster<featureBits, optionalAttributeBits>;

     ```

     Create config object for the cluster, the cluster itself, and then use it

     ```cpp

     // the config
     MyWiredPowerSourceCluster::Config config("Wired Power Source (description)"_span, PowerSource::WiredCurrentTypeEnum::kDc);
     config.wiredNominalVoltage = 23000; // 23V

     // the cluster
     RegisteredServerCluster<MyWiredPowerSourceCluster> powerSourceInstance(powerSourceEndpointId, config);

     // register the cluster, this will call `Startup` on the cluster
     CodeDrivenDataModelProvider::Instance().Registry().Register(powerSourceInstance.Registration());

     // use the cluster
     powerSourceInstance.Cluster().SetWiredAssessedInputVoltage(20000); // 20V

     ```

     Note that functions associated with attributes that are not supported will
     throw a compile error.

 -   ## Configuration for three batteries, one simple, one rechargeable, one replaceable

     Simple battery will use the `BatPercentRemaining` optional attribute.
     Rechargeable battery will use the `BatPercentRemaining`,
     `BatChargingCurrent` optional attributes. Replaceable battery will use the
     `BatTimeRemaining`, `BatCapacity` optional attributes.

     It will be very beneficial to use one template specialization for the three
     of these configurations.

     ```cpp
      #include <app/clusters/power-source-server/PowerSourceCluster.h>
      #include <app/server-cluster/SingleEndpointServerClusterRegistry.h>
      #include <platform/DefaultTimerDelegate.h>
      #include <data-model-providers/codedriven/CodeDrivenDataModelProvider.h>

      using namespace app;
      using namespace app::Clusters;

      constexpr EndpointId powerSourceEndpointId1 = 1;
      constexpr EndpointId powerSourceEndpointId2 = 2;
      constexpr EndpointId powerSourceEndpointId3 = 3;

      DefaultTimerDelegate timerDelegate;
     ```

     Define the template specialization to be used

     ```cpp
     constexpr uint32_t GetOptionalAttributeBits()
     {
         PowerSource::PowerSourceOptionalAttributeSet optAttributes{};
         // enable all optional attributes that are used in any of the configurations
         optAttributes.Set<PowerSource::Attributes::BatPercentRemaining::Id>();
         optAttributes.Set<PowerSource::Attributes::BatTimeRemaining::Id>();
         optAttributes.Set<PowerSource::Attributes::BatChargingCurrent::Id>();
         optAttributes.Set<PowerSource::Attributes::BatCapacity::Id>();
         return optAttributes.Raw();
     }

     constexpr uint32_t optionalAttributeBits = GetOptionalAttributeBits();

     // enable all features that are used in any of the configurations
     constexpr uint32_t featureBits = BitFlags<PowerSource::Feature>(
         PowerSource::Feature::kBattery,
         PowerSource::Feature::kRechargeable,
         PowerSource::Feature::kReplaceable
     ).Raw();

     using MyBatteryPowerSourceCluster = PowerSourceCluster<featureBits, optionalAttributeBits>;

     ```

     Create config objects for the clusters, the clusters, and then use them All
     three objects will have the same functionality in terms of accessible
     functions and config field members

     But it is possible to inform the cluster exactly what attributes are used or
     supported from the manufacturer side using the field
     `usedOptionalAttributes` in the config object. This will make the cluster to
     report specific information about what the cluster supports to the data
     model. This will mean, that technically the cluster will have the capability
     to support certain attributes, but if manufacturer can't support it, the
     data model will see them as unsupported.

     ```cpp

     // The attribute sets of configurations
     PowerSource::PowerSourceOptionalAttributeSet attrSet1{};
     attrSet1.Set<PowerSource::Attributes::BatPercentRemaining::Id>();

     PowerSource::PowerSourceOptionalAttributeSet attrSet2{};
     attrSet2.Set<PowerSource::Attributes::BatPercentRemaining::Id>();
     attrSet2.Set<PowerSource::Attributes::BatChargingCurrent::Id>();

     PowerSource::PowerSourceOptionalAttributeSet attrSet3{};
     attrSet3.Set<PowerSource::Attributes::BatTimeRemaining::Id>();
     attrSet3.Set<PowerSource::Attributes::BatCapacity::Id>();

     // the configs
     MyBatteryPowerSourceCluster::Config config1("Simple battery cluster"_span, PowerSource::BatReplaceabilityEnum::kUnspecified, timerDelegate);
     config1.batPercentRemaining = 200; // 100%, doubled percentage
     config1.usedOptionalAttributes = attrSet1;

     MyBatteryPowerSourceCluster::Config config2("Rechargeable battery cluster"_span, PowerSource::BatReplaceabilityEnum::kNotReplaceable, timerDelegate);
     // this will make the cluster report itself as rechargeable, otherwise it would be like a simple cluster to the data model
     config2.MakeRechargeable();
     config2.batPercentRemaining = 200;
     config2.batChargingCurrent = 5000; // 5A
     config2.usedOptionalAttributes = attrSet2;

     MyBatteryPowerSourceCluster::Config config3("Replaceable battery cluster"_span, PowerSource::BatReplaceabilityEnum::kUserReplaceable, timerDelegate);
     // make it replaceable
     config3.MakeReplaceable("Description for replacement"_span, /* quantity */ 1);
     config3.batTimeRemaining = 3600; // 1h estimated uptime
     config3.batCapacity = 2000; // 2000 mAh capacity
     config3.usedOptionalAttributes = attrSet3;

     // the clusters
     RegisteredServerCluster<MyBatteryPowerSourceCluster> simpleBatteryInstance(powerSourceEndpointId1, config1);
     RegisteredServerCluster<MyBatteryPowerSourceCluster> rechargeableBatteryInstance(powerSourceEndpointId2, config2);
     RegisteredServerCluster<MyBatteryPowerSourceCluster> replaceableBatteryInstance(powerSourceEndpointId3, config3);

     // register the clusters, this will call `Startup` on them
     CodeDrivenDataModelProvider::Instance().Registry().Register(simpleBatteryInstance.Registration());
     CodeDrivenDataModelProvider::Instance().Registry().Register(rechargeableBatteryInstance.Registration());
     CodeDrivenDataModelProvider::Instance().Registry().Register(replaceableBatteryInstance.Registration());

     // use the clusters ...
     replaceableBatteryInstance.Cluster().SetBatReplacementNeeded(true);

     ```

 -   ## Configuration for one wired power source and one simple battery

     When it is needed to have both wired and battery power sources, it is not
     possible to do this with one template specialization by design.

     ```cpp
      #include <app/clusters/power-source-server/PowerSourceCluster.h>
      #include <app/server-cluster/SingleEndpointServerClusterRegistry.h>
      #include <platform/DefaultTimerDelegate.h>
      #include <data-model-providers/codedriven/CodeDrivenDataModelProvider.h>

      using namespace app;
      using namespace app::Clusters;

      constexpr EndpointId powerSourceEndpointId1 = 1;
      constexpr EndpointId powerSourceEndpointId2 = 2;

      DefaultTimerDelegate timerDelegate;
     ```

     Define the template specializations to be used

     ```cpp

     // enable all features that are used in any wired configuration (so just kWired)
     using MyWiredPowerSourceCluster = PowerSourceCluster<BitFlags<PowerSource::Feature>(PowerSource::Feature::kWired).Raw(), 0 /* no optional attributes */>;


     // enable kBattery for this type
     using MyBatteryPowerSourceCluster = PowerSourceCluster<BitFlags<PowerSource::Feature>(PowerSource::Feature::kBattery).Raw(), 0/* no optional attributes */>;

     ```

     Create config objects for the clusters, the clusters, and then use them

     ```cpp

     // the configs
     MyWiredPowerSourceCluster::Config config1("Wired cluster"_span, PowerSource::WiredCurrentTypeEnum::kAc);
     config1.status = PowerSource::PowerSourceStatusEnum::kUnavailable;

     MyBatteryPowerSourceCluster::Config config2("Simple battery cluster"_span, PowerSource::BatReplaceabilityEnum::kNotReplaceable, timerDelegate);

     // the clusters
     RegisteredServerCluster<MyWiredPowerSourceCluster> wiredInstance(powerSourceEndpointId1, config1);
     RegisteredServerCluster<MyBatteryPowerSourceCluster> batteryInstance(powerSourceEndpointId2, config2);

     // register the clusters, this will call `Startup` on them
     CodeDrivenDataModelProvider::Instance().Registry().Register(wiredInstance.Registration());
     CodeDrivenDataModelProvider::Instance().Registry().Register(batteryInstance.Registration());

     // use the clusters ...
     wiredInstance.Cluster().SetOrder(2);

     ```

 ### Notes

 For simplicity there are 4 already named specializations of the class in the
 `NamedPowerSourceClusters.h` -

 -   `MinimalWiredPowerSourceCluster`
 -   `MinimalBatteryPowerSourceCluster`
 -   `FullWiredPowerSourceCluster` (supports ALL wired optional attributes)
 -   `FullBatteryPowerSourceCluster` (supports ALL battery optional attributes,
     and is BOTH replaceable and rechargeable)

 Instead of `RegisteredServerCluster` one can use `LazyRegisteredServerCluster`
 which can defer the creation and overall provides dynamic lifetime management.

 Some attributes can be can be set only in the config object, and not after the
 clusters creation, because they are `Fixed` attributes.

 Again, all this is to have the cluster to be the smallest possible type for the
 functionality needed. So if you do not have any FLASH restrictions, you can use
 `Full*PowerSourceCluster`s for everything.
	# Power Source Cluster

	The Power Source cluster is used to monitor and report the state of a power
	source. A power source can be either a battery or a wired power source.

	## Overview

	This directory contains an implementation of Matter Power Source cluster. This
	implementation does not handle the persistence of the `Order` attribute. Because
	the `Order` attribute is read-only, only the direct user of the cluster can
	change it, so it is expected of them to handle the persistence of the attribute.
	This implementation also doesn't handle the storage of fixed string attributes
	and the attribute `endpointList`. This implementation notifies the data model
	when an attribute changes in the way that the spec mandates.

	## Usage

	The cluster needs to be created manually and registered directly using
	`CodeDrivenDataModelProvider`. Creation can be done using
	`RegisteredServerCluster` and `LazyRegisteredServerCluster` in
	`src/app/server-cluster/SingleEndpointServerClusterRegistry.h`.

	### How does the cluster work

	Because of flash considerations the implementation is a template based on the
	feature set and attribute set for things that the user wants to be supported.
	This will be made more clear using examples

	### Examples

	- ## Configuration for a wired power source besides mandatory attributes.

	This cluster supports `WiredAssessedInputVoltage` and `WiredNominalVoltage`
	optional attributes

	```cpp
	#include <app/clusters/power-source-server/PowerSourceCluster.h>
	#include <app/server-cluster/SingleEndpointServerClusterRegistry.h>
	#include <data-model-providers/codedriven/CodeDrivenDataModelProvider.h>

	using namespace app;
	using namespace app::Clusters;

	constexpr EndpointId powerSourceEndpointId = 1;
	```

	Define the template specialization to be used

	```cpp
	// this is the "more correct" way to do this :)
	constexpr uint32_t GetOptionalAttributeBits()
	{
	PowerSource::PowerSourceOptionalAttributeSet optAttributes{};
	optAttributes.Set<PowerSource::Attributes::WiredAssessedInputVoltage::Id>();
	optAttributes.Set<PowerSource::Attributes::WiredNominalVoltage::Id>();
	return optAttributes.Raw();
	}

	constexpr uint32_t optionalAttributeBits = GetOptionalAttributeBits();

	// -- OR --

	constexpr uint32_t optionalAttributeBits = OptionalAttributeSet<
	PowerSource::Attributes::WiredAssessedInputVoltage::Id,
	PowerSource::Attributes::WiredNominalVoltage::Id>::All();

	constexpr uint32_t featureBits = BitFlags<PowerSource::Feature>(PowerSource::Feature::kWired).Raw();

	using MyWiredPowerSourceCluster = PowerSourceCluster<featureBits, optionalAttributeBits>;

	```

	Create config object for the cluster, the cluster itself, and then use it

	```cpp

	// the config
	MyWiredPowerSourceCluster::Config config("Wired Power Source (description)"_span, PowerSource::WiredCurrentTypeEnum::kDc);
	config.wiredNominalVoltage = 23000; // 23V

	// the cluster
	RegisteredServerCluster<MyWiredPowerSourceCluster> powerSourceInstance(powerSourceEndpointId, config);

	// register the cluster, this will call `Startup` on the cluster
	CodeDrivenDataModelProvider::Instance().Registry().Register(powerSourceInstance.Registration());

	// use the cluster
	powerSourceInstance.Cluster().SetWiredAssessedInputVoltage(20000); // 20V

	```

	Note that functions associated with attributes that are not supported will
	throw a compile error.

	- ## Configuration for three batteries, one simple, one rechargeable, one replaceable

	Simple battery will use the `BatPercentRemaining` optional attribute.
	Rechargeable battery will use the `BatPercentRemaining`,
	`BatChargingCurrent` optional attributes. Replaceable battery will use the
	`BatTimeRemaining`, `BatCapacity` optional attributes.

	It will be very beneficial to use one template specialization for the three
	of these configurations.

	```cpp
	#include <app/clusters/power-source-server/PowerSourceCluster.h>
	#include <app/server-cluster/SingleEndpointServerClusterRegistry.h>
	#include <platform/DefaultTimerDelegate.h>
	#include <data-model-providers/codedriven/CodeDrivenDataModelProvider.h>

	using namespace app;
	using namespace app::Clusters;

	constexpr EndpointId powerSourceEndpointId1 = 1;
	constexpr EndpointId powerSourceEndpointId2 = 2;
	constexpr EndpointId powerSourceEndpointId3 = 3;

	DefaultTimerDelegate timerDelegate;
	```

	Define the template specialization to be used

	```cpp
	constexpr uint32_t GetOptionalAttributeBits()
	{
	PowerSource::PowerSourceOptionalAttributeSet optAttributes{};
	// enable all optional attributes that are used in any of the configurations
	optAttributes.Set<PowerSource::Attributes::BatPercentRemaining::Id>();
	optAttributes.Set<PowerSource::Attributes::BatTimeRemaining::Id>();
	optAttributes.Set<PowerSource::Attributes::BatChargingCurrent::Id>();
	optAttributes.Set<PowerSource::Attributes::BatCapacity::Id>();
	return optAttributes.Raw();
	}

	constexpr uint32_t optionalAttributeBits = GetOptionalAttributeBits();

	// enable all features that are used in any of the configurations
	constexpr uint32_t featureBits = BitFlags<PowerSource::Feature>(
	PowerSource::Feature::kBattery,
	PowerSource::Feature::kRechargeable,
	PowerSource::Feature::kReplaceable
	).Raw();

	using MyBatteryPowerSourceCluster = PowerSourceCluster<featureBits, optionalAttributeBits>;

	```

	Create config objects for the clusters, the clusters, and then use them All
	three objects will have the same functionality in terms of accessible
	functions and config field members

	But it is possible to inform the cluster exactly what attributes are used or
	supported from the manufacturer side using the field
	`usedOptionalAttributes` in the config object. This will make the cluster to
	report specific information about what the cluster supports to the data
	model. This will mean, that technically the cluster will have the capability
	to support certain attributes, but if manufacturer can't support it, the
	data model will see them as unsupported.

	```cpp

	// The attribute sets of configurations
	PowerSource::PowerSourceOptionalAttributeSet attrSet1{};
	attrSet1.Set<PowerSource::Attributes::BatPercentRemaining::Id>();

	PowerSource::PowerSourceOptionalAttributeSet attrSet2{};
	attrSet2.Set<PowerSource::Attributes::BatPercentRemaining::Id>();
	attrSet2.Set<PowerSource::Attributes::BatChargingCurrent::Id>();

	PowerSource::PowerSourceOptionalAttributeSet attrSet3{};
	attrSet3.Set<PowerSource::Attributes::BatTimeRemaining::Id>();
	attrSet3.Set<PowerSource::Attributes::BatCapacity::Id>();

	// the configs
	MyBatteryPowerSourceCluster::Config config1("Simple battery cluster"_span, PowerSource::BatReplaceabilityEnum::kUnspecified, timerDelegate);
	config1.batPercentRemaining = 200; // 100%, doubled percentage
	config1.usedOptionalAttributes = attrSet1;

	MyBatteryPowerSourceCluster::Config config2("Rechargeable battery cluster"_span, PowerSource::BatReplaceabilityEnum::kNotReplaceable, timerDelegate);
	// this will make the cluster report itself as rechargeable, otherwise it would be like a simple cluster to the data model
	config2.MakeRechargeable();
	config2.batPercentRemaining = 200;
	config2.batChargingCurrent = 5000; // 5A
	config2.usedOptionalAttributes = attrSet2;

	MyBatteryPowerSourceCluster::Config config3("Replaceable battery cluster"_span, PowerSource::BatReplaceabilityEnum::kUserReplaceable, timerDelegate);
	// make it replaceable
	config3.MakeReplaceable("Description for replacement"_span, /* quantity */ 1);
	config3.batTimeRemaining = 3600; // 1h estimated uptime
	config3.batCapacity = 2000; // 2000 mAh capacity
	config3.usedOptionalAttributes = attrSet3;

	// the clusters
	RegisteredServerCluster<MyBatteryPowerSourceCluster> simpleBatteryInstance(powerSourceEndpointId1, config1);
	RegisteredServerCluster<MyBatteryPowerSourceCluster> rechargeableBatteryInstance(powerSourceEndpointId2, config2);
	RegisteredServerCluster<MyBatteryPowerSourceCluster> replaceableBatteryInstance(powerSourceEndpointId3, config3);

	// register the clusters, this will call `Startup` on them
	CodeDrivenDataModelProvider::Instance().Registry().Register(simpleBatteryInstance.Registration());
	CodeDrivenDataModelProvider::Instance().Registry().Register(rechargeableBatteryInstance.Registration());
	CodeDrivenDataModelProvider::Instance().Registry().Register(replaceableBatteryInstance.Registration());

	// use the clusters ...
	replaceableBatteryInstance.Cluster().SetBatReplacementNeeded(true);

	```

	- ## Configuration for one wired power source and one simple battery

	When it is needed to have both wired and battery power sources, it is not
	possible to do this with one template specialization by design.

	```cpp
	#include <app/clusters/power-source-server/PowerSourceCluster.h>
	#include <app/server-cluster/SingleEndpointServerClusterRegistry.h>
	#include <platform/DefaultTimerDelegate.h>
	#include <data-model-providers/codedriven/CodeDrivenDataModelProvider.h>

	using namespace app;
	using namespace app::Clusters;

	constexpr EndpointId powerSourceEndpointId1 = 1;
	constexpr EndpointId powerSourceEndpointId2 = 2;

	DefaultTimerDelegate timerDelegate;
	```

	Define the template specializations to be used

	```cpp

	// enable all features that are used in any wired configuration (so just kWired)
	using MyWiredPowerSourceCluster = PowerSourceCluster<BitFlags<PowerSource::Feature>(PowerSource::Feature::kWired).Raw(), 0 /* no optional attributes */>;


	// enable kBattery for this type
	using MyBatteryPowerSourceCluster = PowerSourceCluster<BitFlags<PowerSource::Feature>(PowerSource::Feature::kBattery).Raw(), 0/* no optional attributes */>;

	```

	Create config objects for the clusters, the clusters, and then use them

	```cpp

	// the configs
	MyWiredPowerSourceCluster::Config config1("Wired cluster"_span, PowerSource::WiredCurrentTypeEnum::kAc);
	config1.status = PowerSource::PowerSourceStatusEnum::kUnavailable;

	MyBatteryPowerSourceCluster::Config config2("Simple battery cluster"_span, PowerSource::BatReplaceabilityEnum::kNotReplaceable, timerDelegate);

	// the clusters
	RegisteredServerCluster<MyWiredPowerSourceCluster> wiredInstance(powerSourceEndpointId1, config1);
	RegisteredServerCluster<MyBatteryPowerSourceCluster> batteryInstance(powerSourceEndpointId2, config2);

	// register the clusters, this will call `Startup` on them
	CodeDrivenDataModelProvider::Instance().Registry().Register(wiredInstance.Registration());
	CodeDrivenDataModelProvider::Instance().Registry().Register(batteryInstance.Registration());

	// use the clusters ...
	wiredInstance.Cluster().SetOrder(2);

	```

	### Notes

	For simplicity there are 4 already named specializations of the class in the
	`NamedPowerSourceClusters.h` -

	- `MinimalWiredPowerSourceCluster`
	- `MinimalBatteryPowerSourceCluster`
	- `FullWiredPowerSourceCluster` (supports ALL wired optional attributes)
	- `FullBatteryPowerSourceCluster` (supports ALL battery optional attributes,
	and is BOTH replaceable and rechargeable)

	Instead of `RegisteredServerCluster` one can use `LazyRegisteredServerCluster`
	which can defer the creation and overall provides dynamic lifetime management.

	Some attributes can be can be set only in the config object, and not after the
	clusters creation, because they are `Fixed` attributes.

	Again, all this is to have the cluster to be the smallest possible type for the
	functionality needed. So if you do not have any FLASH restrictions, you can use
	`Full*PowerSourceCluster`s for everything.