OpenThread API を使用した開発

1. はじめに

Nest からリリースされた OpenThread は、Thread® ネットワーキング プロトコルのオープンソース実装です。Google Nest は、Google Nest 製品で使用される技術を広くデベロッパーに提供し、スマートホーム製品の開発を加速させるために OpenThread をリリースしました。

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

この Codelab では、OpenThread API を使用して Thread ネットワークを開始し、デバイスロールの変更を監視して対応するとともに UDP メッセージを送信し、これらのアクションを実際のハードウェア上のボタンと LED に関連付けます。

学習内容

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

必要なもの

ハードウェア:

• Nordic Semiconductor nRF52840 開発ボード x 3
• 3 つの USB - マイクロ USB ケーブル（ボードを接続する）
• USB ポートが 3 つ以上ある Linux マシン

ソフトウェア:

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

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

2. 開始するには

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

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

• ビルドとフラッシュに必要なすべてのソフトウェアの詳細
• OpenThread の構築方法と Nordic nRF52840 ボードへのフラッシュ方法を学習
• Thread ネットワークの基本を示します。

この Codelab では、OpenThread のビルドとボードのフラッシュに必要な環境について詳しく説明しませんが、ボードをフラッシュするための基本的な手順のみを示しています。ここでは、「スレッド ネットワークの構築」Codelab を完了していることを前提としています。

Thread ネットワークの構築 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 パッケージをインストールする必要があります。必要に応じて「スレッド ネットワークの構築」Codelab を完了すれば、インストールに必要な機能がすべて揃います。そうでない場合は、その Codelab を完了してから、OpenThread をビルドして nRF52840 開発ボードに書き込むようにしてください。

Thread ネットワークの構築 Codelab を完了する

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 などのアプリケーション サービス
• ネットワーク認証情報の管理、およびコミッショナーとジョイナーのロール
• ボーダー ルーターの管理
• お子様の管理機能や Jam 検出などの拡張機能

すべての OpenThread API のリファレンス情報は openthread.io/reference にあります。

API の使用

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

たとえば、nRF52840 ボタンと接続に使用する 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 プラットフォームの抽象化を実装する

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

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

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

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

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

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

/**
 * @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 ファイルの include セクションに、ロール変更機能に必要な 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 関数を呼び出すようになります。

/* 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 を点灯する

今回のアプリケーションでは、Button1 でボタンを押したときに、ネットワーク内の他のすべてのデバイスに UDP メッセージを送信します。メッセージの受信を確認するため、応答に応じて他のボードの LED4 をオンに切り替えます。

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

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

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

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

アクション: ヘッダーの追加

main.c ファイルの上部にある include セクションに、マルチキャスト 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 ファイルの include セクションの後、#if ステートメントの前に、UDP 固有の定数を追加して以下を定義します。

#define UDP_PORT 1212

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

ff03::1 は、メッシュローカルのマルチキャスト アドレスです。このアドレスに送信されたメールは、ネットワーク内のすべてのフルスレッド デバイスに送信されます。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 に組み込まれているネットワークのデフォルトがオーバーライドされ、アプリケーションのセキュリティが向上し、ネットワーク内のスレッドノードがアプリケーションを実行しているノードのみに制限されます。

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

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

アクション: ヘッダーの追加。

main.c ファイルの上部にある include セクションに、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 ネットワーク パラメータは次のとおりです。

• チャネル = 15
• PAN ID = 0x2222
• 拡張 PAN ID = C0DE1AB5C0DE1AB5
• ネットワーク キー = 1234C0DE1AB51234C0DE1AB51234C0DE
• ネットワーク名 = OTCodelab

さらに、ルーターの選択用ジッターを減らすため、Google のデバイスではデモの目的でロールをすばやく変更できます。これは、ノードが FTD（フルスレッド デバイス）の場合にのみ行われます。詳しくは次のステップで説明します。

9. API: 制限付き関数

OpenThread の API の中には、デモやテストのためにのみ変更する必要があるものがあります。これらの API は、OpenThread を使用したアプリケーションの本番環境デプロイでは使用しないでください。

たとえば、otThreadSetRouterSelectionJitter 関数は、エンドデバイスが Router に自身を昇格させるのにかかる時間（秒単位）を調整します。この値のデフォルトは、スレッド仕様に従って 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 ソースファイルを追加します。

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

任意のテキスト エディタで ./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 開発ボードに書き込む準備が整いました。各デバイスはフルスレッド デバイス（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 組み込みツールチェーンでこれを 16 進数形式に変換します。

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

ボードをフラッシュする

ot-cli-ftd.hex ファイルを各 nRF52840 ボードにフラッシュします。

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 秒以内に、これらの変化をボード上で確認できました。

UDP マルチキャスト

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

13. デモ: デバイスロールの変更を監視する

フラッシュされたデバイスは、Router Eligible End Device（REED）と呼ばれる特定の種類の Full Thread Device（FTD）です。つまり、お客様は Router またはエンドデバイスのいずれかとして機能し、エンドデバイスから Router に昇格させることができます。

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

また、すべての Thread ネットワークにはリーダーがあります。リーダーは、Thread ネットワーク内の一連の Router を管理するルーターです。すべてのデバイスがオンになっており、20 秒後にはそのうちの 1 つがリーダー（LED1 がオン）になり、他の 2 つのデバイスはルーター（LED2 がオン）になります。

リーダーを削除

リーダーが Thread ネットワークから削除された場合、別の Router は自身をリーダーに昇格し、ネットワークにリーダーが残っていることを確認します。

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

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

ボードをリセットする

3 つすべてのボードの電源を切り、もう一度電源を入れて LED を確認します。電源を入れた最初のボードはリーダーロールで開始する必要があります（LED1 が点灯）。Thread ネットワークの最初のルーターが自動的にリーダーになります。

他の 2 つのボードは、最初はエンドデバイス（LED3 が点灯）としてネットワークに接続しますが、20 秒以内に Router（LED2 は点灯）に昇格させる必要があります。

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

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

スレッドは自己修復するため、パーティションは最終的に 1 つのリーダーを持つ 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 の状態変化を監視して対応する方法
• スレッド ネットワークのすべてのデバイスに UDP メッセージを送信する方法
• Makefile を変更する方法

次のステップ

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

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

関連情報

openthread.io と GitHub で、次のようなさまざまな OpenThread リソースをご確認ください。

• サポートされているプラットフォーム - OpenThread をサポートしているすべてのプラットフォームを確認できます。
• OpenThread のビルド - OpenThread のビルドと構成の詳細
• Thread Primer - Thread のコンセプトの優れたリファレンス

関連資料:

• OpenThread API リファレンス
• Nordic nRF52840 ボードボタンと LED