Übersicht Architektur Abhängigkeiten und Anforderungen Bibliothekskonfigurationsdatei Optimierung Nutzungsbeschränkungen Initialisierung API-Referenz Beispielverwendung Portierung

Bluetooth Low Energy-Bibliothek

Wichtig

Dies ist eine archivierte Version des FreeRTOS-Benutzerhandbuchs zur Verwendung mit der FreeRTOS-Version 202012.00. Die neueste Version dieses Dokuments finden Sie im FreeRTOS-Benutzerhandbuch.

Übersicht

FreeRTOS unterstützt das Veröffentlichen und Abonnieren von MQTT-Themen über Bluetooth Low Energy über ein Proxygerät, z. B. ein Mobiltelefon. Mit der FreeRTOS Bluetooth Low Energy-Bibliothek kann Ihr Mikrocontroller sicher mit dem MQTT-Broker kommunizieren. AWS IoT

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

Mit Mobile SDKs for FreeRTOS Bluetooth-Geräten können Sie native mobile Anwendungen schreiben, die über Bluetooth Low Energy mit den eingebetteten Anwendungen auf Ihrem Mikrocontroller kommunizieren. Weitere Informationen über das Mobiltelefon SDKs finden Sie unter. Mobil SDKs für FreeRTOS-Bluetooth-Geräte

Die FreeRTOS Bluetooth Low Energy-Bibliothek umfasst Dienste für die Konfiguration von Wi-Fi-Netzwerken, die Übertragung großer Datenmengen und die Bereitstellung von Netzwerkabstraktionen über Bluetooth Low Energy. Die FreeRTOS Bluetooth Low Energy-Bibliothek umfasst auch Middleware und Lower-Level APIs für eine direktere Kontrolle über Ihren Bluetooth Low Energy-Stack.

Architektur

Die FreeRTOS Bluetooth Low Energy-Bibliothek besteht aus drei Ebenen: Dienste, Middleware und Low-Level-Wrapper.

Services

Die FreeRTOS Bluetooth Low Energy-Dienstschicht besteht aus vier GATT-Diensten (Generic Attributes), die die Middleware nutzen APIs: Device Information, Wi-Fi Provisioning, Network Abstraction und Large Object Transfer.

Geräteinformationen

Der Geräteinformationsservice sammelt Informationen über Ihren Microcontroller. Dazu gehören:

Die Version von FreeRTOS, die Ihr Gerät verwendet.
Der AWS IoT Endpunkt des Kontos, für das das Gerät registriert ist.
Bluetooth Low Energy-MTU (Maximum Transmission Unit).

WLAN-Bereitstellung

Mit dem WLAN-Bereitstellungsservice können Mikrocontroller mit WLAN-Funktionen Folgendes durchführen:

Auflisten von Netzwerken in Reichweite
Speichern von Netzwerken und Netzwerk-Anmeldeinformationen auf Flash-Speicher
Festlegen der Netzwerkpriorität
Löschen von Netzwerken und Netzwerk-Anmeldeinformationen vom Flash-Speicher

Network Abstraction

Der Netzwerkabstraktionsdienst abstrahiert den Netzwerkverbindungstyp für Anwendungen. Eine gemeinsame API interagiert mit dem Wi-Fi-, Ethernet- und Bluetooth Low Energy-Hardware-Stack Ihres Geräts, sodass eine Anwendung mit mehreren Verbindungstypen kompatibel ist.

Large Object Transfer

Der Large Object Transfer-Service sendet Daten und empfängt Daten von einem Client. Andere Services, wie Wi-Fi Provisioning und Network Abstraction, nutzen den Large Object Transfer-Service zum Senden und Empfangen von Daten. Sie können die Large Object Transfer-API auch verwenden, um direkt mit dem Service zu interagieren.

Middleware

Die FreeRTOS Bluetooth Low Energy-Middleware ist eine Abstraktion von der unteren Ebene. APIs Die Middleware bietet eine benutzerfreundlichere Schnittstelle APIs zum Bluetooth Low Energy-Stack.

Mithilfe von Middleware APIs können Sie mehrere Callbacks auf mehreren Ebenen für ein einzelnes Ereignis registrieren. Die Initialisierung der Bluetooth Low Energy-Middleware initialisiert auch Services und beginnt mit dem Advertising.

Flexibles Callback-Abonnement

Nehmen wir an, Ihre Bluetooth Low Energy-Hardware wird getrennt, und der MQTT über den Bluetooth Low Energy-Service muss die Trennung erkennen. Eine Anwendung, die Sie geschrieben haben, muss diese Verbindungstrennung möglicherweise auch erkennen. Die Bluetooth Low Energy-Middleware kann das Ereignis an verschiedene Teile des Codes weiterleiten, in dem Callbacks registriert wurden, ohne dass die höheren Ebenen um Lower-Level-Ressourcen konkurrieren.

