docs/upgrading.md - third_party/github/project-chip/connectedhomeip - Git at Google

 # Upgrading notes

 ## API changes and code migration

 ### `AttributePersistenceProvider`

 `AttributePersistenceProvider` was moved to `src/app/persistence` and its
 interface was updated:

 -   Read/write operate over pure buffers, without type information

 This update was done so that the interface is decoupled from ember and metadata
 types. The reasons for this approach:

 -   simpler/more modular code (easier to maintain)
 -   Have more generic storage support (including variable size data)
 -   Ability to preserve backward compatibility with existing products without
     increasing flash size by adding additional abstraction layers

 Callers will validate data validity on read instead of relying on data
 validation by the persistence provider.

 See <https://github.com/project-chip/connectedhomeip/pull/39693> for changes.

 The only change is that the `EmberAfAttributeMetadata` argument is not passed in
 anymore into `Read` and implementations are expected to just return the opaque
 data stored. API updates changed:

 -   FROM OLD

     ```cpp
     ReturnErrorOnFailure(ReadValue(aPath, aMetadata, aByteSpan));
     ```

 -   TO NEW

     ```cpp
     ReturnErrorOnFailure(ReadValue(aPath, aByteSpan));
     ReturnErrorOnFailure(ValidateData(aByteSpan, aMetadata));
     ```

     Where callers would implement `ValidateData`. Implementations do not have
     the use of aMetadata anymore and cluster data is opaque now.

 ### `CommandHandler`

 `CommandHandler` ability to directly invoke `Prepare/TLV-Write/Finish` cycles
 has been changed to only expose `AddResponse/AddStatus/AddClusterSpecific*`.

 Original versions of `CommandHandler` exposed the following low-level
 implementation-specific methods: `PrepareCommand`,
 `PrepareInvokeResponseCommand`, `GetCommandDataIBTLVWriter` and `FinishCommand`.
 These are not exposed anymore and instead one should use `AddResponse` or
 `AddResponseData`. When using an `EncodableToTLV` argument, the same
 functionality should be achievable.

 Example

 Before:

 ```cpp

 const CommandHandler::InvokeResponseParameters prepareParams(requestPath);
 ReturnOnFailure(commandHandler->PrepareInvokeResponseCommand(path, prepareParams));

 TLV::TLVWriter *writer = commandHandler->GetCommandDataIBTLVWriter();
 ReturnOnFailure(writer->Put(chip::TLV::ContextTag(1), 123));
 ReturnOnFailure(writer->Put(chip::TLV::ContextTag(2), 234));
 return commandHandler->FinishCommand();
 ```

 After:

 ```cpp

 class ReplyEncoder : public DataModel::EncodableToTLV
 {
 public:
     CHIP_ERROR EncodeTo(TLV::TLVWriter & writer, TLV::Tag tag) const override
     {
         TLV::TLVType outerType;
         ReturnErrorOnFailure(writer.StartContainer(tag, TLV::kTLVType_Structure, outerType));

         ReturnOnFailure(writer.Put(chip::TLV::ContextTag(1), 123));
         ReturnOnFailure(writer.Put(chip::TLV::ContextTag(2), 234));

         return writer.EndContainer(outerType);
     }
 };

 // ...
 ReplyEncoder replyEncoder;
 commandHandler->AddResponse(path, kReplyCommandId, replyEncoder);

 // or if error handling is implemented:
 //
 // ReturnErrorOnFailure(commandHandler->AddResponseData(path, kReplyCommandId, replyEncoder));
 //
 // In many cases error recovery from not being able to send a reply is not easy or expected,
 // so code does AddResponse rather than AddResponseData.

 ```

 ### Decoupling of `CommandHandlerInterface` from EmberTestCodegenModelViaMocks.cpp:1513:77 Metadata

 CommandHandler Interface was coupled with Ember data in ways that caused bugs if
 not set up correctly, updates were made for decoupling, now this data is
 provided through the new interface.

 With this the interfaces
 [`CommandHandlerInterface::RetrieveGeneratedCommands`](#enumerateacceptedcommands-to-retrieveacceptedcommands),
 [`CommandHandlerInterface::RetrieveAcceptedCommands`](#enumerategeneratedcommands-to-retrievegeneratedcommands)
 go through some changes, a shim is provided to make the transition simpler

 #### Full Changes

 ##### EnumerateGeneratedCommands to RetrieveGeneratedCommands

 Changed the old callback based iteration into a ListBuilder based approach for
 the enumeration of generated commands

 `CommandHandlerInterface::EnumerateGeneratedCommands(const ConcreteClusterPath & cluster, CommandIdCallback callback, void * context)`
 becomes
 `CommandHandlerInterface::RetrieveGeneratedCommands(const ConcreteClusterPath & cluster, ListBuilder<CommandId> & builder)`

 Changes for implementation

 -   old

 ```cpp
    for (auto && cmd : { ScanNetworksResponse::Id, NetworkConfigResponse::Id, ConnectNetworkResponse::Id })
    {
        VerifyOrExit(callback(cmd, context) == Loop::Continue, /**/);
    }
 ```

 -   new

 ```cpp
    ReturnErrorOnFailure(
         builder.AppendElements({ ScanNetworksResponse::Id, NetworkConfigResponse::Id, ConnectNetworkResponse::Id })
    )
 ```

 ##### EnumerateAcceptedCommands to RetrieveAcceptedCommands

 Changed the old callback based iteration into a ListBuilder based approach for
 the enumeration of accepted commands. The new Interface allows for the full
 metadata lookup.

 `CommandHandlerInterface::EnumerateAcceptedCommands(const ConcreteClusterPath & cluster, CommandIdCallback callback, void * context)`
 becomes
 `CommandHandlerInterface::RetrieveAcceptedCommands(const ConcreteClusterPath & cluster, ListBuilder<AcceptedCommandEntry> & builder)`

 Changes for implementation:

 -   Old

 ```cpp
     for (auto && cmd : {
              Disable::Id,
              EnableCharging::Id,
          })
     {
         VerifyOrExit(callback(cmd, context) == Loop::Continue, /**/);
     }

     if (HasFeature(Feature::kV2x))
     {
         VerifyOrExit(callback(EnableDischarging::Id, context) == Loop::Continue, /**/);
     }
 ```

 -   new

 ```cpp
     ReturnErrorOnFailure(builder.AppendElements({
         Disable::kMetadataEntry,
         EnableCharging::kMetadataEntry,
     }));
     if (HasFeature(Feature::kV2x))
     {
         ReturnErrorOnFailure(builder.EnsureAppendCapacity(1));
         ReturnErrorOnFailure(
             builder.Append(EnableDischarging::kMetadataEntry)
         );
     }
 ```

 Important Notes:

 Use `EnsureAppendCapacity` before `ListBuilder::Append` to prevent buffer
 overflow when appending a single element, this function never allocates.

 #### Backwards compatibility

 If the changes above are too high friction for upgrading, we provide a shim that
 allows implementing these changes with a very minimal change. It adds a little
 extra code size compared to the code above but should be decent for most cases.

 To use this shim just replace inheriting from CommandHandlerInterface with
 inheriting from CommandHandlerInterfaceShim<> with a list of the cluster IDs
 required for your implementation

 ```diff
 - #include <app/CommandHandlerInterface.h>
 + #include <app/CommandHandlerInterfaceShim.h>
 ...
 - class Instance : public CommandHandlerInterface,
 + class Instance : public CommandHandlerInterfaceShim<NetworkCommissioning::Id>
 ```

 ### `CommandHandlerInterface` in `chip::app::InteractionModelEngine`

 Command handler lists were placed in a separate registry class that is
 independent of the InteractionModelEngine class.

 The following replacements exist:

 -   `chip::app::InteractionModelEngine::RegisterCommandHandler` replaced by
     `chip::app::CommandHandlerInterfaceRegistry::Instance().RegisterCommandHandler`
 -   `chip::app::InteractionModelEngine::UnregisterCommandHandler` replaced by
     `chip::app::CommandHandlerInterfaceRegistry::Instance().UnregisterCommandHandler`
 -   `chip::app::InteractionModelEngine::FindCommandHandler` replaced by
     `chip::app::CommandHandlerInterfaceRegistry::Instance().GetCommandHandler`
 -   `chip::app::InteractionModelEngine::UnregisterCommandHandlers` replaced by
     `chip::app::CommandHandlerInterfaceRegistry::Instance().UnregisterAllCommandHandlersForEndpoint`

 ### AttributeAccessInterface registration and removal

 A new object exists for the attribute access interface registry, accessible as
 `chip::app::AttributeHandlerInterfaceRegistry::Instance()`

 Replacements for methods are:

 -   `registerAttributeAccessOverride` replaced by
     `chip::app::AttributeAccessInterfaceRegistry::Instance().Register`
 -   `unregisterAttributeAccessOverride` replaced by
     `chip::app::AttributeAccessInterfaceRegistry::Instance().Unregister`
 -   `unregisterAllAttributeAccessOverridesForEndpoint` replaced by
     `chip::app::AttributeAccessInterfaceRegistry::Instance().UnregisterAllForEndpoint`
 -   `chip::app::GetAttributeAccessOverride` replaced by
     `chip::app::AttributeAccessInterfaceRegistry::Instance().Get`

 ### `ServerInitParams::dataModelProvider` in `Server::Init` and `FactoryInitParams`

 Server and controller initialization require a set data model provider to work
 rather than auto-initializing ember-compatible code-generated data models.

 To preserve `codegen/zap` generated logic, use
 `CodegenDataModelProviderInstance` (see changes in
 [36558](https://github.com/project-chip/connectedhomeip/pull/36558) and
 [36613](https://github.com/project-chip/connectedhomeip/pull/36613) ).

 To use default attribute persistence, you need to pass in a
 `PersistentStorageDelegate` to `CodegenDataModelProviderInstance`. See example
 changes in [36658](https://github.com/project-chip/connectedhomeip/pull/36658)
 ).
	# Upgrading notes

	## API changes and code migration

	### `AttributePersistenceProvider`

	`AttributePersistenceProvider` was moved to `src/app/persistence` and its
	interface was updated:

	- Read/write operate over pure buffers, without type information

	This update was done so that the interface is decoupled from ember and metadata
	types. The reasons for this approach:

	- simpler/more modular code (easier to maintain)
	- Have more generic storage support (including variable size data)
	- Ability to preserve backward compatibility with existing products without
	increasing flash size by adding additional abstraction layers

	Callers will validate data validity on read instead of relying on data
	validation by the persistence provider.

	See <https://github.com/project-chip/connectedhomeip/pull/39693> for changes.

	The only change is that the `EmberAfAttributeMetadata` argument is not passed in
	anymore into `Read` and implementations are expected to just return the opaque
	data stored. API updates changed:

	- FROM OLD

	```cpp
	ReturnErrorOnFailure(ReadValue(aPath, aMetadata, aByteSpan));
	```

	- TO NEW

	```cpp
	ReturnErrorOnFailure(ReadValue(aPath, aByteSpan));
	ReturnErrorOnFailure(ValidateData(aByteSpan, aMetadata));
	```

	Where callers would implement `ValidateData`. Implementations do not have
	the use of aMetadata anymore and cluster data is opaque now.

	### `CommandHandler`

	`CommandHandler` ability to directly invoke `Prepare/TLV-Write/Finish` cycles
	has been changed to only expose `AddResponse/AddStatus/AddClusterSpecific*`.

	Original versions of `CommandHandler` exposed the following low-level
	implementation-specific methods: `PrepareCommand`,
	`PrepareInvokeResponseCommand`, `GetCommandDataIBTLVWriter` and `FinishCommand`.
	These are not exposed anymore and instead one should use `AddResponse` or
	`AddResponseData`. When using an `EncodableToTLV` argument, the same
	functionality should be achievable.

	Example

	Before:

	```cpp

	const CommandHandler::InvokeResponseParameters prepareParams(requestPath);
	ReturnOnFailure(commandHandler->PrepareInvokeResponseCommand(path, prepareParams));

	TLV::TLVWriter *writer = commandHandler->GetCommandDataIBTLVWriter();
	ReturnOnFailure(writer->Put(chip::TLV::ContextTag(1), 123));
	ReturnOnFailure(writer->Put(chip::TLV::ContextTag(2), 234));
	return commandHandler->FinishCommand();
	```

	After:

	```cpp

	class ReplyEncoder : public DataModel::EncodableToTLV
	{
	public:
	CHIP_ERROR EncodeTo(TLV::TLVWriter & writer, TLV::Tag tag) const override
	{
	TLV::TLVType outerType;
	ReturnErrorOnFailure(writer.StartContainer(tag, TLV::kTLVType_Structure, outerType));

	ReturnOnFailure(writer.Put(chip::TLV::ContextTag(1), 123));
	ReturnOnFailure(writer.Put(chip::TLV::ContextTag(2), 234));

	return writer.EndContainer(outerType);
	}
	};

	// ...
	ReplyEncoder replyEncoder;
	commandHandler->AddResponse(path, kReplyCommandId, replyEncoder);

	// or if error handling is implemented:
	//
	// ReturnErrorOnFailure(commandHandler->AddResponseData(path, kReplyCommandId, replyEncoder));
	//
	// In many cases error recovery from not being able to send a reply is not easy or expected,
	// so code does AddResponse rather than AddResponseData.

	```

	### Decoupling of `CommandHandlerInterface` from EmberTestCodegenModelViaMocks.cpp:1513:77 Metadata

	CommandHandler Interface was coupled with Ember data in ways that caused bugs if
	not set up correctly, updates were made for decoupling, now this data is
	provided through the new interface.

	With this the interfaces
	[`CommandHandlerInterface::RetrieveGeneratedCommands`](#enumerateacceptedcommands-to-retrieveacceptedcommands),
	[`CommandHandlerInterface::RetrieveAcceptedCommands`](#enumerategeneratedcommands-to-retrievegeneratedcommands)
	go through some changes, a shim is provided to make the transition simpler

	#### Full Changes

	##### EnumerateGeneratedCommands to RetrieveGeneratedCommands

	Changed the old callback based iteration into a ListBuilder based approach for
	the enumeration of generated commands

	`CommandHandlerInterface::EnumerateGeneratedCommands(const ConcreteClusterPath & cluster, CommandIdCallback callback, void * context)`
	becomes
	`CommandHandlerInterface::RetrieveGeneratedCommands(const ConcreteClusterPath & cluster, ListBuilder<CommandId> & builder)`

	Changes for implementation

	- old

	```cpp
	for (auto && cmd : { ScanNetworksResponse::Id, NetworkConfigResponse::Id, ConnectNetworkResponse::Id })
	{
	VerifyOrExit(callback(cmd, context) == Loop::Continue, /**/);
	}
	```

	- new

	```cpp
	ReturnErrorOnFailure(
	builder.AppendElements({ ScanNetworksResponse::Id, NetworkConfigResponse::Id, ConnectNetworkResponse::Id })
	)
	```

	##### EnumerateAcceptedCommands to RetrieveAcceptedCommands

	Changed the old callback based iteration into a ListBuilder based approach for
	the enumeration of accepted commands. The new Interface allows for the full
	metadata lookup.

	`CommandHandlerInterface::EnumerateAcceptedCommands(const ConcreteClusterPath & cluster, CommandIdCallback callback, void * context)`
	becomes
	`CommandHandlerInterface::RetrieveAcceptedCommands(const ConcreteClusterPath & cluster, ListBuilder<AcceptedCommandEntry> & builder)`

	Changes for implementation:

	- Old

	```cpp
	for (auto && cmd : {
	Disable::Id,
	EnableCharging::Id,
	})
	{
	VerifyOrExit(callback(cmd, context) == Loop::Continue, /**/);
	}

	if (HasFeature(Feature::kV2x))
	{
	VerifyOrExit(callback(EnableDischarging::Id, context) == Loop::Continue, /**/);
	}
	```

	- new

	```cpp
	ReturnErrorOnFailure(builder.AppendElements({
	Disable::kMetadataEntry,
	EnableCharging::kMetadataEntry,
	}));
	if (HasFeature(Feature::kV2x))
	{
	ReturnErrorOnFailure(builder.EnsureAppendCapacity(1));
	ReturnErrorOnFailure(
	builder.Append(EnableDischarging::kMetadataEntry)
	);
	}
	```

	Important Notes:

	Use `EnsureAppendCapacity` before `ListBuilder::Append` to prevent buffer
	overflow when appending a single element, this function never allocates.

	#### Backwards compatibility

	If the changes above are too high friction for upgrading, we provide a shim that
	allows implementing these changes with a very minimal change. It adds a little
	extra code size compared to the code above but should be decent for most cases.

	To use this shim just replace inheriting from CommandHandlerInterface with
	inheriting from CommandHandlerInterfaceShim<> with a list of the cluster IDs
	required for your implementation

	```diff
	- #include <app/CommandHandlerInterface.h>
	+ #include <app/CommandHandlerInterfaceShim.h>
	...
	- class Instance : public CommandHandlerInterface,
	+ class Instance : public CommandHandlerInterfaceShim<NetworkCommissioning::Id>
	```

	### `CommandHandlerInterface` in `chip::app::InteractionModelEngine`

	Command handler lists were placed in a separate registry class that is
	independent of the InteractionModelEngine class.

	The following replacements exist:

	- `chip::app::InteractionModelEngine::RegisterCommandHandler` replaced by
	`chip::app::CommandHandlerInterfaceRegistry::Instance().RegisterCommandHandler`
	- `chip::app::InteractionModelEngine::UnregisterCommandHandler` replaced by
	`chip::app::CommandHandlerInterfaceRegistry::Instance().UnregisterCommandHandler`
	- `chip::app::InteractionModelEngine::FindCommandHandler` replaced by
	`chip::app::CommandHandlerInterfaceRegistry::Instance().GetCommandHandler`
	- `chip::app::InteractionModelEngine::UnregisterCommandHandlers` replaced by
	`chip::app::CommandHandlerInterfaceRegistry::Instance().UnregisterAllCommandHandlersForEndpoint`

	### AttributeAccessInterface registration and removal

	A new object exists for the attribute access interface registry, accessible as
	`chip::app::AttributeHandlerInterfaceRegistry::Instance()`

	Replacements for methods are:

	- `registerAttributeAccessOverride` replaced by
	`chip::app::AttributeAccessInterfaceRegistry::Instance().Register`
	- `unregisterAttributeAccessOverride` replaced by
	`chip::app::AttributeAccessInterfaceRegistry::Instance().Unregister`
	- `unregisterAllAttributeAccessOverridesForEndpoint` replaced by
	`chip::app::AttributeAccessInterfaceRegistry::Instance().UnregisterAllForEndpoint`
	- `chip::app::GetAttributeAccessOverride` replaced by
	`chip::app::AttributeAccessInterfaceRegistry::Instance().Get`

	### `ServerInitParams::dataModelProvider` in `Server::Init` and `FactoryInitParams`

	Server and controller initialization require a set data model provider to work
	rather than auto-initializing ember-compatible code-generated data models.

	To preserve `codegen/zap` generated logic, use
	`CodegenDataModelProviderInstance` (see changes in
	[36558](https://github.com/project-chip/connectedhomeip/pull/36558) and
	[36613](https://github.com/project-chip/connectedhomeip/pull/36613) ).

	To use default attribute persistence, you need to pass in a
	`PersistentStorageDelegate` to `CodegenDataModelProviderInstance`. See example
	changes in [36658](https://github.com/project-chip/connectedhomeip/pull/36658)
	).