3. Matter Controller
This section introduces the esp_matter_controller component, which can be used to build Matter controller and commissioner on Espressif SoCs.
Several controller/commissioner examples are provided.
This example implements a basic Matter commissioner which can be used for commissioning Matter commissionees to its Matter Fabric.
This example implements a Matter controller in RainMaker Matter Fabric. It is also a Matter server so it is commissioned to RainMaker Matter Fabic via standard Matter commissioning flow. And it uses a custom Matter cluster to update its Node Operational Credentials (NOC) and obtain the device list of the Matter Fabric.
This example implements a Matter controller in RainMaker Matter Fabric without a Matter server instance. It can be provisioned to a Wi-Fi network via network_provisioning. And it uses a custom RainMaker service to obtain Administer NOC and device list of the Matter Fabric.
The device console uses these command prefixes:
matter esp controllerruns controller commands.matter esp groupconfigures groups and keys.matter esp devicemanages devices in the controller example. See the example README for its commands.
3.1. Console modules
Include esp_matter_controller_console.h and register each module you need
once, before starting the shell. The first controller module registers the
command root.
esp_matter::controller::console::register_read_commands();
esp_matter::controller::console::register_write_commands();
esp_matter::controller::console::register_invoke_commands();
esp_matter::controller::console::register_subscribe_commands();
esp_matter::controller::console::register_groups_commands();
ESP_ERROR_CHECK_WITHOUT_ABORT(esp_matter::console::init());
The Read module handles attributes and events. The Subscribe module creates,
lists, and removes subscriptions. Register window, pairing, or ICD commands
with register_window_commands(), register_pairing_commands(), or
register_icd_commands().
Pairing requires CONFIG_ESP_MATTER_COMMISSIONER_ENABLE. ICD and group-settings
registration require a build without Matter server support. Group settings use
the separate matter esp group root. Group Invoke and Write belong to the
Invoke and Write modules and work with or without a Matter server.
Registration can fail if the console has no command-set capacity left. Modules use separate translation units and do not register themselves automatically. The linker can remove unreferenced handlers, help strings, and state. Referenced APIs and shared dependencies remain linked.
An application with its own pairing CLI can call pairing::interaction
without registering the generic pairing console.
3.1.1. Console input
Only registered modules provide commands. Put options such as --timed-ms
before --, followed by one JSON argument. Write takes a tagged attribute
value. Invoke takes a command-fields object, or {} for no fields. Use shell
quoting and escape embedded double quotes and backslashes.
The ESP-IDF line editor filters non-ASCII input. Use JSON Unicode escapes such
as \uXXXX, entered as \\uXXXX through shell escaping.
CONFIG_CHIP_SHELL_CMD_LINE_BUF_MAX_LENGTH limits line length, and
CONFIG_CHIP_SHELL_CMD_LINE_ARG_MAX_COUNT limits the argument count.
3.2. Controller features
The controller is the role of a node that has permissions to enable it to control one or more nodes. It has a complete chain of Node Operational Credentials (NOC) and acts as an administer or an operator in its Matter fabric. And the NodeId of the controller or CASE Authenticated Tag (CAT) of the controller’s NOC should in the Access Control List of other end-devices with administer/operator privilege.
The controller should support the following features:
Send Cluster Invoking commands to other nodes.
Send Read Attribute/Event commands to other nodes.
Send Write Attribute commands to other nodes
Send Subscribe Attribute/Event commands to other nodes.
Join Matter Groups and manage the Group Key Set.
Register and unregister ICD clients.
3.2.1. Cluster Invoking commands
Use invoke to send unicast or group cluster commands. In C++, use
invoke_command::interaction with a request and an explicit delegate pointer.
Pass nullptr to discard successful responses while retaining failure logs.
OnResponse() receives the concrete command path, status, and optional response TLV;
OnDone() reports terminal completion. See Ownership and callbacks for
ownership and error-handling requirements.
Send the cluster command:
matter esp controller invoke <node-id> <endpoint-id> <cluster-id> <command-id> [--timed-ms N] -- <command-data> matter esp controller invoke group <group-id> <cluster-id> <command-id> -- <command-data>
Note
The
command-datashould utilize a JSON object string and the name of each item in this object should be\"<TagNumber>:<DataType>\"or\"<TagName>:<TagNumber>:<DataType>\". The TagNumber should be the same as the command parameter ID in Matter SPEC and the supported DataTypes are listed in$ESP_MATTER_PATH/components/esp_matter/utils/json_to_tlv.hFor the DataType
bytes, the value should be a Base64-Encoded string.
Here are some examples of the command-data format.
For MoveToLevel command in LevelControl cluster, the
command-data({"level": 10, "transitionTime": 0, "optionsMask": 0, "optionsOverride": 0}) should be:matter esp controller invoke <node-id> <endpoint-id> 8 0 -- "{\"0:U8\": 10, \"1:U16\": 0, \"2:U8\": 0, \"3:U8\": 0}"
For KeySetWrite command in GroupKeyManagement cluster, the
command-data({"groupKeySet":{"groupKeySetID": 42, "groupKeySecurityPolicy": 0, "epochKey0": d0d1d2d3d4d5d6d7d8d9dadbdcdddedf, "epochStartTime0": 2220000, "epochKey1": null, "epochStartTime1": null, "epochKey2": null, "epochStartTime2": null}}) should be:matter esp controller invoke <node-id> <endpoint-id> 63 0 -- "{\"0:OBJ\": {\"0:U16\": 42, \"1:U8\": 0, \"2:BYT\": \"0NHS09TV1tfY2drb3N3e3w==\", \"3:U64\": 2220000, \"4:NULL\": null, \"5:NULL\": null, \"6:NULL\": null, \"7:NULL\": null}}"
For AddGroup command in Groups cluster, the
command-data({"groupID": 1, "groupName": "grp1"}) should be:matter esp controller invoke <node-id> <endpoint-id> 0x4 0 -- "{\"0:U16\": 1, \"1:STR\": \"grp1\"}"
3.2.2. Read commands
Use read_command::interaction with attribute and/or event path spans.
Its delegate receives OnReportBegin(), OnAttribute(), OnEvent(),
OnReportEnd(err), and terminal OnDone(err) callbacks. A synchronous
start() failure produces no callbacks.
3.2.2.1. Read attribute commands
Use read attr to read attributes from end-devices.
Attribute read syntax:
matter esp controller read attr <node-id> <endpoint-ids> <cluster-ids> <attribute-ids>
Note
endpoint-ids can represent a single or multiple endpoints, e.g. ‘0’ or ‘0,1’. And the same applies to cluster-ids, attribute-ids, and event-ids below.
3.2.2.2. Read event commands
Use read event to read events from end-devices.
Event read syntax:
matter esp controller read event <node-id> <endpoint-ids> <cluster-ids> <event-ids>
3.2.3. Write attribute commands
write attr writes one complete attribute per command.
In C++, use write_command::interaction with a concrete attribute path, value
encoder, and explicit delegate pointer. Pass nullptr to discard successful
responses while retaining failure logs. A delegate gets the path status in
OnResponse() and terminal completion in OnDone(err).
Attribute write syntax:
matter esp controller write attr <node-id> <endpoint-id> <cluster-id> <attribute-id> [--timed-ms N] -- <attribute-value> matter esp controller write attr group <group-id> <cluster-id> <attribute-id> -- <attribute-value>
Note
attribute_valueshould utilize a JSON object string. And the format of this string is the same as thecommand_datain cluster commands. This JSON object should contain only one item that represents the attribute value.
Here are some examples of the attribute_value format.
For StartUpOnOff attribute of OnOff Cluster, you should use the following JSON structures as the attribute_value to represent the StartUpOnOff 2 and null:
matter esp controller write attr <node_id> <endpoint_id> 6 0x4003 -- "{\"0:U8\": 2}" matter esp controller write attr <node_id> <endpoint_id> 6 0x4003 -- "{\"0:NULL\": null}"
For Binding attribute of Binding cluster, you should use the following JSON structure as the attribute_value to represent the binding list [{"node":1, "endpoint":1, "cluster":6}]:
matter esp controller write attr <node_id> <endpoint_id> 30 0 -- "{\"0:ARR-OBJ\":[{\"1:U64\":1, \"3:U16\":1, \"4:U32\": 6}]}"
For ACL attribute of AccessControl cluster, you should use the following JSON structure as the attribute_value to represent the AccessControlList [{"privilege": 5, "authMode": 2, "subjects": [112233], "targets": null}, {"privilege": 4, "authMode": 3, "subjects": [1], "targets": null}]:
matter esp controller write attr <node_id> <endpoint_id> 31 0 -- "{\"0:ARR-OBJ\":[{\"1:U8\": 5, \"2:U8\": 2, \"3:ARR-U64\": [112233], \"4:NULL\": null}, {\"1:U8\": 4, \"2:U8\": 3, \"3:ARR-U64\": [1], \"4:NULL\": null}]}"
To write multiple attributes, issue separate commands. For example, write the ACL and Binding attributes in order with:
matter esp controller write attr <node_id> <endpoint_id1> 31 0 -- "{\"0:ARR-OBJ\":[{\"1:U8\": 5, \"2:U8\": 2, \"3:ARR-U64\": [112233], \"4:NULL\": null}, {\"1:U8\": 4, \"2:U8\": 3, \"3:ARR-U64\": [1], \"4:NULL\": null}]}" matter esp controller write attr <node_id> <endpoint_id2> 30 0 -- "{\"0:ARR-OBJ\":[{\"1:U64\":1, \"3:U16\":1, \"4:U32\": 6}]}"
Wait for the first Write’s completion before submitting the second if ordering is required; console submission success alone does not indicate completion.
For attributes of type uint64_t or int64_t, if the absolute value is greater than (2^53), you should use string to represent number in JSON structure for precision
matter esp controller write attr <node_id> <endpoint_id> 42 0 -- "{\"0:ARR-OBJ\":[{\"1:U64\": \"9007199254740993\", \"2:U8\": 0}]}"
3.2.4. Subscribe commands
Use subscribe_command::subscription for remote attribute and event reports.
Its delegate receives report callbacks and OnStateChanged(state, cause) for
connection, retry, and termination. Keep the subscription alive until stopped
or terminated, and perform cleanup outside its callbacks under the CHIP lock.
3.2.4.1. Subscribe attribute commands
Use sub add attr to subscribe to attribute reports.
Attribute subscription syntax:
matter esp controller sub add attr <node-id> <endpoint-ids> <cluster-ids> <attribute-ids> <min-interval> <max-interval>
3.2.4.2. Subscribe event commands
Use sub add event to subscribe to event reports.
Send the subscribe-event command:
matter esp controller sub add event <node-id> <endpoint-ids> <cluster-ids> <event-ids> <min-interval> <max-interval>
3.2.4.3. List and remove subscriptions
sub list shows console-owned subscriptions, including connecting and
retrying entries. Each entry shows the fabric, node, state, and subscription ID
when available.
matter esp controller sub list
matter esp controller sub remove <node-id> <subscription-id>
matter esp controller sub remove <node-id> all
matter esp controller sub remove all
Node-specific removal applies to the active fabric. The literal all must be
provided explicitly: missing arguments, invalid IDs, and extra arguments are
rejected without removing anything. Node and subscription IDs accept decimal or
0x-prefixed hexadecimal notation.
Warning
sub remove all removes subscriptions across all nodes and fabrics.
Removal also affects subscriptions created outside the console, whereas
sub list displays only console-owned subscriptions.
3.2.5. Group commands
Group Invoke and Write accept group <id> or an encoded node ID
0xFFFFFFFFFFFFXXXX, where XXXX is the nonzero 16-bit group ID. Both use
the active fabric at submission time. The group form has no endpoint
argument; the encoded node form ignores the endpoint argument. Read and
Subscribe reject group destinations.
Completion reports dispatch, not member acknowledgments. Group commands do not support timed options. Configure matching groups and keys on the controller and targets before sending requests. Manage remote membership through each target’s Groups cluster.
Equivalent group destinations:
matter esp controller invoke group 1 6 1 -- {}
matter esp controller invoke 0xFFFFFFFFFFFF0001 0 6 1 -- {}
matter esp controller write attr group 1 6 0x4003 -- "{\"0:U8\":2}"
matter esp controller write attr 0xFFFFFFFFFFFF0001 0 6 0x4003 -- "{\"0:U8\":2}"
Configure controller-local groups and keys in builds without a Matter server:
matter esp group list
matter esp group add <group-id> <group-name>
matter esp group remove <group-id>
matter esp group keyset list
matter esp group keyset add <ketset-id> <policy> <validity-time> <epoch-key-oct-str>
matter esp group keyset remove <ketset-id>
matter esp group bind <group-id> <ketset-id>
matter esp group unbind <group-id> <ketset-id>
3.2.6. ICD client management
Use ICD client management with CONFIG_ESP_MATTER_CONTROLLER_ENABLE=y and
CONFIG_ESP_MATTER_ENABLE_MATTER_SERVER=n. The controller example registers
the console commands when CONFIG_ENABLE_CHIP_SHELL=y. In a custom application,
call esp_matter::controller::console::register_icd_commands() to register them.
3.2.6.1. ICD console commands
matter esp controller icd list
matter esp controller icd register <node> <check-in-node> <subject> <key-hex> --client-type permanent|ephemeral [--verification-key HEX]
matter esp controller icd unregister <node> <check-in-node> [--verification-key HEX]
matter esp controller icd status
matter esp controller icd stop
node identifies the ICD server. check-in-node identifies the check-in
recipient on the controller’s current fabric; use the controller’s operational
Node ID to receive check-ins on this controller. subject identifies the
subject whose activity the ICD monitors. Node IDs and subjects accept decimal
or 0x-prefixed hexadecimal notation. Supply each key as 32 hexadecimal
digits, without a 0x prefix. The verification key is optional.
register and unregister use the current fabric. Unregistration requires
a local registration with the same ICD server and check-in node. list shows
registration metadata across stored fabrics, including the fabric index, node
IDs, counters, monitored subject, and client type. It omits key material.
The console observes one ICD request at a time. Submission success means the
request was accepted. Wait for the completion log to confirm that both the
remote command and local storage update succeeded. status reports whether
the console still observes the request.
stop detaches observation and stops work before command dispatch. An
already-sent command can still complete and update local storage. A request for
the same peer can return busy while that work finishes, even after status
reports inactive.
3.2.6.2. ICD client API
Include esp_matter_controller_icd_client.h and use the
esp_matter::controller::icd_client namespace. Replace calls to the removed
controller::list_registered_icd() with
icd_client::for_each_registered_icd(callback, context). Its callback receives
an entry_t containing registration metadata. Return CHIP_NO_ERROR to
continue iteration, or another error to stop and return that error to the
caller. Keep storage unchanged during iteration; entry references remain valid
for the callback duration.
For registration and unregistration, keep an icd_client::interaction and
its icd_client::delegate alive while observing the operation. Populate a
request_t with METHOD_REGISTER or METHOD_UNREGISTER and call
start(request, &delegate). Pass the required registration key as 16 bytes;
an omitted verification key uses nullptr and size zero. start() copies
borrowed key data before returning. A synchronous error produces no callbacks.
An accepted request produces deferred callbacks and one terminal OnDone(),
unless you detach the delegate with stop().
OnResponse() provides a valid remote status, including rejection, and an
ICD counter for a successful registration. The response reference remains valid
for the callback duration. OnDone() reports connection, command, or local
storage errors; CHIP_NO_ERROR confirms both remote success and the local
storage update. Remote success can precede a local storage failure.
Use the CHIP stack context for API calls, storage iteration, and destruction
of an active interaction. OnDone() may restart, stop, or destroy the
interaction; OnResponse() may not. stop() detaches the delegate and lets
an already-sent command finish updating storage. active() reports whether
the interaction still observes the request. Pending work for the same scoped
peer can cause CHIP_ERROR_BUSY even after observation stops.
3.3. Commissioner features
The commissioner is an enhanced controller that can perform commissioning which is the sequence of operations to bring a Node into a Fabric by assigning an Operational Node ID and Node Operational credentials.
The commissioner should support the additional features:
Obtain the onboarding payload (QR code or manual code) and use it to starting commissioning.
Verify the commissionee’s Device Attestation Certificate (DAC) chain and Certificate Declaration (CD) during commissioning.
Receive the Certificate Signing Request (CSR) and issue NOC for it during commissioning.
3.3.1. Pairing commands
Enable CONFIG_ESP_MATTER_COMMISSIONER_ENABLE and connect the controller to
its operational IP network before pairing. Supply a QR payload or manual setup
code. The SDK chooses the discovery transport by default; forcing BLE requires
CONFIG_ENABLE_ESP32_BLE_CONTROLLER.
Supplying a resolved address skips discovery. Link-local IPv6 addresses require
an address scope or --interface. Optional Wi-Fi and Thread credentials
provision the device network independently of transport selection.
matter esp controller pair <node> <setup-code> [--transport auto|ble|on-network] [--wifi SSID PASSWORD] [--thread HEX]
matter esp controller pair <node> --address IP --pin PIN [--port N] [--interface NAME]
matter esp controller unpair <node>
UDC pairing requires commissioner discovery. It uses the peer address from a pending UDC entry; supply the node ID and setup PIN. Successful request submission consumes the entry. An inactive entry expires after 30 seconds.
matter esp controller pair udc status
matter esp controller pair udc <node> <pin>
3.3.2. Attestation Verification
3.3.2.1. Attestation Trust Storage
The commissioner offers four options for the Attestation Trust Storage which is used to store and utilize the PAA certificates for the Device Attestation verification. This feature is available when the Enable matter commissioner option is enabled in menuconfig. You can modify this setting in menuconfig Components -> ESP Matter Controller -> Attestation Trust Store.
Attestation Trust Store - TestUse two hardcoded PAA certificates (Chip-Test-PAA-FFF1-Cert&Chip-Test-PAA-NoVID-Cert) in the firmware.
Attestation Trust Store - SPIFFSRead the PAA root certificates from the SPIFFS partition. Please refer to the SPIFFS FileSystem to configure the SPIFFS partition and directory. After this, please configure the partition label in menuconfig
Components->ESP Matter Controller->SPIFFS Attestation Trust Store Partition Label.Attestation Trust Store - DCLRead the PAA root certificates from the DCL(Distributed Compliance Ledger). You can choose to use MainNet or TestNet by calling
chip::Credentials::dcl_attestation_trust_store::get_instance().SetDCLNetType().Attestation Trust Store - CustomRead the PAA root certificates with the custom method. You should call
chip::Credentials::set_custom_attestation_trust_store()beforeesp_matter::controller::matter_controller_client::setup_commissioner()to set the custom attestation trust store.
3.3.2.2. Revoked DAC Chain Check
The commissioner can check whether the DAC chain on the commissionee is revoked during commissioning. This feature is available when the Enable matter commissioner option is enabled in menuconfig. You can configure the DAC Revocation Delegate in menuconfig Components -> ESP Matter Controller -> Check for Revoked DAC Chain.
Revoked DAC Chain Check - NoneNone check for revoked DAC chain.Revoked DAC Chain Check - DCL Revocation PointsCheck the Revoked DAC chain with the revocation points on DCL. The controller will fetch revocation points from DCL. You can choose to use MainNet or TestNet by callingchip::Credentials::dcl_revocation_point_da_revocation_delegate::get_instance().set_dcl_net_type().Revoked DAC Chain Check - CustomCheck the Revoked DAC chain with the custom method. You should callchip::Credentials::set_custom_dac_revocation_delegate()beforeesp_matter::controller::matter_controller_client::setup_commissioner()to set the custom DAC revocation delegate.
3.3.3. Certification Declaration Verification
The commissoner can commission a device that is not certified and using test CD signed by Test CD signing Cert. This feature is available when the Enable matter commissioner option is enabled in menuconfig. You can modify this setting in menuconfig Components -> ESP Matter Controller -> Support Test Certification Declaration. If the option is not enable, only certified device can be commissioned by the commissioner.
3.3.4. NOC Issuer
In the esp_matter commissioner example, the commissioner offers two options to issue the NOC chains for itself and other operational nodes.
Operational Credentials Issuer - TestGenerate Root CA Certificate (RCAC) and RCAC Private Key and issue a Commissioner NOC when setting up the commissioner, and then issue NOCs for other nodes during commissioning with the generated RCAC Certificate and Key.
Operational Credentials Issuer - CustomObtain the NOC chains for the commissioner and other operational nodes with a custom issuer class. The NOC chains can be issued from the cloud with the custom issuer.
3.4. Production Considerations
3.4.1. Controller Production
The Matter Controller should always work with a commissioner which is typically a mobile application that assists with its setup and onboarding.
3.4.1.1. Access Control Privilege
The controller should possess either Administrator or Operator privileges in order to access other nodes within the same Matter fabric. A common approach is to issue a NOC containing an Administrator/Operator CAT for the controller, and to initialize the Access Control List (ACL) of Matter end devices with the corresponding CATs.
3.4.1.2. Controller NOC
To access other nodes within a Matter fabric, the controller must be part of the same fabric. Therefore, there must be a mechanism to deliver the NOC chain to the controller. Upon receiving the chain, the controller can add or update it in its Fabric Table.
3.4.1.3. Device List
The controller should be able to retrieve the list of devices within the same Matter fabric. This list should include the Node IDs and device type information of each node, enabling the controller to determine how to interact with and control the respective Matter end devices.
3.4.2. Commissioner Production
3.4.2.1. Onboarding Payload
The Matter Commissioner should be able to get the QR Code or Manual Code of Matter end-device so that it can start commissioning that device.
3.4.2.2. Device Attestation Verification
The Matter Commissioner should be able to process the following DA verification during commissioning:
Verify that the DAC chain of the commissionee is issued by a trusted Product Attestation Authority (PAA) Certificate in the Connectivity Standards Alliance (CSA) ’s Distributed Compliance Ledger(DCL).
Verify that the CD of the commissionee is issued by CSA.
Verify that the DAC or PAI Certificate is not revoked in CSA’s DCL.
3.4.2.3. NOC Issuer
The Matter Commissioner should be able to install NOC chain on the commissionee during commissioning. The custom NOC issuer should be implemented so that the Matter Commissioner could generate or otherwise obtain NOC chain after receiving CSRResponse command from the commissionee. In production, the NOC issuer is typically a cloud service: the Commissioner retrieves the CSR from the commissionee and forwards it to the cloud service for signing. The local RCAC is intended for testing only and must not be used in production.
3.4.2.4. Access Control List Configuration
The Matter Commissioner should configure the ACL on the Commissionee over PASE session to grant Administer/Operator privilege over CASE authentication type for all the controllers in the Matter fabric.
3.5. Commissioning operation APIs
Include esp_matter_controller_pairing_command.h for
esp_matter::controller::pairing, or
esp_matter_controller_commissioning_window_opener.h for
esp_matter::controller::commissioning_window.
Keep each caller-owned operation and its delegate alive until completion or
stop(). Call APIs, inspect state, and destroy active operations in CHIP
context or while holding the CHIP stack lock. start() copies any request
data it retains before returning. A synchronous rejection produces no callbacks.
3.5.1. Pairing
Pairing defaults to method_t::setup_code. Set
request_t::params.setup_code.payload to a manual code or MT: QR payload.
For a resolved address, call request.set_address({peer_address, setup_pin})
to select method_t::address and initialize its union member.
Wi-Fi and Thread credentials are independent chip::Optional values used to
provision the device network, not to choose a discovery transport. An empty
Wi-Fi password selects an open network. A present but empty Thread dataset is
invalid.
Choose the discovery and PASE transport with
request_t::params.setup_code.transport:
transport_t::automaticis the default. The SDK discovers the device using payload capabilities, including on-network fallback.transport_t::bleuses the payload PIN and discriminator over BLE, regardless of advertised transport flags. It requiresCONFIG_ENABLE_ESP32_BLE_CONTROLLERand rejects compound QR payloads withCHIP_ERROR_INVALID_ARGUMENT.transport_t::on_networkuses IP discovery regardless of payload BLE flags.
Forced transports do not fall back to another transport. Payload validation, authentication, and the configured attestation policy still apply. Operational Matter connections use IP.
namespace pairing = esp_matter::controller::pairing;
pairing::interaction operation;
pairing::request_t request;
request.node_id = node_id;
request.params.setup_code.payload = setup_code;
CHIP_ERROR error = operation.start(request, pairing::options_t(), &delegate);
OnProgress() and OnCommissioningStage() forward SDK progress. Callbacks
may run before start() or cancel() returns, so initialize any state they
access before either call. Once the operation accepts a request, it reports SDK
errors through OnDone(), including errors encountered during start().
Completion means commissioning has finished, not just PASE establishment.
The result contains the node, error, last observed work phase, and SDK commissioning failure details when available. Result references and pointers are valid only during the callback. Do not start, cancel, stop, or destroy a pairing operation from a delegate callback.
A commissioner allows one pairing reservation at a time, including cancellation
cleanup. options_t::timeout_ms defaults to 300000 ms and must be nonzero.
Expiry initiates cancellation. cancel() retains the delegate and reports
CHIP_ERROR_CANCELLED after cleanup. stop() detaches the delegate
immediately, but holds the commissioner reservation until cleanup finishes.
Starts during cleanup return CHIP_ERROR_BUSY. Neither cancellation nor stop
rolls back remote changes.
If the SDK reports a discovery or PASE failure only through a status update,
the operation cancels and reports CHIP_ERROR_CONNECTION_ABORTED without
waiting for the overall timeout. A later, more specific PASE error may be
unavailable.
options_t::register_icd enables ICD registration by default. Each operation
generates its own registration key and persists the completed registration.
3.5.2. Commissioning windows
Choose method_t::basic, method_t::passcode, or method_t::verifier and
set an explicit chip::ScopedNodeId destination. The operation does not look
up an application or console fabric. Passcode requests generate a PIN and salt
when omitted, but reject supplied values that are invalid. Basic windows require
target support for Basic Commissioning.
namespace window = esp_matter::controller::commissioning_window;
window::interaction operation;
window::request_t request(window::method_t::passcode);
request.node = chip::ScopedNodeId(node_id, fabric_index);
request.window_timeout_seconds = 180;
request.params.passcode.discriminator = discriminator;
request.params.passcode.iterations = 10000;
CHIP_ERROR error = operation.start(request, &delegate);
OnResponse() reports remote status and includes the setup payload after a
successful passcode-based opening. OnDone() reports transport or remote
rejection errors. Callbacks run after submission returns. OnDone() may
restart, stop, or destroy the operation; OnResponse() may not.
Each object allows one pending request. Separate objects may operate
concurrently. active() reports local request state, not whether the remote
window is open. stop() does not close an already-open window, and a timeout
does not rule out remote execution.
3.5.3. Unpairing
Call matter_controller_client::unpair(node, callback) to unpair a node. On
success, it removes the peer’s ICD registration before calling the application
callback.
3.6. Client interactions
esp_matter provides the generic interaction APIs. Include
esp_matter_client.h and use the invoke_command, read_command,
write_command, and subscribe_command namespaces under esp_matter::client.
Keep each caller-owned operation and its delegate alive until completion or
stop().
3.6.2. Ownership and callbacks
start() copies path spans and encodes values and command fields before
returning. A synchronous error rejects the request and schedules
no delegate callbacks.
Invoke and Write require an explicit delegate pointer. Pass nullptr to log
asynchronous failures and discard successful responses, or pass a delegate
address to receive callbacks. Read and Subscribe require a delegate. TLV readers
are borrowed only for the callback duration.
Starting another Invoke, Read, or Write releases completed state. An active
operation rejects restart with CHIP_ERROR_INCORRECT_STATE for Invoke or
CHIP_ERROR_BUSY for Read and Write. stop() synchronously detaches the
delegate and prevents later callbacks. Repeated calls are safe, but stopping
cannot undo work already sent to the network.
Invoke, Read, and Write allow stop, destruction, and reuse in terminal
OnDone() callbacks. Do not perform these actions in report, response, or
subscription callbacks. Subscription states are connecting, active,
backoff, and terminated. Call retry_now() only during automatic
resubscription backoff.
3.6.3. Invoke and JSON fields
An Invoke request with fields == nullptr encodes an empty command structure.
client::json_encodable encodes exactly one tagged JSON value, whether a
scalar, an OBJ structure, or an ARR-* array. The encoder replaces the
outer JSON tag with the tag supplied by the interaction. Invoke fields must be
an OBJ value. Use {"0:OBJ":{}} for empty fields. The temporary TLV
buffer is limited to chip::kMaxAppMessageLen. For example:
client::json_encodable fields(R"({"0:OBJ":{"0:U8":2}})");
client::invoke_command::request_t request = {
.endpoint_id = 1,
.cluster_id = 6,
.command_id = 1,
.fields = &fields,
};
CHIP_ERROR err = invoke.start(target, request, &delegate);
The JSON text need only remain valid through start().
Group Invoke does not support timed or response-timeout options. Its
OnDone(CHIP_NO_ERROR) callback means the Interaction Model accepted the
groupcast. It does not confirm that group members received it. Group Invoke
does not call OnResponse().
3.6.4. Read, Write, and Subscribe
Write encoders emit the complete attribute value, including any structure or
array container. client::json_encodable accepts, for example, {"0:U16":42},
{"0:OBJ":{"1:U16":42}}, or {"0:ARR-U8":[1,2]}.
Read and Subscribe requests take spans of Matter attribute and event paths and
copy them during start(). Read supports wildcard paths and is fabric-filtered
by default. Subscribe uses CHIP automatic resubscription according to its request options.
Use write.start(group_id, fabric_index, request, &delegate) for Group Write.
Group Write omits endpoints and does not support data versions, timed writes, or
chunking. OnDone() reports dispatch after start() returns. There are
no path responses or member acknowledgments.
Write always uses a span, including the one-attribute case:
client::json_encodable value("{\"0:U8\":2}");
client::write_command::attribute_write_t attribute = {
.path = chip::app::ConcreteDataAttributePath(1, 6, 0x4003),
.value = &value,
};
client::write_command::request_t request = {
.attributes = chip::Span<const client::write_command::attribute_write_t>(&attribute, 1),
};
CHIP_ERROR err = write.start(target, request, &delegate);
Write prepares all paths and values before accepting the request, then sends
it through one WriteClient. Complete lists use ReplaceAll and may use
Matter chunking for non-timed requests. A timed request that requires chunking
fails synchronously.
A multi-path Write is not atomic. Inspect every OnResponse(path, status).
Later paths may proceed after a recoverable path failure, and earlier successful
writes are not rolled back. OnDone() reports interaction completion, not
success for every path. Supply an explicit JSON value for each write, including
{"0:NULL":null} for null.
3.6.5. Binding fan-out
Server applications use client::binding::dispatcher after Binding Manager
initialization. dispatch(local_endpoint, request, delegate) accepts native
Invoke, Read, Write and Subscribe requests selecting one concrete cluster.
Requests are copied before return; bindings supply the fabric and remote endpoint.
Read and Subscribe skip group bindings. Invoke and Write accept a nullable
delegate pointer; Read and Subscribe require a delegate reference.
Native callbacks identify each destination through source. OnDone() is
per destination, not aggregate completion. Dispatches may overlap on one
dispatcher. stop() cancels all its pending dispatches and native operations
across local endpoints, detaches delegates and suppresses later callbacks.
Keep delegates alive until then. The next dispatch() or stop() releases
completed handles.
Removed bindings stop subscriptions; dispatched finite operations may finish. Fabric removal cancels affected work. New bindings apply on the next dispatch. SDK notifications may be replaced, CASE failures may produce no callback, and native start errors are logged. Returned errors do not undo dispatched work.
Call methods in CHIP context or under the stack lock. OnDone() may dispatch,
stop or destroy the dispatcher. Other callbacks may not stop or destroy it;
dispatch() returns CHIP_ERROR_INCORRECT_STATE during nonterminal native
client callbacks. Subscription state callbacks may occur during dispatch().
3.6.6. Controller console interactions
Controller commands retain the matter esp controller prefix. The supported
subscription commands are sub add attr, sub add event, sub list, and
sub remove. Removal takes <node-id> <subscription-id>, <node-id> all,
or all. Missing arguments never imply all subscriptions. sub list shows
console-owned subscriptions; removal can affect other owners. Node-specific
removal uses the active fabric, while sub remove all covers every fabric.