Biblioteca de Bluetooth de bajo consumo - FreeRTOS
Descripción generalArquitecturaDependencias y requisitosArchivo de configuración de la bibliotecaOptimizaciónRestricciones de usoInicializaciónReferencia de la APIEjemplo de usoPortabilidad

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Biblioteca de Bluetooth de bajo consumo

importante

Esta es una versión archivada de la Guía del usuario de FreeRTOS para su uso con la versión 202012.00 de FreeRTOS. Para obtener la última versión de este documento, consulte la Guía del usuario de FreeRTOS.

Descripción general

FreeRTOS admite la publicación y suscripción a temas de MQTT sobre Bluetooth de bajo consumo a través de un dispositivo proxy, como un teléfono móvil. Con la biblioteca Bluetooth Low Energy de FreeRTOS, su microcontrolador puede comunicarse de forma segura con el AWS IoT intermediario MQTT.

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

Con los dispositivos Bluetooth Mobile SDKs for FreeRTOS, puede escribir aplicaciones móviles nativas que se comuniquen con las aplicaciones integradas en su microcontrolador a través de Bluetooth Low Energy. Para obtener más información sobre el móvil SDKs, consulte. Móvil SDKs para dispositivos Bluetooth Freertos

La biblioteca de Bluetooth de bajo consumo de FreeRTOS incluye servicios para configurar redes Wi-Fi, transferir grandes cantidades de datos y proporcionar abstracciones de red a través de Bluetooth de bajo consumo. La biblioteca Bluetooth de bajo consumo de FreeRTOS también incluye software intermedio y de nivel inferior APIs para un control más directo de la pila Bluetooth de bajo consumo.

Arquitectura

La biblioteca de Bluetooth de bajo consumo de FreeRTOS está compuesta de tres capas: servicios, middleware y contenedores de bajo nivel.

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

Servicios

La capa de servicios Bluetooth Low Energy de FreeRTOS consta de cuatro servicios de atributos genéricos (GATT) que aprovechan el middleware APIs: información del dispositivo, aprovisionamiento de Wi-Fi, abstracción de redes y transferencia de objetos grandes.

Información de dispositivo

El servicio de Información de dispositivo recopila información sobre su microcontrolador que incluye:

  • La versión de FreeRTOS que su dispositivo está utilizando.

  • El AWS IoT punto final de la cuenta en la que está registrado el dispositivo.

  • Unidad de transmisión máxima (MTU) de Bluetooth de bajo consumo.

Aprovisionamiento Wi-Fi

El servicio de Aprovisionamiento Wi-Fi permite microcontroladores con capacidades Wi-Fi para hacer lo siguiente:

  • Crear una lista de redes en el rango de alcance.

  • Guardar redes y credenciales de red en la memoria flash.

  • Establecer prioridad de red.

  • Eliminar redes y credenciales de red de la memoria flash.

Abstracción de red

El servicio de abstracción de red abstrae el tipo de conexión de red para las aplicaciones. Una API común interactúa con la pila de hardware de Wi-Fi, Ethernet y Bluetooth de bajo consumo de su dispositivo, lo que permite que una aplicación sea compatible con varios tipos de conexión.

Transferencia de objetos grandes

El servicio de Transferencia de objetos grandes envía y recibe datos de un cliente. Otros servicios, como Aprovisionamiento Wi-Fi y Abstracción de red, utilizan el servicio de Transferencia de objetos grandes para enviar y recibir datos. También puede utilizar la API de Transferencia de objetos grandes para interactuar con el servicio directamente.

Middleware

El middleware Bluetooth Low Energy de FreeRTOS es una abstracción del nivel inferior. APIs El middleware constituye APIs una interfaz más fácil de usar para la pila Bluetooth Low Energy.

Con el middleware APIs, puede registrar varias devoluciones de llamada, en varios niveles, en un solo evento. La inicialización del middleware de Bluetooth de bajo consumo también inicializa los servicios y comienza la publicidad.

Suscripción de devolución de llamada flexible

Supongamos que su hardware de Bluetooth de bajo consumo se desconecta y el servicio de MQTT sobre Bluetooth de bajo consumo necesita detectar la desconexión. Una aplicación que escribiera también podría necesitar detectar el mismo evento de desconexión. El middleware de Bluetooth de bajo consumo puede enrutar el evento a diferentes partes del código en el que haya registrado devoluciones de llamada, sin que la capas superiores compitan por recursos de nivel inferior.

Contenedores de bajo nivel

Los contenedores de Bluetooth de bajo consumo de FreeRTOS de bajo nivel son una abstracción de la pila de Bluetooth de bajo consumo del fabricante. Los contenedores de bajo nivel ofrecen un conjunto común de herramientas APIs para controlar directamente el hardware. Los de bajo nivel APIs optimizan el uso de la RAM, pero su funcionalidad es limitada.

Usa el servicio Bluetooth Low Energy APIs para interactuar con los servicios Bluetooth Low Energy. El servicio APIs exige más recursos que los de bajo nivel APIs.

Dependencias y requisitos

La biblioteca de Bluetooth de bajo consumo tiene las siguientes dependencias directas:

  • Biblioteca de contenedores lineales

  • Una capa de plataforma que interactúa con el sistema operativo para la administración de subprocesos, temporizadores, funciones de reloj y acceso a la red.

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

Solo el servicio de aprovisionamiento Wi-Fi tiene dependencias de la biblioteca de FreeRTOS:

Servicio de GATT Dependencia
Aprovisionamiento Wi-Fi Biblioteca wifi

Para comunicarse con el intermediario de AWS IoT MQTT, debe tener una AWS cuenta y registrar sus dispositivos como AWS IoT cosas. Para obtener más información sobre la configuración, consulte la Guía para desarrolladores de AWS IoT.

Bluetooth de bajo consumo de FreeRTOS utiliza Amazon Cognito para la autenticación de usuarios en su dispositivo móvil. Para utilizar los servicios proxy de MQTT, debe crear una identidad y grupos de usuarios de Amazon Cognito. Cada identidad de Amazon Cognito debe tener asociada la política apropiada. Para obtener más información, consulte la Guía para desarrolladores de Amazon Cognito.

Archivo de configuración de la biblioteca

Las aplicaciones que usan el servicio de MQTT sobre Bluetooth de bajo consumo de FreeRTOS deben proporcionar un archivo de encabezado iot_ble_config.h, en el que se definen los parámetros de configuración. Los parámetros de configuración sin definir toman los valores predeterminados especificados en iot_ble_config_defaults.h.

Algunos parámetros de configuración importantes son:

IOT_BLE_ADD_CUSTOM_SERVICES

Permite a los usuarios crear sus propios servicios.

IOT_BLE_SET_CUSTOM_ADVERTISEMENT_MSG

Permite a los usuarios personalizar la publicidad y examinar los mensajes de respuesta.

Para obtener más información, consulte la Referencia de la API de Bluetooth de bajo consumo.

Optimización

Al optimizar el rendimiento de la placa, tenga en cuenta lo siguiente:

  • Los de bajo nivel APIs utilizan menos RAM, pero ofrecen una funcionalidad limitada.

  • Puede establecer el parámetro bleconfigMAX_NETWORK en el archivo de encabezado iot_ble_config.h en un valor inferior para reducir la cantidad de pila consumida.

  • Puede aumentar el tamaño de MTU a su valor máximo para limitar el almacenamiento en búfer de mensajes y hacer que el código se ejecute más rápido y consuma menos RAM.

Restricciones de uso

De forma predeterminada, la biblioteca de Bluetooth de bajo consumo de FreeRTOS establece la propiedad eBTpropertySecureConnectionOnly en TRUE, lo que coloca el dispositivo en un modo de Solo conexiones seguras. Como se especifica en Bluetooth Core Specification v5.0, Vol 3, parte C, 10.2.4, cuando un dispositivo se encuentra en modo de Solo conexiones seguras, se requiere el nivel de modo de seguridad LE 1 más alto, el nivel 4 para acceder a cualquier atributo que tenga permisos más altos que el nivel del modo de seguridad LE 1 más bajo, el nivel 1. En el nivel 4 del modo de seguridad LE 1, un dispositivo debe tener capacidades de entrada y salida para la comparación numérica.

Estos son los modos compatibles y sus propiedades asociadas:

Modo 1, nivel 1 (sin seguridad)
/* 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 )
Modo 1, nivel 2 (emparejamiento no autenticado con cifrado)
#define IOT_BLE_ENABLE_NUMERIC_COMPARISON        ( 0 )
#define IOT_BLE_ENABLE_SECURE_CONNECTION         ( 0 )
#define IOT_BLE_INPUT_OUTPUT                     ( eBTIONone )
Modo 1, nivel 3 (emparejamiento autenticado con cifrado)

Este modo no se admite.

Modo 1, nivel 4 (emparejamiento de conexiones seguras LE autenticadas con cifrado)

Este modo se admite de forma predeterminada.

Para obtener más información acerca de los modos de seguridad LE, consulte Bluetooth Core Specification v5.0, Vol 3, parte C, 10.2.1.

Inicialización

Si la aplicación interactúa con la pila de Bluetooth de bajo consumo a través de middleware, solo tiene que inicializar el middleware. El middleware se encarga de inicializar las capas inferiores de la pila.

Middleware

Inicialización del middleware

  1. Inicialice cualquier controlador de hardware de Bluetooth de bajo consumo antes de llamar a la API de middleware de Bluetooth de bajo consumo.

  2. Habilite Bluetooth de bajo consumo.

  3. Inicialice el middleware con IotBLE_Init().

    nota

    Este paso de inicialización no es necesario si está ejecutando las AWS demostraciones. El administrador de red se encarga de la inicialización de la demostración, que se encuentra en freertos/demos/network_manager.

Nivel bajo APIs

Si no desea utilizar los servicios GATT Bluetooth Low Energy de FreeRTOS, puede omitir el middleware e interactuar directamente con el de bajo nivel APIs para ahorrar recursos.

Para inicializar el nivel bajo APIs

  1. Inicialice cualquier controlador de hardware Bluetooth Low Energy antes de llamar al. APIs La inicialización del controlador no forma parte del Bluetooth Low Energy de bajo nivel. APIs

  2. La API de bajo nivel de Bluetooth de bajo consumo dispone de una llamada de habilitación/deshabilitación a la pila de Bluetooth de bajo consumo para optimizar la alimentación y los recursos. Antes de llamar al APIs, debe activar Bluetooth Low Energy.

    const BTInterface_t * pxIface = BTGetBluetoothInterface();
xStatus = pxIface->pxEnable( 0 );

  3. El administrador de Bluetooth contiene APIs los elementos comunes a Bluetooth Low Energy y Bluetooth classic. Las devoluciones de llamada para el administrador común se deben inicializar en segundo lugar.

    xStatus = xBTInterface.pxBTInterface->pxBtManagerInit( &xBTManagerCb );

  4. El adaptador de Bluetooth de bajo consumo se adapta sobre la API común. Debe inicializar sus devoluciones de llamada de la misma forma que se inicializa la API común.

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

  5. Registre su nueva aplicación de usuario.

    xBTInterface.pxBTLeAdapterInterface->pxRegisterBleApp( pxAppUuid );

  6. Inicialice las devoluciones de llamadas a los servidores de GATT.

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

    Después de inicializar el adaptador de Bluetooth de bajo consumo, puede agregar un servidor de GATT. Solo puede registrar los servidor de GATT de uno en uno.

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

  7. Establezca las propiedades de la aplicación solo como conexión segura y tamaño de MTU.

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

Referencia de la API

Para ver una referencia completa de la API, consulte Bluetooth Low Energy API Reference.

Ejemplo de uso

Los siguientes ejemplos muestran cómo utilizar la biblioteca de Bluetooth de bajo consumo para la publicidad y la creación de nuevos servicios. Para aplicaciones de demostración de Bluetooth de bajo consumo de FreeRTOS, consulte Bluetooth Low Energy Demo Applications.

Publicidad

  1. En la aplicación, defina el UUID de la publicidad:

    static const BTUuid_t _advUUID =
{
    .uu.uu128 = IOT_BLE_ADVERTISING_UUID,
    .ucType   = eBTuuidType128
};

  2. A continuación, defina la función de devolución de llamada IotBle_SetCustomAdvCb:

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

    Esta devolución de llamada envía el UUID en el mensaje de publicidad y el nombre completo en la respuesta al examen.

  3. Abra vendors/vendor/boards/board/aws_demos/config_files/iot_ble_config.h y establezca IOT_BLE_SET_CUSTOM_ADVERTISEMENT_MSG en 1. Esto activa la devolución de llamada IotBle_SetCustomAdvCb.

Adición de un nuevo servicio

Para ver ejemplos completos de servicios, consulte freertos/.../ble/services.

  1. Cree UUIDs para las características y los descriptores del servicio:

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

  2. Cree un búfer para registrar los controladores de características y descriptores.

    static uint16_t usHandlesBuffer[egattDemoNbAttributes];

  3. Cree la tabla de atributos. Para ahorrar algo de RAM, defina la tabla como una const.

    importante

    Siempre cree los atributos en orden, con el servicio como el primer atributo.

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

  4. Cree una matriz de devoluciones de llamada. Esta matriz de devoluciones de llamada debe seguir el mismo orden que la matriz de la tabla descrita anteriormente.

    Por ejemplo, si vReadCounter se acciona cuando se accede a xCharCounterUUID_TYPE y vWriteCommand se acciona cuando se accede a xCharControlUUID_TYPE, defina la matriz tal y como se indica a continuación:

    static const IotBleAttributeEventCallback_t pxCallBackArray[egattDemoNbAttributes] =
    {
  NULL,
  vReadCounter,
  vEnableNotification,
  vWriteCommand
};

  5. Cree el servicio:

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

  6. Llame a la API IotBle_CreateService con la estructura que ha creado en el paso anterior. El middleware sincroniza la creación de todos los servicios, por lo que cualquier servicio nuevo ya deberá haberse definido cuando se activa la devolución de llamada IotBle_AddCustomServicesCb.

    1. En vendors/vendor/boards/board/aws_demos/config_files/iot_ble_config.h, establezca IOT_BLE_ADD_CUSTOM_SERVICES en 1.

    2. Cree IotBle _ AddCustomServicesCb en su aplicación:

      void IotBle_AddCustomServicesCb(void)
{
    BTStatus_t xStatus;
    /* Select the handle buffer. */
    xStatus = IotBle_CreateService( (BTService_t *)&xGattDemoService, (IotBleAttributeEventCallback_t *)pxCallBackArray );
}

Portabilidad

Periférico de entrada y salida de usuario

Una conexión segura requiere entrada y salida para comparación numérica. El evento de eBLENumericComparisonCallback pueden registrarse con el administrador de eventos:

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

El periférico deben mostrar la clave de acceso numérica y tomar el resultado de la comparación como una entrada.

Portabilidad de implementaciones de API

Para portar FreeRTOS a un nuevo objetivo, debes implementar algunos APIs para el servicio de aprovisionamiento de Wi-Fi y la funcionalidad Bluetooth de bajo consumo de energía.

Bluetooth de bajo consumo APIs

Para usar el middleware Bluetooth Low Energy de FreeRTOS, debe implementar alguno. APIs

APIs común entre GAP para Bluetooth Classic y GAP para Bluetooth Low Energy

  • pxBtManagerInit

  • pxEnable

  • pxDisable

  • pxGetDeviceProperty

  • pxSetDeviceProperty (Todas las opciones son obligatorios esperan eBTpropertyRemoteRssi y eBTpropertyRemoteVersionInfo)

  • pxPair

  • pxRemoveBond

  • pxGetConnectionState

  • pxPinReply

  • pxSspReply

  • pxGetTxpower

  • pxGetLeAdapter

  • pxDeviceStateChangedCb

  • pxAdapterPropertiesCb

  • pxSspRequestCb

  • pxPairingStateChangedCb

  • pxTxPowerCb

APIs específico de GAP para Bluetooth Low Energy

  • pxRegisterBleApp

  • pxUnregisterBleApp

  • pxBleAdapterInit

  • pxStartAdv

  • pxStopAdv

  • pxSetAdvData

  • pxConnParameterUpdateRequest

  • pxRegisterBleAdapterCb

  • pxAdvStartCb

  • pxSetAdvDataCb

  • pxConnParameterUpdateRequestCb

  • pxCongestionCb

Servidor de 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

Para obtener más información acerca de la portabilidad de la biblioteca de Bluetooth de bajo consumo de FreeRTOS para su plataforma, consulte la sección sobre Portabilidad de Bluetooth de bajo consumo en la Guía de portabilidad de FreeRTOS.