Google は、黒人コミュニティのための人種的公平の促進に取り組んでいます。詳細をご覧ください。

OpenThread API を使用した開発

1. はじめに

Nest がリリースした OpenThread は、Thread® ネットワーキングプロトコルのオープンソース実装です。Google Nest は、Google Nest 製品で使用されているテクノロジーをデベロッパーが幅広く利用できるように OpenThread をリリースし、スマートホーム向け製品の開発を加速させています。

Thread 仕様では、ホームアプリケーション向けの IPv6 ベースの信頼性が高く安全な低消費電力のワイヤレスデバイス間通信プロトコルを定義しています。OpenThread は、IPv6、6LoWPAN、MAC セキュリティ付き IEEE 802.15.4、メッシュリンク確立、メッシュルーティングなど、すべての Thread ネットワーキングレイヤを実装しています。

この Codelab では、OpenThread API を使用して Thread ネットワークを開始し、デバイスの役割の変化をモニタリングして対応し、UDP メッセージを送信します。また、これらのアクションを実際のハードウェアのボタンと LED に関連付けます。

学習内容

Nordic nRF52840 開発ボードのボタンと LED をプログラミングする方法
一般的な OpenThread API と otInstance クラスの使用方法
OpenThread の状態変化をモニタリングして対応する方法
Thread ネットワーク内のすべてのデバイスに UDP メッセージを送信する方法
Makefile を変更する方法

必要なもの

ハードウェア:

Nordic Semiconductor nRF52840 開発ボード x 3
ボードを接続するための USB - マイクロ USB ケーブル 3 本
3 つ以上の USB ポートを備えた Linux マシン

ソフトウェア:

GNU ツールチェーン
Nordic nRF5x コマンドラインツール
Segger J-Link ソフトウェア
OpenThread
Git

特に記載のない限り、この Codelab のコンテンツは クリエイティブコモンズの表示 3.0 ライセンスにより使用許諾されており、コードサンプルは Apache 2.0 ライセンスにより使用許諾されています。

2. 開始するには

ハードウェア Codelab を完了する

この Codelab を開始する前に、nRF52840 ボードと OpenThread を使用して Thread ネットワークを構築する Codelab を完了する必要があります。この Codelab では、次のことを行います。

ビルドとフラッシュに必要なすべてのソフトウェアの詳細
OpenThread をビルドして Nordic nRF52840 ボードにフラッシュする方法について説明します
Thread ネットワークの基本を示します

OpenThread をビルドしてボードをフラッシュするために必要な環境設定は、この Codelab では説明されていません。ボードをフラッシュするための基本的な手順のみが説明されています。Build a Thread Network Codelab をすでに完了していることを前提としています。

Linux マシン

この Codelab は、i386 ベースまたは x86 ベースの Linux マシンを使用して、すべての Thread 開発ボードをフラッシュすることを前提として設計されています。すべての手順は Ubuntu 14.04.5 LTS（Trusty Tahr）でテストしました。

Nordic Semiconductor nRF52840 ボード

この Codelab では、3 つの nRF52840 PDK ボードを使用します。

ソフトウェアをインストールする

OpenThread をビルドしてフラッシュするには、SEGGER J-Link、nRF5x コマンドラインツール、ARM GNU ツールチェーン、さまざまな Linux パッケージをインストールする必要があります。「Thread ネットワークを構築する」Codelab を完了している場合は、必要なものがすべてインストールされています。まだ完了していない場合は、続行する前にその Codelab を完了して、OpenThread を nRF52840 開発ボードにビルドしてフラッシュできるようにしてください。

3. リポジトリのクローンを作成する

OpenThread には、この Codelab の出発点として使用できるサンプルアプリケーションコードが付属しています。

OpenThread Nordic nRF528xx サンプルリポジトリのクローンを作成し、OpenThread をビルドします。

$ git clone --recursive https://github.com/openthread/ot-nrf528xx
$ cd ot-nrf528xx
$ ./script/bootstrap

4. OpenThread API の基本

OpenThread の公開 API は、OpenThread リポジトリの ./openthread/include/openthread にあります。これらの API は、アプリケーションで使用するために、Thread レベルとプラットフォームレベルの両方でさまざまな OpenThread の機能と機能へのアクセスを提供します。

OpenThread インスタンスの情報と制御
IPv6、UDP、CoAP などのアプリケーションサービス
ネットワーク認証情報の管理（Commissioner と Joiner のロールを含む）
ボーダールーターの管理
お子様の管理やジャム検出などの機能の強化

すべての OpenThread API のリファレンス情報は、openthread.io/reference で入手できます。

API を使用する

API を使用するには、アプリケーションファイルの 1 つに API のヘッダーファイルを組み込みます。次に、目的の関数を呼び出します。

たとえば、OpenThread に含まれている CLI サンプルアプリでは、次の API ヘッダーが使用されています。

./openthread/examples/apps/cli/main.c

#include <openthread/config.h>
#include <openthread/cli.h>
#include <openthread/diag.h>
#include <openthread/tasklet.h>
#include <openthread/platform/logging.h>

OpenThread インスタンス

otInstance 構造は、OpenThread API を使用する際に頻繁に使用するものです。初期化されると、この構造体は OpenThread ライブラリの静的インスタンスを表し、ユーザーは OpenThread API 呼び出しを行うことができます。

たとえば、OpenThread インスタンスは CLI サンプルアプリの main() 関数で初期化されます。

