Skip to content

Commit

Permalink
[cli] update README files to clarify a Commissioner is used for chang…
Browse files Browse the repository at this point in the history
…ing datasets (openthread#10026)

Based on discussion in openthread#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.
  • Loading branch information
EskoDijk committed Apr 16, 2024
1 parent 23b3641 commit a234add
Show file tree
Hide file tree
Showing 3 changed files with 18 additions and 1 deletion.
4 changes: 4 additions & 0 deletions src/cli/README_COMMISSIONER.md
Original file line number Diff line number Diff line change
@@ -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).
Expand Down
6 changes: 5 additions & 1 deletion src/cli/README_COMMISSIONING.md
Original file line number Diff line number Diff line change
@@ -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.

Expand Down
9 changes: 9 additions & 0 deletions src/cli/README_DATASET.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down

0 comments on commit a234add

Please sign in to comment.