Gambaran Umum Arsitektur Ketergantungan dan persyaratan File konfigurasi perpustakaan Pengoptimalan Pembatasan penggunaan Inisialisasi Referensi API Contoh penggunaan Porting

Perpustakaan Bluetooth Rendah Energi

penting

Ini adalah versi arsip dari Panduan Pengguna FreeRTOS untuk digunakan dengan rilis FreerTOS 202012.00. Untuk versi terbaru dari dokumen ini, lihat Panduan Pengguna FreeRTOS.

Gambaran Umum

FreeRTOS mendukung penerbitan dan berlangganan topik MQTT melalui Bluetooth Low Energy melalui perangkat proxy, seperti ponsel. Dengan perpustakaan FreeRTOS Bluetooth Low Energy, mikrokontroler Anda dapat berkomunikasi dengan aman dengan broker MQTT. AWS IoT

IoT devices connecting to mobile phone and AWS IoT Core via Bluetooth and Wi-Fi.

Menggunakan Ponsel SDKs untuk Perangkat Bluetooth FreeRTOS, Anda dapat menulis aplikasi seluler asli yang berkomunikasi dengan aplikasi yang disematkan pada mikrokontroler Anda melalui Bluetooth Low Energy. Untuk informasi selengkapnya tentang ponsel SDKs, lihatPonsel SDKs untuk perangkat Bluetooth FreeRTOS.

Pustaka FreeRTOS Bluetooth Low Energy mencakup layanan untuk mengonfigurasi jaringan Wi-Fi, mentransfer data dalam jumlah besar, dan menyediakan abstraksi jaringan melalui Bluetooth Low Energy. Pustaka FreeRTOS Bluetooth Low Energy juga mencakup middleware dan APIs level yang lebih rendah untuk kontrol lebih langsung atas tumpukan Bluetooth Low Energy Anda.

Arsitektur

Tiga lapisan membentuk pustaka FreeRTOS Bluetooth Low Energy: layanan, middleware, dan pembungkus tingkat rendah.

Layered architecture diagram showing User Application at the top, followed by Services, Middleware, Low-level Wrappers, and Manufacturer BLE Stack.

Layanan

Lapisan layanan FreeRTOS Bluetooth Low Energy terdiri dari empat layanan Generic Attributes (GATT) yang memanfaatkan APIs middleware: Device Information, Wi-Fi Provisioning, Network Abstraction, dan Large Object Transfer.

Informasi perangkat

Layanan Informasi Perangkat mengumpulkan informasi tentang mikrokontroler Anda, termasuk:

Versi FreeRTOS yang digunakan perangkat Anda.
AWS IoT Titik akhir akun tempat perangkat terdaftar.
Unit Transmisi Maksimum Energi Rendah Bluetooth (MTU).

Penyediaan Wi-Fi

Layanan penyediaan Wi-Fi memungkinkan mikrokontroler dengan kemampuan Wi-Fi untuk melakukan hal berikut:

Daftar jaringan dalam jangkauan.
Simpan jaringan dan kredenal jaringan ke memori flash.
Tetapkan prioritas jaringan.
Hapus jaringan dan kredenal jaringan dari memori flash.

Abstraksi jaringan

Layanan abstraksi jaringan mengabstraksi jenis koneksi jaringan untuk aplikasi. API umum berinteraksi dengan tumpukan perangkat keras Wi-Fi, Ethernet, dan Bluetooth Low Energy perangkat Anda, memungkinkan aplikasi kompatibel dengan beberapa jenis koneksi.

Transfer Objek Besar

Layanan Transfer Objek Besar mengirimkan data ke dan menerima data dari klien. Layanan lain, seperti Penyediaan Wi-Fi dan Abstraksi Jaringan, menggunakan layanan Transfer Objek Besar untuk mengirim dan menerima data. Anda juga dapat menggunakan Large Object Transfer API untuk berinteraksi dengan layanan secara langsung.

Middleware

FreeRTOS Bluetooth Low Energy middleware adalah abstraksi dari level yang lebih rendah. APIs Middleware APIs membuat antarmuka yang lebih ramah pengguna ke tumpukan Bluetooth Low Energy.

Menggunakan middleware APIs, Anda dapat mendaftarkan beberapa callback, di beberapa lapisan, ke satu acara. Menginisialisasi middleware Bluetooth Low Energy juga menginisialisasi layanan dan mulai beriklan.

Langganan callback fleksibel

Misalkan perangkat keras Bluetooth Low Energy Anda terputus, dan layanan MQTT melalui Bluetooth Low Energy perlu mendeteksi pemutusan sambungan. Aplikasi yang Anda tulis mungkin juga perlu mendeteksi peristiwa pemutusan yang sama. Middleware Bluetooth Low Energy dapat merutekan acara ke berbagai bagian kode tempat Anda telah mendaftarkan callback, tanpa membuat lapisan yang lebih tinggi bersaing untuk sumber daya tingkat yang lebih rendah.

Pembungkus tingkat rendah

Pembungkus FreeRTOS Bluetooth Low Energy tingkat rendah adalah abstraksi dari tumpukan Bluetooth Low Energy pabrikan. Pembungkus tingkat rendah menawarkan satu set umum APIs untuk kontrol langsung atas perangkat keras. Tingkat rendah APIs mengoptimalkan penggunaan RAM, tetapi terbatas dalam fungsionalitas.

Gunakan layanan Bluetooth Low Energy APIs untuk berinteraksi dengan layanan Bluetooth Low Energy. Layanan APIs menuntut lebih banyak sumber daya daripada tingkat rendah APIs.

Ketergantungan dan persyaratan

Pustaka Bluetooth Low Energy memiliki dependensi langsung berikut:

Perpustakaan Kontainer Linear
Lapisan platform yang berinteraksi dengan sistem operasi untuk manajemen thread, timer, fungsi jam, dan akses jaringan.

Diagram showing BLE at the top connected to List/Queue, Network, and Clock components.

Hanya layanan Penyediaan Wi-Fi yang memiliki dependensi pustaka FreeRTOS:

Layanan GATT	Dependensi
Penyediaan Wi-Fi	Pustaka Wi-Fi

Untuk berkomunikasi dengan broker AWS IoT MQTT, Anda harus memiliki AWS akun dan Anda harus mendaftarkan perangkat Anda sebagai barang. AWS IoT Untuk informasi selengkapnya tentang pengaturan, lihat Panduan AWS IoT Pengembang.

FreeRTOS Bluetooth Low Energy menggunakan Amazon Cognito untuk otentikasi pengguna di perangkat seluler Anda. Untuk menggunakan layanan proxy MQTT, Anda harus membuat identitas Amazon Cognito dan kumpulan pengguna. Setiap Identitas Amazon Cognito harus memiliki kebijakan yang sesuai yang dilampirkan padanya. Untuk informasi selengkapnya, lihat Panduan Developer Amazon Cognito .

File konfigurasi perpustakaan

Aplikasi yang menggunakan FreeRTOS MQTT melalui layanan Bluetooth Low Energy harus menyediakan file header, di iot_ble_config.h mana parameter konfigurasi ditentukan. Parameter konfigurasi yang tidak ditentukan mengambil nilai default yang ditentukan dalamiot_ble_config_defaults.h.

Beberapa parameter konfigurasi penting meliputi:

IOT_BLE_ADD_CUSTOM_SERVICES: Memungkinkan pengguna untuk membuat layanan mereka sendiri.
IOT_BLE_SET_CUSTOM_ADVERTISEMENT_MSG: Memungkinkan pengguna untuk menyesuaikan iklan dan memindai pesan respons.

Untuk informasi selengkapnya, lihat Referensi API Energi Rendah Bluetooth.

Pengoptimalan