./openthread/examples/apps/cli/main.c

int main(int argc, char *argv[])
{
    otInstance *instance

...

#if OPENTHREAD_ENABLE_MULTIPLE_INSTANCES
    // Call to query the buffer size
    (void)otInstanceInit(NULL, &otInstanceBufferLength);

    // Call to allocate the buffer
    otInstanceBuffer = (uint8_t *)malloc(otInstanceBufferLength);
    assert(otInstanceBuffer);

    // Initialize OpenThread with the buffer
    instance = otInstanceInit(otInstanceBuffer, &otInstanceBufferLength);
#else
    instance = otInstanceInitSingle();
#endif

...

    return 0;
}

プラットフォーム固有の関数

OpenThread に含まれるサンプルアプリケーションのいずれかにプラットフォーム固有の関数を追加する場合は、まず ./openthread/examples/platforms/openthread-system.h ヘッダーでそれらを宣言し、すべての関数に otSys 名前空間を使用します。次に、プラットフォーム固有のソースファイルに実装します。このように抽象化すると、他のプラットフォームの例でも同じ関数ヘッダーを使用できます。

たとえば、nRF52840 のボタンと LED にフックするために使用する GPIO 関数は、openthread-system.h で宣言する必要があります。

任意のテキストエディタで ./openthread/examples/platforms/openthread-system.h ファイルを開きます。

./openthread/examples/platforms/openthread-system.h

アクション: プラットフォーム固有の GPIO 関数宣言を追加します。

openthread/instance.h ヘッダーの #include の後に、次の関数宣言を追加します。

/**
 * Init LED module.
 *
 */
void otSysLedInit(void);
void otSysLedSet(uint8_t aLed, bool aOn);
void otSysLedToggle(uint8_t aLed);

/**
* A callback will be called when GPIO interrupts occur.
*
*/
typedef void (*otSysButtonCallback)(otInstance *aInstance);
void otSysButtonInit(otSysButtonCallback aCallback);
void otSysButtonProcess(otInstance *aInstance);

これらは次のステップで実装します。

otSysButtonProcess 関数宣言では otInstance が使用されていることに注意してください。これにより、必要に応じて、ボタンが押されたときにアプリケーションが OpenThread インスタンスに関する情報にアクセスできるようになります。すべてはアプリケーションのニーズによって異なります。関数の実装で必要ない場合は、OpenThread API の OT_UNUSED_VARIABLE マクロを使用して、一部のツールチェーンで未使用の変数に関するビルドエラーを抑制できます。これについては後ほど例を示します。

5. GPIO プラットフォームの抽象化を実装

前のステップでは、GPIO に使用できる ./openthread/examples/platforms/openthread-system.h のプラットフォーム固有の関数宣言について説明しました。nRF52840 開発ボードのボタンと LED にアクセスするには、nRF52840 プラットフォーム用にこれらの機能を実装する必要があります。このコードでは、次の関数を追加します。

GPIO ピンとモードを初期化する
ピンの電圧を制御する
GPIO 割り込みを有効にしてコールバックを登録する

./src/src ディレクトリに、gpio.c という名前の新しいファイルを作成します。この新しいファイルに次の内容を追加します。

./src/src/gpio.c（新しいファイル）

アクション: 定義を追加します。

これらの定義は、nRF52840 固有の値と OpenThread アプリケーションレベルで使用される変数の間の抽象化として機能します。

/**
 * @file
 *   This file implements the system abstraction for GPIO and GPIOTE.
 *
 */

#define BUTTON_GPIO_PORT 0x50000300UL
#define BUTTON_PIN 11 // button #1

#define GPIO_LOGIC_HI 0
#define GPIO_LOGIC_LOW 1

#define LED_GPIO_PORT 0x50000300UL
#define LED_1_PIN 13 // turn on to indicate leader role
#define LED_2_PIN 14 // turn on to indicate router role
#define LED_3_PIN 15 // turn on to indicate child role
#define LED_4_PIN 16 // turn on to indicate UDP receive

nRF52840 のボタンと LED の詳細については、Nordic Semiconductor Infocenter をご覧ください。

アクション: ヘッダーインクルードを追加します。

次に、GPIO 機能に必要なヘッダーインクルードを追加します。

/* Header for the functions defined here */
#include "openthread-system.h"

#include <string.h>

/* Header to access an OpenThread instance */
#include <openthread/instance.h>

/* Headers for lower-level nRF52840 functions */
#include "platform-nrf5.h"
#include "hal/nrf_gpio.h"
#include "hal/nrf_gpiote.h"
#include "nrfx/drivers/include/nrfx_gpiote.h"

対応: ボタン 1 のコールバック関数と割り込み関数を追加します。

次に、このコードを追加します。in_pin1_handler 関数は、ボタン押下機能が初期化されたときに登録されるコールバックです（このファイルの後半を参照）。

in_pin1_handler に渡された変数は関数内で実際には使用されないため、このコールバックで OT_UNUSED_VARIABLE マクロが使用されていることに注意してください。

/* Declaring callback function for button 1. */
static otSysButtonCallback sButtonHandler;
static bool                sButtonPressed;

/**
 * @brief Function to receive interrupt and call back function
 * set by the application for button 1.
 *
 */
static void in_pin1_handler(uint32_t pin, nrf_gpiote_polarity_t action)
{
    OT_UNUSED_VARIABLE(pin);
    OT_UNUSED_VARIABLE(action);
    sButtonPressed = true;
}

