[cli] update README files to clarify a Commissioner is used for changing datasets (#10026)

Based on discussion in #9901 , this clarifies in the documentation
that the CLI `dataset` commands can only be used in specific
situations (like testing), and that these commands allow setting
invalid (combinations of) parameters also. It points to the
Commissioner as the correct way of doing dataset updates in
production.

It also adds "Overview" sections that were missing in two README
files.
This commit is contained in:
Esko Dijk
2024-04-16 14:21:31 -07:00
committed by GitHub
parent 23b3641476
commit a234addb13
3 changed files with 18 additions and 1 deletions
+4
View File
@@ -1,5 +1,9 @@
# OpenThread CLI - Commissioner
## Overview
The Commissioner is an entity that can add new Thread devices securely to a Thread network. It also can manage a Thread network by changing network configuration parameters ([Operational Datasets](README_DATASET.md)) or sending specific management/diagnostic commands to selected Thread devices. Before a Commissioner can do its tasks, it has to petition to the Leader to get permission to become the Commissioner.
## Quick Start
See [README_COMMISSIONING.md](README_COMMISSIONING.md).
+5 -1
View File
@@ -1,10 +1,14 @@
# OpenThread CLI - Commissioning
## Overview
Commissioning is the process of adding a new Thread device, called the Joiner, to a Thread network. This process is done under guidance of a [Commissioner](README_COMMISSIONER.md).
## Quick Start
### Form Network
Form a network with the device that has Commissioner support.
Form a network with the Thread device that has Commissioner support.
1. Generate and view new network configuration.
+9
View File
@@ -4,6 +4,15 @@
Thread network configuration parameters are managed using Active and Pending Operational Dataset objects.
### WARNING - Restrictions for production use!
The 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:
- To configure network parameters for the first device in a newly created Thread network.
- For testing (not applicable to production devices).
In 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.
### Active Operational Dataset
The Active Operational Dataset includes parameters that are currently in use across an entire Thread network. The Active Operational Dataset contains: