Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

Mengembangkan dengan OpenThread API

1. Pengantar

26b7f4f6b3ea0700.png

OpenThread yang dirilis oleh Nest adalah implementasi open source protokol jaringan Thread®. Nest telah merilis OpenThread untuk menyediakan teknologi yang digunakan di produk Nest secara luas bagi developer guna mempercepat pengembangan produk untuk rumah yang terhubung.

Spesifikasi Thread menetapkan protokol komunikasi perangkat-ke-perangkat nirkabel berbasis IPv6 yang andal, aman, dan rendah daya untuk aplikasi rumah. OpenThread mengimplementasikan semua lapisan jaringan Thread termasuk IPv6, 6LoWPAN, IEEE 802.15.4 dengan keamanan MAC, Mesh Link Assignment, dan Mesh Routing.

Dalam Codelab ini, Anda akan menggunakan OpenThread API untuk memulai jaringan Thread, memantau dan bereaksi terhadap perubahan peran perangkat, serta mengirim pesan UDP, serta mengaitkan tindakan ini ke tombol dan LED pada hardware sungguhan.

2a6db2e258c32237.png

Yang akan Anda pelajari

  • Cara memprogram tombol dan LED pada papan pengembangan Nordic nRF52840
  • Cara menggunakan OpenThread API umum dan class otInstance
  • Cara memantau dan bereaksi terhadap perubahan status OpenThread
  • Cara mengirim pesan UDP ke semua perangkat dalam jaringan Thread
  • Cara mengubah Makefile

Yang Anda butuhkan

Perangkat keras:

  • 3 papan dev Nordic Semiconductor nRF52840
  • 3 kabel USB ke USB Mikro untuk menghubungkan papan
  • Mesin Linux dengan setidaknya 3 port USB

Perangkat lunak:

  • Toolchain GNU
  • Alat command line Nordic nRF5x
  • Software Segger J-Link
  • OpenThread
  • Git

Kecuali dinyatakan lain, konten Codelab ini dilisensikan berdasarkan Lisensi Creative Commons Attribution 3.0, dan contoh kode dilisensikan berdasarkan Lisensi Apache 2.0.

2. Memulai

Menyelesaikan Codelab Hardware

Sebelum memulai Codelab ini, Anda harus menyelesaikan Codelab Build a Thread Network dengan nRF52840 Boards dan OpenThread, yang:

  • Detail semua software yang Anda perlukan untuk membuat dan mem-flash
  • Mengajari Anda cara mem-build OpenThread dan mem-flash-nya di papan Nordic nRF52840
  • Menunjukkan dasar-dasar jaringan Thread

Tidak ada lingkungan yang disiapkan untuk mem-build OpenThread dan mem-flash board yang dijelaskan di Codelab ini—hanya petunjuk dasar untuk melakukan board. Diasumsikan bahwa Anda telah menyelesaikan Codelab Jaringan Build a Thread.

Mesin Linux

Codelab ini dirancang untuk menggunakan mesin Linux berbasis i386 atau x86 untuk mem-flash semua board pengembangan Thread. Semua langkah telah diuji di Ubuntu 14.04.5 LTS (Trusty Tahr).

Papan Nordic Semiconductor nRF52840

Codelab ini menggunakan tiga board nRF52840 PDK.

a6693da3ce213856.png

Instal Software

Untuk membuat dan mem-flash OpenThread, Anda perlu menginstal SEGGER J-Link, alat nRF5x Command Line, ARM GNU Toolchain, dan berbagai paket Linux. Jika sudah menyelesaikan Codelab Membuat Jaringan Thread sebagaimana diperlukan, Anda harus sudah menginstal semua yang diperlukan. Jika tidak, selesaikan Codelab tersebut sebelum melanjutkan untuk memastikan Anda dapat mem-build dan mem-flash OpenThread ke board dev nRF52840.

3. Membuat cloning repositori

OpenThread dilengkapi dengan contoh kode aplikasi yang bisa Anda gunakan sebagai titik awal untuk Codelab ini.

Clone contoh OpenThread Nordic nRF528xx repo dan build OpenThread:

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

4. Dasar-Dasar API OpenThread

API publik OpenThread terletak di ./openthread/include/openthread di repositori OpenThread. API ini menyediakan akses ke berbagai fitur dan fungsionalitas OpenThread pada tingkat Thread dan platform untuk digunakan dalam aplikasi Anda:

  • Kontrol dan informasi instance OpenThread
  • Layanan aplikasi seperti IPv6, UDP, dan CoAP
  • Pengelolaan kredensial jaringan, beserta peran Komisaris dan Joiner
  • Pengelolaan Border Router
  • Fitur yang disempurnakan seperti Pengawasan Anak dan Deteksi Jam

Informasi referensi mengenai semua API OpenThread tersedia di openthread.io/reference.

Menggunakan API

Untuk menggunakan API, sertakan file header-nya di salah satu file aplikasi Anda. Kemudian, panggil fungsi yang diinginkan.

Misalnya, aplikasi contoh CLI yang disertakan dengan OpenThread menggunakan header API berikut:

./threadthread/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>

Instance OpenThread

Struktur otInstance adalah sesuatu yang akan sering Anda gunakan saat bekerja dengan OpenThread API. Setelah diinisialisasi, struktur ini mewakili instance statis library OpenThread dan memungkinkan pengguna melakukan panggilan OpenThread API.

Misalnya, instance OpenThread diinisialisasi dalam fungsi main() dari aplikasi contoh CLI:

./threadthread/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;
}

Fungsi khusus platform

Jika Anda ingin menambahkan fungsi khusus platform ke salah satu aplikasi contoh yang disertakan dengan OpenThread, pertama-tama deklarasikan fungsi tersebut di header ./openthread/examples/platforms/openthread-system.h, menggunakan namespace otSys untuk semua fungsi. Kemudian, terapkan kode tersebut dalam file sumber khusus platform. Diabstraksi dengan cara ini, Anda dapat menggunakan header fungsi yang sama untuk platform contoh lainnya.

Misalnya, fungsi GPIO yang akan kita gunakan untuk terhubung ke tombol nRF52840 dan LED harus dideklarasikan di openthread-system.h.

Buka file ./openthread/examples/platforms/openthread-system.h dalam editor teks pilihan Anda.

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

TINDAKAN: Tambahkan deklarasi fungsi GPIO khusus platform.

Tambahkan deklarasi fungsi ini setelah #include untuk header openthread/instance.h:

/**
 * 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);

Kami akan menerapkannya pada langkah berikutnya.

Perhatikan bahwa deklarasi fungsi otSysButtonProcess menggunakan otInstance. Dengan begitu, aplikasi dapat mengakses informasi tentang instance OpenThread saat tombol ditekan, jika diperlukan. Semuanya bergantung pada kebutuhan aplikasi Anda. Jika tidak memerlukannya dalam implementasi fungsi, Anda dapat menggunakan makro OT_UNUSED_VARIABLE dari OpenThread API untuk menyembunyikan error build terkait variabel yang tidak digunakan untuk beberapa toolchain. Kita akan melihat contohnya nanti.

5. Mengimplementasikan abstraksi platform GPIO

Pada langkah sebelumnya, kita telah membahas deklarasi fungsi khusus platform di ./openthread/examples/platforms/openthread-system.h yang dapat digunakan untuk GPIO. Untuk mengakses tombol dan LED pada papan dev nRF52840, Anda perlu menerapkan fungsi tersebut untuk platform nRF52840. Dalam kode ini, Anda akan menambahkan fungsi yang:

  • Menginisialisasi pin dan mode GPIO
  • Mengontrol voltase di pin
  • Mengaktifkan interupsi GPIO dan mendaftarkan callback

Di direktori ./src/src, buat file baru bernama gpio.c. Dalam file baru ini, tambahkan konten berikut.

./src/src/gpio.c (file baru)

TINDAKAN: Tambahkan definisi.

Definisi ini berfungsi sebagai abstraksi antara nilai spesifik nRF52840 dan variabel yang digunakan di level aplikasi 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

Untuk informasi selengkapnya tentang tombol dan LED nRF52840, lihat Pusat Informasi Semikonduktor Nordic.

TINDAKAN: Tambahkan header yang disertakan.

Berikutnya, tambahkan header dengan menyertakan yang Anda perlukan untuk fungsi 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"

ACTION: Tambahkan fungsi callback dan interupsi untuk Tombol 1.

Berikutnya, tambahkan kode ini. Fungsi in_pin1_handler adalah callback yang terdaftar saat fungsi penekanan tombol diinisialisasi (kemudian dalam file ini).

Perhatikan bahwa callback ini menggunakan makro OT_UNUSED_VARIABLE, karena variabel yang diteruskan ke in_pin1_handler tidak benar-benar digunakan dalam fungsi.

/* 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;
}

TINDAKAN: Tambahkan fungsi untuk mengonfigurasi LED.

Tambahkan kode ini untuk mengonfigurasi mode dan status semua LED selama inisialisasi.

/**
 * @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);
}

TINDAKAN: Tambahkan fungsi untuk menyetel mode LED.

Fungsi ini akan digunakan saat peran perangkat berubah.

/**
 * @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;
    }
}

TINDAKAN: Tambahkan fungsi untuk beralih mode LED.

Fungsi ini akan digunakan untuk mengaktifkan LED4 saat perangkat menerima pesan UDP multicast.

/**
 * @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;
    }
}

TINDAKAN: Tambahkan fungsi untuk menginisialisasi dan memproses penekanan tombol.

Fungsi pertama menginisialisasi board untuk menekan tombol, dan yang kedua mengirimkan pesan UDP multicast saat Tombol 1 ditekan.

/**
 * @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);
    }
}

TINDAKAN: Simpan dan tutup file gpio.c .

6. API: Bereaksi terhadap perubahan peran perangkat

Dalam aplikasi, kami ingin LED yang berbeda menyala bergantung pada peran perangkat. Mari kita lacak peran berikut: Leader, Router, End Device. Kita dapat menetapkannya ke LED seperti berikut:

  • LED1 = Pemimpin
  • LED2 = Router
  • LED3 = Perangkat Akhir

Untuk mengaktifkan fungsi ini, aplikasi perlu mengetahui kapan peran perangkat telah berubah dan cara menyalakan LED yang tepat sebagai respons. Kita akan menggunakan instance OpenThread untuk bagian pertama, dan abstraksi platform GPIO untuk bagian kedua.

Buka file ./openthread/examples/apps/cli/main.c dalam editor teks pilihan Anda.

./threadthread/examples/apps/cli/main.c

TINDAKAN: Tambahkan header yang disertakan.

Di bagian penyertaan file main.c, tambahkan file header API yang Anda perlukan untuk fitur perubahan peran.

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

TINDAKAN: Tambahkan deklarasi fungsi pengendali untuk perubahan status instance OpenThread.

Tambahkan deklarasi ini ke main.c, setelah header menyertakan dan sebelum pernyataan #if apa pun. Fungsi ini akan ditentukan setelah aplikasi utama.

void handleNetifStateChanged(uint32_t aFlags, void *aContext);

TINDAKAN: Tambahkan pendaftaran callback untuk fungsi pengendali perubahan status.

Di main.c, tambahkan fungsi ini ke fungsi main() setelah panggilan otAppCliInit. Pendaftaran callback ini memberi tahu OpenThread untuk memanggil fungsi handleNetifStateChange setiap kali status instance OpenThread berubah.

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

TINDAKAN: Tambahkan penerapan perubahan status.

Di main.c, setelah fungsi main(), implementasikan fungsi handleNetifStateChanged. Fungsi ini memeriksa flag OT_CHANGED_THREAD_ROLE instance OpenThread dan jika berubah, menyalakan/mematikan LED sesuai kebutuhan.

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: Menggunakan multicast untuk menyalakan LED

Dalam aplikasi, kita juga ingin mengirim pesan UDP ke semua perangkat lain di jaringan saat Button1 ditekan di satu papan. Untuk mengonfirmasi penerimaan pesan, kami akan mengaktifkan LED4 di papan lain sebagai respons.

Untuk mengaktifkan fungsi ini, aplikasi harus:

  • Menginisialisasi koneksi UDP saat memulai
  • Dapat mengirim pesan UDP ke alamat multicast lokal mesh
  • Menangani pesan UDP yang masuk
  • Beralih ke LED4 sebagai respons terhadap pesan UDP yang masuk

Buka file ./openthread/examples/apps/cli/main.c dalam editor teks pilihan Anda.

./threadthread/examples/apps/cli/main.c

TINDAKAN: Tambahkan header yang disertakan.

Di bagian penyertaan di bagian atas file main.c, tambahkan file header API yang diperlukan untuk fitur UDP multicast.

#include <string.h>

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

#include "utils/code_utils.h"

Header code_utils.h digunakan untuk makro otEXPECT dan otEXPECT_ACTION yang memvalidasi kondisi runtime dan menangani error dengan baik.

TINDAKAN: Tambahkan definisi dan konstanta:

Dalam file main.c, setelah bagian yang disertakan dan sebelum pernyataan #if, tambahkan konstanta khusus UDP dan tentukan:

#define UDP_PORT 1212

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

ff03::1 adalah alamat multicast lokal mesh. Pesan apa pun yang dikirim ke alamat ini akan dikirimkan ke semua Perangkat Utas Penuh di jaringan. Lihat Multicast di openthread.io untuk informasi selengkapnya tentang dukungan multicast di OpenThread.

TINDAKAN: Tambahkan deklarasi fungsi.

Di file main.c, setelah definisi otTaskletsSignalPending dan sebelum fungsi main(), tambahkan fungsi khusus UDP, serta variabel statis untuk mewakili soket 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;

TINDAKAN: Tambahkan panggilan untuk melakukan inisialisasi LED dan tombol GPIO.

Di main.c, tambahkan panggilan fungsi ini ke fungsi main() setelah panggilan otSetStateChangedCallback. Fungsi ini menginisialisasi pin GPIO dan GPIOTE dan menetapkan pengendali tombol untuk menangani peristiwa push tombol.

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

TINDAKAN: Tambahkan panggilan inisialisasi UDP.

Di main.c, tambahkan fungsi ini ke fungsi main() setelah panggilan otSysButtonInit yang baru saja Anda tambahkan:

initUdp(instance);

Panggilan ini memastikan soket UDP diinisialisasi saat aplikasi dimulai. Tanpa kunci ini, perangkat tidak dapat mengirim atau menerima pesan UDP.

TINDAKAN: Tambahkan panggilan untuk memproses peristiwa tombol GPIO.

Di main.c, tambahkan panggilan fungsi ini ke fungsi main() setelah panggilan otSysProcessDrivers, di loop while. Fungsi ini, yang dideklarasikan di gpio.c, memeriksa apakah tombol ditekan, dan jika ya, memanggil pengendali (handleButtonInterrupt) yang ditetapkan pada langkah di atas.

otSysButtonProcess(instance);

TINDAKAN: Mengimplementasikan Handler Interrupt Tombol.

Di main.c, tambahkan implementasi fungsi handleButtonInterrupt setelah fungsi handleNetifStateChanged yang Anda tambahkan di langkah sebelumnya:

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

TINDAKAN: Mengimplementasikan inisialisasi UDP.

Di main.c, tambahkan implementasi fungsi initUdp setelah fungsi handleButtonInterrupt yang baru saja Anda tambahkan:

/**
 * 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 adalah port yang Anda tentukan sebelumnya (1212). Fungsi otUdpOpen membuka soket dan mendaftarkan fungsi callback (handleUdpReceive) saat pesan UDP diterima. otUdpBind mengikat soket ke antarmuka jaringan Thread dengan meneruskan OT_NETIF_THREAD. Untuk opsi antarmuka jaringan lainnya, lihat enumerasi otNetifIdentifier di Referensi UDP API.

TINDAKAN: Terapkan pesan UDP.

Di main.c, tambahkan implementasi fungsi sendUdp setelah fungsi initUdp yang baru saja Anda tambahkan:

/**
 * 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);
    }
}

Perhatikan makro otEXPECT dan otEXPECT_ACTION. Hal ini memastikan bahwa pesan UDP valid dan dialokasikan dengan benar dalam buffer, dan jika tidak, fungsi akan menangani error dengan baik dengan melompat ke blok exit, tempat buffer akan kosong.

Lihat Referensi IPv6 dan UDP di openthread.io untuk informasi selengkapnya tentang fungsi yang digunakan untuk menginisialisasi UDP.

TINDAKAN: Mengimplementasikan penanganan pesan UDP.

Di main.c, tambahkan implementasi fungsi handleUdpReceive setelah fungsi sendUdp yang baru saja Anda tambahkan. Fungsi ini hanya mengaktifkan 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: Mengonfigurasi jaringan Thread

Untuk kemudahan demonstrasi, kami ingin perangkat kami segera memulai Thread dan bergabung bersama ke jaringan saat diaktifkan. Untuk melakukannya, kita akan menggunakan struktur otOperationalDataset. Struktur ini menyimpan semua parameter yang diperlukan untuk mengirimkan kredensial jaringan Thread ke perangkat.

Penggunaan struktur ini akan menggantikan default jaringan yang disertakan dalam OpenThread, untuk membuat aplikasi kami lebih aman dan membatasi node Thread dalam jaringan kami hanya untuk mereka yang menjalankan aplikasi.

Sekali lagi, buka file ./openthread/examples/apps/cli/main.c di editor teks pilihan Anda.

./threadthread/examples/apps/cli/main.c

TINDAKAN: Tambahkan header.

Dalam bagian penyertaan di bagian atas file main.c, tambahkan file header API yang harus Anda konfigurasi jaringan Thread:

#include <openthread/dataset_ftd.h>

TINDAKAN: Tambahkan deklarasi fungsi untuk menyetel konfigurasi jaringan.

Tambahkan deklarasi ini ke main.c, setelah header menyertakan dan sebelum pernyataan #if apa pun. Fungsi ini akan ditentukan setelah fungsi aplikasi utama.

static void setNetworkConfiguration(otInstance *aInstance);

TINDAKAN: Tambahkan panggilan konfigurasi jaringan.

Di main.c, tambahkan panggilan fungsi ini ke fungsi main() setelah panggilan otSetStateChangedCallback. Fungsi ini mengonfigurasi set data jaringan Thread.

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

TINDAKAN: Tambahkan panggilan untuk mengaktifkan stack dan antarmuka jaringan Thread.

Di main.c, tambahkan panggilan fungsi ini ke fungsi main() setelah panggilan otSysButtonInit.

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

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

TINDAKAN: Mengimplementasikan konfigurasi jaringan Thread.

Di main.c, tambahkan implementasi fungsi setNetworkConfiguration setelah fungsi main():

/**
 * 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);
}

Seperti yang dijelaskan dalam fungsi, parameter jaringan Thread yang kami gunakan untuk aplikasi ini adalah:

  • Saluran = 15
  • ID PAN = 0x2222
  • ID PAN yang Diperluas = C0DE1AB5C0DE1AB5
  • Kunci Jaringan = 1234C0DE1AB51234C0DE1AB51234C0DE
  • Nama Jaringan = OTCodelab

Selain itu, di sinilah kami mengurangi Router Selection Jitter, sehingga perangkat kami mengubah peran lebih cepat untuk tujuan demo. Perhatikan bahwa ini hanya dilakukan jika node adalah FTD (Full Thread Device). Selengkapnya tentang hal itu di langkah berikutnya.

9. API: Fungsi yang dibatasi

Beberapa API OpenThread memodifikasi setelan yang seharusnya hanya dimodifikasi untuk tujuan demo atau pengujian. API ini tidak boleh digunakan dalam deployment produksi aplikasi menggunakan OpenThread.

Misalnya, fungsi otThreadSetRouterSelectionJitter menyesuaikan waktu (dalam detik) yang diperlukan Perangkat Akhir untuk mempromosikan dirinya sendiri ke Router. Default untuk nilai ini adalah 120, sesuai Spesifikasi Thread. Untuk kemudahan penggunaan dalam Codelab ini, kita akan mengubahnya menjadi 20, sehingga Anda tidak perlu menunggu terlalu lama untuk node Thread untuk mengubah peran.

Catatan: Perangkat MTD tidak menjadi router, dan dukungan untuk fungsi seperti otThreadSetRouterSelectionJitter tidak disertakan dalam build MTD. Nanti kita perlu menentukan opsi CMake -DOT_MTD=OFF, jika tidak, kita akan mengalami kegagalan build.

Anda dapat mengonfirmasi hal ini dengan melihat definisi fungsi otThreadSetRouterSelectionJitter yang terdapat dalam perintah preprosesor OPENTHREAD_FTD:

./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. Update CMake

Sebelum Anda membuat aplikasi, ada beberapa update minor yang diperlukan untuk tiga file CMake. Ini digunakan oleh sistem build untuk mengompilasi dan menautkan aplikasi Anda.

./third_party/NordicSemiconductor/CMakeLists.txt

Sekarang tambahkan beberapa flag ke NordicSemiconductor CMakeLists.txt, untuk memastikan fungsi GPIO ditentukan dalam aplikasi.

TINDAKAN: Menambahkan tanda ke file CMakeLists.txt .

Buka ./third_party/NordicSemiconductor/CMakeLists.txt di editor teks pilihan Anda, dan tambahkan baris berikut di bagian 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

Edit file ./src/CMakeLists.txt untuk menambahkan file sumber gpio.c baru:

TINDAKAN: Tambahkan sumber gpio ke file ./src/CMakeLists.txt .

Buka ./src/CMakeLists.txt di editor teks pilihan Anda, lalu tambahkan file ke bagian NRF_COMM_SOURCES.

...

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

...

./third_party/NordicSemiconductor/CMakeLists.txt

Terakhir, tambahkan file driver nrfx_gpiote.c ke file CMakeLists.txt NordicSemiconductor, sehingga file ini disertakan dalam build library driver Nordic.

TINDAKAN: Tambahkan driver gpio ke file CMakeLists.txt NordicSemiconductor.

Buka ./third_party/NordicSemiconductor/CMakeLists.txt di editor teks pilihan Anda, lalu tambahkan file ke bagian COMMON_SOURCES.

...

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

11. Menyiapkan perangkat

Dengan semua pembaruan kode yang dilakukan, Anda siap untuk membangun dan mem-flash aplikasi ke ketiga papan dev Nordic nRF52840. Setiap perangkat akan berfungsi sebagai Perangkat Rangkaian Lengkap (FTD).

Mem-build OpenThread

Mem-build biner FTD OpenThread untuk platform nRF52840.

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

Buka direktori dengan biner OpenThread FTD CLI, lalu konversikan ke format hex dengan ARM Embedded Toolchain:

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

Mem-flash board

Melakukan flash file ot-cli-ftd.hex ke setiap board nRF52840.

Colokkan kabel USB ke port debug Micro-USB di samping pin daya eksternal pada board nRF52840, lalu colokkan ke mesin Linux. Setel LED5 dengan benar.

20a3b4b480356447.png

Seperti sebelumnya, perhatikan nomor seri board nRF52840:

c00d519ebec7e5f0.jpeg

Buka lokasi Alat Command Line nRFx, dan flash file hex FTD OpenThread CLI ke board nRF52840, menggunakan nomor seri board:

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

LED5 akan mati sebentar selama flashing. Output berikut dihasilkan setelah berhasil:

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.

Ulangi langkah ini "Flash boards" langkah untuk dua board lainnya. Setiap board harus dihubungkan ke mesin Linux dengan cara yang sama, dan perintah untuk melakukan flash sama, kecuali untuk nomor seri board. Pastikan untuk menggunakan nomor seri setiap board yang unik di

nrfjprog perintah flash.

Jika berhasil, LED1, LED2, atau LED3 akan menyala di setiap board. Anda bahkan mungkin melihat sakelar LED yang menyala dari 3 hingga 2 (atau 2 hingga 1) segera setelah berkedip (fitur perubahan peran perangkat).

12. Fungsi aplikasi

Ketiga board nRF52840 sekarang seharusnya sudah diaktifkan dan menjalankan aplikasi OpenThread. Seperti yang dijelaskan sebelumnya, aplikasi ini memiliki dua fitur utama.

Indikator peran perangkat

LED yang menyala di setiap board mencerminkan peran node Thread saat ini:

  • LED1 = Pemimpin
  • LED2 = Router
  • LED3 = Perangkat Akhir

Saat peran berubah, LED yang menyala juga akan menyala. Anda seharusnya sudah melihat perubahan ini di papan atau dua perangkat dalam waktu 20 detik dari setiap perangkat yang dinyalakan.

Multicast UDP

Saat Button1 ditekan di papan, pesan UDP akan dikirim ke alamat multicast lokal mesh, yang mencakup semua node lain di jaringan Thread. Sebagai tanggapan untuk menerima pesan ini, LED4 di semua board lainnya akan diaktifkan atau dinonaktifkan. LED4 tetap aktif atau nonaktif untuk setiap board hingga menerima pesan UDP lain.

203dd094acca1f97.png

9bbd96d9b1c63504.png

13. Demo: Amati perubahan peran perangkat

Perangkat yang telah di-flash adalah Jenis Perangkat Thread Penuh (FTD) tertentu yang disebut Perangkat Akhir yang Layak Router (REED). Ini berarti mereka dapat berfungsi sebagai Router atau Perangkat Akhir, dan dapat mempromosikan diri mereka dari Perangkat Akhir ke Router.

Thread dapat mendukung hingga 32 Router, tetapi mencoba untuk menjaga jumlah Router antara 16 dan 23. Jika REED terpasang sebagai Perangkat Akhir dan jumlah Router kurang dari 16, perangkat tersebut secara otomatis mempromosikan dirinya ke Router. Perubahan ini akan terjadi secara acak dalam jumlah detik yang Anda tetapkan nilai otThreadSetRouterSelectionJitter dalam aplikasi (20 detik).

Setiap jaringan Thread juga memiliki Leader, yang merupakan Router yang bertanggung jawab untuk mengelola kumpulan Router di jaringan Thread. Dengan semua perangkat aktif, setelah 20 detik salah satunya harus menjadi Leader (LED1 aktif) dan dua lainnya harus menjadi Router (LED2 aktif).

4e1e885861a66570.png

Hapus Pemimpin

Jika Leader dihapus dari jaringan Thread, Router yang berbeda akan mempromosikan dirinya sendiri menjadi Leader, untuk memastikan jaringan tersebut masih memiliki Leader.

Nonaktifkan Papan pemimpin (panel dengan LED1 menyala) menggunakan tombol Daya. Tunggu sekitar 20 detik. Pada salah satu dari dua papan yang tersisa, LED2 (Router) akan mati dan LED1 (Leader) akan menyala. Perangkat ini sekarang menjadi Leader pada jaringan Thread.

4c57c87adb40e0e3.png

Aktifkan kembali papan pemimpin asli. Aplikasi akan otomatis bergabung kembali dengan jaringan Thread sebagai Perangkat Akhir (LED3 menyala). Dalam waktu 20 detik (Jitter Pemilihan Router), alat ini mempromosikan dirinya sendiri ke Router (LED2 menyala).

5f40afca2dcc4b5b.png

Mereset board

Matikan ketiga board, lalu nyalakan kembali dan amati LEDnya. Papan pertama yang dihidupkan harus dimulai dalam peran Pemimpin (LED1 menyala) — Router pertama dalam jaringan Thread otomatis menjadi Pemimpin.

Dua papan lainnya awalnya terhubung ke jaringan sebagai Perangkat Akhir (LED3 menyala) tetapi harus mempromosikan diri mereka ke Router (LED2 menyala) dalam waktu 20 detik.

Partisi jaringan

Jika board tidak menerima daya yang cukup, atau koneksi radio di antaranya lemah, jaringan Thread dapat dibagi menjadi beberapa partisi dan Anda mungkin memiliki lebih dari satu perangkat yang ditampilkan sebagai Leader.

Thread akan melakukan pemulihan mandiri, sehingga partisi pada akhirnya akan bergabung kembali ke dalam satu partisi dengan satu Leader.

14. Demo: Mengirim multicast UDP

Jika melanjutkan latihan sebelumnya, LED4 tidak boleh menyala di perangkat mana pun.

Pilih papan mana pun dan tekan Tombol1. LED4 pada semua board lain di jaringan Thread yang menjalankan aplikasi harus mengalihkan statusnya. Jika melanjutkan dari latihan sebelumnya, seharusnya sekarang sudah aktif.

f186a2618fdbe3fd.png

Tekan Tombol1 untuk papan yang sama lagi. LED4 di semua board lainnya harus beralih lagi.

Tekan Button1 pada board yang berbeda dan amati bagaimana LED4 beralih pada board lainnya. Tekan Tombol1 di salah satu papan tempat LED4 saat ini menyala. LED4 tetap menyala untuk board tersebut, tetapi menyala yang lain.

f5865ccb8ab7aa34.png

Partisi jaringan

Jika board telah dipartisi dan ada lebih dari satu Leader di antara papan tersebut, hasil pesan multicast akan berbeda di antara board. Jika Anda menekan Tombol1 pada papan yang telah dipartisi (dan dengan demikian adalah satu-satunya anggota dari jaringan Thread yang dipartisi), LED4 di papan lain tidak akan menyala sebagai respons. Jika ini terjadi, reset board—idealnya reformasi tersebut akan membentuk ulang satu jaringan Thread dan pesan UDP akan berfungsi dengan benar.

15. Selamat!

Anda telah membuat aplikasi yang menggunakan OpenThread API.

Anda sekarang tahu:

  • Cara memprogram tombol dan LED pada papan pengembangan Nordic nRF52840
  • Cara menggunakan OpenThread API umum dan class otInstance
  • Cara memantau dan bereaksi terhadap perubahan status OpenThread
  • Cara mengirim pesan UDP ke semua perangkat dalam jaringan Thread
  • Cara mengubah Makefile

Langkah berikutnya

Berdasarkan Codelab ini, coba latihan berikut:

  • Memodifikasi modul GPIO untuk menggunakan pin GPIO sebagai ganti LED onboard, dan menghubungkan LED RGB eksternal yang berubah warna berdasarkan peran Router
  • Menambahkan dukungan GPIO untuk platform contoh lain
  • Daripada menggunakan multicast untuk mem-ping semua perangkat dari penekanan tombol, gunakan Router/Leader API untuk menemukan dan melakukan ping ke masing-masing perangkat
  • Hubungkan jaringan mesh Anda ke internet menggunakan OpenThread Border Router dan multicast dari luar jaringan Thread untuk menyalakan LED

Bacaan lebih lanjut

Buka openthread.io dan GitHub untuk berbagai resource OpenThread, termasuk:

Referensi: