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