Saat mengoptimalkan kinerja papan Anda, pertimbangkan hal berikut:

Tingkat rendah APIs menggunakan lebih sedikit RAM, tetapi menawarkan fungsionalitas terbatas.
Anda dapat mengatur bleconfigMAX_NETWORK parameter dalam file iot_ble_config.h header ke nilai yang lebih rendah untuk mengurangi jumlah tumpukan yang dikonsumsi.
Anda dapat meningkatkan ukuran MTU ke nilai maksimumnya untuk membatasi buffering pesan, dan membuat kode berjalan lebih cepat dan mengkonsumsi lebih sedikit RAM.

Pembatasan penggunaan

Secara default, pustaka FreeRTOS Bluetooth Low Energy menyetel eBTpropertySecureConnectionOnly properti ke TRUE, yang menempatkan perangkat dalam mode Secure Connections Only. Seperti yang ditentukan oleh Spesifikasi Inti Bluetooth v5.0, Vol 3, Bagian C, 10.2.4, ketika perangkat berada dalam mode Secure Connections Only, mode keamanan LE tertinggi 1 level, level 4, diperlukan untuk akses ke atribut apa pun yang memiliki izin lebih tinggi dari level 1 mode keamanan LE terendah, level 1. Pada mode keamanan LE 1 level 4, perangkat harus memiliki kemampuan input dan output untuk perbandingan numerik.

Berikut adalah mode yang didukung, dan properti terkaitnya:

Mode 1, Level 1 (Tidak ada keamanan)


/* Disable numeric comparison */
#define IOT_BLE_ENABLE_NUMERIC_COMPARISON        ( 0 )
#define IOT_BLE_ENABLE_SECURE_CONNECTION         ( 0 )
#define IOT_BLE_INPUT_OUTPUT                     ( eBTIONone )
#define IOT_BLE_ENCRYPTION_REQUIRED               ( 0 )

Mode 1, Level 2 (Pasangan tidak diautentikasi dengan enkripsi)


#define IOT_BLE_ENABLE_NUMERIC_COMPARISON        ( 0 )
#define IOT_BLE_ENABLE_SECURE_CONNECTION         ( 0 )
#define IOT_BLE_INPUT_OUTPUT                     ( eBTIONone )

Mode 1, Level 3 (Pasangan yang diautentikasi dengan enkripsi)

Mode ini tidak didukung.

Mode 1, Level 4 (Diautentikasi LE Secure Connections dipasangkan dengan enkripsi)

Mode ini didukung secara default.

Untuk informasi tentang mode keamanan LE, lihat Spesifikasi Inti Bluetooth v5.0, Vol 3, Bagian C, 10.2.1.

Inisialisasi

Jika aplikasi Anda berinteraksi dengan tumpukan Bluetooth Low Energy melalui middleware, Anda hanya perlu menginisialisasi middleware. Middleware menangani inisialisasi lapisan bawah tumpukan.

Middleware

Untuk menginisialisasi middleware

Inisialisasi driver perangkat keras Bluetooth Low Energy sebelum Anda memanggil API middleware Bluetooth Low Energy.
Aktifkan Bluetooth Energi Rendah.
Inisialisasi middleware dengan. IotBLE_Init()

catatan
Langkah inisialisasi ini tidak diperlukan jika Anda menjalankan AWS demo. Inisialisasi demo ditangani oleh Network Manager, yang terletak di. freertos/demos/network_manager

Tingkat rendah APIs

Jika Anda tidak ingin menggunakan layanan FreeRTOS Bluetooth Low Energy GATT, Anda dapat melewati middleware dan berinteraksi langsung dengan level rendah untuk menghemat sumber daya. APIs

Untuk menginisialisasi tingkat rendah APIs

