Artur Tynecki | 0efd318 | 2022-12-05 20:18:32 +0100 | [diff] [blame] | 1 | # Commissioning Open IoT SDK devices |
| 2 | |
| 3 | Matter devices based on Open IoT SDK reset into a ready for commissioning state. |
| 4 | This allows a controller to connect to them and set configuration options before |
| 5 | the device becomes available on the Matter network. |
| 6 | |
| 7 | Open IoT SDK Matter devices, due to the connectivity setup, start already |
| 8 | connected to the IP network and do not require credentials provisioning. |
| 9 | |
Artur Tynecki | 44c7faf | 2023-05-22 17:30:49 +0200 | [diff] [blame] | 10 | ## Building Matter controller |
Artur Tynecki | 0efd318 | 2022-12-05 20:18:32 +0100 | [diff] [blame] | 11 | |
Artur Tynecki | 44c7faf | 2023-05-22 17:30:49 +0200 | [diff] [blame] | 12 | The [Matter controller](../../src/controller/README.md) is a client application |
| 13 | that allows commission and control of the Matter node. |
| 14 | |
| 15 | The [POSIX CLI chip-tool](../../examples/chip-tool/README.md) is the recommended |
| 16 | Matter controller to use with Open IoT SDK devices. |
| 17 | |
| 18 | To build `chip-tool` execute command: |
| 19 | |
| 20 | ``` |
| 21 | scripts/examples/gn_build_example.sh examples/chip-tool out/chip-tool |
| 22 | ``` |
Artur Tynecki | 0efd318 | 2022-12-05 20:18:32 +0100 | [diff] [blame] | 23 | |
| 24 | ## Device commissioning |
| 25 | |
Artur Tynecki | 44c7faf | 2023-05-22 17:30:49 +0200 | [diff] [blame] | 26 | Open IoT SDK examples require to setup a specific |
| 27 | [network environment](./openiotsdk_examples.md#networking-setup): |
| 28 | |
| 29 | ``` |
| 30 | export TEST_NETWORK_NAME=OIStest |
| 31 | sudo ${MATTER_ROOT}/scripts/setup/openiotsdk/network_setup.sh -n $TEST_NETWORK_NAME restart |
| 32 | ``` |
| 33 | |
| 34 | Both the device application and the controller should be started in a separate |
| 35 | terminal sessions and inside the created network namespace. Use the |
| 36 | `{MATTER_ROOT}/scripts/examples/scripts/run_in_ns.sh` helper script to execute |
| 37 | the specific shell command inside the network namespace. |
| 38 | |
| 39 | Run the application in `device terminal` and use the network namespace: |
| 40 | |
| 41 | ``` |
| 42 | ${MATTER_ROOT}/scripts/examples/scripts/run_in_ns.sh ${TEST_NETWORK_NAME}ns |
| 43 | ${MATTER_ROOT}/scripts/examples/openiotsdk_example.sh -C run -n ${TEST_NETWORK_NAME}tap |
| 44 | <example name> |
| 45 | ``` |
Artur Tynecki | 0efd318 | 2022-12-05 20:18:32 +0100 | [diff] [blame] | 46 | |
| 47 | After the device boots, it's in ready for commissioning mode and starts the mDNS |
Artur Tynecki | 44c7faf | 2023-05-22 17:30:49 +0200 | [diff] [blame] | 48 | advertisement. |
| 49 | |
| 50 | To commission the node in `client terminal` run Matter controller in the same |
| 51 | network namespace with pairing command: |
Artur Tynecki | 0efd318 | 2022-12-05 20:18:32 +0100 | [diff] [blame] | 52 | |
| 53 | ``` |
Artur Tynecki | 44c7faf | 2023-05-22 17:30:49 +0200 | [diff] [blame] | 54 | ${MATTER_ROOT}/scripts/run_in_ns.sh ${TEST_NETWORK_NAME}ns ./out/chip-tool/chip-tool pairing onnetwork-long <node_id> <pin_code> <discriminator> |
Artur Tynecki | 0efd318 | 2022-12-05 20:18:32 +0100 | [diff] [blame] | 55 | ``` |
| 56 | |
Artur Tynecki | 44c7faf | 2023-05-22 17:30:49 +0200 | [diff] [blame] | 57 | The `node_id` is chosen by the user. `pin_code` and `discriminator` are node |
| 58 | parameters printed when running the application in the `device terminal`. |
Artur Tynecki | 0efd318 | 2022-12-05 20:18:32 +0100 | [diff] [blame] | 59 | |
| 60 | Example: |
| 61 | |
Artur Tynecki | 44c7faf | 2023-05-22 17:30:49 +0200 | [diff] [blame] | 62 | ``` |
| 63 | ${MATTER_ROOT}/scripts/run_in_ns.sh ${TEST_NETWORK_NAME}ns ./out/chip-tool/chip-tool pairing onnetwork-long 123 20202021 3840 |
| 64 | ``` |
| 65 | |
| 66 | The application output a trace when commissioning succeeds. This trace is |
| 67 | displayed in the `device terminal`: |
| 68 | |
| 69 | ``` |
| 70 | [INF] [SVR] Commissioning completed successfully |
| 71 | ``` |
| 72 | |
| 73 | ## Sending ZCL cluster commands |
| 74 | |
| 75 | Before sending cluster commands [commission](#device-commissioning) the device. |
| 76 | |
| 77 | To perform cluster action, run the Matter controller in the `client terminal` |
| 78 | and use the same network namespace: |
| 79 | |
| 80 | ``` |
| 81 | ${MATTER_ROOT}/scripts/run_in_ns.sh ${TEST_NETWORK_NAME}ns ./out/chip-tool/chip-tool <cluster_name> <command_name> [param1 param2 ...] |
| 82 | ``` |
| 83 | |
| 84 | Example: |
| 85 | |
| 86 | ``` |
| 87 | ${MATTER_ROOT}/scripts/run_in_ns.sh ${TEST_NETWORK_NAME}ns ./out/chip-tool/chip-tool basicinformation read vendor-id 123 0 |
| 88 | ``` |