1# OpenThread CLI - Operational Datasets 2 3## Overview 4 5Thread network configuration parameters are managed using Active and Pending Operational Dataset objects. 6 7### WARNING - Restrictions for production use! 8 9The CLI commands to write/change the Active and Pending Operational Datasets may allow setting invalid parameters, or invalid combinations of parameters, for testing purposes. These CLI commands can only be used: 10 11- To configure network parameters for the first device in a newly created Thread network. 12- For testing (not applicable to production devices). 13 14In production Thread networks, the correct method to write/change Operational Datasets is via a [Commissioner](README_COMMISSIONER.md) that performs [commissioning](README_COMMISSIONING.md). Production devices that are not an active Commissioner and are part of a Thread network MUST NOT modify the Operational Datasets in any way. 15 16### Active Operational Dataset 17 18The Active Operational Dataset includes parameters that are currently in use across an entire Thread network. The Active Operational Dataset contains: 19 20- Active Timestamp 21- Channel 22- Channel Mask 23- Extended PAN ID 24- Mesh-Local Prefix 25- Network Name 26- PAN ID 27- PSKc 28- Security Policy 29 30### Pending Operational Dataset 31 32The Pending Operational Dataset is used to communicate changes to the Active Operational Dataset before they take effect. The Pending Operational Dataset contains all the parameters from the Active Operational Dataset, with the addition of: 33 34- Delay Timer 35- Pending Timestamp 36 37## Quick Start 38 39### Form Network 40 411. Generate and view new network configuration. 42 43 ```bash 44 > dataset init new 45 Done 46 > dataset 47 Active Timestamp: 1 48 Channel: 15 49 Channel Mask: 0x07fff800 50 Ext PAN ID: 39758ec8144b07fb 51 Mesh Local Prefix: fdf1:f1ad:d079:7dc0::/64 52 Network Key: f366cec7a446bab978d90d27abe38f23 53 Network Name: OpenThread-5938 54 PAN ID: 0x5938 55 PSKc: 3ca67c969efb0d0c74a4d8ee923b576c 56 Security Policy: 672 onrc 0 57 Done 58 ``` 59 602. Commit new dataset to the Active Operational Dataset in non-volatile storage. 61 62 ```bash 63 dataset commit active 64 Done 65 ``` 66 673. Enable Thread interface 68 69 ```bash 70 > ifconfig up 71 Done 72 > thread start 73 Done 74 ``` 75 76### Attach to Existing Network 77 78Only the Network Key is required for a device to attach to a Thread network. 79 80While not required, specifying the channel avoids the need to search across multiple channels, improving both latency and efficiency of the attach process. 81 82After the device successfully attaches to a Thread network, the device will retrieve the complete Active Operational Dataset. 83 841. Create a partial Active Operational Dataset. 85 86 ```bash 87 > dataset networkkey dfd34f0f05cad978ec4e32b0413038ff 88 Done 89 > dataset commit active 90 Done 91 ``` 92 932. Enable Thread interface. 94 95 ```bash 96 > ifconfig up 97 Done 98 > thread start 99 Done 100 ``` 101 1023. After attaching, validate that the device received the complete Active Operational Dataset. 103 104 ```bash 105 > dataset active 106 Active Timestamp: 1 107 Channel: 15 108 Channel Mask: 0x07fff800 109 Ext PAN ID: 39758ec8144b07fb 110 Mesh Local Prefix: fdf1:f1ad:d079:7dc0::/64 111 Network Key: f366cec7a446bab978d90d27abe38f23 112 Network Name: OpenThread-5938 113 PAN ID: 0x5938 114 PSKc: 3ca67c969efb0d0c74a4d8ee923b576c 115 Security Policy: 672 onrc 0 116 Done 117 ``` 118 119### Using the Dataset Updater to update Operational Dataset 120 121Dataset Updater can be used for a delayed update of network parameters on all devices of a Thread Network. 122 1231. Clear the dataset buffer and add the Dataset fields to update. 124 125 ```bash 126 > dataset clear 127 Done 128 129 > dataset channel 12 130 Done 131 ``` 132 1332. Set the delay timer parameter (example uses 5 minutes or 300000 ms). Check the resulting dataset. There is no need to specify active or pending timestamps because the Dataset Updater will handle this. If specified the `dataset updater start` will issue an error. 134 135 ```bash 136 > dataset delay 300000 137 138 > dataset 139 Channel: 12 140 Delay: 30000 141 Done 142 ``` 143 1443. Start the Dataset Updater, which will prepare a Pending Operation Dataset and inform the Leader to distribute it to other devices. 145 146 ```bash 147 > dataset updater start 148 Done 149 150 > dataset updater 151 Enabled 152 ``` 153 1544. After about 5 minutes, the changes are applied to the Active Operational Dataset on the Leader. This can also be checked at other devices on the network: these should have applied the new Dataset too, at approximately the same time as the Leader has done this. 155 156 ```bash 157 > dataset active 158 Active Timestamp: 10 159 Channel: 12 160 Channel Mask: 0x07fff800 161 Ext PAN ID: 324a71d90cdc8345 162 Mesh Local Prefix: fd7d:da74:df5e:80c::/64 163 Network Key: be768535bac1b8d228960038311d6ca2 164 Network Name: OpenThread-bcaf 165 PAN ID: 0xbcaf 166 PSKc: e79b274ab22414a814ed5cce6a30be67 167 Security Policy: 672 onrc 0 168 Done 169 ``` 170 171### Using the Pending Operational Dataset for Delayed Dataset Updates 172 173The Pending Operational Dataset can be used for a delayed update of network parameters on all devices of a Thread Network. If certain Active Operational Dataset parameters need to be changed, but the change would impact the connectivity of the network, delaying the update helps to let all devices receive the new parameters before the update is applied. Examples of such parameters are the channel, PAN ID, certain Security Policy bits, or Network Key. 174 175The delay timer determines the time period after which the Pending Operational Dataset takes effect and becomes the Active Operational Dataset. The following example shows how a Pending Operational Dataset with delay timer can be set at a Leader device. The Leader will initiate the distribution of the Pending Operational Dataset to the rest of the devices in the network. 176 177Normally, an active Commissioner will set a new Pending Operational Dataset. For testing purposes, we will do this in the example directly on the Leader using the CLI - so without using a Commissioner. 178 1791. The main parameter to change is the channel. We can display the current Active Operational Dataset to see that the current channel is 16. 180 181 ```bash 182 > dataset active 183 Active Timestamp: 1691070443 184 Channel: 16 185 Channel Mask: 0x07fff800 186 Ext PAN ID: 324a71d90cdc8345 187 Mesh Local Prefix: fd7d:da74:df5e:80c::/64 188 Network Key: be768535bac1b8d228960038311d6ca2 189 Network Name: OpenThread-bcaf 190 PAN ID: 0xbcaf 191 PSKc: e79b274ab22414a814ed5cce6a30be67 192 Security Policy: 672 onrc 0 193 Done 194 ``` 195 1962. Create a new Dataset in the dataset buffer, by copying the Active Operational Dataset. Then change the channel number to 12 and increase the timestamp. 197 198 ```bash 199 > dataset init active 200 Done 201 > dataset activetimestamp 1696177379 202 Done 203 > dataset pendingtimestamp 1696177379 204 Done 205 > dataset channel 12 206 Done 207 ``` 208 2093. Set the delay timer parameter to 5 minutes (300000 ms). Show the resulting Dataset that's ready to be used. 210 211 ```bash 212 > dataset delay 300000 213 Done 214 > dataset 215 Pending Timestamp: 1696177379 216 Active Timestamp: 1696177379 217 Channel: 12 218 Channel Mask: 0x07fff800 219 Delay: 300000 220 Ext PAN ID: 324a71d90cdc8345 221 Mesh Local Prefix: fd7d:da74:df5e:80c::/64 222 Network Key: be768535bac1b8d228960038311d6ca2 223 Network Name: OpenThread-bcaf 224 PAN ID: 0xbcaf 225 PSKc: e79b274ab22414a814ed5cce6a30be67 226 Security Policy: 672 onrc 0 227 Done 228 ``` 229 2304. Commit the new Dataset as the Pending Operational Dataset. This also starts the delay timer countdown. The Leader then starts the distribution of the Pending Operational Dataset to other devices in the network. 231 232 ```bash 233 > dataset commit pending 234 Done 235 ``` 236 2375. To verify that the delay timer is counting down, display the Pending Operational Dataset after a few seconds. 238 239 ```bash 240 > dataset pending 241 Pending Timestamp: 1696177379 242 Active Timestamp: 1696177379 243 Channel: 12 244 Channel Mask: 0x07fff800 245 Delay: 293051 246 Ext PAN ID: 324a71d90cdc8345 247 Mesh Local Prefix: fd7d:da74:df5e:80c::/64 248 Network Key: be768535bac1b8d228960038311d6ca2 249 Network Name: OpenThread-bcaf 250 PAN ID: 0xbcaf 251 PSKc: e79b274ab22414a814ed5cce6a30be67 252 Security Policy: 672 onrc 0 253 Done 254 ``` 255 256 This shows that indeed the delay timer has started counting down from its initial value `300000`. The same can be optionally checked on other devices in the network. 257 2586) After about 5 minutes, check that the Pending Operational Dataset has been applied at the Leader. This can also be checked at other devices on the network: these should have applied the new Dataset too, at approximately the same time as the Leader has done this. 259 260 ```bash 261 > dataset active 262 Active Timestamp: 1696177379 263 Channel: 12 264 Channel Mask: 0x07fff800 265 Ext PAN ID: 324a71d90cdc8345 266 Mesh Local Prefix: fd7d:da74:df5e:80c::/64 267 Network Key: be768535bac1b8d228960038311d6ca2 268 Network Name: OpenThread-bcaf 269 PAN ID: 0xbcaf 270 PSKc: e79b274ab22414a814ed5cce6a30be67 271 Security Policy: 672 onrc 0 272 Done 273 ``` 274 275 This shows that the Active Operational Dataset has now been updated to use channel 12. And the Pending Operational Dataset is no longer present, as can be seen by this command: 276 277 ```bash 278 > dataset pending 279 Error 23: NotFound 280 ``` 281 282## Command List 283 284- [help](#help) 285- [active](#active) 286- [activetimestamp](#activetimestamp) 287- [channel](#channel) 288- [channelmask](#channelmask) 289- [clear](#clear) 290- [commit](#commit) 291- [delay](#delay) 292- [extpanid](#extpanid) 293- [init](#init) 294- [meshlocalprefix](#meshlocalprefix) 295- [mgmtgetcommand](#mgmtgetcommand) 296- [mgmtsetcommand](#mgmtsetcommand) 297- [networkkey](#networkkey) 298- [networkname](#networkname) 299- [panid](#panid) 300- [pending](#pending) 301- [pendingtimestamp](#pendingtimestamp) 302- [pskc](#pskc) 303- [securitypolicy](#securitypolicy) 304- [tlvs](#tlvs) 305- [updater](#updater) 306 307## Command Details 308 309### help 310 311Usage: `dataset help` 312 313Print dataset help menu. 314 315```bash 316> dataset help 317help 318active 319activetimestamp 320channel 321channelmask 322clear 323commit 324delay 325extpanid 326init 327meshlocalprefix 328mgmtgetcommand 329mgmtsetcommand 330networkkey 331networkname 332panid 333pending 334pendingtimestamp 335pskc 336securitypolicy 337set 338tlvs 339Done 340``` 341 342### active 343 344Usage: `dataset active [-x]` 345 346Print Active Operational Dataset in human-readable form. 347 348```bash 349> dataset active 350Active Timestamp: 1 351Channel: 15 352Channel Mask: 0x07fff800 353Ext PAN ID: 39758ec8144b07fb 354Mesh Local Prefix: fdf1:f1ad:d079:7dc0::/64 355Network Key: f366cec7a446bab978d90d27abe38f23 356Network Name: OpenThread-5938 357PAN ID: 0x5938 358PSKc: 3ca67c969efb0d0c74a4d8ee923b576c 359Security Policy: 672 onrc 0 360Done 361``` 362 363Print Active Operational Dataset as hex-encoded TLVs. 364 365```bash 366> dataset active -x 3670e080000000000010000000300000f35060004001fffe0020839758ec8144b07fb0708fdf1f1add0797dc00510f366cec7a446bab978d90d27abe38f23030f4f70656e5468726561642d353933380102593804103ca67c969efb0d0c74a4d8ee923b576c0c0402a0f7f8 368Done 369``` 370 371### activetimestamp 372 373Usage: `dataset activetimestamp [timestamp]` 374 375Get active timestamp seconds. It represents a "Unix time", in number of seconds since Jan 1st, 1970. 376 377```bash 378> dataset activetimestamp 379123456789 380Done 381``` 382 383Set active timestamp seconds. 384 385```bash 386> dataset activetimestamp 123456789 387Done 388``` 389 390### channel 391 392Usage: `channel [channel]` 393 394Get channel. 395 396```bash 397> dataset channel 39812 399Done 400``` 401 402Set channel. 403 404```bash 405> dataset channel 12 406Done 407``` 408 409### channelmask 410 411Usage: `dataset channelmask [channelmask]` 412 413Get channel mask. 414 415```bash 416> dataset channelmask 4170x07fff800 418Done 419``` 420 421Set channel mask. 422 423```bash 424> dataset channelmask 0x07fff800 425Done 426``` 427 428### clear 429 430Usage: `dataset clear` 431 432Reset operational dataset buffer. 433 434```bash 435> dataset clear 436Done 437``` 438 439### commit 440 441Usage: `dataset commit <active|pending>` 442 443Commit operational dataset buffer to active/pending operational dataset. 444 445```bash 446> dataset commit active 447Done 448``` 449 450### delay 451 452Usage: `dataset delay [delay]` 453 454Get delay timer value. The timer value is in milliseconds. 455 456```bash 457> dataset delay 4581000 459Done 460``` 461 462Set delay timer value. 463 464```bash 465> dataset delay 100000 466Done 467``` 468 469### extpanid 470 471Usage: `dataset extpanid [extpanid]` 472 473Get extended panid. 474 475```bash 476> dataset extpanid 477000db80123456789 478Done 479``` 480 481Set extended panid. 482 483**NOTE** The commissioning credential in the dataset buffer becomes stale after changing this value. Use [pskc](#pskc) to reset. 484 485```bash 486> dataset extpanid 000db80123456789 487Done 488``` 489 490### init 491 492Usage: `dataset init <active|new|pending|tlvs <hex-encoded TLVs>>` 493 494Initialize operational dataset buffer. Use `new` to initialize with randomly selected values: 495 496```bash 497> dataset init new 498Done 499``` 500 501Use `active` or `pending` to initialize the dataset buffer with a copy of the current Active Operational Dataset or Pending Operational Dataset, respectively: 502 503```bash 504> dataset init active 505Done 506``` 507 508Use the `tlvs` option to initialize the dataset buffer from a string of hex-encoded TLVs: 509 510```bash 511> dataset init tlvs 0e080000000000010000000300001235060004001fffe002088665f03e6e42e7750708fda576e5f9a5bd8c0510506071d8391be671569e080d52870fd5030f4f70656e5468726561642d633538640102c58d04108a926cf8b13275a012ceedeeae40910d0c0402a0f7f8 512Done 513``` 514 515### meshlocalprefix 516 517Usage: `dataset meshlocalprefix [prefix]` 518 519Get mesh local prefix. 520 521```bash 522> dataset meshlocalprefix 523fd00:db8:0:0::/64 524Done 525``` 526 527Set mesh local prefix. 528 529```bash 530> dataset meshlocalprefix fd00:db8:: 531Done 532``` 533 534### mgmtgetcommand 535 536Usage: `dataset mgmtgetcommand <active|pending> [address <destination>] [TLV list] [-x]` 537 538Send MGMT_ACTIVE_GET or MGMT_PENDING_GET. 539 540```bash 541> dataset mgmtgetcommand active address fdde:ad00:beef:0:558:f56b:d688:799 activetimestamp securitypolicy 542Done 543``` 544 545### mgmtsetcommand 546 547Usage: `dataset mgmtsetcommand <active|pending> [TLV Type list] [-x]` 548 549Send MGMT_ACTIVE_SET or MGMT_PENDING_SET. 550 551```bash 552> dataset mgmtsetcommand active activetimestamp 123 securitypolicy 1 onrc 0 553Done 554``` 555 556### networkkey 557 558Usage: `dataset networkkey [key]` 559 560Get network key 561 562```bash 563> dataset networkkey 56400112233445566778899aabbccddeeff 565Done 566``` 567 568Set network key. 569 570```bash 571> dataset networkkey 00112233445566778899aabbccddeeff 572Done 573``` 574 575### networkname 576 577Usage: `dataset networkname [name]` 578 579Get network name. 580 581```bash 582> dataset networkname 583OpenThread 584Done 585``` 586 587Set network name. 588 589**NOTE** The commissioning credential in the dataset buffer becomes stale after changing this value. Use [pskc](#pskc) to reset. 590 591```bash 592> dataset networkname OpenThread 593Done 594``` 595 596### panid 597 598Usage: `dataset panid [panid]` 599 600Get panid. 601 602```bash 603> dataset panid 6040x1234 605Done 606``` 607 608Set panid. 609 610```bash 611> dataset panid 0x1234 612Done 613``` 614 615### pending 616 617Usage: `dataset pending [-x]` 618 619Print Pending Operational Dataset in human-readable form. 620 621```bash 622> dataset pending 623Pending Timestamp: 2 624Active Timestamp: 1 625Channel: 26 626Channel Mask: 0x07fff800 627Delay: 58706 628Ext PAN ID: a74182f4d3f4de41 629Mesh Local Prefix: fd46:c1b9:e159:5574::/64 630Network Key: ed916e454d96fd00184f10a6f5c9e1d3 631Network Name: OpenThread-bff8 632PAN ID: 0xbff8 633PSKc: 264f78414adc683191863d968f72d1b7 634Security Policy: 672 onrc 0 635Done 636``` 637 638Print Pending Operational Dataset as hex-encoded TLVs. 639 640```bash 641> dataset pending -x 6420e0800000000000100003308000000000002000034040000b512000300001a35060004001fffe00208a74182f4d3f4de410708fd46c1b9e15955740510ed916e454d96fd00184f10a6f5c9e1d3030f4f70656e5468726561642d626666380102bff80410264f78414adc683191863d968f72d1b70c0402a0f7f8 643Done 644``` 645 646### pendingtimestamp 647 648Usage: `dataset pendingtimestamp [timestamp]` 649 650Get pending timestamp seconds. It represents a "Unix time", in number of seconds since Jan 1st, 1970. 651 652```bash 653> dataset pendingtimestamp 654123456789 655Done 656``` 657 658Set pending timestamp seconds. 659 660```bash 661> dataset pendingtimestamp 123456789 662Done 663``` 664 665### pskc 666 667Usage: `pskc [-p] [<key>|<passphrase>]` 668 669Get PSKc. 670 671```bash 672> dataset pskc 67367c0c203aa0b042bfb5381c47aef4d9e 674Done 675``` 676 677Set PSKc. 678 679With `-p`(**only for FTD**) generate PSKc from \<passphrase\> (UTF-8 encoded) together with network name and extended PAN ID in the dataset buffer if set or values in the current stack if not, otherwise set PSKc as \<key\> (hex format). 680 681```bash 682> dataset pskc 67c0c203aa0b042bfb5381c47aef4d9e 683Done 684> dataset pskc -p 123456 685Done 686``` 687 688### securitypolicy 689 690Usage: `dataset securitypolicy [<rotationtime> [onrcCepR] [versionthreshold]]` 691 692Get security policy. 693 694```bash 695> dataset securitypolicy 696672 onrc 0 697Done 698``` 699 700Set security policy. 701 702- o: Obtaining the Network Key for out-of-band commissioning is enabled. 703- n: Native Commissioning using PSKc is allowed. 704- r: Thread 1.x Routers are enabled. 705- c: External Commissioner authentication is allowed using PSKc. 706- C: Thread 1.2 Commercial Commissioning is enabled. 707- e: Thread 1.2 Autonomous Enrollment is enabled. 708- p: Thread 1.2 Network Key Provisioning is enabled. 709- R: Non-CCM routers are allowed in Thread 1.2 CCM networks. 710 711If the `versionthreshold` parameter is not provided, a default value of zero is assumed. 712 713```bash 714> dataset securitypolicy 672 onrc 0 715Done 716``` 717 718### set 719 720Usage: `dataset set <active|pending> <dataset>` 721 722Set the Active Operational Dataset using hex-encoded TLVs. 723 724```bash 725> dataset set active 0e080000000000010000000300000f35060004001fffe0020839758ec8144b07fb0708fdf1f1add0797dc00510f366cec7a446bab978d90d27abe38f23030f4f70656e5468726561642d353933380102593804103ca67c969efb0d0c74a4d8ee923b576c0c0402a0f7f8 726Done 727``` 728 729Set the Pending Operational Dataset using hex-encoded TLVs. 730 731```bash 732> dataset set pending 0e0800000000000100003308000000000002000034040000b512000300001a35060004001fffe00208a74182f4d3f4de410708fd46c1b9e15955740510ed916e454d96fd00184f10a6f5c9e1d3030f4f70656e5468726561642d626666380102bff80410264f78414adc683191863d968f72d1b70c0402a0f7f8 733Done 734``` 735 736### tlvs 737 738Usage: `dataset tlvs` 739 740Convert the Operational Dataset to hex-encoded TLVs. 741 742```bash 743> dataset 744Active Timestamp: 1 745Channel: 22 746Channel Mask: 0x07fff800 747Ext PAN ID: d196fa2040e973b6 748Mesh Local Prefix: fdbb:c310:c48f:3a39::/64 749Network Key: 9929154dbc363218bcd22f907caf5c15 750Network Name: OpenThread-de2b 751PAN ID: 0xde2b 752PSKc: 15b2c16f7ba92ed4bc7b1ee054f1553f 753Security Policy: 672 onrc 0 754Done 755 756> dataset tlvs 7570e080000000000010000000300001635060004001fffe00208d196fa2040e973b60708fdbbc310c48f3a3905109929154dbc363218bcd22f907caf5c15030f4f70656e5468726561642d646532620102de2b041015b2c16f7ba92ed4bc7b1ee054f1553f0c0402a0f7f8 758Done 759``` 760 761### updater 762 763Usage: `dataset updater` 764 765Requires `OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE`. 766 767Indicate whether there is an ongoing Operation Dataset update request. 768 769```bash 770> dataset updater 771Enabled 772``` 773 774### updater start 775 776Usage: `dataset updater start` 777 778Requires `OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE`. 779 780Request network to update its Operation Dataset to the current operational dataset buffer. 781 782The current operational dataset buffer should contain the fields to be updated with their new values. It must not contain Active or Pending Timestamp fields. The Delay field is optional. If not provided, a default value (1000 ms) is used. 783 784```bash 785> channel 78619 787Done 788 789> dataset clear 790Done 791> dataset channel 15 792Done 793> dataset 794Channel: 15 795Done 796 797> dataset updater start 798Done 799> dataset updater 800Enabled 801Done 802 803Dataset update complete: OK 804 805> channel 80615 807Done 808``` 809 810### updater cancel 811 812Usage: `dataset updater cancel` 813 814Requires `OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE`. 815 816Cancels an ongoing (if any) Operational Dataset update request. 817 818```bash 819> dataset updater start 820Done 821> dataset updater 822Enabled 823Done 824> 825> dataset updater cancel 826Done 827> dataset updater 828Disabled 829Done 830``` 831