Inisialisasi driver perangkat keras Bluetooth Low Energy sebelum Anda menelepon. APIs Inisialisasi driver bukan bagian dari Bluetooth Low Energy APIs low-level.
Bluetooth Low Energy low-level API menyediakan panggilan aktifkan/nonaktifkan ke tumpukan Bluetooth Low Energy untuk mengoptimalkan daya dan sumber daya. Sebelum menelepon APIs, Anda harus mengaktifkan Bluetooth Low Energy.
```
const BTInterface_t * pxIface = BTGetBluetoothInterface();
xStatus = pxIface->pxEnable( 0 );
```
Manajer Bluetooth berisi APIs yang umum untuk Bluetooth Low Energy dan Bluetooth classic. Callback untuk manajer umum harus diinisialisasi kedua.
```
xStatus = xBTInterface.pxBTInterface->pxBtManagerInit( &xBTManagerCb );
```

Adaptor Bluetooth Low Energy cocok di atas API umum. Anda harus menginisialisasi callback-nya seperti Anda menginisialisasi API umum.


xBTInterface.pxBTLeAdapterInterface = ( BTBleAdapter_t * ) xBTInterface.pxBTInterface->pxGetLeAdapter();
xStatus = xBTInterface.pxBTLeAdapterInterface->pxBleAdapterInit( &xBTBleAdapterCb );

Daftarkan aplikasi pengguna baru Anda.


xBTInterface.pxBTLeAdapterInterface->pxRegisterBleApp( pxAppUuid );

Inisialisasi callback ke server GATT.


xBTInterface.pxGattServerInterface = ( BTGattServerInterface_t * ) xBTInterface.pxBTLeAdapterInterface->ppvGetGattServerInterface();
xBTInterface.pxGattServerInterface->pxGattServerInit( &xBTGattServerCb );

Setelah Anda menginisialisasi adaptor Bluetooth Low Energy, Anda dapat menambahkan server GATT. Anda hanya dapat mendaftarkan satu server GATT dalam satu waktu.


xStatus = xBTInterface.pxGattServerInterface->pxRegisterServer( pxAppUuid );

Atur properti aplikasi seperti koneksi aman saja dan ukuran MTU.


xStatus = xBTInterface.pxBTInterface->pxSetDeviceProperty( &pxProperty[ usIndex ] );

Referensi API

Untuk referensi API selengkapnya, lihat Referensi API Energi Rendah Bluetooth.

Contoh penggunaan

Contoh di bawah ini menunjukkan cara menggunakan pustaka Bluetooth Low Energy untuk mengiklankan dan membuat layanan baru. Untuk aplikasi demo FreeRTOS Bluetooth Low Energy lengkap, lihat Aplikasi Demo Energi Rendah Bluetooth.


void IotBle_SetCustomAdvCb( IotBleAdvertisementParams_t * pAdvParams,  IotBleAdvertisementParams_t * pScanParams)
{
    memset(pAdvParams, 0, sizeof(IotBleAdvertisementParams_t));
    memset(pScanParams, 0, sizeof(IotBleAdvertisementParams_t));

    /* Set advertisement message */
    pAdvParams->pUUID1 = &_advUUID;
    pAdvParams->nameType = BTGattAdvNameNone;

    /* This is the scan response, set it back to true. */
    pScanParams->setScanRsp = true;
    pScanParams->nameType = BTGattAdvNameComplete;
}

Callback ini mengirimkan UUID dalam pesan iklan dan nama lengkap dalam respons pemindaian.

Bukavendors/vendor/boards/board/aws_demos/config_files/iot_ble_config.h, dan atur IOT_BLE_SET_CUSTOM_ADVERTISEMENT_MSG ke1. Ini memicu IotBle_SetCustomAdvCb panggilan balik.

Menambahkan layanan baru

Untuk contoh lengkap layanan, lihatfreertos/.../ble/services.

Buat UUIDs untuk karakteristik dan deskriptor layanan:


