Thread network configuration parameters are managed using Active and Pending Operational Dataset objects.
The Active Operational Dataset includes parameters that are currently in use across an entire Thread network. The Active Operational Dataset contains:
The 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:
Generate and view new network configuration.
> dataset init new Done > dataset Active Timestamp: 1 Channel: 15 Channel Mask: 0x07fff800 Ext PAN ID: 39758ec8144b07fb Mesh Local Prefix: fdf1:f1ad:d079:7dc0::/64 Network Key: f366cec7a446bab978d90d27abe38f23 Network Name: OpenThread-5938 PAN ID: 0x5938 PSKc: 3ca67c969efb0d0c74a4d8ee923b576c Security Policy: 672 onrc 0 Done
Commit new dataset to the Active Operational Dataset in non-volatile storage.
dataset commit active Done
Enable Thread interface
> ifconfig up Done > thread start Done
Only the Network Key is required for a device to attach to a Thread network.
While not required, specifying the channel avoids the need to search across multiple channels, improving both latency and efficiency of the attach process.
After the device successfully attaches to a Thread network, the device will retrieve the complete Active Operational Dataset.
Create a partial Active Operational Dataset.
> dataset networkkey dfd34f0f05cad978ec4e32b0413038ff Done > dataset commit active Done
Enable Thread interface.
> ifconfig up Done > thread start Done
After attaching, validate that the device received the complete Active Operational Dataset.
> dataset active Active Timestamp: 1 Channel: 15 Channel Mask: 0x07fff800 Ext PAN ID: 39758ec8144b07fb Mesh Local Prefix: fdf1:f1ad:d079:7dc0::/64 Network Key: f366cec7a446bab978d90d27abe38f23 Network Name: OpenThread-5938 PAN ID: 0x5938 PSKc: 3ca67c969efb0d0c74a4d8ee923b576c Security Policy: 672 onrc 0 Done
Dataset Updater can be used for a delayed update of network parameters on all devices of a Thread Network.
Clear the dataset buffer and add the Dataset fields to update.
> dataset clear Done > dataset channel 12 Done
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.
> dataset delay 300000 > dataset Channel: 12 Delay: 30000 Done
Start the Dataset Updater, which will prepare a Pending Operation Dataset and inform the Leader to distribute it to other devices.
> dataset updater start Done > dataset updater Enabled
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.
> dataset active Active Timestamp: 10 Channel: 12 Channel Mask: 0x07fff800 Ext PAN ID: 324a71d90cdc8345 Mesh Local Prefix: fd7d:da74:df5e:80c::/64 Network Key: be768535bac1b8d228960038311d6ca2 Network Name: OpenThread-bcaf PAN ID: 0xbcaf PSKc: e79b274ab22414a814ed5cce6a30be67 Security Policy: 672 onrc 0 Done
The 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.
The 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.
Normally, 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.
The main parameter to change is the channel. We can display the current Active Operational Dataset to see that the current channel is 16.
> dataset active Active Timestamp: 1691070443 Channel: 16 Channel Mask: 0x07fff800 Ext PAN ID: 324a71d90cdc8345 Mesh Local Prefix: fd7d:da74:df5e:80c::/64 Network Key: be768535bac1b8d228960038311d6ca2 Network Name: OpenThread-bcaf PAN ID: 0xbcaf PSKc: e79b274ab22414a814ed5cce6a30be67 Security Policy: 672 onrc 0 Done
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.
> dataset init active Done > dataset activetimestamp 1696177379 Done > dataset pendingtimestamp 1696177379 Done > dataset channel 12 Done
Set the delay timer parameter to 5 minutes (300000 ms). Show the resulting Dataset that's ready to be used.
> dataset delay 300000 Done > dataset Pending Timestamp: 1696177379 Active Timestamp: 1696177379 Channel: 12 Channel Mask: 0x07fff800 Delay: 300000 Ext PAN ID: 324a71d90cdc8345 Mesh Local Prefix: fd7d:da74:df5e:80c::/64 Network Key: be768535bac1b8d228960038311d6ca2 Network Name: OpenThread-bcaf PAN ID: 0xbcaf PSKc: e79b274ab22414a814ed5cce6a30be67 Security Policy: 672 onrc 0 Done
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.
> dataset commit pending Done
To verify that the delay timer is counting down, display the Pending Operational Dataset after a few seconds.
> dataset pending Pending Timestamp: 1696177379 Active Timestamp: 1696177379 Channel: 12 Channel Mask: 0x07fff800 Delay: 293051 Ext PAN ID: 324a71d90cdc8345 Mesh Local Prefix: fd7d:da74:df5e:80c::/64 Network Key: be768535bac1b8d228960038311d6ca2 Network Name: OpenThread-bcaf PAN ID: 0xbcaf PSKc: e79b274ab22414a814ed5cce6a30be67 Security Policy: 672 onrc 0 Done
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.
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.
> dataset active Active Timestamp: 1696177379 Channel: 12 Channel Mask: 0x07fff800 Ext PAN ID: 324a71d90cdc8345 Mesh Local Prefix: fd7d:da74:df5e:80c::/64 Network Key: be768535bac1b8d228960038311d6ca2 Network Name: OpenThread-bcaf PAN ID: 0xbcaf PSKc: e79b274ab22414a814ed5cce6a30be67 Security Policy: 672 onrc 0 Done
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:
> dataset pending Error 23: NotFound
Usage: dataset help
Print dataset help menu.
> dataset help help active activetimestamp channel channelmask clear commit delay extpanid init meshlocalprefix mgmtgetcommand mgmtsetcommand networkkey networkname panid pending pendingtimestamp pskc securitypolicy set tlvs Done
Usage: dataset active [-x]
Print Active Operational Dataset in human-readable form.
> dataset active Active Timestamp: 1 Channel: 15 Channel Mask: 0x07fff800 Ext PAN ID: 39758ec8144b07fb Mesh Local Prefix: fdf1:f1ad:d079:7dc0::/64 Network Key: f366cec7a446bab978d90d27abe38f23 Network Name: OpenThread-5938 PAN ID: 0x5938 PSKc: 3ca67c969efb0d0c74a4d8ee923b576c Security Policy: 672 onrc 0 Done
Print Active Operational Dataset as hex-encoded TLVs.
> dataset active -x 0e080000000000010000000300000f35060004001fffe0020839758ec8144b07fb0708fdf1f1add0797dc00510f366cec7a446bab978d90d27abe38f23030f4f70656e5468726561642d353933380102593804103ca67c969efb0d0c74a4d8ee923b576c0c0402a0f7f8 Done
Usage: dataset activetimestamp [timestamp]
Get active timestamp seconds. It represents a "Unix time", in number of seconds since Jan 1st, 1970.
> dataset activetimestamp 123456789 Done
Set active timestamp seconds.
> dataset activetimestamp 123456789 Done
Usage: channel [channel]
Get channel.
> dataset channel 12 Done
Set channel.
> dataset channel 12 Done
Usage: dataset channelmask [channelmask]
Get channel mask.
> dataset channelmask 0x07fff800 Done
Set channel mask.
> dataset channelmask 0x07fff800 Done
Usage: dataset clear
Reset operational dataset buffer.
> dataset clear Done
Usage: dataset commit <active|pending>
Commit operational dataset buffer to active/pending operational dataset.
> dataset commit active Done
Usage: dataset delay [delay]
Get delay timer value. The timer value is in milliseconds.
> dataset delay 1000 Done
Set delay timer value.
> dataset delay 100000 Done
Usage: dataset extpanid [extpanid]
Get extended panid.
> dataset extpanid 000db80123456789 Done
Set extended panid.
NOTE The commissioning credential in the dataset buffer becomes stale after changing this value. Use pskc to reset.
> dataset extpanid 000db80123456789 Done
Usage: dataset init <active|new|pending|tlvs <hex-encoded TLVs>>
Initialize operational dataset buffer. Use new
to initialize with randomly selected values:
> dataset init new Done
Use active
or pending
to initialize the dataset buffer with a copy of the current Active Operational Dataset or Pending Operational Dataset, respectively:
> dataset init active Done
Use the tlvs
option to initialize the dataset buffer from a string of hex-encoded TLVs:
> dataset init tlvs 0e080000000000010000000300001235060004001fffe002088665f03e6e42e7750708fda576e5f9a5bd8c0510506071d8391be671569e080d52870fd5030f4f70656e5468726561642d633538640102c58d04108a926cf8b13275a012ceedeeae40910d0c0402a0f7f8 Done
Usage: dataset meshlocalprefix [prefix]
Get mesh local prefix.
> dataset meshlocalprefix fd00:db8:0:0::/64 Done
Set mesh local prefix.
> dataset meshlocalprefix fd00:db8:: Done
Usage: dataset mgmtgetcommand <active|pending> [address <destination>] [TLV list] [-x]
Send MGMT_ACTIVE_GET or MGMT_PENDING_GET.
> dataset mgmtgetcommand active address fdde:ad00:beef:0:558:f56b:d688:799 activetimestamp securitypolicy Done
Usage: dataset mgmtsetcommand <active|pending> [TLV Type list] [-x]
Send MGMT_ACTIVE_SET or MGMT_PENDING_SET.
> dataset mgmtsetcommand active activetimestamp 123 securitypolicy 1 onrc 0 Done
Usage: dataset networkkey [key]
Get network key
> dataset networkkey 00112233445566778899aabbccddeeff Done
Set network key.
> dataset networkkey 00112233445566778899aabbccddeeff Done
Usage: dataset networkname [name]
Get network name.
> dataset networkname OpenThread Done
Set network name.
NOTE The commissioning credential in the dataset buffer becomes stale after changing this value. Use pskc to reset.
> dataset networkname OpenThread Done
Usage: dataset panid [panid]
Get panid.
> dataset panid 0x1234 Done
Set panid.
> dataset panid 0x1234 Done
Usage: dataset pending [-x]
Print Pending Operational Dataset in human-readable form.
> dataset pending Pending Timestamp: 2 Active Timestamp: 1 Channel: 26 Channel Mask: 0x07fff800 Delay: 58706 Ext PAN ID: a74182f4d3f4de41 Mesh Local Prefix: fd46:c1b9:e159:5574::/64 Network Key: ed916e454d96fd00184f10a6f5c9e1d3 Network Name: OpenThread-bff8 PAN ID: 0xbff8 PSKc: 264f78414adc683191863d968f72d1b7 Security Policy: 672 onrc 0 Done
Print Pending Operational Dataset as hex-encoded TLVs.
> dataset pending -x 0e0800000000000100003308000000000002000034040000b512000300001a35060004001fffe00208a74182f4d3f4de410708fd46c1b9e15955740510ed916e454d96fd00184f10a6f5c9e1d3030f4f70656e5468726561642d626666380102bff80410264f78414adc683191863d968f72d1b70c0402a0f7f8 Done
Usage: dataset pendingtimestamp [timestamp]
Get pending timestamp seconds. It represents a "Unix time", in number of seconds since Jan 1st, 1970.
> dataset pendingtimestamp 123456789 Done
Set pending timestamp seconds.
> dataset pendingtimestamp 123456789 Done
Usage: pskc [-p] [<key>|<passphrase>]
Get PSKc.
> dataset pskc 67c0c203aa0b042bfb5381c47aef4d9e Done
Set PSKc.
With -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).
> dataset pskc 67c0c203aa0b042bfb5381c47aef4d9e Done > dataset pskc -p 123456 Done
Usage: dataset securitypolicy [<rotationtime> [onrcCepR] [versionthreshold]]
Get security policy.
> dataset securitypolicy 672 onrc 0 Done
Set security policy.
If the versionthreshold
parameter is not provided, a default value of zero is assumed.
> dataset securitypolicy 672 onrc 0 Done
Usage: dataset set <active|pending> <dataset>
Set the Active Operational Dataset using hex-encoded TLVs.
> dataset set active 0e080000000000010000000300000f35060004001fffe0020839758ec8144b07fb0708fdf1f1add0797dc00510f366cec7a446bab978d90d27abe38f23030f4f70656e5468726561642d353933380102593804103ca67c969efb0d0c74a4d8ee923b576c0c0402a0f7f8 Done
Set the Pending Operational Dataset using hex-encoded TLVs.
> dataset set pending 0e0800000000000100003308000000000002000034040000b512000300001a35060004001fffe00208a74182f4d3f4de410708fd46c1b9e15955740510ed916e454d96fd00184f10a6f5c9e1d3030f4f70656e5468726561642d626666380102bff80410264f78414adc683191863d968f72d1b70c0402a0f7f8 Done
Usage: dataset tlvs
Convert the Operational Dataset to hex-encoded TLVs.
> dataset Active Timestamp: 1 Channel: 22 Channel Mask: 0x07fff800 Ext PAN ID: d196fa2040e973b6 Mesh Local Prefix: fdbb:c310:c48f:3a39::/64 Network Key: 9929154dbc363218bcd22f907caf5c15 Network Name: OpenThread-de2b PAN ID: 0xde2b PSKc: 15b2c16f7ba92ed4bc7b1ee054f1553f Security Policy: 672 onrc 0 Done > dataset tlvs 0e080000000000010000000300001635060004001fffe00208d196fa2040e973b60708fdbbc310c48f3a3905109929154dbc363218bcd22f907caf5c15030f4f70656e5468726561642d646532620102de2b041015b2c16f7ba92ed4bc7b1ee054f1553f0c0402a0f7f8 Done
Usage: dataset updater
Requires OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE
.
Indicate whether there is an ongoing Operation Dataset update request.
> dataset updater Enabled
Usage: dataset updater start
Requires OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE
.
Request network to update its Operation Dataset to the current operational dataset buffer.
The 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.
> channel 19 Done > dataset clear Done > dataset channel 15 Done > dataset Channel: 15 Done > dataset updater start Done > dataset updater Enabled Done Dataset update complete: OK > channel 15 Done
Usage: dataset updater cancel
Requires OPENTHREAD_CONFIG_DATASET_UPDATER_ENABLE
.
Cancels an ongoing (if any) Operational Dataset update request.
> dataset updater start Done > dataset updater Enabled Done > > dataset updater cancel Done > dataset updater Disabled Done