アクション: LED を構成する関数を追加します。

このコードを追加して、初期化中にすべての LED のモードと状態を構成します。

/**
 * @brief Function for configuring: PIN_IN pin for input, PIN_OUT pin for output,
 * and configures GPIOTE to give an interrupt on pin change.
 */

void otSysLedInit(void)
{
    /* Configure GPIO mode: output */
    nrf_gpio_cfg_output(LED_1_PIN);
    nrf_gpio_cfg_output(LED_2_PIN);
    nrf_gpio_cfg_output(LED_3_PIN);
    nrf_gpio_cfg_output(LED_4_PIN);

    /* Clear all output first */
    nrf_gpio_pin_write(LED_1_PIN, GPIO_LOGIC_LOW);
    nrf_gpio_pin_write(LED_2_PIN, GPIO_LOGIC_LOW);
    nrf_gpio_pin_write(LED_3_PIN, GPIO_LOGIC_LOW);
    nrf_gpio_pin_write(LED_4_PIN, GPIO_LOGIC_LOW);

    /* Initialize gpiote for button(s) input.
     Button event handlers are set in the application (main.c) */
    ret_code_t err_code;
    err_code = nrfx_gpiote_init();
    APP_ERROR_CHECK(err_code);
}

アクション: LED のモードを設定する関数を追加します。

この関数は、デバイスのロールが変更されたときに使用されます。

/**
 * @brief Function to set the mode of an LED.
 */

void otSysLedSet(uint8_t aLed, bool aOn)
{
    switch (aLed)
    {
    case 1:
        nrf_gpio_pin_write(LED_1_PIN, (aOn == GPIO_LOGIC_HI));
        break;
    case 2:
        nrf_gpio_pin_write(LED_2_PIN, (aOn == GPIO_LOGIC_HI));
        break;
    case 3:
        nrf_gpio_pin_write(LED_3_PIN, (aOn == GPIO_LOGIC_HI));
        break;
    case 4:
        nrf_gpio_pin_write(LED_4_PIN, (aOn == GPIO_LOGIC_HI));
        break;
    }
}

アクション: LED のモードを切り替える関数を追加します。

この関数は、デバイスがマルチキャスト UDP メッセージを受信したときに LED4 を切り替えるために使用されます。

/**
 * @brief Function to toggle the mode of an LED.
 */
void otSysLedToggle(uint8_t aLed)
{
    switch (aLed)
    {
    case 1:
        nrf_gpio_pin_toggle(LED_1_PIN);
        break;
    case 2:
        nrf_gpio_pin_toggle(LED_2_PIN);
        break;
    case 3:
        nrf_gpio_pin_toggle(LED_3_PIN);
        break;
    case 4:
        nrf_gpio_pin_toggle(LED_4_PIN);
        break;
    }
}

アクション: ボタン押下を初期化して処理する関数を追加します。

最初の関数はボタンを押すためのボードを初期化し、2 番目の関数はボタン 1 が押されたときにマルチキャスト UDP メッセージを送信します。

/**
 * @brief Function to initialize the button.
 */
void otSysButtonInit(otSysButtonCallback aCallback)
{
    nrfx_gpiote_in_config_t in_config = NRFX_GPIOTE_CONFIG_IN_SENSE_LOTOHI(true);
    in_config.pull                    = NRF_GPIO_PIN_PULLUP;

    ret_code_t err_code;
    err_code = nrfx_gpiote_in_init(BUTTON_PIN, &in_config, in_pin1_handler);
    APP_ERROR_CHECK(err_code);

    sButtonHandler = aCallback;
    sButtonPressed = false;

    nrfx_gpiote_in_event_enable(BUTTON_PIN, true);
}

void otSysButtonProcess(otInstance *aInstance)
{
    if (sButtonPressed)
    {
        sButtonPressed = false;
        sButtonHandler(aInstance);
    }
}

操作: gpio.c ファイルを保存して閉じます。

6. API: デバイスの役割の変更に対応

このアプリケーションでは、デバイスの役割に応じて異なる LED を点灯させたいと考えています。リーダー、ルーター、エンドデバイスのロールを追跡しましょう。これらを LED に割り当てることができます。

LED1 = リーダー
LED2 = ルーター
LED3 = エンドデバイス

この機能を有効にするには、デバイスの役割が変更されたタイミングと、それに応じて正しい LED を点灯させる方法をアプリが認識する必要があります。前半では OpenThread インスタンスを使用し、後半では GPIO プラットフォーム抽象化を使用します。

任意のテキストエディタで ./openthread/examples/apps/cli/main.c ファイルを開きます。

./openthread/examples/apps/cli/main.c

アクション: ヘッダーインクルードを追加します。

main.c ファイルの includes セクションに、ロール変更機能に必要な API ヘッダーファイルを追加します。

#include <openthread/instance.h>
#include <openthread/thread.h>
#include <openthread/thread_ftd.h>

アクション: OpenThread インスタンスの状態変化のハンドラ関数宣言を追加します。

この宣言を main.c に追加します。ヘッダーのインクルードの後、#if ステートメントの前に配置します。この関数は、メインアプリケーションの後に定義されます。

void handleNetifStateChanged(uint32_t aFlags, void *aContext);

アクション: 状態変更ハンドラ関数のコールバック登録を追加します。

main.c で、otAppCliInit 呼び出しの後に、この関数を main() 関数に追加します。このコールバック登録により、OpenThread インスタンスの状態が変化するたびに handleNetifStateChange 関数を呼び出すよう OpenThread に指示します。

/* Register Thread state change handler */
otSetStateChangedCallback(instance, handleNetifStateChanged, instance);

アクション: 状態変更の実装を追加します。

main.c で、main() 関数の後に handleNetifStateChanged 関数を実装します。この関数は、OpenThread インスタンスの OT_CHANGED_THREAD_ROLE フラグを確認し、変更されている場合は、必要に応じて LED をオン/オフにします。

void handleNetifStateChanged(uint32_t aFlags, void *aContext)
{
   if ((aFlags & OT_CHANGED_THREAD_ROLE) != 0)
   {
       otDeviceRole changedRole = otThreadGetDeviceRole(aContext);

       switch (changedRole)
       {
       case OT_DEVICE_ROLE_LEADER:
           otSysLedSet(1, true);
           otSysLedSet(2, false);
           otSysLedSet(3, false);
           break;

       case OT_DEVICE_ROLE_ROUTER:
           otSysLedSet(1, false);
           otSysLedSet(2, true);
           otSysLedSet(3, false);
           break;

       case OT_DEVICE_ROLE_CHILD:
           otSysLedSet(1, false);
           otSysLedSet(2, false);
           otSysLedSet(3, true);
           break;

       case OT_DEVICE_ROLE_DETACHED:
       case OT_DEVICE_ROLE_DISABLED:
           /* Clear LED4 if Thread is not enabled. */
           otSysLedSet(4, false);
           break;
        }
    }
}

7. API: マルチキャストを使用して LED をオンにする

このアプリケーションでは、1 つのボードで Button1 が押されたときに、ネットワーク内の他のすべてのデバイスに UDP メッセージを送信することも必要です。メッセージの受信を確認するため、他のボードの LED4 を切り替えます。

この機能を有効にするには、アプリで次の処理を行う必要があります。

起動時に UDP 接続を初期化
メッシュローカルマルチキャストアドレスに UDP メッセージを送信できる
受信した UDP メッセージを処理する
受信した UDP メッセージに応じて LED4 を切り替える

任意のテキストエディタで ./openthread/examples/apps/cli/main.c ファイルを開きます。

./openthread/examples/apps/cli/main.c

アクション: ヘッダーインクルードを追加します。

main.c ファイルの上部にある includes セクションに、マルチキャスト UDP 機能に必要な API ヘッダーファイルを追加します。

#include <string.h>

#include <openthread/message.h>
#include <openthread/udp.h>

#include "utils/code_utils.h"

code_utils.h ヘッダーは、実行時の条件を検証し、エラーを適切に処理する otEXPECT マクロと otEXPECT_ACTION マクロに使用されます。

アクション: 定義と定数を追加します。

main.c ファイルの includes セクションの後、#if ステートメントの前に、UDP 固有の定数と定義を追加します。

#define UDP_PORT 1212

static const char UDP_DEST_ADDR[] = "ff03::1";
static const char UDP_PAYLOAD[]   = "Hello OpenThread World!";

ff03::1 は、メッシュローカルマルチキャストアドレスです。このアドレスに送信されたメッセージは、ネットワーク内のすべての Full Thread Device に送信されます。OpenThread でのマルチキャストサポートの詳細については、openthread.io のマルチキャストをご覧ください。

対応: 関数宣言を追加します。

main.c ファイルで、otTaskletsSignalPending 定義の後、main() 関数の前に、UDP 固有の関数と、UDP ソケットを表す静的変数を追加します。

static void initUdp(otInstance *aInstance);
static void sendUdp(otInstance *aInstance);

static void handleButtonInterrupt(otInstance *aInstance);

void handleUdpReceive(void *aContext, otMessage *aMessage, 
                      const otMessageInfo *aMessageInfo);

static otUdpSocket sUdpSocket;

アクション: GPIO LED とボタンを初期化する呼び出しを追加します。

main.c で、これらの関数呼び出しを otSetStateChangedCallback 呼び出しの後に main() 関数に追加します。これらの関数は、GPIO ピンと GPIOTE ピンを初期化し、ボタンハンドラを設定してボタンのプッシュイベントを処理します。

/* init GPIO LEDs and button */
otSysLedInit();
otSysButtonInit(handleButtonInterrupt);

アクション: UDP 初期化呼び出しを追加します。

main.c で、追加した otSysButtonInit 呼び出しの後に、main() 関数に次の関数を追加します。

initUdp(instance);

この呼び出しにより、アプリの起動時に UDP ソケットが確実に初期化されます。これがないと、デバイスは UDP メッセージを送受信できません。

アクション: GPIO ボタンイベントを処理する呼び出しを追加します。

main.c で、while ループ内の otSysProcessDrivers 呼び出しの後に、main() 関数に次の関数呼び出しを追加します。gpio.c で宣言されたこの関数は、ボタンが押されたかどうかを確認し、押された場合は、上記の手順で設定されたハンドラ（handleButtonInterrupt）を呼び出します。

otSysButtonProcess(instance);

対応: ボタン割り込みハンドラを実装します。

main.c で、前のステップで追加した handleNetifStateChanged 関数の後に、handleButtonInterrupt 関数の実装を追加します。

/**
 * Function to handle button push event
 */
void handleButtonInterrupt(otInstance *aInstance)
{
    sendUdp(aInstance);
}

アクション: UDP の初期化を実装します。

main.c で、先ほど追加した handleButtonInterrupt 関数の後に initUdp 関数の実装を追加します。

/**
 * Initialize UDP socket
 */
void initUdp(otInstance *aInstance)
{
    otSockAddr  listenSockAddr;

    memset(&sUdpSocket, 0, sizeof(sUdpSocket));
    memset(&listenSockAddr, 0, sizeof(listenSockAddr));

    listenSockAddr.mPort    = UDP_PORT;

    otUdpOpen(aInstance, &sUdpSocket, handleUdpReceive, aInstance);
    otUdpBind(aInstance, &sUdpSocket, &listenSockAddr, OT_NETIF_THREAD);
}

UDP_PORT は、前に定義したポート（1212）です。otUdpOpen 関数は、ソケットを開き、UDP メッセージを受信したときに呼び出されるコールバック関数（handleUdpReceive）を登録します。otUdpBind は、OT_NETIF_THREAD を渡すことで、ソケットを Thread ネットワークインターフェースにバインドします。その他のネットワークインターフェースオプションについては、UDP API リファレンスの otNetifIdentifier 列挙型をご覧ください。

対応: UDP メッセージングを実装します。

main.c で、先ほど追加した initUdp 関数の後に sendUdp 関数の実装を追加します。

/**
 * Send a UDP datagram
 */
void sendUdp(otInstance *aInstance)
{
    otError       error = OT_ERROR_NONE;
    otMessage *   message;
    otMessageInfo messageInfo;
    otIp6Address  destinationAddr;

    memset(&messageInfo, 0, sizeof(messageInfo));

    otIp6AddressFromString(UDP_DEST_ADDR, &destinationAddr);
    messageInfo.mPeerAddr    = destinationAddr;
    messageInfo.mPeerPort    = UDP_PORT;

    message = otUdpNewMessage(aInstance, NULL);
    otEXPECT_ACTION(message != NULL, error = OT_ERROR_NO_BUFS);

    error = otMessageAppend(message, UDP_PAYLOAD, sizeof(UDP_PAYLOAD));
    otEXPECT(error == OT_ERROR_NONE);

    error = otUdpSend(aInstance, &sUdpSocket, message, &messageInfo);

 exit:
    if (error != OT_ERROR_NONE && message != NULL)
    {
        otMessageFree(message);
    }
}

otEXPECT マクロと otEXPECT_ACTION マクロに注意してください。これにより、UDP メッセージが有効で、バッファに正しく割り当てられていることを確認します。そうでない場合、関数は exit ブロックにジャンプしてバッファを解放することで、エラーを適切に処理します。

UDP の初期化に使用される関数の詳細については、openthread.io の IPv6 と UDP のリファレンスをご覧ください。

アクション: UDP メッセージ処理を実装します。

main.c で、先ほど追加した sendUdp 関数の後に handleUdpReceive 関数の実装を追加します。この関数は LED4 を切り替えるだけです。

/**
 * Function to handle UDP datagrams received on the listening socket
 */
void handleUdpReceive(void *aContext, otMessage *aMessage,
                      const otMessageInfo *aMessageInfo)
{
    OT_UNUSED_VARIABLE(aContext);
    OT_UNUSED_VARIABLE(aMessage);
    OT_UNUSED_VARIABLE(aMessageInfo);

    otSysLedToggle(4);
}

8. API: Thread ネットワークを構成する

デモを簡単にするため、デバイスの電源を入れるとすぐに Thread が起動し、ネットワークに接続されるようにします。これを行うには、otOperationalDataset 構造体を使用します。この構造体には、Thread ネットワークの認証情報をデバイスに送信するために必要なすべてのパラメータが保持されます。

この構造を使用すると、OpenThread に組み込まれているネットワークのデフォルトがオーバーライドされ、アプリケーションのセキュリティが強化され、ネットワーク内の Thread ノードがアプリケーションを実行しているノードのみに制限されます。

任意のテキストエディタで ./openthread/examples/apps/cli/main.c ファイルを再度開きます。

./openthread/examples/apps/cli/main.c

アクション: ヘッダーインクルードを追加します。

main.c ファイルの先頭にある includes セクションに、Thread ネットワークの構成に必要な API ヘッダーファイルを追加します。

#include <openthread/dataset_ftd.h>

アクション: ネットワーク設定を行うための関数宣言を追加します。

この宣言を main.c に追加します。ヘッダーのインクルードの後、#if ステートメントの前に配置します。この関数は、メインアプリケーション関数の後に定義されます。

static void setNetworkConfiguration(otInstance *aInstance);

アクション: ネットワーク構成呼び出しを追加します。

main.c で、otSetStateChangedCallback 呼び出しの後に、main() 関数に次の関数呼び出しを追加します。この関数は、Thread ネットワークデータセットを構成します。

/* Override default network credentials */
setNetworkConfiguration(instance);

アクション: Thread ネットワークインターフェースとスタックを有効にする呼び出しを追加します。

main.c で、これらの関数呼び出しを otSysButtonInit 呼び出しの後に main() 関数に追加します。

/* Start the Thread network interface (CLI cmd > ifconfig up) */
otIp6SetEnabled(instance, true);

/* Start the Thread stack (CLI cmd > thread start) */
otThreadSetEnabled(instance, true);

アクション: Thread ネットワーク構成を実装します。

main.c で、main() 関数の後に setNetworkConfiguration 関数の実装を追加します。

/**
 * Override default network settings, such as panid, so the devices can join a
 network
 */
void setNetworkConfiguration(otInstance *aInstance)
{
    static char          aNetworkName[] = "OTCodelab";
    otOperationalDataset aDataset;

    memset(&aDataset, 0, sizeof(otOperationalDataset));

    /*
     * Fields that can be configured in otOperationDataset to override defaults:
     *     Network Name, Mesh Local Prefix, Extended PAN ID, PAN ID, Delay Timer,
     *     Channel, Channel Mask Page 0, Network Key, PSKc, Security Policy
     */
    aDataset.mActiveTimestamp.mSeconds             = 1;
    aDataset.mActiveTimestamp.mTicks               = 0;
    aDataset.mActiveTimestamp.mAuthoritative       = false;
    aDataset.mComponents.mIsActiveTimestampPresent = true;

    /* Set Channel to 15 */
    aDataset.mChannel                      = 15;
    aDataset.mComponents.mIsChannelPresent = true;

    /* Set Pan ID to 2222 */
    aDataset.mPanId                      = (otPanId)0x2222;
    aDataset.mComponents.mIsPanIdPresent = true;

    /* Set Extended Pan ID to C0DE1AB5C0DE1AB5 */
    uint8_t extPanId[OT_EXT_PAN_ID_SIZE] = {0xC0, 0xDE, 0x1A, 0xB5, 0xC0, 0xDE, 0x1A, 0xB5};
    memcpy(aDataset.mExtendedPanId.m8, extPanId, sizeof(aDataset.mExtendedPanId));
    aDataset.mComponents.mIsExtendedPanIdPresent = true;

    /* Set network key to 1234C0DE1AB51234C0DE1AB51234C0DE */
    uint8_t key[OT_NETWORK_KEY_SIZE] = {0x12, 0x34, 0xC0, 0xDE, 0x1A, 0xB5, 0x12, 0x34, 0xC0, 0xDE, 0x1A, 0xB5, 0x12, 0x34, 0xC0, 0xDE};
    memcpy(aDataset.mNetworkKey.m8, key, sizeof(aDataset.mNetworkKey));
    aDataset.mComponents.mIsNetworkKeyPresent = true;

    /* Set Network Name to OTCodelab */
    size_t length = strlen(aNetworkName);
    assert(length <= OT_NETWORK_NAME_MAX_SIZE);
    memcpy(aDataset.mNetworkName.m8, aNetworkName, length);
    aDataset.mComponents.mIsNetworkNamePresent = true;

    otDatasetSetActive(aInstance, &aDataset);
    /* Set the router selection jitter to override the 2 minute default.
       CLI cmd > routerselectionjitter 20
       Warning: For demo purposes only - not to be used in a real product */
    uint8_t jitterValue = 20;
    otThreadSetRouterSelectionJitter(aInstance, jitterValue);
}

関数で詳しく説明されているように、このアプリで使用している Thread ネットワークパラメータは次のとおりです。

Channel = 15
PAN ID = 0x2222
拡張 PAN ID = C0DE1AB5C0DE1AB5
ネットワークキー = 1234C0DE1AB51234C0DE1AB51234C0DE
Network Name = OTCodelab

また、ここではルーター選択ジッターを減らして、デモ用にデバイスの役割をより迅速に変更します。これは、ノードが FTD（Full Thread Device）の場合にのみ行われます。詳しくは次のステップで説明します。

9. API: 制限付き関数

OpenThread の API の一部は、デモやテストの目的でのみ変更すべき設定を変更します。これらの API は、OpenThread を使用するアプリの本番環境へのデプロイでは使用しないでください。

たとえば、otThreadSetRouterSelectionJitter 関数は、エンドデバイスがルーターに昇格するのにかかる時間（秒単位）を調整します。Thread 仕様に従い、この値のデフォルトは 120 です。この Codelab では、使いやすさを考慮して 20 に変更します。これにより、Thread ノードがロールを変更するまで長く待つ必要がなくなります。

注: MTD デバイスはルーターにはならず、otThreadSetRouterSelectionJitter などの機能のサポートは MTD ビルドには含まれていません。後で CMake オプション -DOT_MTD=OFF を指定する必要があります。指定しないと、ビルドが失敗します。

これは、OPENTHREAD_FTD のプリプロセッサディレクティブに含まれる otThreadSetRouterSelectionJitter 関数定義を確認することで確認できます。

./openthread/src/core/api/thread_ftd_api.cpp

#if OPENTHREAD_FTD

#include <openthread/thread_ftd.h>

...

void otThreadSetRouterSelectionJitter(otInstance *aInstance, uint8_t aRouterJitter)
{
    Instance &instance = *static_cast<Instance *>(aInstance);

    instance.GetThreadNetif().GetMle().SetRouterSelectionJitter(aRouterJitter);
}

...

#endif // OPENTHREAD_FTD

10. CMake の更新

アプリケーションをビルドする前に、3 つの CMake ファイルにいくつかの小さな更新が必要です。これらは、ビルドシステムがアプリケーションをコンパイルしてリンクするために使用されます。

./third_party/NordicSemiconductor/CMakeLists.txt

次に、NordicSemiconductor CMakeLists.txt にフラグを追加して、GPIO 関数がアプリケーションで定義されていることを確認します。

アクション: CMakeLists.txt ファイルにフラグを追加します。

任意のテキストエディタで ./third_party/NordicSemiconductor/CMakeLists.txt を開き、COMMON_FLAG セクションに次の行を追加します。

...
set(COMMON_FLAG
    -DSPIS_ENABLED=1
    -DSPIS0_ENABLED=1
    -DNRFX_SPIS_ENABLED=1
    -DNRFX_SPIS0_ENABLED=1
    ...

    # Defined in ./third_party/NordicSemiconductor/nrfx/templates/nRF52840/nrfx_config.h
    -DGPIOTE_ENABLED=1
    -DGPIOTE_CONFIG_IRQ_PRIORITY=7
    -DGPIOTE_CONFIG_NUM_OF_LOW_POWER_EVENTS=1
)

...

./src/CMakeLists.txt

./src/CMakeLists.txt ファイルを編集して、新しい gpio.c ソースファイルを追加します。

アクション: ./src/CMakeLists.txt ファイルに gpio ソースを追加します。

任意のテキストエディタで ./src/CMakeLists.txt を開き、NRF_COMM_SOURCES セクションにファイルを追加します。

...

set(NRF_COMM_SOURCES
  ...
  src/gpio.c
  ...
)

...

./third_party/NordicSemiconductor/CMakeLists.txt

最後に、nrfx_gpiote.c ドライバファイルを NordicSemiconductor CMakeLists.txt ファイルに追加して、Nordic ドライバのライブラリビルドに含めます。

アクション: gpio ドライバを NordicSemiconductor CMakeLists.txt ファイルに追加します。

任意のテキストエディタで ./third_party/NordicSemiconductor/CMakeLists.txt を開き、COMMON_SOURCES セクションにファイルを追加します。

...

set(COMMON_SOURCES
  ...
  nrfx/drivers/src/nrfx_gpiote.c
  ...
)
...

11. デバイスをセットアップする

すべてのコード更新が完了したら、アプリケーションをビルドして、3 つの Nordic nRF52840 開発ボードすべてにフラッシュする準備が整います。各デバイスは Full Thread Device（FTD）として機能します。

OpenThread をビルドする

nRF52840 プラットフォーム用の OpenThread FTD バイナリをビルドします。

$ cd ~/ot-nrf528xx
$ ./script/build nrf52840 UART_trans -DOT_MTD=OFF -DOT_APP_RCP=OFF -DOT_RCP=OFF

OpenThread FTD CLI バイナリを含むディレクトリに移動し、ARM Embedded Toolchain を使用して 16 進形式に変換します。

$ cd build/bin
$ arm-none-eabi-objcopy -O ihex ot-cli-ftd ot-cli-ftd.hex

ボードをフラッシュする

各 nRF52840 ボードに ot-cli-ftd.hex ファイルを書き込みます。

nRF52840 ボードの外部電源ピンの横にあるマイクロ USB デバッグポートに USB ケーブルを接続し、Linux マシンに差し込みます。正しく設定すると、LED5 が点灯します。

前と同様に、nRF52840 ボードのシリアル番号をメモします。

nRFx コマンドラインツールの場所に移動し、ボードのシリアル番号を使用して、OpenThread CLI FTD の 16 進数ファイルを nRF52840 ボードに書き込みます。

$ cd ~/nrfjprog
$ ./nrfjprog -f nrf52 -s 683704924 --verify --chiperase --program \
       ~/openthread/output/nrf52840/bin/ot-cli-ftd.hex --reset

点滅中に LED5 が一時的に消灯します。成功すると、次の出力が生成されます。

Parsing hex file.
Erasing user available code and UICR flash areas.
Applying system reset.
Checking that the area to write is not protected.
Programing device.
Applying system reset.
Run.

他の 2 つのボードについても、この「ボードをフラッシュする」の手順を繰り返します。各ボードは同じ方法で Linux マシンに接続する必要があります。ボードのシリアル番号を除き、フラッシュするコマンドは同じです。各ボードの一意のシリアル番号を

nrfjprog フラッシュコマンド。

成功すると、各ボードの LED1、LED2、LED3 のいずれかが点灯します。点灯している LED が点滅後すぐに 3 から 2（または 2 から 1）に切り替わることもあります（デバイスの役割変更機能）。

12. アプリケーションの機能

3 つの nRF52840 ボードすべてに電力が供給され、OpenThread アプリケーションが実行されているはずです。前述のとおり、このアプリケーションには 2 つの主な機能があります。

デバイスの役割インジケーター

各ボードの点灯している LED は、Thread ノードの現在の役割を示します。

LED1 = リーダー
LED2 = ルーター
LED3 = エンドデバイス

役割が変わると、点灯する LED も変わります。これらの変更は、各デバイスの電源投入後 20 秒以内に 1 つまたは 2 つのボードに反映されます。

UDP マルチキャスト

ボードの Button1 が押されると、UDP メッセージがメッシュローカルマルチキャストアドレスに送信されます。このアドレスには、Thread ネットワーク内の他のすべてのノードが含まれます。このメッセージを受信すると、他のすべてのボードの LED4 がオンまたはオフに切り替わります。LED4 は、別の UDP メッセージを受信するまで、各ボードでオンまたはオフのままになります。

13. デモ: デバイスの役割の変更を観察する

フラッシュしたデバイスは、ルーター対応エンドデバイス（REED）と呼ばれる特定の種類のフル Thread デバイス（FTD）です。つまり、ルーターまたはエンドデバイスとして機能し、エンドデバイスからルーターに昇格できます。