#define xServiceUUID_TYPE \
{\
    .uu.uu128 = gattDemoSVC_UUID, \
    .ucType   = eBTuuidType128 \
}
#define xCharCounterUUID_TYPE \
{\
    .uu.uu128 = gattDemoCHAR_COUNTER_UUID,\
    .ucType   = eBTuuidType128\
}
#define xCharControlUUID_TYPE \
{\
    .uu.uu128 = gattDemoCHAR_CONTROL_UUID,\
    .ucType   = eBTuuidType128\
}
#define xClientCharCfgUUID_TYPE \
{\
    .uu.uu16 = gattDemoCLIENT_CHAR_CFG_UUID,\
    .ucType  = eBTuuidType16\
}

Buat buffer untuk mendaftarkan pegangan karakteristik dan deskriptor:
```
static uint16_t usHandlesBuffer[egattDemoNbAttributes];
```

Buat tabel atribut. Untuk menyimpan beberapa RAM, tentukan tabel sebagai fileconst.

penting

Selalu buat atribut secara berurutan, dengan layanan sebagai atribut pertama.


static const BTAttribute_t pxAttributeTable[] = {
     {    
         .xServiceUUID =  xServiceUUID_TYPE
     },
    {
         .xAttributeType = eBTDbCharacteristic,
         .xCharacteristic = 
         {
              .xUuid = xCharCounterUUID_TYPE,
              .xPermissions = ( IOT_BLE_CHAR_READ_PERM ),
              .xProperties = ( eBTPropRead | eBTPropNotify )
          }
     },
     {
         .xAttributeType = eBTDbDescriptor,
         .xCharacteristicDescr =
         {
             .xUuid = xClientCharCfgUUID_TYPE,
             .xPermissions = ( IOT_BLE_CHAR_READ_PERM | IOT_BLE_CHAR_WRITE_PERM )
          }
     },
    {
         .xAttributeType = eBTDbCharacteristic,
         .xCharacteristic = 
         {
              .xUuid = xCharControlUUID_TYPE,
              .xPermissions = ( IOT_BLE_CHAR_READ_PERM | IOT_BLE_CHAR_WRITE_PERM  ),
              .xProperties = ( eBTPropRead | eBTPropWrite )
          }
     }
};

Buat array callback. Array callback ini harus mengikuti urutan yang sama seperti array tabel yang didefinisikan di atas.

Misalnya, jika vReadCounter dipicu saat xCharCounterUUID_TYPE diakses, dan vWriteCommand dipicu saat xCharControlUUID_TYPE diakses, tentukan array sebagai berikut:
```
static const IotBleAttributeEventCallback_t pxCallBackArray[egattDemoNbAttributes] =
    {
  NULL,
  vReadCounter,
  vEnableNotification,
  vWriteCommand
};
```

Buat layanan:


static const BTService_t xGattDemoService = 
{
  .xNumberOfAttributes = egattDemoNbAttributes,
  .ucInstId = 0,
  .xType = eBTServiceTypePrimary,
  .pusHandlesBuffer = usHandlesBuffer,
  .pxBLEAttributes = (BTAttribute_t *)pxAttributeTable
};

Panggil API IotBle_CreateService dengan struktur yang Anda buat pada langkah sebelumnya. Middleware menyinkronkan pembuatan semua layanan, sehingga setiap layanan baru harus sudah ditentukan ketika IotBle_AddCustomServicesCb callback dipicu.
1. Setel IOT_BLE_ADD_CUSTOM_SERVICES ke 1 dalamvendors/vendor/boards/board/aws_demos/config_files/iot_ble_config.h.
2. Buat IotBle _ AddCustomServicesCb di aplikasi Anda:
```
void IotBle_AddCustomServicesCb(void)
{
    BTStatus_t xStatus;
    /* Select the handle buffer. */
    xStatus = IotBle_CreateService( (BTService_t *)&xGattDemoService, (IotBleAttributeEventCallback_t *)pxCallBackArray );
}
```

Porting

Input pengguna dan output periferal

