Document: Thread Commissioning Demonstration with OpenThread and Border Router

[lanyuwen]

We need a document to describe how to perform Thread Commissioning with OpenThread and OpenThread Border Router.

Content may cover these steps:

• Build and program NCP device
• Build an OpenThread Border Router with a RPi 3B
• Form a Thread network with OpenThread Border Router
• Install ThreadGroup Commissioning App
• Scan and select Border Router through Commissioning App
• Build and program a Joiner device
• Commission a Joiner device into the existing Thread network
• Ping or communicate with a host located in Internet

[Vyrastas]

Everything but the Thread Commissioning App part has been posted on openthread.io:

https://openthread.io/guides/border_router/build
https://openthread.io/guides/building/commissioning

Since there are issues with the Thread Commissioning App and OTBR, we'll need that public version updated so others can use it.

[beriberikix]

I just received an update for the Thread Commissioning App, v1.01.11.7a3daa7. Does this build fix the remaining issues blocking it working with borderrouter?

[jwhui]

Yes it does :)

[DuaneEllis-TI]

W.R.T. To documentation the commissioning process you might take a look at the changes I did with the commissioning test app

Work was done in this Pull request: #92

The key thing here is here: ${borderrouter}/tests/meshcop, and the otbr-commissioner C program

The standalone test application can commission any thread device from the Linux command line. The command line syntax presented below as a shell script fragment below explains the steps.

#! /bin/sh
# Clear the ARGS variable.
ARGS=""
    
# OpenThread network parameters all items are found on 
# the OTBR-WEB "form network" screen.
ARGS="$ARGS --network-name      $OT_NETWORK_NAME"
ARGS="$ARGS --xpanid            $OT_XPANID"
ARGS="$ARGS --agent-passphrase  $OT_AGENT_PASSPHRASE"

# Details about the joiner.
ARGS="$ARGS --joiner-eui64      $OT_JOINER_EUI64"
ARGS="$ARGS --joiner-passphrase $OT_JOINER_PASSPHRASE"

# How to talk to the agent, this would come from mDNS broadcasts.
# In this example we specify the details on the command line.
ARGS="$ARGS --agent-addr        $OT_AGENT_IPADDR"
ARGS="$ARGS --agent-port        $OT_AGENT_IPPORT"

# As this test application is for debugging it includes an "envelope" 
# timeout in case things go wrong.
# By Envelope, we mean the entire commissioning process end to end
# Here we set a 200 second timeout.
# In practice, it is typically 60 seconds.
# using a RaspberryPi or BeagleBoneBlack + CC2538
ARGS="$ARGS --comm-envelope-timeout 200"

# Note: there are other options, use "--help" to list them.

# Tell the tool to "commission a device"
ARGS="$ARGS --commission-device"
  # Commission
$OTBR_COMMISSIONER_EXE $ARGS

[DuaneEllis-TI]

W.R.T. This item >> Ping or communicate with a host located in Internet

A simple suggestion is:

a) In the "thirdparty/libcoap" directory

By default, openthread builds libcoap with --disable-examples and --disable-documentation

b) If you rebuild libcoap but ENABLE the examples, you have two test applications, one of which is "coap-client"

The "coap-client" is a simple command line tool that can easily be used to perform non-secure CoAP requests with devices on the Thread Network.

[Vyrastas]

Hi @DuaneEllis-TI , thanks for pointing these out. It might be best to have brief READMEs on general usage of these tools in those directories, and have overviews / use cases of them on openthread.io. Thoughts?

We're close to publishing a guide for the last item (external commissioning w/ the Thread App), so that should be up soon. As part of that I'll probably add a README on using the pskc generator in /tools since that needs to be used to manually form a network using OTBR.

[DuaneEllis-TI]

1. Agreed - a nice read me would be great - but - we need a pointer to tell the user where to go to find them, example: a file located in the directory: /buried/so/deep/you/cannot/find/it/ha/ha/ha/README.txt are sadly, actually hard to find. :-(

2. that said - There should be a README locally next to the tool and with text that says: "go read the openthread.io" for more details and examples.

3. w.r.t. the "pskc generator' The 'otbr-commissioner' application can - via command line parameters accept either the raw 3 components to the the PSKc (ie: Phrase, NetworkName, and Xpandi) and can compute the PSKc, or you can optionally specify the PSKc on the command line

4. FYI - external commissioning app has many problems:

• The spinning icon spins - but the commissioner does not have a commissioning data set - the NCP will create a log message that says: "Not capable" - the work around is to re-scan the external barcode.

• The commissioning app, when it receives a "COM_KA" response with status = REJECT, the app does not stop the spinning icon

• There are password problems - if you change the name of the network (ie: use otbr-web) and reform a network, changing the name of the network, ie: old: "morning-test-network", new: "noon-test-network" it should ask for a new pass phrase it does nto.

• What is often required on the android app is to: goto Android -> Settings -> Apps -> Select the Thread App -> Delete All Data (do not choose the un-install) - then restart the thread app

[Vyrastas]

Yes, I definitely want to call these things out on openthread.io, so they're easier to find.

For the external commissioner app, I'm assuming those apply to the most recent version. @jwhui is there a way to report bugs or issues with the app? I can add important caveats / troubleshooting to the upcoming guide in the meantime.

[Vyrastas]

External Commissioning content is now live.

https://openthread.io/guides/border_router/external_commissioning

I've got tasks down to handle some of the other concerns brought up, so I'm going to close this Issue, as it's complete for all listed items.

[lanyuwen]

Excellent, thank you Jeff!