1.. _bluetooth_mesh_shell: 2 3Bluetooth Mesh Shell 4#################### 5 6The Bluetooth mesh shell subsystem provides a set of Bluetooth mesh shell commands for the :ref:`shell_api` module. 7It allows for testing and exploring the Bluetooth mesh API through an interactive interface, without having to write an application. 8 9The Bluetooth mesh shell interface provides access to most Bluetooth mesh features, including provisioning, configuration, and message sending. 10 11Prerequisites 12************* 13 14The Bluetooth mesh shell subsystem depends on the :ref:`bluetooth_mesh_models_cfg_cli` and :ref:`bluetooth_mesh_models_health_cli` models. 15 16Application 17*********** 18 19The Bluetooth mesh shell subsystem is most easily used through the Bluetooth mesh shell application under ``tests/bluetooth/mesh_shell``. 20See :ref:`shell_api` for information on how to connect and interact with the Bluetooth mesh shell application. 21 22Basic usage 23*********** 24 25The Bluetooth mesh shell subsystem adds a single ``mesh`` command, which holds a set of sub-commands. Every time the device boots up, make sure to call ``mesh init`` before any of the other Bluetooth mesh shell commands can be called:: 26 27 uart:~$ mesh init 28 29Provisioning 30============ 31 32The mesh node must be provisioned to become part of the network. This is only necessary the first time the device boots up, as the device will remember its provisioning data between reboots. 33 34The simplest way to provision the device is through self-provisioning. To provision the device with the default network key and address ``0x0001``, execute:: 35 36 uart:~$ mesh provision 0 0x0001 37 38Since all mesh nodes use the same values for the default network key, this can be done on multiple devices, as long as they're assigned non-overlapping unicast addresses. Alternatively, to provision the device into an existing network, the unprovisioned beacon can be enabled with ``mesh pb-adv on`` or ``mesh pb-gatt on``. The beacons can be picked up by an external provisioner, which can provision the node into its network. 39 40Once the mesh node is part of a network, its transmission parameters can be controlled by the general configuration commands: 41 42* To set the destination address, call ``mesh dst <addr>``. 43* To set the network key index, call ``mesh netidx <NetIdx>``. 44* To set the application key index, call ``mesh appidx <AppIdx>``. 45 46By default, the transmission parameters are set to send messages to the provisioned address and network key. 47 48Configuration 49============= 50 51By setting the destination address to the local unicast address (``0x0001`` in the ``mesh provision`` command above), we can perform self-configuration through any of the :ref:`bluetooth_mesh_shell_cfg_cli` commands. 52 53A good first step is to read out the node's own composition data:: 54 55 uart:~$ mesh get-comp 56 57This prints a list of the composition data of the node, including a list of its model IDs. 58 59Next, since the device has no application keys by default, it's a good idea to add one:: 60 61 uart:~$ mesh app-key-add 0 0 62 63Message sending 64=============== 65 66With an application key added (see above), the mesh node's transition parameters are all valid, and the Bluetooth mesh shell can send raw mesh messages through the network. 67 68For example, to send a Generic OnOff Set message, call:: 69 70 uart:~$ mesh net-send 82020100 71 72.. note:: 73 All multibyte fields model messages are in little endian, except the opcode. 74 75The message will be sent to the current destination address, using the current network and application key indexes. As the destination address points to the local unicast address by default, the device will only send packets to itself. To change the destination address to the All Nodes broadcast address, call:: 76 77 uart:~$ mesh dst 0xffff 78 79With the destination address set to ``0xffff``, any other mesh nodes in the network with the configured network and application keys will receive and process the messages we send. 80 81.. note:: 82 To change the configuration of the device, the destination address must be set back to the local unicast address before issuing any configuration commands. 83 84Sending raw mesh packets is a good way to test model message handler implementations during development, as it can be done without having to implement the sending model. By default, only the reception of the model messages can be tested this way, as the Bluetooth mesh shell only includes the foundation models. To receive a packet in the mesh node, you have to add a model with a valid opcode handler list to the composition data in ``subsys/bluetooth/mesh/shell.c``, and print the incoming message to the shell in the handler callback. 85 86Parameter formats 87***************** 88 89The Bluetooth mesh shell commands are parsed with a variety of formats: 90 91.. list-table:: Parameter formats 92 :widths: 1 4 2 93 :header-rows: 1 94 95 * - Type 96 - Description 97 - Example 98 * - Integers 99 - The default format unless something else is specified. Can be either decimal or hexadecimal. 100 - ``1234``, ``0xabcd01234`` 101 * - Hexstrings 102 - For raw byte arrays, like UUIDs, key values and message payloads, the parameters should be formatted as an unbroken string of hexadecimal values without any prefix. 103 - ``deadbeef01234`` 104 * - Booleans 105 - Boolean values are denoted in the API documentation as ``<val: on, off>``. 106 - ``on``, ``off``, ``enabled``, ``disabled``, ``1``, ``0`` 107 108Commands 109******** 110 111The Bluetooth mesh shell implements a large set of commands. Some of the commands accept parameters, which are mentioned in brackets after the command name. For example, ``mesh lpn <value: off, on>``. Mandatory parameters are marked with angle brackets (e.g. ``<NetKeyIndex>``), and optional parameters are marked with square brackets (e.g. ``[destination address]``). 112 113The Bluetooth mesh shell commands are divided into the following groups: 114 115.. contents:: 116 :depth: 1 117 :local: 118 119.. note:: 120 Some commands depend on specific features being enabled in the compile time configuration of the application. Not all features are enabled by default. The list of available Bluetooth mesh shell commands can be shown in the shell by calling ``mesh`` without any arguments. 121 122General configuration 123===================== 124 125``mesh init`` 126------------- 127 128 Initialize the mesh. This command must be run before any other mesh command. 129 130 131``mesh reset <addr>`` 132--------------------- 133 134 reset the local mesh node to its initial unprovisioned state or reset a remote node and remove it from the network. 135 * ``addr``: address of the node to reset. 136 137 138``mesh lpn <value: off, on>`` 139----------------------------- 140 141 Enable or disable Low Power operation. Once enabled, the device will turn off its radio and start polling for friend nodes. The device will not be able to receive messages from the mesh network until the friendship has been established. 142 143 * ``value``: Sets whether Low Power operation is enabled. 144 145 146``mesh poll`` 147------------- 148 149 Perform a poll to the friend node, to receive any pending messages. Only available when LPN is enabled. 150 151 152``mesh ident`` 153-------------- 154 155 Enable the Proxy Node Identity beacon, allowing Proxy devices to connect explicitly to this device. The beacon will run for 60 seconds before the node returns to normal Proxy beacons. 156 157 158``mesh dst [destination address]`` 159---------------------------------- 160 161 Get or set the message destination address. The destination address determines where mesh packets are sent with the shell, but has no effect on modules outside the shell's control. 162 163 * ``destination address``: If present, sets the new 16-bit mesh destination address. If omitted, the current destination address is printed. 164 165 166``mesh netidx [NetIdx]`` 167------------------------ 168 169 Get or set the message network index. The network index determines which network key is used to encrypt mesh packets that are sent with the shell, but has no effect on modules outside the shell's control. The network key must already be added to the device, either through provisioning or by a Configuration Client. 170 171 * ``NetIdx``: If present, sets the new network index. If omitted, the current network index is printed. 172 173 174``mesh appidx [AppIdx]`` 175------------------------ 176 177 Get or set the message application index. The application index determines which application key is used to encrypt mesh packets that are sent with the shell, but has no effect on modules outside the shell's control. The application key must already be added to the device by a Configuration Client, and must be bound to the current network index. 178 179 * ``AppIdx``: If present, sets the new application index. If omitted, the current application index is printed. 180 181 182``mesh net-send <hex string>`` 183------------------------------ 184 185 Send a raw mesh message with the current destination address, network and application index. The message opcode must be encoded manually. 186 187 * ``hex string`` Raw hexadecimal representation of the message to send. 188 189 190Testing 191======= 192 193``mesh iv-update`` 194------------------ 195 196 Force an IV update. 197 198 199``mesh iv-update-test <value: off, on>`` 200---------------------------------------- 201 202 Set the IV update test mode. In test mode, the IV update timing requirements are bypassed. 203 204 * ``value``: Enable or disable the IV update test mode. 205 206 207``mesh rpl-clear`` 208------------------ 209 210 Clear the replay protection list, forcing the node to forget all received messages. 211 212.. warning:: 213 214 Clearing the replay protection list breaks the security mechanisms of the mesh node, making it susceptible to message replay attacks. This should never be performed in a real deployment. 215 216 217Provisioning 218============ 219 220``mesh pb-gatt <val: off, on>`` 221------------------------------- 222 223 Start or stop advertising a connectable unprovisioned beacon. The connectable unprovisioned beacon allows the mesh node to be discovered by nearby GATT based provisioners, and provisioned through the GATT bearer. 224 225 * ``val``: Enable or disable provisioning with GATT 226 227 228``mesh pb-adv <val: off, on>`` 229------------------------------ 230 231 Start or stop advertising the unprovisioned beacon. The unprovisioned beacon allows the mesh node to be discovered by nearby advertising-based provisioners, and provisioned through the advertising bearer. 232 233 * ``val``: Enable or disable provisioning with advertiser 234 235 236``mesh provision-adv <UUID> <NetKeyIndex> <addr> <AttentionDuration>`` 237---------------------------------------------------------------------- 238 239 Provision a nearby device into the mesh. The mesh node starts scanning for unprovisioned beacons with the given UUID. Once found, the unprovisioned device will be added to the mesh network with the given unicast address, and given the network key indicated by ``NetKeyIndex``. 240 241 * ``UUID``: UUID of the unprovisioned device. 242 * ``NetKeyIndex``: Index of the network key to pass to the device. 243 * ``addr``: First unicast address to assign to the unprovisioned device. The device will occupy as many addresses as it has elements, and all must be available. 244 * ``AttentionDuration``: The duration in seconds the unprovisioned device will identify itself for, if supported. See :ref:`bluetooth_mesh_models_health_srv_attention` for details. 245 246 247``mesh uuid <UUID: 1-16 hex values>`` 248------------------------------------- 249 250 Set the mesh node's UUID, used in the unprovisioned beacons. 251 252 * ``UUID``: New 128-bit UUID value. Any missing bytes will be zero. 253 254 255``mesh input-num <number>`` 256--------------------------- 257 258 Input a numeric OOB authentication value. Only valid when prompted by the shell during provisioning. The input number must match the number presented by the other participant in the provisioning. 259 260 * ``number``: Decimal authentication number. 261 262 263``mesh input-str <string>`` 264--------------------------- 265 266 Input an alphanumeric OOB authentication value. Only valid when prompted by the shell during provisioning. The input string must match the string presented by the other participant in the provisioning. 267 268 * ``string``: Unquoted alphanumeric authentication string. 269 270 271``mesh static-oob [val: 1-16 hex values]`` 272------------------------------------------ 273 274 Set or clear the static OOB authentication value. The static OOB authentication value must be set before provisioning starts to have any effect. The static OOB value must be same on both participants in the provisioning. 275 276 * ``val``: If present, indicates the new hexadecimal value of the static OOB. If omitted, the static OOB value is cleared. 277 278 279``mesh provision <NetKeyIndex> <addr> [IVIndex]`` 280------------------------------------------------- 281 282 Provision the mesh node itself. If the Configuration database is enabled, the network key must be created. Otherwise, the default key value is used. 283 284 * ``NetKeyIndex``: Index of the network key to provision. 285 * ``addr``: First unicast address to assign to the device. The device will occupy as many addresses as it has elements, and all must be available. 286 * ``IVindex``: Indicates the current network IV index. Defaults to 0 if omitted. 287 288 289``mesh beacon-listen <val: off, on>`` 290------------------------------------- 291 292 Enable or disable printing of incoming unprovisioned beacons. Allows a provisioner device to detect nearby unprovisioned devices and provision them. 293 294 * ``val``: Whether to enable the unprovisioned beacon printing. 295 296.. _bluetooth_mesh_shell_cfg_cli: 297 298Configuration Client model 299========================== 300 301The Bluetooth mesh shell module instantiates a Configuration Client model for configuring itself and other nodes in the mesh network. 302 303The Configuration Client uses the general messages parameters set by ``mesh dst`` and ``mesh netidx`` to target specific nodes. When the Bluetooth mesh shell node is provisioned, the Configuration Client model targets itself by default. When another node has been provisioned by the Bluetooth mesh shell, the Configuration Client model targets the new node. The Configuration Client always sends messages using the Device key bound to the destination address, so it will only be able to configure itself and mesh nodes it provisioned. 304 305``mesh timeout [timeout in seconds]`` 306------------------------------------- 307 308 Get and set the Config Client model timeout used during message sending. 309 310 * ``timeout in seconds``: If present, set the Config Client model timeout in seconds. If omitted, the current timeout is printed. 311 312 313``mesh get-comp [page]`` 314------------------------ 315 316 Read a composition data page. The full composition data page will be printed. If the target does not have the given page, it will return the last page before it. 317 318 * ``page``: The composition data page to request. Defaults to 0 if omitted. 319 320 321``mesh beacon [val: off, on]`` 322------------------------------ 323 324 Get or set the network beacon transmission. 325 326 * ``val``: If present, enables or disables sending of the network beacon. If omitted, the current network beacon state is printed. 327 328 329``mesh ttl [ttl: 0x00, 0x02-0x7f]`` 330----------------------------------- 331 332 Get or set the default TTL value. 333 334 * ``ttl``: If present, sets the new default TTL value. If omitted, the current default TTL value is printed. 335 336 337``mesh friend [val: off, on]`` 338------------------------------ 339 340 Get or set the Friend feature. 341 342 * ``val``: If present, enables or disables the Friend feature. If omitted, the current Friend feature state is printed: 343 344 * ``0x00``: The feature is supported, but disabled. 345 * ``0x01``: The feature is enabled. 346 * ``0x02``: The feature is not supported. 347 348 349``mesh gatt-proxy [val: off, on]`` 350---------------------------------- 351 352 Get or set the GATT Proxy feature. 353 354 * ``val``: If present, enables or disables the GATT Proxy feature. If omitted, the current GATT Proxy feature state is printed: 355 356 * ``0x00``: The feature is supported, but disabled. 357 * ``0x01``: The feature is enabled. 358 * ``0x02``: The feature is not supported. 359 360 361``mesh relay [<val: off, on> [<count: 0-7> [interval: 10-320]]]`` 362----------------------------------------------------------------- 363 364 Get or set the Relay feature and its parameters. 365 366 * ``val``: If present, enables or disables the Relay feature. If omitted, the current Relay feature state is printed: 367 368 * ``0x00``: The feature is supported, but disabled. 369 * ``0x01``: The feature is enabled. 370 * ``0x02``: The feature is not supported. 371 372 * ``count``: Sets the new relay retransmit count if ``val`` is ``on``. Ignored if ``val`` is ``off``. Defaults to ``2`` if omitted. 373 * ``interval``: Sets the new relay retransmit interval in milliseconds if ``val`` is ``on``. Ignored if ``val`` is ``off``. Defaults to ``20`` if omitted. 374 375 376``mesh net-transmit-param [<count: 0-7> <interval: 10-320>]`` 377------------------------------------------------------------- 378 379 Get or set the network transmit parameters. 380 381 * ``count``: Sets the number of additional network transmits for every sent message. 382 * ``interval``: Sets the new network retransmit interval in milliseconds. 383 384 385``mesh net-key-add <NetKeyIndex> [val]`` 386---------------------------------------- 387 388 Add a network key to the target node. Adds the key to the Configuration Database if enabled. 389 390 * ``NetKeyIndex``: The network key index to add. 391 * ``val``: If present, sets the key value as a 128-bit hexadecimal value. Any missing bytes will be zero. Only valid if the key does not already exist in the Configuration Database. If omitted, the default key value is used. 392 393 394``mesh net-key-get`` 395-------------------- 396 397 Get a list of known network key indexes. 398 399 400``mesh net-key-del <NetKeyIndex>`` 401---------------------------------------- 402 403 Delete a network key from the target node. 404 405 * ``NetKeyIndex``: The network key index to delete. 406 407 408``mesh app-key-add <NetKeyIndex> <AppKeyIndex> [val]`` 409------------------------------------------------------ 410 411 Add an application key to the target node. Adds the key to the Configuration Database if enabled. 412 413 * ``NetKeyIndex``: The network key index the application key is bound to. 414 * ``AppKeyIndex``: The application key index to add. 415 * ``val``: If present, sets the key value as a 128-bit hexadecimal value. Any missing bytes will be zero. Only valid if the key does not already exist in the Configuration Database. If omitted, the default key value is used. 416 417 418``mesh app-key-get <NetKeyIndex>`` 419---------------------------------- 420 421 Get a list of known application key indexes bound to the given network key index. 422 423 * ``NetKeyIndex``: Network key indexes to get a list of application key indexes from. 424 425 426``mesh app-key-del <NetKeyIndex> <AppKeyIndex>`` 427------------------------------------------------ 428 429 Delete an application key from the target node. 430 431 * ``NetKeyIndex``: The network key index the application key is bound to. 432 * ``AppKeyIndex``: The application key index to delete. 433 434 435``mesh mod-app-bind <addr> <AppIndex> <Model ID> [Company ID]`` 436--------------------------------------------------------------- 437 438 Bind an application key to a model. Models can only encrypt and decrypt messages sent with application keys they are bound to. 439 440 * ``addr``: Address of the element the model is on. 441 * ``AppIndex``: The application key to bind to the model. 442 * ``Model ID``: The model ID of the model to bind the key to. 443 * ``Company ID``: If present, determines the Company ID of the model. If omitted, the model is a Bluetooth SIG defined model. 444 445 446 447``mesh mod-app-unbind <addr> <AppIndex> <Model ID> [Company ID]`` 448----------------------------------------------------------------- 449 450 Unbind an application key from a model. 451 452 * ``addr``: Address of the element the model is on. 453 * ``AppIndex``: The application key to unbind from the model. 454 * ``Model ID``: The model ID of the model to unbind the key from. 455 * ``Company ID``: If present, determines the Company ID of the model. If omitted, the model is a Bluetooth SIG defined model. 456 457 458``mesh mod-app-get <elem addr> <Model ID> [Company ID]`` 459-------------------------------------------------------- 460 461 Get a list of application keys bound to a model. 462 463 * ``elem addr``: Address of the element the model is on. 464 * ``Model ID``: The model ID of the model to get the bound keys of. 465 * ``Company ID``: If present, determines the Company ID of the model. If omitted, the model is a Bluetooth SIG defined model. 466 467 468``mesh mod-pub <addr> <mod id> [cid] [<PubAddr> <AppKeyIndex> <cred: off, on> <ttl> <period> <count> <interval>]`` 469------------------------------------------------------------------------------------------------------------------ 470 471 Get or set the publication parameters of a model. If all publication parameters are included, they become the new publication parameters of the model. If all publication parameters are omitted, print the current publication parameters of the model. 472 473 * ``addr``: Address of the element the model is on. 474 * ``Model ID``: The model ID of the model to get the bound keys of. 475 * ``cid``: If present, determines the Company ID of the model. If omitted, the model is a Bluetooth SIG defined model. 476 477 Publication parameters: 478 479 * ``PubAddr``: The destination address to publish to. 480 * ``AppKeyIndex``: The application key index to publish with. 481 * ``cred``: Whether to publish with Friendship credentials when acting as a Low Power Node. 482 * ``ttl``: TTL value to publish with (``0x00`` to ``0x07f``). 483 * ``period``: Encoded publication period, or 0 to disable periodic publication. 484 * ``count``: Number of retransmission for each published message (``0`` to ``7``). 485 * ``interval`` The interval between each retransmission, in milliseconds. Must be a multiple of 50. 486 487 488``mesh mod-sub-add <elem addr> <sub addr> <Model ID> [Company ID]`` 489------------------------------------------------------------------- 490 491 Subscription the model to a group address. Models only receive messages sent to their unicast address or a group or virtual address they subscribe to. Models may subscribe to multiple group and virtual addresses. 492 493 * ``elem addr``: Address of the element the model is on. 494 * ``sub addr``: 16-bit group address the model should subscribe to (``0xc000`` to ``0xFEFF``). 495 * ``Model ID``: The model ID of the model to add the subscription to. 496 * ``Company ID``: If present, determines the Company ID of the model. If omitted, the model is a Bluetooth SIG defined model. 497 498 499``mesh mod-sub-del <elem addr> <sub addr> <Model ID> [Company ID]`` 500------------------------------------------------------------------- 501 502 Unsubscribe a model from a group address. 503 504 * ``elem addr``: Address of the element the model is on. 505 * ``sub addr``: 16-bit group address the model should remove from its subscription list (``0xc000`` to ``0xFEFF``). 506 * ``Model ID``: The model ID of the model to add the subscription to. 507 * ``Company ID``: If present, determines the Company ID of the model. If omitted, the model is a Bluetooth SIG defined model. 508 509 510``mesh mod-sub-add-va <elem addr> <Label UUID> <Model ID> [Company ID]`` 511------------------------------------------------------------------------ 512 513 Subscribe the model to a virtual address. Models only receive messages sent to their unicast address or a group or virtual address they subscribe to. Models may subscribe to multiple group and virtual addresses. 514 515 * ``elem addr``: Address of the element the model is on. 516 * ``Label UUID``: 128-bit label UUID of the virtual address to subscribe to. Any omitted bytes will be zero. 517 * ``Model ID``: The model ID of the model to add the subscription to. 518 * ``Company ID``: If present, determines the Company ID of the model. If omitted, the model is a Bluetooth SIG defined model. 519 520 521``mesh mod-sub-del-va <elem addr> <Label UUID> <Model ID> [Company ID]`` 522------------------------------------------------------------------------ 523 524 Unsubscribe a model from a virtual address. 525 526 * ``elem addr``: Address of the element the model is on. 527 * ``Label UUID``: 128-bit label UUID of the virtual address to remove the subscribtion of. Any omitted bytes will be zero. 528 * ``Model ID``: The model ID of the model to add the subscription to. 529 * ``Company ID``: If present, determines the Company ID of the model. If omitted, the model is a Bluetooth SIG defined model. 530 531 532``mesh mod-sub-get <elem addr> <Model ID> [Company ID]`` 533-------------------------------------------------------- 534 535 Get a list of addresses the model subscribes to. 536 537 * ``elem addr``: Address of the element the model is on. 538 * ``Model ID``: The model ID of the model to get the subscription list of. 539 * ``Company ID``: If present, determines the Company ID of the model. If omitted, the model is a Bluetooth SIG defined model. 540 541 542``mesh hb-sub [<src> <dst> <period>]`` 543-------------------------------------- 544 545 Get or set the Heartbeat subscription parameters. A node only receives Heartbeat messages matching the Heartbeat subscription parameters. Sets the Heartbeat subscription parameters if present, or prints the current Heartbeat subscription parameters if called with no parameters. 546 547 * ``src``: Unicast source address to receive Heartbeat messages from. 548 * ``dst``: Destination address to receive Heartbeat messages on. 549 * ``period``: Logarithmic representation of the Heartbeat subscription period: 550 551 * ``0``: Heartbeat subscription will be disabled. 552 * ``1`` to ``17``: The node will subscribe to Heartbeat messages for 2\ :sup:`(period - 1)` seconds. 553 554 555``mesh hb-pub [<dst> <count> <period> <ttl> <features> <NetKeyIndex>]`` 556----------------------------------------------------------------------- 557 558 Get or set the Heartbeat publication parameters. Sets the Heartbeat publication parameters if present, or prints the current Heartbeat publication parameters if called with no parameters. 559 560 * ``dst``: Destination address to publish Heartbeat messages to. 561 * ``count``: Logarithmic representation of the number of Heartbeat messages to publish periodically: 562 563 * ``0``: Heartbeat messages are not published periodically. 564 * ``1`` to ``17``: The node will periodically publish 2\ :sup:`(count - 1)` Heartbeat messages. 565 * ``255``: Heartbeat messages will be published periodically indefinitely. 566 567 * ``period``: Logarithmic representation of the Heartbeat publication period: 568 569 * ``0``: Heartbeat messages are not published periodically. 570 * ``1`` to ``17``: The node will publish Heartbeat messages every 2\ :sup:`(period - 1)` seconds. 571 572 * ``ttl``: The TTL value to publish Heartbeat messages with (``0x00`` to ``0x7f``). 573 * ``features``: Bitfield of features that should trigger a Heartbeat publication when changed: 574 575 * ``Bit 0``: Relay feature. 576 * ``Bit 1``: Proxy feature. 577 * ``Bit 2``: Friend feature. 578 * ``Bit 3``: Low Power feature. 579 580 * ``NetKeyIndex``: Index of the network key to publish Heartbeat messages with. 581 582 583Health Client model 584=================== 585 586The Bluetooth mesh shell module instantiates a Health Client model for configuring itself and other nodes in the mesh network. 587 588The Health Client uses the general messages parameters set by ``mesh dst`` and ``mesh netidx`` to target specific nodes. When the Bluetooth mesh shell node is provisioned, the Health Client model targets itself by default. When another node has been provisioned by the Bluetooth mesh shell, the Health Client model targets the new node. The Health Client always sends messages using the Device key bound to the destination address, so it will only be able to configure itself and mesh nodes it provisioned. 589 590``mesh fault-get <Company ID>`` 591------------------------------- 592 593 Get a list of registered faults for a Company ID. 594 595 * ``Company ID``: Company ID to get faults for. 596 597 598``mesh fault-clear <Company ID>`` 599--------------------------------- 600 601 Clear the list of faults for a Company ID. 602 603 * ``Company ID``: Company ID to clear the faults for. 604 605 606``mesh fault-clear-unack <Company ID>`` 607--------------------------------------- 608 609 Clear the list of faults for a Company ID without requesting a response. 610 611 * ``Company ID``: Company ID to clear the faults for. 612 613 614``mesh fault-test <Company ID> <Test ID>`` 615------------------------------------------ 616 617 Invoke a self-test procedure, and show a list of triggered faults. 618 619 * ``Company ID``: Company ID to perform self-tests for. 620 * ``Test ID``: Test to perform. 621 622 623``mesh fault-test-unack <Company ID> <Test ID>`` 624------------------------------------------------ 625 626 Invoke a self-test procedure without requesting a response. 627 628 * ``Company ID``: Company ID to perform self-tests for. 629 * ``Test ID``: Test to perform. 630 631 632``mesh period-get`` 633------------------- 634 635 Get the current Health Server publish period divisor. 636 637 638``mesh period-set <divisor>`` 639----------------------------- 640 641 Set the current Health Server publish period divisor. When a fault is detected, the Health Server will start publishing is fault status with a reduced interval. The reduced interval is determined by the Health Server publish period divisor: Fault publish period = Publish period / 2\ :sup:`divisor`. 642 643 * ``divisor``: The new Health Server publish period divisor. 644 645 646``mesh period-set-unack <divisor>`` 647----------------------------------- 648 649 Set the current Health Server publish period divisor. When a fault is detected, the Health Server will start publishing is fault status with a reduced interval. The reduced interval is determined by the Health Server publish period divisor: Fault publish period = Publish period / 2\ :sup:`divisor`. 650 651 * ``divisor``: The new Health Server publish period divisor. 652 653 654``mesh attention-get`` 655---------------------- 656 657 Get the current Health Server attention state. 658 659 660``mesh attention-set <timer>`` 661------------------------------ 662 663 Enable the Health Server attention state for some time. 664 665 * ``timer``: Duration of the attention state, in seconds (``0`` to ``255``) 666 667 668``mesh attention-set-unack <timer>`` 669------------------------------------ 670 671 Enable the Health Server attention state for some time without requesting a response. 672 673 * ``timer``: Duration of the attention state, in seconds (``0`` to ``255``) 674 675 676Health Server model 677=================== 678 679``mesh add-fault <Fault ID>`` 680----------------------------- 681 682 Register a new Fault for the Linux Foundation Company ID. 683 684 * ``Fault ID``: ID of the fault to register (``0x0001`` to ``0xFFFF``) 685 686 687``mesh del-fault [Fault ID]`` 688----------------------------- 689 690 Remove registered faults for the Linux Foundation Company ID. 691 692 * ``Fault ID``: If present, the given fault ID will be deleted. If omitted, all registered faults will be cleared. 693 694 695Configuration database 696====================== 697 698The Configuration database is an optional mesh subsystem that can be enabled through the :kconfig:`CONFIG_BT_MESH_CDB` configuration option. The Configuration database is only available on provisioner devices, and allows them to store all information about the mesh network. To avoid conflicts, there should only be one mesh node in the network with the Configuration database enabled. This node is the Configurator, and is responsible for adding new nodes to the network and configuring them. 699 700``mesh cdb-create [NetKey]`` 701---------------------------- 702 703 Create a Configuration database. 704 705 * ``NetKey``: Optional network key value of the primary network key (NetKeyIndex=0). Defaults to the default key value if omitted. 706 707 708``mesh cdb-clear`` 709------------------ 710 711 Clear all data from the Configuration database. 712 713 714``mesh cdb-show`` 715----------------- 716 717 Show all data in the Configuration database. 718 719 720``mesh cdb-node-add <UUID> <addr> <num-elem> <NetKeyIdx> [DevKey]`` 721------------------------------------------------------------------- 722 723 Manually add a mesh node to the configuration database. Note that devices provisioned with ``mesh provision`` and ``mesh provision-adv`` will be added automatically if the Configuration Database is enabled and created. 724 725 * ``UUID``: 128-bit hexadecimal UUID of the node. Any omitted bytes will be zero. 726 * ``addr``: Unicast address of the node, or 0 to automatically choose the lowest available address. 727 * ``num-elem``: Number of elements on the node. 728 * ``NetKeyIdx``: The network key the node was provisioned with. 729 * ``DevKey``: Optional 128-bit device key value for the device. If omitted, a random value will be generated. 730 731 732``mesh cdb-node-del <addr>`` 733---------------------------- 734 735 Delete a mesh node from the Configuration database. If possible, the node should be reset with ``mesh reset`` before it is deleted from the Configuration database, to avoid unexpected behavior and uncontrolled access to the network. 736 737 * ``addr`` Address of the node to delete. 738 739 740``mesh cdb-subnet-add <NeyKeyIdx> [<NetKey>]`` 741---------------------------------------------- 742 743 Add a network key to the Configuration database. The network key can later be passed to mesh nodes in the network. Note that adding a key to the Configuration database does not automatically add it to the local node's list of known network keys. 744 745 * ``NetKeyIdx``: Key index of the network key to add. 746 * ``NetKey``: Optional 128-bit network key value. Any missing bytes will be zero. If omitted, a random value will be generated. 747 748 749``mesh cdb-subnet-del <NetKeyIdx>`` 750----------------------------------- 751 752 Delete a network key from the Configuration database. 753 754 * ``NetKeyIdx``: Key index of the network key to delete. 755 756 757``mesh cdb-app-key-add <NetKeyIdx> <AppKeyIdx> [<AppKey>]`` 758----------------------------------------------------------- 759 760 Add an application key to the Configuration database. The application key can later be passed to mesh nodes in the network. Note that adding a key to the Configuration database does not automatically add it to the local node's list of known application keys. 761 762 * ``NetKeyIdx``: Network key index the application key is bound to. 763 * ``AppKeyIdx``: Key index of the application key to add. 764 * ``AppKey``: Optional 128-bit application key value. Any missing bytes will be zero. If omitted, a random value will be generated. 765 766 767``mesh cdb-app-key-del <AppKeyIdx>`` 768------------------------------------ 769 770 Delete an application key from the Configuration database. 771 772 * ``AppKeyIdx``: Key index of the application key to delete. 773
