[example] add minimum commissioner example

openthread · Jun 8, 2021 · 09e1a1c · 09e1a1c
1 parent 79ad31d
commit 09e1a1c
Show file tree

Hide file tree

Showing 7 changed files with 472 additions and 0 deletions.
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -70,3 +70,30 @@ jobs:
           lcov --directory build/ --capture --output-file coverage.info
           lcov --list coverage.info
           bash <(curl -s https://codecov.io/bash) -f coverage.info
+
+  mini-commissioner:
+    runs-on: ubuntu-18.04
+    steps:
+      - uses: actions/checkout@v2
+      - name: Bootstrap
+        run: |
+          script/bootstrap.sh
+      - name: Build
+        run: |
+          cd example && mkdir build && cd build
+          cmake -GNinja                           \
+                -DCMAKE_CXX_STANDARD=11           \
+                -DCMAKE_CXX_STANDARD_REQUIRED=ON  \
+                -DCMAKE_BUILD_TYPE=Release        \
+                -DCMAKE_INSTALL_PREFIX=/usr/local \
+                -DOT_COMM_REFERENCE_DEVICE=ON     \
+                -DOT_COMM_CCM=OFF                 \
+                -DOT_COMM_WARNING_AS_ERROR=ON     \
+                ..
+          ninja
+          sudo ninja install
+      - name: Run mini-commissioner tests
+        run: |
+          cd tests/integration
+          ./bootstrap.sh
+          ./mini_commissioner/test_mini_commissioner.sh
diff --git a/example/BUILDING.md b/example/BUILDING.md
@@ -0,0 +1,32 @@
+# Build Minimum Thread Commissioner
+
+## CMake Build
+
+```shell
+cd ~/ot-commissioner/example
+mkdir -p build && cd build
+cmake -GNinja -DBUILD_SHARED_LIBS=ON ..
+ninja
+```
+
+A `mini_commissioner` binary will be generated in `build/`.
+
+## Standalone build
+
+Build and install the OT Commissioner library:
+
+```c++
+cd ~/ot-commissioner
+mkdir -p build && cd build
+cmake -GNinja -DBUILD_SHARED_LIBS=ON ..
+sudo ninja install
+```
+
+Build the `mini_commissioner` app:
+
+```c++
+cd ~/ot-commissioner/example
+clang++ -std=c++11 -Wall -g mini_commissioner.cpp -o mini_commissioner -lcommissioner -lcommissioner-common
+```
+
+The `mini_commissioner` binary will be generated in current directory.
diff --git a/example/CMakeLists.txt b/example/CMakeLists.txt
@@ -0,0 +1,46 @@
+#
+#  Copyright (c) 2021, The OpenThread Commissioner Authors.
+#  All rights reserved.
+#
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are met:
+#  1. Redistributions of source code must retain the above copyright
+#     notice, this list of conditions and the following disclaimer.
+#  2. Redistributions in binary form must reproduce the above copyright
+#     notice, this list of conditions and the following disclaimer in the
+#     documentation and/or other materials provided with the distribution.
+#  3. Neither the name of the copyright holder nor the
+#     names of its contributors may be used to endorse or promote products
+#     derived from this software without specific prior written permission.
+#
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+#  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+#  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+#  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+#  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+#  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+#  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+#  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+#  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+#  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+#  POSSIBILITY OF SUCH DAMAGE.
+#
+
+cmake_minimum_required(VERSION 3.10.1)
+project(mini-commissioner VERSION 0.1.0)
+
+# The commissioner library requires C++11 or higher.
+set(CMAKE_CXX_STANDARD 11)
+
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/..
+                 ${CMAKE_CURRENT_BINARY_DIR}/commissioner
+                 EXCLUDE_FROM_ALL
+)
+
+add_executable(mini-commissioner mini_commissioner.cpp)
+
+target_link_libraries(mini-commissioner PRIVATE commissioner)
+
+install(TARGETS mini-commissioner
+        RUNTIME DESTINATION bin
+)
diff --git a/example/README.md b/example/README.md
@@ -0,0 +1,83 @@
+# Minimum Thread Commissioner
+
+This directory includes an example of building a minimum Thread Commissioner with the OT Commissioner library. The minimum Thread Commissioner petitions to given Border Router, enables MeshCoP for all joiners and commissions joiners.
+
+## Build
+
+See [BUILDING.md](./BUILDING.md) for building this mini Commissioner program. You can find details about the Border Router (`ot-daemon`) and simulation devices in this [codelab](https://openthread.io/codelabs/openthread-simulation-posix).
+
+## Run the Commissioner
+
+### Start the BR (ot-daemon)
+
+See the [codelab](https://openthread.io/codelabs/openthread-simulation-posix).
+
+### Start the Mini Commissioner
+
+After a successful build, we should get a `mini_commissioner` binary which can be started with four arguments:
+
+```shell
+./mini_commissioner ::1 49191 00112233445566778899aabbccddeeff ABCDEF
+```
+
+You can get the usage by starting `mini_commissioner` with no arguments:
+
+```shell
+./minim_commissioner
+usage:
+    mini_commissioner <br-addr> <br-port> <pskc-hex> <pskd>
+```
+
+> Note: the WiFi/ethernet interface address of the BR should be used but not the Thread interface address.
+
+If everything go smooth, we will get outputs like below:
+
+```shell
+./mini_commissioner ::1 49191 ca117352886a861cce8a91021e65dd1c ABCDEF
+===================================================
+[Border Router address] : ::1
+[Border Router port]    : 49191
+[PSKc]                  : ca117352886a861cce8a91021e65dd1c
+[PSKd]                  : ABCDEF
+===================================================
+
+===================================================
+type CRTL + C to quit!
+===================================================
+
+petitioning to [::1]:49191
+the commissioner is active: true
+enabling MeshCoP for all joiners
+waiting for joiners
+```
+
+> Note: you are free to quit at any time with `CTRL+C`.
+
+### Start the joiner
+
+See the [codelab](https://openthread.io/codelabs/openthread-simulation-posix).
+
+if everything go smooth, we will get output like below for two times of joining:
+
+```shell
+joiner "5ab1f2745b625c90" is requesting join the Thread network
+joiner "5ab1f2745b625c90" is connected: OK
+joiner "5ab1f2745b625c90" is commissioned
+[Vendor Name]          : OPENTHREAD
+[Vendor Model]         : NRF52840
+[Vendor SW Version]    : 20191113-01632-g
+[Vendor Stack Version] : f4ce36000010
+[Provisioning URL]     :
+[Vendor Data]          :
+
+joiner "5ab1f2745b625c90" is requesting join the Thread network
+joiner "5ab1f2745b625c90" is connected: OK
+joiner "5ab1f2745b625c90" is commissioned
+[Vendor Name]          : OPENTHREAD
+[Vendor Model]         : NRF52840
+[Vendor SW Version]    : 20191113-01632-g
+[Vendor Stack Version] : f4ce36000010
+[Provisioning URL]     :
+[Vendor Data]          :
+
+```