[cli] update Dataset documentation with Pending Dataset usage and tim…

…e units (openthread#9475)

Also fixes a pskc -> PSKc typo; and explain better how to init
dataset. Based on existing documentation I struggled a long time to
create a Pending Dataset in the proper way, so I thought it would be
good to document this better.

src/cli/README_DATASET.md

@@ -107,6 +107,117 @@ After the device successfully attaches to a Thread network, the device will retr
    Done
    ```
 
+### Using the Pending Operational Dataset for Delayed Dataset Updates
+
+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.
+
+1. The main parameter to change is the channel. We can display the current Active Operational Dataset to see that the current channel is 16.
+
+   ```bash
+   > 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
+   ```
+
+2. 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.
+
+   ```bash
+   > dataset init active
+   Done
+   > dataset activetimestamp 1696177379
+   Done
+   > dataset pendingtimestamp 1696177379
+   Done
+   > dataset channel 12
+   Done
+   ```
+
+3. Set the delay timer parameter to 5 minutes (300000 ms). Show the resulting Dataset that's ready to be used.
+
+   ```bash
+   > 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
+   ```
+
+4. 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.
+
+   ```bash
+   > dataset commit pending
+   Done
+   ```
+
+5. To verify that the delay timer is counting down, display the Pending Operational Dataset after a few seconds.
+
+   ```bash
+   > 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.
+
+6) 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.
+
+   ```bash
+   > 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:
+
+   ```bash
+   > dataset pending
+   Error 23: NotFound
+   ```
+
 ## Command List
 
 - [help](#help)
@@ -199,7 +310,7 @@ Done
 
 Usage: `dataset activetimestamp [timestamp]`
 
-Get active timestamp seconds.
+Get active timestamp seconds. It represents a "Unix time", in number of seconds since Jan 1st, 1970.
 
 ```bash
 > dataset activetimestamp
@@ -278,7 +389,7 @@ Done
 
 Usage: `dataset delay [delay]`
 
-Get delay timer value.
+Get delay timer value. The timer value is in milliseconds.
 
 ```bash
 > dataset delay
@@ -289,7 +400,7 @@ Done
 Set delay timer value.
 
 ```bash
-> dataset delay 1000
+> dataset delay 100000
 Done
 ```
 
@@ -318,13 +429,27 @@ Done
 
 Usage: `dataset init <active|new|pending|tlvs <hex-encoded TLVs>>`
 
-Initialize operational dataset buffer.
+Initialize operational dataset buffer. Use `new` to initialize with randomly selected values:
 
 ```bash
 > 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:
+
+```bash
+> dataset init active
+Done
+```
+
+Use the `tlvs` option to initialize the dataset buffer from a string of hex-encoded TLVs:
+
+```bash
+> dataset init tlvs 0e080000000000010000000300001235060004001fffe002088665f03e6e42e7750708fda576e5f9a5bd8c0510506071d8391be671569e080d52870fd5030f4f70656e5468726561642d633538640102c58d04108a926cf8b13275a012ceedeeae40910d0c0402a0f7f8
+Done
+```
+
 ### meshlocalprefix
 
 Usage: `dataset meshlocalprefix [prefix]`
@@ -460,7 +585,7 @@ Done
 
 Usage: `dataset pendingtimestamp [timestamp]`
 
-Get pending timestamp seconds.
+Get pending timestamp seconds. It represents a "Unix time", in number of seconds since Jan 1st, 1970.
 
 ```bash
 > dataset pendingtimestamp
@@ -479,17 +604,17 @@ Done
 
 Usage: `pskc [-p] [<key>|<passphrase>]`
 
-Get pskc.
+Get PSKc.
 
 ```bash
 > dataset pskc
 67c0c203aa0b042bfb5381c47aef4d9e
 Done
 ```
 
-Set pskc.
+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).
+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).
 
 ```bash
 > dataset pskc 67c0c203aa0b042bfb5381c47aef4d9e