blob: 5d785ef15d594c1bcea3a4737d0ed71c5acee22e [file] [log] [blame] [view]
Grzegorz Ferenc4f64f502021-06-28 21:01:58 +02001# Using CLI in nRF Connect examples
Damian Królikee937e62020-12-07 15:46:30 +01002
Grzegorz Ferenc8a4f2f12021-08-16 15:53:49 +02003Some Matter examples for the development kits from Nordic Semiconductor include
4a command-line interface that allows access to application logs and
5[Zephyr shell](https://docs.zephyrproject.org/1.13.0/subsystems/shell.html).
Damian Królikee937e62020-12-07 15:46:30 +01006
Grzegorz Ferenc18377392023-03-16 13:26:34 +01007<hr>
8
Damian Królikee937e62020-12-07 15:46:30 +01009## Accessing the CLI console
10
11To access the CLI console, use a serial terminal emulator of your choice, like
12Minicom or GNU Screen. Use the baud rate set to `115200`.
13
Grzegorz Ferenc18377392023-03-16 13:26:34 +010014### Example: Starting the CLI console with Minicom
15
Damian Królikee937e62020-12-07 15:46:30 +010016For example, to start using the CLI console with Minicom, run the following
Andrei Litvina76f75e2022-04-13 08:34:42 -100017command with `/dev/ttyACM0` replaced with the device node name of your
Damian Królikee937e62020-12-07 15:46:30 +010018development kit:
19
Grzegorz Ferenc18377392023-03-16 13:26:34 +010020```
21minicom -D /dev/ttyACM0 -b 115200
22```
Damian Królikee937e62020-12-07 15:46:30 +010023
Łukasz Duda4b61b4f2021-03-04 21:44:51 +010024When you reboot the kit, you will see the boot logs in the console, similar to
Damian Królikee937e62020-12-07 15:46:30 +010025the following messages:
26
27```shell
28uart:~$
29I: nRF5 802154 radio initialized
30I: 8 Sectors of 4096 bytes
31I: alloc wra: 0, ff0
32I: data wra: 0, 0
33*** Booting Zephyr OS build v2.4.0-ncs1 ***
34I: Init CHIP stack
35...
36```
37
38This means that the console is working correctly and you can start using shell
39commands. For example, issuing the `kernel threads` command will print
40information about all running threads:
41
42```shell
43uart:~$ kernel threads
44Scheduler: 277 since last call
45Threads:
46 0x20006518 CHIP
47 options: 0x0, priority: -1 timeout: 536896912
48 state: pending
49 stack size 8192, unused 7256, usage 936 / 8192 (11 %)
50
51 0x20004ab0 SDC RX
52 options: 0x0, priority: -10 timeout: 536890152
53 state: pending
54 stack size 1024, unused 848, usage 176 / 1024 (17 %)
55...
56```
57
Grzegorz Ferenc18377392023-03-16 13:26:34 +010058<hr>
59
Damian Królikee937e62020-12-07 15:46:30 +010060## Listing all commands
61
62To list all available commands, use the Tab key, which is normally used for the
63command completion feature.
64
65Pressing the Tab key in an empty command line prints the list of available
66commands:
67
68```shell
69uart:~$
70 clear date device flash
71 help history kernel nrf_clock_control
72 ot resize shell
73```
74
75Pressing the Tab key with a command entered in the command line cycles through
76available options for the given command.
77
Grzegorz Ferenc18377392023-03-16 13:26:34 +010078<hr>
79
Damian Królikee937e62020-12-07 15:46:30 +010080## Using OpenThread commands
81
82[OpenThread commands](https://github.com/openthread/openthread/blob/master/src/cli/README.md)
Grzegorz Ferenc18377392023-03-16 13:26:34 +010083are accessible from the shell, but they must preceded by `ot`. For example:
Damian Królikee937e62020-12-07 15:46:30 +010084
85```shell
Markus Becker228b35d2023-04-24 16:15:39 +020086uart:~$ ot networkkey
Damian Królikee937e62020-12-07 15:46:30 +01008700112233445566778899aabbccddeeff
88Done
89```
Kamil Kasperczyk07c39472021-04-17 01:06:26 +020090
Grzegorz Ferenc18377392023-03-16 13:26:34 +010091<hr>
92
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +020093## Using Matter-specific commands
Kamil Kasperczyk07c39472021-04-17 01:06:26 +020094
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +020095The nRF Connect examples let you use several Matter-specific CLI commands.
Kamil Kasperczyk07c39472021-04-17 01:06:26 +020096
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +020097These commands are not available by default and to enable using them, set the
98`CONFIG_CHIP_LIB_SHELL=y` Kconfig option in the `prj.conf` file of the given
99example.
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200100
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200101Every invoked command must be preceded by the `matter` prefix.
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200102
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +0200103See the following subsections for the description of each Matter-specific
104command.
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200105
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100106### `device` command group
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200107
108Handles a group of commands that are used to manage the device. You must use
109this command together with one of the additional subcommands listed below.
110
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100111#### `factoryreset` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200112
113Performs device factory reset that is hardware reset preceded by erasing of the
Grzegorz Ferencbae3e7d2021-10-19 15:49:45 +0200114whole Matter settings stored in a non-volatile memory.
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200115
116```shell
xBill912302d2022-01-05 00:07:15 +0900117uart:~$ matter device factoryreset
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200118Performing factory reset ...
119```
120
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100121### `onboardingcodes` command group
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200122
123Handles a group of commands that are used to view information about device
xBill912302d2022-01-05 00:07:15 +0900124onboarding codes. The `onboardingcodes` command takes one required parameter for
125the rendezvous type, then an optional parameter for printing a specific type of
126onboarding code.
127
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100128The full format of the command is as follows:
xBill912302d2022-01-05 00:07:15 +0900129
130```
131onboardingcodes none|softap|ble|onnetwork [qrcode|qrcodeurl|manualpairingcode]
132```
133
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100134#### `none` subcommand
135
136Prints all onboarding codes. For example:
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200137
138```shell
xBill912302d2022-01-05 00:07:15 +0900139uart:~$ matter onboardingcodes none
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200140QRCode: MT:W0GU2OTB00KA0648G00
Hrishikesh Dhayagude4cdecc92022-07-19 21:55:16 +0530141QRCodeUrl: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AW0GU2OTB00KA0648G00
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200142ManualPairingCode: 34970112332
143```
144
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100145#### `none qrcode` subcommand
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200146
147Prints the device
148[onboarding QR code payload](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/nrfconnect_android_commissioning.md#preparing-accessory-device).
149Takes no arguments.
150
151```shell
xBill912302d2022-01-05 00:07:15 +0900152uart:~$ matter onboardingcodes none qrcode
Damian Królik955679e2021-06-07 19:05:24 +0200153MT:W0GU2OTB00KA0648G00
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200154```
155
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100156#### `none qrcodeurl` subcommand
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200157
158Prints the URL to view the
159[device onboarding QR code](https://github.com/project-chip/connectedhomeip/blob/master/docs/guides/nrfconnect_android_commissioning.md#preparing-accessory-device)
160in a web browser. Takes no arguments.
161
162```shell
xBill912302d2022-01-05 00:07:15 +0900163uart:~$ matter onboardingcodes none qrcodeurl
Hrishikesh Dhayagude4cdecc92022-07-19 21:55:16 +0530164https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3AW0GU2OTB00KA0648G00
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200165```
166
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100167#### `none manualpairingcode` subcommand
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200168
169Prints the pairing code for the manual onboarding of a device. Takes no
170arguments.
171
172```shell
xBill912302d2022-01-05 00:07:15 +0900173uart:~$ matter onboardingcodes none manualpairingcode
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +020017434970112332
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200175```
176
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100177### `config` command group
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200178
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200179Handles a group of commands that are used to view device configuration
180information. You can use this command without any subcommand to print all
181available configuration data or to add a specific subcommand.
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200182
183```shell
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100184uart:~$ matter config
C Freeman482e6fd2022-02-09 15:50:07 -0500185VendorId: 65521 (0xFFF1)
186ProductId: 32768 (0x8000)
Markus Beckerec95ba72021-11-25 15:25:51 +0100187HardwareVersion: 1 (0x1)
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200188FabricId:
189PinCode: 020202021
190Discriminator: f00
191DeviceId:
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200192```
193
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200194The `config` command can also take the subcommands listed below.
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200195
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100196#### `pincode` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200197
198Prints the PIN code for device setup. Takes no arguments.
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200199
200```shell
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200201uart:~$ matter config pincode
202020202021
203```
204
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100205#### `discriminator` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200206
207Prints the device setup discriminator. Takes no arguments.
208
209```shell
210uart:~$ matter config discriminator
211f00
212```
213
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100214#### `vendorid` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200215
216Prints the vendor ID of the device. Takes no arguments.
217
218```shell
219uart:~$ matter config vendorid
C Freeman482e6fd2022-02-09 15:50:07 -050022065521 (0xFFFF1)
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200221```
222
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100223#### `productid` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200224
225Prints the product ID of the device. Takes no arguments.
226
227```shell
228uart:~$ matter config productid
C Freeman482e6fd2022-02-09 15:50:07 -050022932768 (0x8000)
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200230```
231
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100232#### `hardwarever` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200233
Markus Beckerec95ba72021-11-25 15:25:51 +0100234Prints the hardware version of the device. Takes no arguments.
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200235
236```shell
Markus Beckerec95ba72021-11-25 15:25:51 +0100237uart:~$ matter config hardwarever
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +02002381 (0x1)
239```
240
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100241#### `deviceid` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200242
243Prints the device identifier. Takes no arguments.
244
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100245#### `fabricid` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200246
247Prints the fabric identifier. Takes no arguments.
248
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100249### `ble` command group
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200250
251Handles a group of commands that are used to control the device Bluetooth LE
252transport state. You must use this command together with one of the additional
253subcommands listed below.
254
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100255#### `help` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200256
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100257Prints help information about the `ble` command group.
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200258
259```shell
260uart:~$ matter ble help
261 help Usage: ble <subcommand>
262 adv Enable or disable advertisement. Usage: ble adv <start|stop|state>
263```
264
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100265#### `adv start` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200266
267Enables Bluetooth LE advertising.
268
269```shell
270uart:~$ matter ble adv start
271Starting BLE advertising
272```
273
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100274#### `adv stop` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200275
276Disables Bluetooth LE advertising.
277
278```shell
279uart:~$ matter ble adv stop
280Stopping BLE advertising
281```
282
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100283#### `adv status` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200284
285Prints the information about the current Bluetooth LE advertising status.
286
287```shell
288uart:~$ matter ble adv state
289BLE advertising is disabled
290
291```
292
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100293### `nfc` command group
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200294
295Handles a group of commands that are used to control the device NFC tag
296emulation state. You must use this command together with one of the additional
297subcommands listed below.
298
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100299#### `start` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200300
301Starts the NFC tag emulation.
302
303```shell
304uart:~$ matter nfc start
305NFC tag emulation started
306```
307
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100308#### `stop` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200309
310Stops the NFC tag emulation.
311
312```shell
313uart:~$ matter nfc stop
314NFC tag emulation stopped
315```
316
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100317#### `state` subcommand
Kamil Kasperczyk2f0c6912021-06-25 00:33:52 +0200318
319Prints the information about the NFC tag emulation status.
320
321```shell
322uart:~$ matter nfc state
323NFC tag emulation is disabled
Kamil Kasperczyk07c39472021-04-17 01:06:26 +0200324```
Kamil Kasperczyk13888a62021-07-13 11:15:30 +0200325
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100326### `dns` command group
Kamil Kasperczyk13888a62021-07-13 11:15:30 +0200327
328Handles a group of commands that are used to trigger performing DNS queries. You
329must use this command together with one of the additional subcommands listed
330below.
331
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100332#### `browse` subcommand
Kamil Kasperczyk13888a62021-07-13 11:15:30 +0200333
334Browses for DNS services of `_matterc_udp` type and prints the received
335response. Takes no argument.
336
337```shell
338uart:~$ matter dns browse
339Browsing ...
340DNS browse succeeded:
341 Hostname: 0E824F0CA6DE309C
342 Vendor ID: 9050
343 Product ID: 20043
344 Long discriminator: 3840
345 Device type: 0
346 Device name:
347 Commissioning mode: 0
348 IP addresses:
349 fd08:b65e:db8e:f9c7:2cc2:2043:1366:3b31
350```
351
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100352#### `resolve` subcommand
Kamil Kasperczyk13888a62021-07-13 11:15:30 +0200353
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100354Resolves the specified Matter node service given by the _fabric-id_ and
355_node-id_.
Kamil Kasperczyk13888a62021-07-13 11:15:30 +0200356
357```shell
Grzegorz Ferenc18377392023-03-16 13:26:34 +0100358uart:~$ matter dns resolve fabric-id node-id
Kamil Kasperczyk13888a62021-07-13 11:15:30 +0200359Resolving ...
360DNS resolve for 000000014A77CBB3-0000000000BC5C01 succeeded:
361 IP address: fd08:b65e:db8e:f9c7:8052:1a8e:4dd4:e1f3
Aron Rosenbergf4a6b282021-07-16 14:03:30 -0700362 Port: 5540
Kamil Kasperczyk13888a62021-07-13 11:15:30 +0200363```