Low-Level-Wrapper

Die Low-Level-FreeRTOS Bluetooth Low Energy-Wrapper sind eine Abstraktion aus dem Bluetooth Low Energy-Stack des Herstellers. Low-Level-Wrapper bieten ein einheitliches Set zur direkten Steuerung der Hardware. APIs Die Low-Level-Module APIs optimieren die RAM-Nutzung, sind jedoch in ihrer Funktionalität eingeschränkt.

Verwenden Sie den Bluetooth Low Energy-Dienst APIs , um mit den Bluetooth Low Energy-Diensten zu interagieren. Der Dienst benötigt APIs mehr Ressourcen als der APIs Low-Level-Dienst.

Abhängigkeiten und Anforderungen

Die Bluetooth Low Energy-Bibliothek hat die folgenden direkten Abhängigkeiten:

Linear Containers-Bibliothek
Eine Plattformschicht, die mit dem Betriebssystem für Thread-Management, Timer, Taktgeberfunktionen und Netzwerkzugriff verbunden ist.

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

Nur der Wi-Fi Provisioning Service hat Abhängigkeiten von der FreeRTOS-Bibliothek:

GATT-Service	-Abhängigkeit
WLAN-Bereitstellung	WLAN-Bibliothek

Um mit dem AWS IoT MQTT-Broker kommunizieren zu können, benötigen Sie ein AWS Konto und müssen Ihre Geräte als Dinge registrieren. AWS IoT Weitere Informationen zur Einrichtung finden Sie im AWS IoT Entwicklerhandbuch.

FreeRTOS Bluetooth Low Energy verwendet Amazon Cognito für die Benutzerauthentifizierung auf Ihrem Mobilgerät. Um MQTT-Proxydienste verwenden zu können, müssen Sie eine Amazon Cognito Cognito-Identität und Benutzerpools erstellen. Jeder Amazon Cognito Identity muss die entsprechende Richtlinie beigefügt sein. Weitere Informationen finden Sie im Amazon Cognito Entwicklerhandbuch.

Bibliothekskonfigurationsdatei

Anwendungen, die den FreeRTOS MQTT over Bluetooth Low Energy-Dienst verwenden, müssen eine iot_ble_config.h Header-Datei bereitstellen, in der Konfigurationsparameter definiert sind. Nicht definierte Konfigurationsparameter nehmen die in iot_ble_config_defaults.h angegebenen Standardwerte an.

Einige wichtige Konfigurationsparameter sind:

IOT_BLE_ADD_CUSTOM_SERVICES: Ermöglicht es Benutzern, ihre eigenen Services zu erstellen.
IOT_BLE_SET_CUSTOM_ADVERTISEMENT_MSG: Ermöglicht Benutzern, das Advertising anzupassen und Antwortnachrichten zu scannen.

Weitere Informationen finden Sie unter API-Referenz Bluetooth Low Energy (BLE).

Optimierung

Wenn Sie die Leistung Ihres Boards optimieren, sollten Sie Folgendes berücksichtigen:

Low-Level APIs verbrauchen weniger RAM, bieten aber eingeschränkte Funktionalität.
Sie können den Parameter bleconfigMAX_NETWORK in der iot_ble_config.h-Header-Datei auf einen niedrigeren Wert setzen, um die Menge des verbrauchten Stacks zu verringern.
Außerdem können Sie die MTU-Größe auf ihren maximalen Wert erhöhen, um das Puffern von Nachrichten zu begrenzen, den Code schneller ausführen zu lassen und so weniger RAM zu verbrauchen.

Nutzungsbeschränkungen

Standardmäßig setzt die FreeRTOS Bluetooth Low Energy-Bibliothek die eBTpropertySecureConnectionOnly Eigenschaft auf TRUE, wodurch das Gerät in den Modus Nur sichere Verbindungen versetzt wird. Wie unter Bluetooth-Kernspezifikation v5.0, Vol. 3, Teil C, 10.2.4 angegeben, ist für ein Gerät im Modus "Nur sichere Verbindungen" der höchste LE-Sicherheitsmodus "1 Level, Level 4" für den Zugriff auf alle Attribute erforderlich, die höhere Berechtigungen als den niedrigsten LE-Sicherheitsmodus "1 Level, Level 1" aufweisen. Im LE-Sicherheitsmodus 1, Level 4, muss ein Gerät über Ein- und Ausgabefunktionen für den numerischen Abgleich verfügen.

Hier sind die unterstützten Modi und die zugehörigen Eigenschaften:

Modus 1, Level 1 (Keine Sicherheit)


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

Modus 1, Level 2 (Nicht authentifizierte Kopplung mit Verschlüsselung)


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

Modus 1, Level 3 (Authentifizierte Kopplung mit Verschlüsselung)

Dieser Modus wird nicht unterstützt.

Modus 1, Level 4 (Authentifizierte LE Secure-Verbindungen mit Verschlüsselung)

Dieser Modus wird standardmäßig unterstützt.

Weitere Informationen über LE-Sicherheitsmodi finden Sie in der Bluetooth-Kernspezifikation v5.0, Vol. 3, Teil C, 10.2.1.

Initialisierung

Wenn Ihre Anwendung über die Middleware mit dem Bluetooth Low Energy-Stack interagiert, müssen Sie nur die Middleware initialisieren. Die Middleware übernimmt die Initialisierung der niedrigeren Ebenen des Stacks.

Middleware

So wird die Middleware initialisiert

Initialisieren Sie alle Bluetooth Low Energy-Hardwaretreiber, bevor Sie die Bluetooth Low Energy-Middleware-API aufrufen.
Aktivieren Sie Bluetooth Low Energy.
Initialisieren Sie die Middleware mit IotBLE_Init().

Anmerkung
Dieser Initialisierungsschritt ist nicht erforderlich, wenn Sie die Demos ausführen. AWS Die Demo-Initialisierung wird vom Netzwerkmanager durchgeführt, der sich in freertos/demos/network_manager befindet.

Niedriges Niveau APIs

Wenn Sie die FreeRTOS Bluetooth Low Energy GATT-Dienste nicht nutzen möchten, können Sie die Middleware umgehen und direkt mit dem Low-Level interagieren, um Ressourcen zu sparen. APIs

Um das Low-Level zu initialisieren APIs

Initialisieren Sie alle Bluetooth Low Energy-Hardwaretreiber, bevor Sie den aufrufen. APIs Die Treiberinitialisierung ist nicht Teil des Bluetooth Low Energy-Low-Levels. APIs
Die Bluetooth Low Energy Low-Level-API ermöglicht ein Aktivieren/Deaktivieren des Bluetooth Low Energy-Stacks zur Optimierung von Leistung und Ressourcen. Bevor Sie den anrufen APIs, müssen Sie Bluetooth Low Energy aktivieren.
```
const BTInterface_t * pxIface = BTGetBluetoothInterface();
xStatus = pxIface->pxEnable( 0 );
```
Der Bluetooth-Manager enthält APIs die Funktionen, die sowohl Bluetooth Low Energy als auch Bluetooth Classic gemeinsam haben. Die Callbacks für den gemeinsamen Manager müssen als Zweites initialisiert werden.
```
xStatus = xBTInterface.pxBTInterface->pxBtManagerInit( &xBTManagerCb );
```

Der Bluetooth Low Energy-Adapter befindet sich über der allgemeinern API. Sie müssen seine Callbacks auf dieselbe Art initialisieren, wie Sie die gemeinsame API initialisiert haben.


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

Registrieren Sie Ihre neue Benutzeranwendung.


xBTInterface.pxBTLeAdapterInterface->pxRegisterBleApp( pxAppUuid );

Initialisieren Sie die Callbacks an die GATT-Server.


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

Nachdem Sie den Bluetooth Low Energy-Adapter initialisiert haben, können Sie einen GATT-Server hinzufügen. Es kann immer nur ein GATT-Server registriert werden.


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

Legen Sie Eigenschaften wie "Nur sichere Verbindungen" und MTU-Größe fest.


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

API-Referenz

Die vollständige API-Referenz finden Sie unter API-Referenz Bluetooth Low Energy (BLE).

Beispielverwendung

Die folgenden Beispiele zeigen, wie Sie die Bluetooth Low Energy-Bibliothek für Werbung und zur Erstellung neuer Services nutzen können. Vollständige FreeRTOS Bluetooth Low Energy-Demoanwendungen finden Sie unter Bluetooth Low Energy-Demo-Anwendungen.


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

Dieser Callback sendet die UUID in der Advertising-Nachricht und den vollständigen Namen in der Scan-Antwort.

Öffnen Sie vendors/vendor/boards/board/aws_demos/config_files/iot_ble_config.h und legen Sie IOT_BLE_SET_CUSTOM_ADVERTISEMENT_MSG auf 1 fest. Dadurch wird der IotBle_SetCustomAdvCb-Callback ausgelöst.

Hinzufügen eines neuen Services

Ausführliche Beispiele für Services finden Sie unter freertos/.../ble/services.

Erstellen Sie UUIDs für die Merkmale und Deskriptoren des Dienstes:


#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\
}

Erstellen Sie einen Puffer, um die Handles der Charakteristika und Deskriptoren zu registrieren:
```
static uint16_t usHandlesBuffer[egattDemoNbAttributes];
```

