Working with the CHIP Tool

The CHIP Tool (chip-tool) is a Matter controller implementation that allows to commission a Matter device into the network and to communicate with it using Matter messages, which may encode Data Model actions, such as cluster commands.

The tool also provides other utilities specific to Matter, such as parsing of the setup payload or performing discovery actions.

Source files

You can find source files of the CHIP Tool in the examples/chip-tool directory.

Note: The CHIP Tool caches the configuration state in the /tmp/chip_tool_config.ini file. Deleting this and other .ini files in the /tmp directory can sometimes resolve issues related to stale configuration.

Building and running the CHIP Tool

Before you can use the CHIP Tool, you must compile it from source on Linux (amd64/aarch64) or macOS. If you want to run it on Raspberry Pi, it must use a 64-bit OS.

Note: To ensure compatibility, always build the CHIP Tool and the Matter device from the same revision of the connectedhomeip repository.

Building the CHIP Tool

To build and run the CHIP Tool:

1. Install all required packages for Matter and prepare the source code and the build system. Read the Building Matter guide for instructions.

2. Open a command prompt in the connectedhomeip directory.

3. Run the following command:

   ./scripts/examples/gn_build_example.sh examples/chip-tool BUILD_PATH
   

   In this command, BUILD_PATH specifies where the target binaries are to be placed.

Running the CHIP Tool

To check if the CHIP Tool runs correctly, execute the following command from the BUILD_PATH directory:

$ ./chip-tool

As a result, the CHIP Tool starts in the default single-command mode and prints all available commands. These are called clusters in this context, but not all listed commands correspond to the clusters in the Data Model (for example, pairing or discover commands). Each listed command can however become the root of the new more complex command by appending it with sub-commands. Examples of specific commands and their use cases are described in the Supported commands and options section.

CHIP Tool modes

The CHIP Tool can run in one of the following modes:

Single-command mode (default)

In this mode, the CHIP Tool will exit with a timeout error if any single command does not complete within a certain timeout period.

The timeout error will look similar to the following one:

[1650992689511] [32397:1415601] CHIP: [TOO] Run command failure: ../../../examples/chip-tool/commands/common/CHIPCommand.cpp:392: CHIP Error 0x00000032: Timeout

Moreover, when using the single-command mode, the CHIP Tool will establish a new CASE session with every command sent.

Modifying timeout duration in single-command mode

This timeout can be modified for any command execution by supplying the optional --timeout parameter, which takes a value in seconds, with the maximum being 65535 seconds.

Example of command:

$ ./chip-tool otasoftwareupdaterequestor subscribe-event state-transition 5 10 0x1234567890 0 --timeout 65535

Interactive mode

In this mode, a command will terminate with an error if it does not complete within the timeout period. However, the CHIP Tool will not be terminated and it will not terminate processes that previous commands have started. Moreover, when using the interactive mode, the CHIP Tool will establish a new CASE session only when there is no session available yet. On the following commands, it will use the existing session.

Starting the interactive mode

For commands such as event subscriptions that need to run for an extended period of time, the CHIP Tool can be started in interactive mode first before running the command.

To start the interactive mode, run the following command:

$ ./chip-tool interactive start

In this mode, you can subscribe to events or attributes. For detailed steps, see Subscribing to events or attributes.

Using CHIP Tool for Matter device testing

The following steps depend on the application clusters that you implemented on the device.

The steps are using the Matter Lighting Application Example with the Bluetooth LE commissioning method support. You can use other Matter examples and still follow this procedure. If you use a different example, the Step 7 may vary depending on the clusters implemented in your application.

Step 1: Prepare the Matter device

Build and program the device with the Matter device firmware by following the Matter Lighting Application Example documentation.

Step 2: Enable Bluetooth LE advertising on Matter device

Some examples are configured to advertise automatically on boot. Other examples require physical trigger, for example pushing a button. Follow the documentation of the Matter device example for the chosen platform to learn how Bluetooth LE advertising is enabled for the given example.

Step 3: Set up the IP network

To follow the next steps, the IP network must be up and running. For instance, the Thread network can be established using OpenThread Border Router.

Step 4: Determine network pairing credentials

You must provide the CHIP Tool with network credentials that will be used in the device commissioning procedure to configure the device with a network interface, such as Thread or Wi-Fi.

The Matter specification does not define the preferred way of how the network credentials are to be obtained by controller. In this guide, we are going to provide steps for obtaining Thread and Wi-Fi network credentials.

Obtaining Thread network credentials

Fetch and store the current Active Operational Dataset from the Thread Border Router. This step may vary depending on the Thread Border Router implementation.

If you are using OpenThread Border Router (OTBR), retrieve this information using one of the following commands:

• For OTBR running in Docker:

  sudo docker exec -it otbr sh -c "sudo ot-ctl dataset active -x"
  0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8
  Done
  

• For OTBR native installation:

  sudo ot-ctl dataset active -x
  0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8
  Done
  

For Thread, you might also use a different out-of-band method to fetch the network credentials.

Obtaining Wi-Fi network credentials

You must get the following Wi-Fi network credentials to commission the Matter device to the Wi-Fi network:

• Wi-Fi SSID
• Wi-Fi password

The steps required to determine the SSID and password may vary depending on the setup. For instance, you might need to contact your local Wi-Fi network administrator.

Step 5: Determine Matter device's discriminator and setup PIN code

Matter uses the following values:

• Discriminator - A 12-bit value used to discern between multiple commissionable device advertisements.
• Setup PIN code - A 27-bit value used to authenticate the device.

You can find these values in the logging terminal of the device (for instance UART) when the device boots up. For example:

I: 254 [DL]Device Configuration:
I: 257 [DL] Serial Number: TEST_SN
I: 260 [DL] Vendor Id: 65521 (0xFFF1)
I: 263 [DL] Product Id: 32768 (0x8000)
I: 267 [DL] Hardware Version: 1
I: 270 [DL] Setup Pin Code: 20202021
I: 273 [DL] Setup Discriminator: 3840 (0xF00)
I: 278 [DL] Manufacturing Date: (not set)
I: 281 [DL] Device Type: 65535 (0xFFFF)

In this printout, the discriminator is 3840 (0xF00) and the setup PIN code is 20202021.

Step 6: Commission Matter device into an existing IP network

Before communicating with the Matter device, first it must join an existing IP network.

Matter devices can use different commissioning channels:

• Devices that are not yet connected to the target IP network use Bluetooth LE as the commissioning channel.
• Devices that have already joined an IP network only need to use the IP protocol for commissioning to the Matter network.

Commissioning over Bluetooth LE

In this case, your device can join the existing IP network over Bluetooth LE and then be commissioned into a Matter network.

Different scenarios are available for Thread and Wi-Fi networks, as described in the following subsections.

After connecting the device over Bluetooth LE, the controller prints the following log:

Secure Session to Device Established

This log message means that the PASE (Password-Authenticated Session Establishment) session using SPAKE2+ protocol has been established.

Commissioning into a Thread network over Bluetooth LE

To commission the device to the existing Thread network, use the following command pattern:

$ ./chip-tool pairing ble-thread <node_id> hex:<operational_dataset> <pin_code> <discriminator>

In this command:

• <node_id> is the user-defined ID of the node being commissioned.
• <operational_dataset> is the Operational Dataset determined in the step 4.
• <pin_code> and <discriminator> are device-specific keys determined in the step 5.

Commissioning into a Wi-Fi network over Bluetooth LE

To commission the device to the existing Wi-Fi network, use the following command pattern:

$ ./chip-tool pairing ble-wifi <node_id> <ssid> <password> <pin_code> <discriminator>

In this command:

• <node_id> is the user-defined ID of the node being commissioned.
• <ssid> and <password> are credentials determined in the step 3.
• <pin_code> and <discriminator> are device-specific keys determined in the step 5.

If you prefer the hexadecimal format, use the hex: prefix. For example:

$ ./chip-tool pairing ble-wifi <node_id> hex:<ssid> hex:<password> <pin_code> <discriminator>

Note: The <node_id> can be provided as a hexadecimal value with the 0x prefix.

Commissioning into a network over IP

This option is available when the Matter device is already present in an IP network, but it has not been commissioned to a Matter network yet.

To commission the device, you can use either the setup PIN code or the setup PIN code and the discriminator, both of which you obtained in the step 5. Alternatively, you can also use a QR code payload.

Commissioning with setup PIN code

To discover devices and try to pair with one of them using the provided setup code, use the following command pattern:

$ ./chip-tool pairing onnetwork <node_id> <pin_code>

The command keeps trying devices until pairing with one of them succeeds or until it runs out of pairing possibilities. In this command:

• <node_id> is the user-defined ID of the node being commissioned.
• <pin_code> is device specific setup PIN code determined in the step 5 and used to discover the device.

Commissioning with long discriminator

To discover devices with a long discriminator and try to pair with one of them using the provided setup code, use the following command pattern:

$ ./chip-tool pairing onnetwork-long <node_id> <pin_code> <discriminator>

The command keeps trying devices until pairing with one of them succeeds or until it runs out of pairing possibilities. In this command:

• <node_id> is the user-defined ID of the node being commissioned.
• <pin_code> and <discriminator> are device specific keys determined in the step 5.

Commissioning with QR code payload or manual pairing code

Matter devices log the QR code payload and manual pairing code when they boot.

To discover devices based on the given QR code payload or manual pairing code and try to pair with one of them, use the following command pattern:

$ ./chip-tool pairing code <node_id> <qrcode_payload-or-manual_code>

The command keeps trying devices until pairing with one of them succeeds or until it runs out of pairing possibilities. In this command:

• <node_id> is the user-defined ID of the node being commissioned.
• <qrcode_payload-or-manual_code> is the QR code payload ID, for example MT:Y.K9042C00KA0648G00, or a manual pairing code like 749701123365521327694.

Forgetting the already-commissioned device

In case commissioning needs to be retested, the following command removes the device with the given node ID from the list of commissioned Matter devices:

$ ./chip-tool pairing unpair <node_id>

In this command, <node_id> is the user-defined ID of the node which is going to be forgotten by the CHIP Tool.

Step 7: Control application Data Model clusters

Having completed all previous steps, you have the Matter device successfully commissioned to the network. You can now test the device by interacting with Data Model clusters.

Example: Matter Lighting Application Example

In case of the Matter Lighting Application Example we referenced in step 1, the application implements the On/Off and Level Control clusters. This means that you can test it by toggling the bulb (using the onoff cluster commands) or by manipulating its brightness (using the levelcontrol cluster commands):

• Use the following command pattern to toggle the OnOff attribute state (e.g. visualized by the LED state):

  $ ./chip-tool onoff toggle <node_id> <endpoint_id>
  

  In this command:

  • <node_id> is the user-defined ID of the commissioned node.
  • <endpoint_id> is the ID of the endpoint with OnOff cluster implemented.

• Use the following command pattern to change the value of the CurrentLevel attribute (e.g. visualized by the LED brightness):

  $ ./chip-tool levelcontrol move-to-level <level> <transition_time> <option_mask> <option_override> <node_id> <endpoint_id>
  

  In this command:

  • <level> is the brightness level encoded between 0 and 254, unless a custom range is configured in the cluster.
  • <transition_time> is the transition time.
  • <option_mask> is the option mask.
  • <option_override> is the option override.
  • <node_id> is the user-defined ID of the commissioned node.
  • <endpoint_id> is the ID of the endpoint with LevelControl cluster implemented.

Step 8: Read basic information from the Matter device

Every Matter device supports the Basic cluster, which maintains the collection of attributes that a controller can obtain from a device. These attributes can include the vendor name, the product name, or the software version.

Use the CHIP Tool's read command on the basic cluster to read those values from the device:

$ ./chip-tool basic read vendor-name <node_id> <endpoint_id>
$ ./chip-tool basic read product-name <node_id> <endpoint_id>
$ ./chip-tool basic read software-version <node_id> <endpoint_id>

In these commands:

• <node_id> is the user-defined ID of the commissioned node.
• <endpoint_id> is the ID of the endpoint with Basic cluster implemented.

You can also use the following command to list all available commands for Basic cluster:

$ ./chip-tool basic

Supported commands and options

This section contains a general list of various CHIP Tool commands and options, not limited to commissioning procedure and cluster interaction.

Printing all supported clusters

To print all clusters supported by the CHIP Tool, run the following command:

$ ./chip-tool

Example of output:

[1647346057.900626][394605:394605] CHIP:TOO: Missing cluster name
Usage:
  ./chip-tool cluster_name command_name [param1 param2 ...]

  +-------------------------------------------------------------------------------------+
  | Clusters:                                                                           |
  +-------------------------------------------------------------------------------------+
  | * accesscontrol                                                                     |
  | * accountlogin                                                                      |
  | * administratorcommissioning                                                        |
  | * alarms                                                                            |
  | * any                                                                               |
  | * appliancecontrol                                                                  |
  | * applianceeventsandalert                                                           |
  | * applianceidentification                                                           |
  | * appliancestatistics                                                               |
  | * applicationbasic                                                                  |

Getting the list of commands supported for a specific cluster

To print the list of commands supported by a specific cluster, use the following command pattern:

$ ./chip-tool <cluster_name>

In this command:

• <cluster_name> is one of the available clusters (listed with chip-tool).

Example of command:

$ ./chip-tool onoff

Example of output:

[1647417645.182824][404411:404411] CHIP:TOO: Missing command name
Usage:
  ./chip-tool onoff command_name [param1 param2 ...]

  +-------------------------------------------------------------------------------------+
  | Commands:                                                                           |
  +-------------------------------------------------------------------------------------+
  | * command-by-id                                                                     |
  | * off                                                                               |
  | * on                                                                                |
  | * toggle                                                                            |
  | * off-with-effect                                                                   |
  | * on-with-recall-global-scene                                                       |
  | * on-with-timed-off                                                                 |
  | * read-by-id                                                                        |
  | * read                                                                              |
  | * write-by-id                                                                       |
  | * write                                                                             |
  | * subscribe-by-id                                                                   |
  | * subscribe                                                                         |
  | * read-event-by-id                                                                  |
  | * subscribe-event-by-id                                                             |
  +-------------------------------------------------------------------------------------+
[1647417645.183836][404411:404411] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:84: Error 0x0000002F

Getting the list of attributes supported for a specific cluster

To get the list of attributes for a specific cluster, use the following command pattern:

$ ./chip-tool <cluster_name> read

In this command:

• <cluster_name> is one of the available clusters (listed with chip-tool).

Example of command:

$ ./chip-tool onoff read

Example of output:

[1647417857.913942][404444:404444] CHIP:TOO: Missing attribute name
Usage:
  ./chip-tool onoff read attribute-name [param1 param2 ...]

  +-------------------------------------------------------------------------------------+
  | Attributes:                                                                         |
  +-------------------------------------------------------------------------------------+
  | * on-off                                                                            |
  | * global-scene-control                                                              |
  | * on-time                                                                           |
  | * off-wait-time                                                                     |
  | * start-up-on-off                                                                   |
  | * server-generated-command-list                                                     |
  | * client-generated-command-list                                                     |
  | * attribute-list                                                                    |
  | * feature-map                                                                       |
  | * cluster-revision                                                                  |
  +-------------------------------------------------------------------------------------+
[1647417857.914110][404444:404444] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:120: Error 0x0000002F

Getting the list of command options

To get the list of parameters for a specific command, use the following command pattern:

$ ./chip-tool <cluster_name> <target_command>

In this command:

• <cluster_name> is one of the available clusters (listed with chip-tool).
• <target_command> is one of the target command names.

Example of command:

$ ./chip-tool onoff on

Example of output:

[1647417976.556313][404456:404456] CHIP:TOO: InitArgs: Wrong arguments number: 0 instead of 2
Usage:
  ./chip-tool onoff on node-id/group-id endpoint-id-ignored-for-group-commands [--paa-trust-store-path] [--commissioner-name] [--trace_file] [--trace_log] [--ble-adapter] [--timedInteractionTimeoutMs] [--suppressResponse]
[1647417976.556362][404456:404456] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:135: Error 0x0000002F

Selected command options

This section lists selected options that can be used to configure the input command.

Choosing the Bluetooth adapter

To choose the Bluetooth adapter used by the CHIP Tool, use the following command pattern:

--ble-adapter <id>

In this command:

• <id> is the ID of HCI device.

Example of usage:

$ ./chip-tool pairing ble-thread 1 hex:0e080000000000010000000300001335060004001fffe002084fe76e9a8b5edaf50708fde46f999f0698e20510d47f5027a414ffeebaefa92285cc84fa030f4f70656e5468726561642d653439630102e49c0410b92f8c7fbb4f9f3e08492ee3915fbd2f0c0402a0fff8 20202021 3840 --ble-adapter 0

Using message tracing

Message tracing allows capturing CHIP Tool secure messages that can be used for test automation. The tracing uses several types of flags that control where the traces should go.

The following flags are available:

• Trace file flag:

  --trace_file <filename>
  

  Here, <filename> is the name of the file where the trace data is stored. It can be appended to a command in the following way:

  $ ./chip-tool pairing <pairing_options> --trace_file <filename>
  

• Trace log flag:

  --trace_log <onoff>
  

  Here, <onoff> is a [0/1] flag, which when set to 1 prints the trace data with automation logs to the console.

Running a test suite against a paired peer device

The CHIP Tool allows to run a set of tests, already compiled in the tool, against a paired Matter device.

• To get the list of available tests, run the following command:

  $ ./chip-tool tests
  

• To execute a particular test against the paired device, use the following command pattern:

  $ ./chip-tool tests <test_name>
  

  In this command:

  • <test_name> is the name of the particular test.

See the Examples section for an example of how to run a test from the test suite.

Parsing the setup payload

The CHIP Tool offers a utility for parsing the Matter onboarding setup payload and printing it in a readable form. For example, the payload can be printed on the device console during boot.

To parse the setup code, use the payload command with the parse-setup-payload sub-command, as in the following command pattern:

$ ./chip-tool payload parse-setup-payload <payload>

Here, <payload> is the ID of the payload to be parsed.

Examples of commands:

• Setup QR code payload:

  $ ./chip-tool payload parse-setup-payload MT:6FCJ142C00KA0648G00
  

• Manual pairing code:

  $ ./chip-tool payload parse-setup-payload 34970112332
  

Parsing additional data payload

To parse additional data payload, use the following command pattern:

$ ./chip-tool parse-additional-data-payload <payload>

In this command:

• <payload> is the ID of the payload with additional data to be parsed.

Discover actions

The discover command can be used to resolve node ID and discover available Matter devices.

Use the following command to print the available sub-commands of the discover command:

$ ./chip-tool discover

Resolving node name

To resolve the DNS-SD name corresponding with the given Node ID and update the address of the node in the device controller, use the following command pattern:

$ ./chip-tool discover resolve <node_id> <fabric_id>

In this command:

• <node_id> is the ID of node to be resolved.
• <fabric_id> is the ID of the Matter fabric to which the node belongs.

Discovering available Matter devices

To discover all Matter commissionables available in the operation area, run the following command:

$ ./chip-tool discover commissionables

Discovering available Matter commissioners

To discover all Matter commissioners available in the operation area, run the following command:

$ ./chip-tool discover commissioners

Pairing

The pairing command supports different means regarding Matter device commissioning procedure.

Thread and Wi-Fi commissioning use cases are described in the Using the CHIP Tool for Matter device testing section.

To list all pairing sub-commands, run the following command:

$ ./chip-tool pairing

Interacting with Data Model clusters

As mentioned in the Using the CHIP Tool for Matter device testing section, executing the chip-tool command with a particular cluster name lists all operations supported for this cluster, as in the following command pattern:

$ ./chip-tool <cluster_name>

Example of command:

$ ./chip-tool binding

Example of output:

[1647502596.396184][411686:411686] CHIP:TOO: Missing command name
Usage:
  ./chip-tool binding command_name [param1 param2 ...]

  +-------------------------------------------------------------------------------------+
  | Commands:                                                                           |
  +-------------------------------------------------------------------------------------+
  | * command-by-id                                                                     |
  | * read-by-id                                                                        |
  | * read                                                                              |
  | * write-by-id                                                                       |
  | * write                                                                             |
  | * subscribe-by-id                                                                   |
  | * subscribe                                                                         |
  | * read-event-by-id                                                                  |
  | * subscribe-event-by-id                                                             |
  +-------------------------------------------------------------------------------------+
[1647502596.396299][411686:411686] CHIP:TOO: Run command failure: ../../examples/chip-tool/commands/common/Commands.cpp:84: Error 0x0000002F

According to this list, the binding cluster supports operations such as read or write. Attributes from that cluster can also be subscribed by the controller, which means that the CHIP Tool will receive notifications, for instance when the attribute value is changed or a specific event happens.

Examples

This section lists examples of the CHIP Tool commands dedicated to specific use cases.

Writing ACL to the accesscontrol cluster

The Access Control List (ACL) concept allows to govern all Data Model interactions (such as read attribute, write attribute, invoke command). For more information about ACL, see Access Control Guide.

To write ACL to the accesscontrol cluster, use the following command pattern:

$ ./chip-tool accesscontrol write acl <acl_data> <node_id> <endpoint_id>

In this command:

• <acl_data> is the ACL data formatted as a JSON array.
• <node_id> is the ID of the node that is going to receive ACL.
• <endpoint_id> is the ID of the endpoint on which the accesscontrol cluster is implemented.

Adding a binding table to the binding cluster

Binding describes a relationship between the device that contains the binding cluster and the end device. The proper ACL must be added to allow the end device to receive commands from the bonded device. After the binding process, the bonded device contains information about connected device, such as IPv6 address and the route to the endpoint in the Matter network.

To add a binding table to the binding cluster, use the following command pattern:

$ ./chip-tool binding write binding  <binding_data> <node_id> <endpoint_id>

In this command:

• <binding_data> is the binding data formatted as a JSON array.
• <node_id> is the ID of the node that is going to receive the binding.
• <endpoint_id> is the ID of the endpoint on which the binding cluster is implemented.

Running TestClusters test

Complete the following steps to run one test from the test suite:

1. Clean the initialization of state using the following command:

   rm -fr /tmp/chip_*
   

2. In a shell window, start the DUT device:

   ./out/debug/standalone/chip-all-clusters-app
   

3. In a second shell window, pair the DUT with the CHIP Tool:

   ./out/debug/standalone/chip-tool pairing onnetwork 333221 20202021
   

4. Run the test with the following command:

   ./out/debug/standalone/chip-tool tests TestCluster --nodeId 333221
   

Read the CHIP Test Suits page for more information about how the test suite is structured.

Multi-admin scenario

Multi-admin feature allows you to join Matter device to several Matter fabrics and have several different Matter administrators administer it.

Complete the steps mentioned in the following sections.

Step 1: Commission to fabric

Commission the Matter device to first fabric following the Using CHIP Tool for Matter device testing section.

Step 2: Open the commissioning window

Make sure the administrator from the first fabric opens the commissioning window for a new administrator from another fabric.

Open the commissioning window on the paired Matter device by using the following command pattern:

$ ./chip-tool pairing open-commissioning-window <node_id> <option> <window_timeout> <iteration> <discriminator>

In this command:

• <node_id> is the ID of the node that should open commissioning window.
• <option> is equal to 1 for Enhanced Commissioning Method and 0 for Basic Commissioning Method.
• <window_timeout> is time in seconds, before the commissioning window closes.
• <iteration> is number of PBKDF iterations to use to derive the PAKE verifier.
• <discriminator> is device specific discriminator determined during commissioning.

Note: The <iteration> and <discriminator> values are ignored if the <option> is set to 0.

Example of command:

$ ./chip-tool pairing open-commissioning-window 1 1 300 1000 2365

Step 3: Save the pairing code

Write down the manual pairing code or the QR code payload printed in the command output, as it will be required by the second Matter admin to join Matter device to its fabric.

Example of output:

[1663675289.149337][56387:56392] CHIP:DMG: Received Command Response Status for Endpoint=0 Cluster=0x0000_003C Command=0x0000_0000 Status=0x0
[1663675289.149356][56387:56392] CHIP:CTL: Successfully opened pairing window on the device
[1663675289.149409][56387:56392] CHIP:CTL: Manual pairing code: [36281602573]
[1663675289.149445][56387:56392] CHIP:CTL: SetupQRCode: [MT:4CT91AFN00YHEE7E300]

Step 4: Commission the Matter device to a new fabric

Complete the following steps:

1. Open another instance of the CHIP Tool.

2. In the new instance of the CHIP Tool, commission the Matter device to a new fabric by using the following command pattern:

   $ ./chip-tool pairing code <payload> <node_id> --commissioner-name <commissioner_name>
   

   In this command:

   • <payload> is the the QR code payload or a manual pairing code generated by the first commissioner instance when opened commissioning window
   • <node_id> is the user-defined ID of the node being commissioned. It doesn't need to be the same ID, as for the first fabric.
   • <commissioner_name> is the name of the second fabric. Valid values are “alpha”, “beta”, “gamma”, and integers greater than or equal to 4. The default if not specified is “alpha”.

   Example of command:

   $ ./chip-tool pairing code 36281602573 1 --commissioner-name beta
   

Step 5: Test reception of commands

After completing the above steps, the Matter device should be able to receive and answer Matter commands sent in the second fabric. For example, you can use the following command pattern to toggle the OnOff attribute state on a device supporting OnOff cluster:

$ ./chip-tool onoff toggle <node_id> <endpoint_id> --commissioner-name <commissioner_name>

In this command:

• <node_id> is the user-defined ID of the commissioned node.
• <endpoint_id> is the ID of the endpoint with OnOff cluster implemented.
• <commissioner_name> is the name of the second fabric. Valid values are “alpha”, “beta”, “gamma”, and integers greater than or equal to 4. The default if not specified is “alpha”.

Example of command:

$ ./chip-tool onoff toggle 1 1 --commissioner-name beta

Subscribing to events or attributes

Subscribing to an event or an attribute lets you mirror the state of the event or the attribute as it changes in the Matter network. The list of events or attributes you can subscribe to depends on the chosen cluster.

You can have more than one subscription at any given time and subscribe to more than one attribute or event within one subscription (those attributes or events can come from different clusters). However, you cannot subscribe to both attributes and events as part of a single subscription. In other words, each subscription must be dedicated exclusively to either attributes or events.

For more information about subscriptions, see the Matter specification at chapter 8, section 5 (Subscribe Interaction).

Note: The subscription behavior will be different if you set the subscription to be sent with the parameter isUrgent set to True. See the Matter specification for more information.

Subscribing to an attribute

The following procedure will use the doorlock cluster as an example. Complete the following steps:

1. Start the CHIP Tool in interactive mode by running the following command:

   $ ./chiptool interactive start
   

   All of the commands that follow will be executed in the interactive mode (>>>).

2. Run the following command to display all the available attributes you can subscribe to for the given <cluster-name>:

   >>> <cluster-name> subscribe
   

   The list of all available attributes for the cluster will appears.

   Note: Your accessory might not support all of these attributes. You will get an error if the controller sends an unsupported attribute.

   For example, for the door lock cluster:

   >>> doorlock subscribe
   

   The following list will appear:

   +-------------------------------------------------------------------------------------+
   | Attributes:                                                                         |
   +-------------------------------------------------------------------------------------+
   | * lock-state                                                                        |
   | * lock-type                                                                         |
   | * actuator-enabled                                                                  |
   | * door-state                                                                        |
   | * door-open-events                                                                  |
   | * door-closed-events                                                                |
   | * open-period                                                                       |
   | * number-of-total-users-supported                                                   |
   | * number-of-pinusers-supported                                                      |
   | * number-of-rfidusers-supported                                                     |
   | * number-of-week-day-schedules-supported-per-user                                   |
   | * number-of-year-day-schedules-supported-per-user                                   |
   | * number-of-holiday-schedules-supported                                             |
   | * max-pincode-length                                                                |
   | * min-pincode-length                                                                |
   | * max-rfidcode-length                                                               |
   | * min-rfidcode-length                                                               |
   | * credential-rules-support                                                          |
   | * number-of-credentials-supported-per-user                                          |
   | * language                                                                          |
   | * ledsettings                                                                       |
   | * auto-relock-time                                                                  |
   | * sound-volume                                                                      |
   | * operating-mode                                                                    |
   | * supported-operating-modes                                                         |
   | * default-configuration-register                                                    |
   | * enable-local-programming                                                          |
   | * enable-one-touch-locking                                                          |
   | * enable-inside-status-led                                                          |
   | * enable-privacy-mode-button                                                        |
   | * local-programming-features                                                        |
   | * wrong-code-entry-limit                                                            |
   | * user-code-temporary-disable-time                                                  |
   | * send-pinover-the-air                                                              |
   | * require-pinfor-remote-operation                                                   |
   | * expiring-user-timeout                                                             |
   | * generated-command-list                                                            |
   | * accepted-command-list                                                             |
   | * event-list                                                                        |
   | * attribute-list                                                                    |
   | * feature-map                                                                       |
   | * cluster-revision                                                                  |
   +-------------------------------------------------------------------------------------+
   