Thread は最大 32 個のルーターをサポートできますが、ルーターの数を 16 ～ 23 個に保つようにします。REED がエンドデバイスとして接続され、ルーターの数が 16 未満の場合、自動的にルーターに昇格します。この変更は、アプリケーションで otThreadSetRouterSelectionJitter 値に設定した秒数（20 秒）以内のランダムなタイミングで発生します。

すべての Thread ネットワークにはリーダーも存在します。リーダーは、Thread ネットワーク内のルーターのセットを管理するルーターです。すべてのデバイスの電源をオンにしてから 20 秒ほど経つと、1 つがリーダー（LED1 が点灯）、残りの 2 つがルーター（LED2 が点灯）になります。

リーダーを削除する

リーダーが Thread ネットワークから削除されると、別のルーターがリーダーに昇格し、ネットワークにリーダーが残るようにします。

電源スイッチを使用して、リーダーボード（LED1 が点灯しているもの）をオフにします。20 秒ほど待ちます。残りの 2 つのボードのうちの 1 つで、LED2（ルーター）がオフになり、LED1（リーダー）がオンになります。このデバイスが Thread ネットワークのリーダーになりました。

元のリーダーボードを再度有効にします。エンドデバイスとして Thread ネットワークに自動的に再接続されます（LED3 が点灯します）。20 秒以内（ルーター選択ジッター）に、ルーターに昇格します（LED2 が点灯します）。

ボードをリセットする

3 つのボードすべてをオフにしてから、再びオンにして LED を確認します。最初に電源が投入されたボードはリーダーの役割で起動します（LED1 が点灯）。Thread ネットワークの最初のルーターは自動的にリーダーになります。

他の 2 つのボードは、最初はエンドデバイスとしてネットワークに接続されます（LED3 が点灯）。ただし、20 秒以内にルーターに昇格します（LED2 が点灯）。

ネットワークパーティション

ボードに十分な電力が供給されていない場合や、ボード間の無線接続が弱い場合、Thread ネットワークがパーティションに分割され、リーダーとして表示されるデバイスが複数になることがあります。

スレッドは自己修復するため、パーティションは最終的に 1 つのリーダーを持つ単一のパーティションにマージされます。

14. デモ: UDP マルチキャストを送信する

前回の演習から続行する場合は、どのデバイスでも LED4 が点灯していないはずです。

任意のボードを選択して Button1 を押します。アプリケーションを実行している Thread ネットワーク内の他のすべてのボードの LED4 の状態が切り替わります。前の演習から続行している場合は、オンになっているはずです。

同じボードの Button1 をもう一度押します。他のすべてのボードの LED4 が再び切り替わります。

別のボードの Button1 を押して、他のボードの LED4 が切り替わる様子を確認します。LED4 が点灯しているボードのいずれかで Button1 を押します。LED4 はそのボードでは点灯したままですが、他のボードでは切り替わります。

ネットワークパーティション

ボードがパーティショニングされていて、複数のリーダーが存在する場合、マルチキャストメッセージの結果はボード間で異なります。パーティション分割されたボード（パーティション分割された Thread ネットワークの唯一のメンバー）で Button1 を押すと、他のボードの LED4 は点灯しません。この場合は、ボードをリセットします。理想的には、単一の Thread ネットワークが再形成され、UDP メッセージングが正しく動作するはずです。

15. 完了

OpenThread API を使用するアプリケーションを作成しました。

これで、次のことがわかりました。

Nordic nRF52840 開発ボードのボタンと LED をプログラミングする方法
一般的な OpenThread API と otInstance クラスの使用方法
OpenThread の状態変化をモニタリングして対応する方法
Thread ネットワーク内のすべてのデバイスに UDP メッセージを送信する方法
Makefile を変更する方法

次のステップ

この Codelab で学んだことを活かして、以下の演習に挑戦してみましょう。

オンボード LED の代わりに GPIO ピンを使用するように GPIO モジュールを変更し、ルーターの役割に基づいて色が変わる外部 RGB LED を接続する
別のサンプルプラットフォームの GPIO サポートを追加
ボタンを押したときにマルチキャストを使用してすべてのデバイスに ping を送信するのではなく、ルーター/リーダー API を使用して個々のデバイスを特定し、ping を送信します。
OpenThread ボーダールーターを使用してメッシュネットワークをインターネットに接続し、Thread ネットワークの外部からマルチキャストして LED を点灯させる

OpenThread API を使用した開発 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

1. はじめに

学習内容

必要なもの

2. 開始するには

ハードウェア Codelab を完了する

Linux マシン

Nordic Semiconductor nRF52840 ボード

ソフトウェアをインストールする

3. リポジトリのクローンを作成する

4. OpenThread API の基本

API を使用する

OpenThread インスタンス

プラットフォーム固有の関数

5. GPIO プラットフォームの抽象化を実装

./src/src/gpio.c（新しいファイル）

6. API: デバイスの役割の変更に対応

7. API: マルチキャストを使用して LED をオンにする

8. API: Thread ネットワークを構成する

9. API: 制限付き関数

10. CMake の更新

11. デバイスをセットアップする

OpenThread をビルドする

ボードをフラッシュする

12. アプリケーションの機能

デバイスの役割インジケーター

UDP マルチキャスト

13. デモ: デバイスの役割の変更を観察する

リーダーを削除する

ボードをリセットする

ネットワーク パーティション

14. デモ: UDP マルチキャストを送信する

ネットワーク パーティション

15. 完了

次のステップ

関連情報

OpenThread API を使用した開発

ネットワークパーティション

ネットワークパーティション