mirror of
https://github.com/espressif/openthread.git
synced 2026-09-14 05:00:11 +00:00
Esko Dijk
f121ebcffa
This enables the TCAT Commissioner to receive data such as TLS Alerts, or asynchronously sent 'event' TLVs, over TLS. Processing TLS Alert is required to detect the sending of Alert by the TCAT Device, which is a requirement to be verified in cert tests. An async background process is started to receive and log the received events. Also some minor improvements in connection state management: when certain commands are given after the TCAT link is disconnected, or when a TCAT link could not be established, a message will be printed to clearly say it's disconnected, instead of a cryptic error. Error messages are now clearly prefixed with 'Error:'. The CA certificate store for CommCert3 is extended with an additional CA certificate, so that it can be verified in cert tests that a TCAT Device rejects a wrong Commissioner with a TLS Alert (previously this couldn't be tested). Also includes a fix of the pyproject.toml such that Poetry does not display the long warning on installation. Also includes an improvement of TLV displaying to the user with a STRING field, if the value is a string. Also includes some syntax fixes that were flagged by the IDE, such as missing return types for methods, or member variables that were not initialized in the __init__().
89 lines
3.2 KiB
Markdown
89 lines
3.2 KiB
Markdown
# TCAT Commissioner (BBTC) Client
|
|
|
|
## Overview
|
|
|
|
This is a Python implementation of a Bluetooth-Based Thread Commissioning (BBTC) client, based on Thread's TCAT (Thread Commissioning over Authenticated TLS) functionality.
|
|
|
|
## Installation
|
|
|
|
If you don't have the poetry module installed (check with `poetry --version`), install it first following the [official installation instructions](https://python-poetry.org/docs/#installation).
|
|
|
|
For example, if pipx is available:
|
|
|
|
```bash
|
|
pipx install poetry
|
|
```
|
|
|
|
If pipx is not available, it can be installed for Linux/Windows/MacOS following the [pipx installation instructions](https://pipx.pypa.io/stable/installation/).
|
|
|
|
Then, install this project using Poetry:
|
|
|
|
```
|
|
poetry install
|
|
```
|
|
|
|
This will install all the required modules to a virtual environment, which can be used by calling `poetry run <COMMAND>` from the project directory.
|
|
|
|
Note: Installation on Windows requires that [Build Tools for Visual Studio C/C++](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) be installed first.
|
|
|
|
## Usage
|
|
|
|
To see the supported commandline arguments of BBTC client, use:
|
|
|
|
```
|
|
poetry run python3 bbtc.py --help
|
|
```
|
|
|
|
In order to connect to a TCAT device, run:
|
|
|
|
```bash
|
|
poetry run python3 bbtc.py {<device specifier> | --scan}
|
|
```
|
|
|
|
where `<device specifier>` can be:
|
|
|
|
- `--name <NAME>` - name advertised by the device
|
|
- `--mac <ADDRESS>` - physical address of the device's Bluetooth interface
|
|
|
|
Using the `--scan` option will scan for every TCAT device and display them in a list, to allow selection of the target.
|
|
|
|
For example:
|
|
|
|
```
|
|
poetry run python3 bbtc.py --name 'Thread BLE'
|
|
```
|
|
|
|
The application will connect to the first matching device discovered and set up a secure TLS channel. The user is then presented with the CLI.
|
|
|
|
## Usage with a specific TCAT Commissioner identity
|
|
|
|
The TCAT Commissioner's certificate specifies what permissions it has obtained for specific features of managing a TCAT Device. By default, the identity in the `auth` directory is used. In order to use a different TCAT Commissioner certificate (identity), use the `--cert_path` argument, as follows:
|
|
|
|
```bash
|
|
poetry run python3 bbtc.py --cert_path <certs-path> {<device specifier> | --scan}
|
|
```
|
|
|
|
where `<certs-path>` is the directory where the private key, certificate, and CA certificate(s) of the TCAT Commissioner are stored.
|
|
|
|
For example to use a pre-configured identity `CommCert2` (related to Thread certification tests):
|
|
|
|
```
|
|
poetry run python3 bbtc.py --cert_path ./auth-cert/CommCert2 --name 'Thread BLE'
|
|
```
|
|
|
|
The `auth-cert` directory contains some other identities too, for testing purposes. Refer to Thread TCAT test plan documents for details.
|
|
|
|
See [GENERATING_CERTIFICATES.md](GENERATING_CERTIFICATES.md) for details on generating own certificates.
|
|
|
|
## TCAT Commissioner CLI Commands
|
|
|
|
The application supports the following interactive CLI commands:
|
|
|
|
- `help` - Display available commands.
|
|
- `commission` - Commission the device with current dataset.
|
|
- `thread start` - Enable Thread interface.
|
|
- `thread stop` - Disable Thread interface.
|
|
- `hello` - Send "hello world" application data and read the response.
|
|
- `exit` - Close the connection and exit.
|
|
- `dataset` - View and manipulate current dataset. Use `dataset help` for more information.
|