Koneksi yang aman membutuhkan input dan output untuk perbandingan numerik. eBLENumericComparisonCallbackAcara dapat didaftarkan menggunakan manajer acara:


xEventCb.pxNumericComparisonCb = &prvNumericComparisonCb;
xStatus = BLE_RegisterEventCb( eBLENumericComparisonCallback, xEventCb );

Periferal harus menampilkan passkey numerik dan mengambil hasil perbandingan sebagai input.

Implementasi API porting

Untuk mem-port FreeRTOS ke target baru, Anda harus menerapkan APIs beberapa untuk layanan Penyediaan Wi-Fi dan fungsionalitas Bluetooth Low Energy.

Bluetooth Energi Rendah APIs

Untuk menggunakan middleware FreeRTOS Bluetooth Low Energy, Anda harus menerapkan beberapa. APIs

APIs umum antara GAP untuk Bluetooth Classic dan GAP untuk Bluetooth Low Energy

pxBtManagerInit
pxEnable
pxDisable
pxGetDeviceProperty
pxSetDeviceProperty(Semua opsi wajib diharapkan eBTpropertyRemoteRssi daneBTpropertyRemoteVersionInfo)
pxPair
pxRemoveBond
pxGetConnectionState
pxPinReply
pxSspReply
pxGetTxpower
pxGetLeAdapter
pxDeviceStateChangedCb
pxAdapterPropertiesCb
pxSspRequestCb
pxPairingStateChangedCb
pxTxPowerCb

APIs khusus untuk GAP untuk Bluetooth Low Energy

pxRegisterBleApp
pxUnregisterBleApp
pxBleAdapterInit
pxStartAdv
pxStopAdv
pxSetAdvData
pxConnParameterUpdateRequest
pxRegisterBleAdapterCb
pxAdvStartCb
pxSetAdvDataCb
pxConnParameterUpdateRequestCb
pxCongestionCb

Server GATT

pxRegisterServer
pxUnregisterServer
pxGattServerInit
pxAddService
pxAddIncludedService
pxAddCharacteristic
pxSetVal
pxAddDescriptor
pxStartService
pxStopService
pxDeleteService
pxSendIndication
pxSendResponse
pxMtuChangedCb
pxCongestionCb
pxIndicationSentCb
pxRequestExecWriteCb
pxRequestWriteCb
pxRequestReadCb
pxServiceDeletedCb
pxServiceStoppedCb
pxServiceStartedCb
pxDescriptorAddedCb
pxSetValCallbackCb
pxCharacteristicAddedCb
pxIncludedServiceAddedCb
pxServiceAddedCb
pxConnectionCb
pxUnregisterServerCb
pxRegisterServerCb

Untuk informasi selengkapnya tentang porting pustaka FreeRTOS Bluetooth Low Energy ke platform Anda, lihat Mem-porting Perpustakaan Energi Rendah Bluetooth di Panduan Porting FreerTOS.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

BackoffAlgoritma

Ponsel SDKs untuk perangkat Bluetooth FreeRTOS

Perpustakaan Bluetooth Rendah Energi

penting

Gambaran Umum

Arsitektur

Layanan

Informasi perangkat

Penyediaan Wi-Fi

Abstraksi jaringan

Transfer Objek Besar

Middleware

Langganan callback fleksibel

Pembungkus tingkat rendah

Ketergantungan dan persyaratan

File konfigurasi perpustakaan

Pengoptimalan

Pembatasan penggunaan

Inisialisasi

Middleware

catatan

Tingkat rendah APIs

Referensi API

Contoh penggunaan

Iklan

Menambahkan layanan baru

penting

Porting

Input pengguna dan output periferal

Implementasi API porting

Bluetooth Energi Rendah APIs

APIs umum antara GAP untuk Bluetooth Classic dan GAP untuk Bluetooth Low Energy

APIs khusus untuk GAP untuk Bluetooth Low Energy

Server GATT