Legen Sie die Attributstabelle an. Um etwas RAM zu sparen, definieren Sie die Tabelle als const.

Wichtig

Legen Sie die Attribute immer einer Reihenfolge, in der der Service als erstes Attribut steht.


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

Erstellen Sie ein Array von Callbacks. Dieses Array von Callbacks muss der gleichen Reihenfolge folgen wie das oben definierte Tabellenarray.

Wenn beispielsweise vReadCounter beim Zugriff auf xCharCounterUUID_TYPE ausgelöst wird und vWriteCommand beim Zugriff auf xCharControlUUID_TYPE ausgelöst wird, definieren Sie das Array wie folgt:
```
static const IotBleAttributeEventCallback_t pxCallBackArray[egattDemoNbAttributes] =
    {
  NULL,
  vReadCounter,
  vEnableNotification,
  vWriteCommand
};
```

Erstellen Sie den Service.


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

Rufen Sie die IotBle_CreateService-API mit der Struktur auf, die Sie im vorherigen Schritt erstellt haben. Die Middleware synchronisiert die Erstellung aller Services, sodass alle neuen Services bereits definiert sein müssen, wenn der IotBle_AddCustomServicesCb-Callback ausgelöst wird.
1. Legen Sie in vendors/vendor/boards/board/aws_demos/config_files/iot_ble_config.h IOT_BLE_ADD_CUSTOM_SERVICES auf 1 fest.
2. Erstellen Sie IotBle _ AddCustomServicesCb in Ihrer Anwendung:
```
void IotBle_AddCustomServicesCb(void)
{
    BTStatus_t xStatus;
    /* Select the handle buffer. */
    xStatus = IotBle_CreateService( (BTService_t *)&xGattDemoService, (IotBleAttributeEventCallback_t *)pxCallBackArray );
}
```

Portierung

Ein- und Ausgabeperipheriegeräte des Benutzers

Für den numerischen Abgleich benötigt eine sichere Verbindung sowohl Eingaben als auch Ausgaben. Das Ereignis eBLENumericComparisonCallback kann mit dem Ereignis-Manager registriert werden:


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

Das Peripheriegerät muss den numerischen Hauptschlüssel anzeigen und das Ergebnis des Vergleichs als Eingabe verwenden.

Portieren von API-Implementierungen

Um FreeRTOS auf ein neues Ziel zu portieren, müssen Sie einige APIs für den Wi-Fi Provisioning Service und die Bluetooth Low Energy-Funktionalität implementieren.

Bluetooth Low Energy APIs

Um die FreeRTOS Bluetooth Low Energy-Middleware verwenden zu können, müssen Sie einige implementieren. APIs

APIs Gemeinsamkeiten zwischen GAP für Bluetooth Classic und GAP für Bluetooth Low Energy

pxBtManagerInit
pxEnable
pxDisable
pxGetDeviceProperty
pxSetDeviceProperty (Alle Optionen außer eBTpropertyRemoteRssi und eBTpropertyRemoteVersionInfo sind obligatorisch.)
pxPair
pxRemoveBond
pxGetConnectionState
pxPinReply
pxSspReply
pxGetTxpower
pxGetLeAdapter
pxDeviceStateChangedCb
pxAdapterPropertiesCb
pxSspRequestCb
pxPairingStateChangedCb
pxTxPowerCb

APIs spezifisch für GAP für Bluetooth Low Energy

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

GATT-Server

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

Weitere Informationen zur Portierung der FreeRTOS Bluetooth Low Energy-Bibliothek auf Ihre Plattform finden Sie unter Portierung der Bluetooth Low Energy Library im FreeRTOS Porting Guide.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

BackOff-Algorithmus

Mobil SDKs für FreeRTOS-Bluetooth-Geräte

Bluetooth Low Energy-Bibliothek

Wichtig

Übersicht

Architektur

Services

Geräteinformationen

WLAN-Bereitstellung

Network Abstraction

Large Object Transfer

Middleware

Flexibles Callback-Abonnement

Low-Level-Wrapper

Abhängigkeiten und Anforderungen

Bibliothekskonfigurationsdatei

Optimierung

Nutzungsbeschränkungen

Initialisierung

Middleware

Anmerkung

Niedriges Niveau APIs

API-Referenz

Beispielverwendung

Werbung

Hinzufügen eines neuen Services

Wichtig

Portierung

Ein- und Ausgabeperipheriegeräte des Benutzers

Portieren von API-Implementierungen

Bluetooth Low Energy APIs

APIs Gemeinsamkeiten zwischen GAP für Bluetooth Classic und GAP für Bluetooth Low Energy

APIs spezifisch für GAP für Bluetooth Low Energy

GATT-Server