3. Add the argument of your choice to the subscription command, using the following pattern:

   >>> <cluster-name> subscribe <argument> <min-interval> <max-interval> <node_id> <endpoint_id>
   

   In this command:

   • <cluster-name> is the name of the cluster.
   • <argument> is the name of the chosen argument.
   • <min-interval> specifies the minimum number of seconds that must elapse since the last report for the server to send a new report.
   • <max-interval> specifies the number of seconds that must elapse since the last report for the server to send a new report.
   • <node-id> is the user-defined ID of the commissioned node.
   • <endpoint_id> is the ID of the endpoint where the chosen cluster is implemented.

   For example:

   >>> doorlock subscribe lock-state 5 10 1 1
   

After this command is run, the CHIP Tool will check the state of the door lock every time it changes (for example, as a result of a button press or an external ecosystem action) and update it in its own records.

Subscribing to an event

The procedure for subscribing to an event is similar to subscribing to an attribute.

The following procedure will use the doorlock cluster as an example. Complete the following steps:

1. Start the CHIP Tool in interactive mode by running the following command:

   $ ./chiptool interactive start
   

   All of the commands that follow will be executed in the interactive mode (>>>).

2. Run the following command to display all the available events you can subscribe to for the given <cluster-name>:

   >>> <cluster-name> subscribe-event
   

   The list of all available events for the cluster will appears.

   Note: Your accessory might not support all of these events. You will get an error if the controller sends an unsupported event.

   For example, for the door lock cluster:

   >>> doorlock subscribe-event
   

   The following list will appear:

   +-------------------------------------------------------------------------------------+
   | Events:                                                                             |
   +-------------------------------------------------------------------------------------+
   | * door-lock-alarm                                                                   |
   | * door-state-change                                                                 |
   | * lock-operation                                                                    |
   | * lock-operation-error                                                              |
   | * lock-user-change                                                                  |
   +-------------------------------------------------------------------------------------+
   

3. Add the event of your choice to the subscription command, using the following pattern:

   >>> <cluster-name> subscribe-event <event-name> <min-interval> <max-interval> <node_id> <endpoint_id>
   

   In this command:

   • <cluster-name> is the name of the cluster.
   • <event-name> is the name of the chosen event.
   • <min-interval> specifies the minimum number of seconds that must elapse since the last report for the server to send a new report.
   • <max-interval> specifies the number of seconds that must elapse since the last report for the server to send a new report.
   • <node_id> is the user-defined ID of the commissioned node.
   • <endpoint_id> is the ID of the endpoint where the chosen cluster is implemented.

   For example:

   >>> doorlock subscribe-event door-lock-alarm 5 10 1 1
   

After this command is run, the CHIP Tool will check the state of the door lock every time it changes (for example, as a result of a button press or an external ecosystem action) and update it in its own records.

Subscribing using attribute ID or event ID

You can also use the following commands instead of subscribe to subscribe using the attribute ID or the event ID:

• subscribe-by-id
• subscribe-event-by-id

The steps are the same as for the subscribe or subscribe-event commands.