Présentation Architecture Dépendances et exigences Fichier de configuration des bibliothèques Optimisation Restrictions liées à l'utilisation Initialisation Référence d’API Exemple d’utilisation Portage

Bibliothèque Bluetooth Low Energy

Important

Il s'agit d'une version archivée du guide de l'utilisateur de FreeRTOS à utiliser avec la version 202012.00 de FreeRTOS. Pour obtenir la dernière version de ce document, consultez le guide de l'utilisateur de FreeRTOS.

Présentation

FreeRTOS prend en charge la publication et l'abonnement à des sujets MQTT via Bluetooth Low Energy via un périphérique proxy, tel qu'un téléphone portable. Grâce à la bibliothèque FreeRTOS Bluetooth Low Energy, votre microcontrôleur peut communiquer en toute sécurité avec le courtier MQTT. AWS IoT

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

À l'aide des appareils Bluetooth Mobile SDKs for FreeRTOS, vous pouvez écrire des applications mobiles natives qui communiquent avec les applications intégrées à votre microcontrôleur via Bluetooth Low Energy. Pour plus d'informations sur le mobile SDKs, consultezMobile SDKs pour appareils Bluetooth FreeRTOS.

La bibliothèque FreeRTOS Bluetooth Low Energy inclut des services permettant de configurer des réseaux Wi-Fi, de transférer de grandes quantités de données et de fournir des abstractions réseau via Bluetooth Low Energy. La bibliothèque FreeRTOS Bluetooth Low Energy inclut également un intergiciel et un APIs niveau inférieur pour un contrôle plus direct de votre pile Bluetooth Low Energy.

Architecture

Trois couches constituent la bibliothèque FreeRTOS Bluetooth Low Energy : les services, les intergiciels et les wrappers de bas niveau.

Services

La couche de services Bluetooth Low Energy FreeRTOS comprend quatre services d'attributs génériques (GATT) qui tirent parti du APIs middleware : informations sur les appareils, provisionnement Wi-Fi, abstraction du réseau et transfert d'objets volumineux.

Informations sur les périphériques

Le service d'informations sur les appareils recueille des informations sur votre microcontrôleur, y compris :

Version de FreeRTOS utilisée par votre appareil.
AWS IoT Point de terminaison du compte pour lequel l'appareil est enregistré.
Unité de transmission maximale Bluetooth Low Energy (MTU).

Mise en service Wi-Fi

La mise en service Wi-Fi permet aux microcontrôleurs dotés de fonctionnalités Wi-Fi d'effectuer les opérations suivantes :

Répertorier les réseaux dans une plage.
Enregistrer les réseaux et les informations d'identification correspondantes sur la mémoire flash.
Définir la priorité du réseau.
Supprimer les réseaux et les informations d'identification correspondantes de la mémoire flash.

Abstraction réseau

Le service d'abstraction réseau extrait le type de connexion réseau pour les applications. Une API courante interagit avec le Wi-Fi, l'Ethernet et la pile matérielle Bluetooth Low Energy de votre appareil, ce qui permet à une application d'être compatible avec plusieurs types de connexion.

Transfert d'objets volumineux

Le service de transfert d'objets volumineux envoie des données et reçoit des données à partir d'un client. D'autres services, tels que la mise en service du Wi-Fi et l'abstraction réseau, utilisent le service de transfert d'objets volumineux pour envoyer et recevoir des données. Vous pouvez également utiliser l'API de transfert d'objets volumineux pour interagir avec le service directement.

Intergiciel

Le middleware Bluetooth Low Energy FreeRTOS est une abstraction du niveau inférieur. APIs Le middleware constitue APIs une interface plus conviviale pour la pile Bluetooth Low Energy.

À l'aide d'un intergiciel APIs, vous pouvez enregistrer plusieurs rappels, sur plusieurs couches, pour un seul événement. L'initialisation de l'intergiciel Bluetooth Low Energy initialise également des services et démarre la publicité.

Abonnement de rappel flexible

Supposons que votre matériel Bluetooth Low Energy se déconnecte et que le service MQTT sur Bluetooth Low Energy ait besoin de détecter la déconnexion. Une application que vous avez créée peut également avoir à détecter le même événement de déconnexion. L'intergiciel BLE peut acheminer l'événement à différentes parties du code où vous avez enregistré des rappels, sans que les couches supérieures n'aient à se disputer les ressources de niveau inférieur.

Wrappers de bas niveau

Les wrappers Bluetooth Low Energy FreeRTOS de bas niveau sont une abstraction de la gamme Bluetooth Low Energy du fabricant. Les wrappers de bas niveau offrent un ensemble commun de composants APIs permettant un contrôle direct du matériel. Les bas niveaux APIs optimisent l'utilisation de la RAM, mais leurs fonctionnalités sont limitées.

Utilisez le service Bluetooth Low Energy APIs pour interagir avec les services Bluetooth Low Energy. Le service APIs demande plus de ressources que le bas niveau. APIs

Dépendances et exigences

La bibliothèque Bluetooth Low Energy comporte les dépendances directes suivantes :

Bibliothèque de conteneurs linéaires
Une couche de plateforme en interface avec le système d'exploitation pour la gestion des threads, les minuteurs, les fonctions d'horloge et l'accès réseau.

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

Seul le service Wi-Fi Provisioning possède des dépendances à la bibliothèque FreeRTOS :

Service GATT	Dépendance
Mise en service Wi-Fi	Bibliothèque Wi-Fi

Pour communiquer avec le courtier AWS IoT MQTT, vous devez avoir un AWS compte et enregistrer vos appareils en tant qu' AWS IoT objets. Pour en savoir plus sur la configuration, consultez le Manuel du développeur AWS IoT.

FreeRTOS Bluetooth Low Energy utilise Amazon Cognito pour l'authentification des utilisateurs sur votre appareil mobile. Pour utiliser les services proxy MQTT, vous devez créer une identité Amazon Cognito et des groupes d'utilisateurs. Chaque identité Amazon Cognito doit être associée à la politique appropriée. Pour plus d'informations, consultez le Guide du développeur Amazon Cognito.

Fichier de configuration des bibliothèques

Les applications qui utilisent le service FreeRTOS MQTT over Bluetooth Low Energy doivent fournir iot_ble_config.h un fichier d'en-tête dans lequel les paramètres de configuration sont définis. Les paramètres de configuration non définis utilisent les valeurs par défaut spécifiées dans iot_ble_config_defaults.h.

Voici quelques paramètres de configuration importants :

IOT_BLE_ADD_CUSTOM_SERVICES: Autorise les utilisateurs à créer leurs propres services.
IOT_BLE_SET_CUSTOM_ADVERTISEMENT_MSG: Permet aux utilisateurs de personnaliser la publicité et d'analyser les messages de réponse.

Pour de plus amples informations, veuillez consulter Référence d'API Bluetooth Low Energy.

Optimisation

Lors de l'optimisation des performances de votre carte, prenez en considération les éléments suivants :

Les bas niveaux APIs utilisent moins de RAM, mais offrent des fonctionnalités limitées.
Vous pouvez définir le paramètre bleconfigMAX_NETWORK dans le fichier d'en-tête iot_ble_config.h sur une valeur inférieure afin de réduire la quantité de pile consommée.
Vous pouvez augmenter la taille MTU à sa valeur maximale pour limiter la mise en mémoire tampon des messages, accélérer l'exécution du code et consommer moins de RAM.

Restrictions liées à l'utilisation

Par défaut, la bibliothèque FreeRTOS Bluetooth Low Energy définit eBTpropertySecureConnectionOnly la propriété sur TRUE, ce qui place l'appareil en mode Connexions sécurisées uniquement. Comme défini par la spécification Bluetooth Core v5.0, vol 3, partie C, 10.2.4, lorsqu'un appareil utilise un mode autorisant uniquement les connexions sécurisées, le plus haut niveau de sécurité basse énergie du mode 1, à savoir le niveau 4, est requis pour l'accès à n'importe quel attribut disposant d'autorisations supérieures au niveau de sécurité basse énergie inférieur du mode 1, à savoir le niveau 1. Dans le mode de sécurité basse énergie 1 de niveau 4, un appareil doit avoir des fonctionnalités d'entrée et de sortie pour la comparaison numérique.

Voici les modes pris en charge et les propriétés associées :

Mode 1, Niveau 1 (aucune sécurité)


/* 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, Niveau 2 (appairage non authentifié avec chiffrement)


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

Mode 1, Niveau 3 (appairage authentifié avec chiffrement)

Ce mode n'est pas pris en charge.

Mode 1, Niveau 4 (appairage des connexions sécurisées LE authentifiées avec chiffrement)

Ce mode est pris en charge par défaut.

Pour de plus amples informations sur les modes de sécurité basse énergie, veuillez consulter la spécification Bluetooth Core v5.0, vol 3, partie C, 10.2.1.

Initialisation

Si votre application interagit avec la pile Bluetooth Low Energy via un intergiciel, vous devez uniquement initialiser ce dernier. L'intergiciel s'occupe de l'initialisation des couches inférieures de la pile.

Intergiciel

Pour initialiser le middleware

Initialisez n'importe quel pilote matériel Bluetooth Low Energy avant d'appeler l'API d'intergiciel Bluetooth Low Energy.
Activez Bluetooth Low Energy.
Initialisez l'intergiciel avec IotBLE_Init().

Note
Cette étape d'initialisation n'est pas requise si vous exécutez les AWS démos. L'initialisation des démonstrations est gérée par le gestionnaire de réseau local, situé à freertos/demos/network_manager.

Faible niveau APIs

Si vous ne souhaitez pas utiliser les services FreeRTOS Bluetooth Low Energy GATT, vous pouvez contourner le middleware et interagir directement avec le bas niveau pour économiser des ressources. APIs

Pour initialiser le bas niveau APIs

Initialisez tous les pilotes matériels Bluetooth Low Energy avant d'appeler le APIs. L'initialisation du pilote ne fait pas partie du niveau bas APIs du Bluetooth Low Energy.
L'API Bluetooth Low Energy de bas niveau fournit un appel d'activation et de désactivation à la pile Bluetooth Low Energy pour optimiser la puissance et les ressources. Avant d'appeler le APIs, vous devez activer Bluetooth Low Energy.
```
const BTInterface_t * pxIface = BTGetBluetoothInterface();
xStatus = pxIface->pxEnable( 0 );
```
Le gestionnaire Bluetooth contient APIs des informations communes à Bluetooth Low Energy et à Bluetooth Classic. Les rappels du gestionnaire doivent ensuite être initialisés.
```
xStatus = xBTInterface.pxBTInterface->pxBtManagerInit( &xBTManagerCb );
```

L'adaptateur Bluetooth Low Energy peut être ajouté en plus de l'API courante. Vous devez initialiser ses rappels courants comme vous avez initialisé l'API courante.


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

Enregistrez votre nouvelle application utilisateur.


xBTInterface.pxBTLeAdapterInterface->pxRegisterBleApp( pxAppUuid );

Initialisez les rappels aux serveurs GATT.


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

Une fois que vous avez initialisé l'adaptateur Bluetooth Low Energy, vous pouvez ajouter un serveur GATT. Vous pouvez enregistrer un seul serveur GATT à la fois.


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

Définissez les propriétés de l'application comme la connexion sécurisée uniquement et la taille MTU.
```
xStatus = xBTInterface.pxBTInterface->pxSetDeviceProperty( &pxProperty[ usIndex ] );
```

Référence d’API

Pour obtenir une référence d'API complète, veuillez consulter Référence d'API Bluetooth Low Energy.

Exemple d’utilisation

Les exemples ci-dessous montrent comment utiliser la bibliothèque Bluetooth Low Energy pour la publicité et la création de nouveaux services. Pour les applications de démonstration FreeRTOS Bluetooth Low Energy complètes, voir Applications de démonstration Bluetooth Low Energy.


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

Ce rappel envoie l'UUID dans le message de publicité et le nom complet dans la réponse d'analyse.

Ouvrez vendors/vendor/boards/board/aws_demos/config_files/iot_ble_config.h et définissez IOT_BLE_SET_CUSTOM_ADVERTISEMENT_MSG sur 1. Cela déclenche le rappel IotBle_SetCustomAdvCb.

Ajout d'un nouveau service

Pour consulter l'ensemble des exemples de services, accédez à freertos/.../ble/services.

Créez UUIDs pour les caractéristiques et les descripteurs du service :


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

Créez un tampon pour enregistrer les handles de la caractéristique et des descripteurs :
```
static uint16_t usHandlesBuffer[egattDemoNbAttributes];
```

Créez la table de l'attribut. Pour enregistrer une RAM, définissez la table en tant que const.

Important

Créez toujours les attributs dans l'ordre, avec le service en tant que premier attribut.


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

Créez un tableau des rappels. Ce tableau de rappels doit suivre le même ordre que le tableau de table défini ci-dessus.

Par exemple, si vReadCounter est déclenché lorsque xCharCounterUUID_TYPE est consulté, et si vWriteCommand se déclenche lorsque xCharControlUUID_TYPE est consulté, définissez le tableau comme suit :
```
static const IotBleAttributeEventCallback_t pxCallBackArray[egattDemoNbAttributes] =
    {
  NULL,
  vReadCounter,
  vEnableNotification,
  vWriteCommand
};
```

Créez le service :


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

Appelez l'API IotBle_CreateService avec la structure que vous avez créée à l'étape précédente. L'intergiciel synchronise la création de tous les services, ce qui signifie que tous les nouveaux services doivent être déjà définis lorsque le rappel IotBle_AddCustomServicesCb est déclenché.
1. Définissez IOT_BLE_ADD_CUSTOM_SERVICES sur 1 dans vendors/vendor/boards/board/aws_demos/config_files/iot_ble_config.h.
2. Créez IotBle _ AddCustomServicesCb dans votre application :
```
void IotBle_AddCustomServicesCb(void)
{
    BTStatus_t xStatus;
    /* Select the handle buffer. */
    xStatus = IotBle_CreateService( (BTService_t *)&xGattDemoService, (IotBleAttributeEventCallback_t *)pxCallBackArray );
}
```

Portage

Périphériques utilisateur d'entrée et de sortie

Une connexion sécurisée nécessite des entrées et des sorties pour la comparaison numérique. L'événement eBLENumericComparisonCallback peut être enregistré à l'aide du gestionnaire d'événements :


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

Le périphérique doit afficher la clé numérique et utiliser le résultat de la comparaison comme entrée.

Portage des implémentations d'API

Pour transférer FreeRTOS vers une nouvelle cible, vous devez en implémenter APIs certains pour le service Wi-Fi Provisioning et la fonctionnalité Bluetooth Low Energy.

Bluetooth Low Energy APIs

Pour utiliser le middleware Bluetooth Low Energy FreeRTOS, vous devez en implémenter certains. APIs

APIs commun entre GAP pour Bluetooth Classic et GAP pour Bluetooth Low Energy

pxBtManagerInit
pxEnable
pxDisable
pxGetDeviceProperty
pxSetDeviceProperty (toutes les options sont obligatoires, sauf eBTpropertyRemoteRssi et eBTpropertyRemoteVersionInfo)
pxPair
pxRemoveBond
pxGetConnectionState
pxPinReply
pxSspReply
pxGetTxpower
pxGetLeAdapter
pxDeviceStateChangedCb
pxAdapterPropertiesCb
pxSspRequestCb
pxPairingStateChangedCb
pxTxPowerCb

APIs spécifique à GAP pour 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

Pour plus d'informations sur le portage de la bibliothèque Bluetooth Low Energy FreeRTOS sur votre plateforme, voir Portage de la bibliothèque Bluetooth Low Energy dans le Guide de portage FreeRTOS.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Algorithme de sauvegarde

Mobile SDKs pour appareils Bluetooth FreeRTOS

Bibliothèque Bluetooth Low Energy

Important

Présentation

Architecture

Services

Informations sur les périphériques

Mise en service Wi-Fi

Abstraction réseau

Transfert d'objets volumineux

Intergiciel

Abonnement de rappel flexible

Wrappers de bas niveau

Dépendances et exigences

Fichier de configuration des bibliothèques

Optimisation

Restrictions liées à l'utilisation

Initialisation

Intergiciel

Note

Faible niveau APIs

Référence d’API

Exemple d’utilisation

Publicité

Ajout d'un nouveau service

Important

Portage

Périphériques utilisateur d'entrée et de sortie

Portage des implémentations d'API

Bluetooth Low Energy APIs

APIs commun entre GAP pour Bluetooth Classic et GAP pour Bluetooth Low Energy

APIs spécifique à GAP pour Bluetooth Low Energy

GATT Server