From a234addb133aacdc527dfd7d3ba18923d42c7ef7 Mon Sep 17 00:00:00 2001 From: Esko Dijk Date: Tue, 16 Apr 2024 23:21:31 +0200 Subject: [PATCH] [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. --- src/cli/README_COMMISSIONER.md | 4 ++++ src/cli/README_COMMISSIONING.md | 6 +++++- src/cli/README_DATASET.md | 9 +++++++++ 3 files changed, 18 insertions(+), 1 deletion(-) diff --git a/src/cli/README_COMMISSIONER.md b/src/cli/README_COMMISSIONER.md index 013b4167da9..5dc1152f345 100644 --- a/src/cli/README_COMMISSIONER.md +++ b/src/cli/README_COMMISSIONER.md @@ -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). diff --git a/src/cli/README_COMMISSIONING.md b/src/cli/README_COMMISSIONING.md index 8262a8c5b54..857bb7a4689 100644 --- a/src/cli/README_COMMISSIONING.md +++ b/src/cli/README_COMMISSIONING.md @@ -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. diff --git a/src/cli/README_DATASET.md b/src/cli/README_DATASET.md index 1f32cce97d1..abed5080d62 100644 --- a/src/cli/README_DATASET.md +++ b/src/cli/README_DATASET.md @@ -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: