blob: 520cff033d611d420c5098b03d521e4b94783e4a [file] [log] [blame] [view]
Artur Tynecki0efd3182022-12-05 20:18:32 +01001# Commissioning Open IoT SDK devices
2
3Matter devices based on Open IoT SDK reset into a ready for commissioning state.
4This allows a controller to connect to them and set configuration options before
5the device becomes available on the Matter network.
6
7Open IoT SDK Matter devices, due to the connectivity setup, start already
8connected to the IP network and do not require credentials provisioning.
9
Artur Tynecki44c7faf2023-05-22 17:30:49 +020010## Building Matter controller
Artur Tynecki0efd3182022-12-05 20:18:32 +010011
Artur Tynecki44c7faf2023-05-22 17:30:49 +020012The [Matter controller](../../src/controller/README.md) is a client application
13that allows commission and control of the Matter node.
14
15The [POSIX CLI chip-tool](../../examples/chip-tool/README.md) is the recommended
16Matter controller to use with Open IoT SDK devices.
17
18To build `chip-tool` execute command:
19
20```
21scripts/examples/gn_build_example.sh examples/chip-tool out/chip-tool
22```
Artur Tynecki0efd3182022-12-05 20:18:32 +010023
24## Device commissioning
25
Artur Tynecki44c7faf2023-05-22 17:30:49 +020026Open IoT SDK examples require to setup a specific
27[network environment](./openiotsdk_examples.md#networking-setup):
28
29```
30export TEST_NETWORK_NAME=OIStest
31sudo ${MATTER_ROOT}/scripts/setup/openiotsdk/network_setup.sh -n $TEST_NETWORK_NAME restart
32```
33
34Both the device application and the controller should be started in a separate
35terminal sessions and inside the created network namespace. Use the
36`{MATTER_ROOT}/scripts/examples/scripts/run_in_ns.sh` helper script to execute
37the specific shell command inside the network namespace.
38
39Run 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 Tynecki0efd3182022-12-05 20:18:32 +010046
47After the device boots, it's in ready for commissioning mode and starts the mDNS
Artur Tynecki44c7faf2023-05-22 17:30:49 +020048advertisement.
49
50To commission the node in `client terminal` run Matter controller in the same
51network namespace with pairing command:
Artur Tynecki0efd3182022-12-05 20:18:32 +010052
53```
Artur Tynecki44c7faf2023-05-22 17:30:49 +020054${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 Tynecki0efd3182022-12-05 20:18:32 +010055```
56
Artur Tynecki44c7faf2023-05-22 17:30:49 +020057The `node_id` is chosen by the user. `pin_code` and `discriminator` are node
58parameters printed when running the application in the `device terminal`.
Artur Tynecki0efd3182022-12-05 20:18:32 +010059
60Example:
61
Artur Tynecki44c7faf2023-05-22 17:30:49 +020062```
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
66The application output a trace when commissioning succeeds. This trace is
67displayed in the `device terminal`:
68
69```
70[INF] [SVR] Commissioning completed successfully
71```
72
73## Sending ZCL cluster commands
74
75Before sending cluster commands [commission](#device-commissioning) the device.
76
77To perform cluster action, run the Matter controller in the `client terminal`
78and 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
84Example:
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```