Visão geral Arquitetura Dependências e requisitos Arquivo de configuração da biblioteca Otimização Restrições de uso Inicialização Referência da API Exemplo de uso Portabilidade

Biblioteca de Bluetooth Low Energy

Importante

Esta é uma versão arquivada do Guia do usuário do FreeRTOS para usar com a versão 202012.00 do FreeRTOS. Para obter a versão mais recente deste documento, consulte o Guia do usuário do FreeRTOS.

Visão geral

O FreeRTOS oferece suporte à publicação e inscrição em tópicos do MQTT pela Bluetooth Low Energy por meio de um dispositivo de proxy, como um celular. Com a biblioteca FreeRTOS Bluetooth Low Energy, seu microcontrolador pode se comunicar com segurança com o broker MQTT. AWS IoT

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

Usando o Mobile SDKs for FreeRTOS Bluetooth, você pode escrever aplicativos móveis nativos que se comunicam com os aplicativos incorporados em seu microcontrolador via Bluetooth Low Energy. Para obter mais informações sobre o celular SDKs, consulteCelular SDKs para dispositivos Bluetooth FreeRTOS.

A biblioteca Bluetooth Low Energy do FreeRTOS inclui serviços para configurar redes Wi-Fi, transferir grandes quantidades de dados e fornecer abstrações de rede pela Bluetooth Low Energy. A biblioteca FreeRTOS Bluetooth Low Energy também inclui middleware e APIs nível inferior para um controle mais direto sobre sua pilha Bluetooth Low Energy.

Arquitetura

Três camadas compõem a biblioteca Bluetooth Low Energy do FreeRTOS serviços, middleware e wrappers de nível inferior.

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

Serviços

A camada de serviços Bluetooth Low Energy do FreeRTOS consiste em quatro serviços de atributos genéricos (GATT) que utilizam o APIs middleware: informações do dispositivo, provisionamento de Wi-Fi, abstração de rede e transferência de objetos grandes.

Informações do dispositivo

O serviço de Informações do dispositivo reúne informações sobre o microcontrolador, incluindo:

A versão do FreeRTOS que o dispositivo está usando.
O AWS IoT endpoint da conta na qual o dispositivo está registrado.
Unidade de transmissão máxima de Bluetooth Low Energy (MTU).

Provisionamento de Wi-Fi

O serviço de provisionamento de Wi-Fi permite que os microcontroladores com recursos de Wi-Fi façam o seguinte:

Listar redes no intervalo.
Salvar redes e credenciais de rede na memória flash.
Definir a prioridade da rede.
Excluir redes e credenciais de rede da memória flash.

Abstração de rede

O serviço de abstração de rede abstrai o tipo de conexão de rede para aplicações. Uma API comum interage com a pilha de hardware Wi-Fi, Ethernet e Bluetooth Low Energy do seu dispositivo, permitindo que uma aplicação seja compatível com vários tipos de conexão.

Transferência de objetos grandes

O serviço de transferência de objetos grandes envia e recebe dados de um cliente. Outros serviços, como provisionamento de Wi-Fi e abstração de rede, usam o serviço de transferência de objetos grandes para enviar e receber dados. Você também pode usar a API de transferência de objetos grandes para interagir com o serviço diretamente.

Middleware

O middleware FreeRTOS Bluetooth Low Energy é uma abstração do nível inferior. APIs O middleware APIs compõe uma interface mais amigável para a pilha Bluetooth Low Energy.

Usando o middleware APIs, você pode registrar vários retornos de chamada, em várias camadas, em um único evento. Iniciar o middleware da biblioteca Bluetooth Low Energy também inicializa serviços e começa a publicidade.

Assinatura de retorno de chamada flexível

Suponha que o hardware Bluetooth Low Energy se desconecta, e o serviço MQTT por Bluetooth Low Energy precisa detectar a desconexão. Uma aplicação gravada também poderá ter que detectar o mesmo evento de desconexão. O middleware Bluetooth Low Energy pode rotear o evento para diferentes partes do código onde os retornos de chamada foram registrados, sem fazer com que as camadas mais altas compitam por recursos de nível inferior.

Wrappers de baixo nível

Os wrappers de nível baixo da Bluetooth Low Energy do FreeRTOS são uma abstração da pilha do fabricante Bluetooth Low Energy. Os invólucros de baixo nível oferecem um conjunto comum APIs de controle direto sobre o hardware. Os de baixo nível APIs otimizam o uso da RAM, mas têm funcionalidade limitada.

Use o serviço Bluetooth Low Energy APIs para interagir com os serviços Bluetooth Low Energy. O serviço APIs exige mais recursos do que o de baixo nível APIs.

Dependências e requisitos

A biblioteca Bluetooth Low Energy tem as seguintes dependências diretas:

Biblioteca Linear Containers
Uma camada de plataforma que faz interface com o sistema operacional para o gerenciamento de threads, temporizadores, funções de relógio e acesso à rede.

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

Somente o serviço de provisionamento de Wi-Fi tem dependências de biblioteca do FreeRTOS:

Serviço de GATT	Dependência
Provisionamento de Wi-Fi	Biblioteca de Wi-Fi

Para se comunicar com o corretor AWS IoT MQTT, você deve ter uma AWS conta e registrar seus dispositivos como AWS IoT coisas. Para obter mais informações sobre a configuração, consulte o Guia do desenvolvedor do AWS IoT.

O Bluetooth Low Energy do FreeRTOS usa o Amazon Cognito para a autenticação do usuário em seu dispositivo móvel. Para usar os serviços de proxy MQTT, é necessário criar uma identidade do Amazon Cognito e grupos de usuários. Cada identidade do Amazon Cognito deve ter a política adequada anexada. Para obter mais informações, consulte o Guia do desenvolvedor do Amazon Cognito.

Arquivo de configuração da biblioteca

As aplicações que usam o serviço MQTT do FreeRTOS pela Bluetooth Low Energy devem fornecer um arquivo de cabeçalho iot_ble_config.h, no qual são definidos parâmetros de configuração. Os parâmetros de configuração não definidos assumem os valores padrão especificados em iot_ble_config_defaults.h.

Alguns parâmetros de configuração importantes incluem:

IOT_BLE_ADD_CUSTOM_SERVICES: Permite que os usuários criem seus próprios serviços.
IOT_BLE_SET_CUSTOM_ADVERTISEMENT_MSG: Permite que os usuários personalizem o anúncio e verifiquem as mensagens de resposta.

Para obter mais informações, consulte Referência de API do Bluetooth Low Energy.

Otimização

Ao otimizar o desempenho da placa, considere o seguinte:

O nível baixo APIs usa menos RAM, mas oferece funcionalidade limitada.
Você pode definir o parâmetro bleconfigMAX_NETWORK no arquivo de cabeçalho iot_ble_config.h como um valor menor para reduzir a quantidade consumida da pilha.
Você pode aumentar o tamanho da MTU até seu valor máximo para limitar o armazenamento em buffer de mensagens e fazer com que o código execute mais rápido e consuma menos RAM.

Restrições de uso

Por padrão, a biblioteca Bluetooth Low Energy do FreeRTOS define a propriedade eBTpropertySecureConnectionOnly como VERDADEIRA, que coloca o dispositivo em um modo Somente conexões seguras. Conforme especificado pela Bluetooth Core Specification v5.0, Vol. 3, Parte C, 10.2.4, quando um dispositivo está no modo Somente conexões seguras, é necessário o nível de segurança LE mais alto do modo 1, o nível 4, para acessar qualquer atributo que tem permissões mais altas que o nível de segurança LE mais baixo do modo 1, o nível 1. No nível 4 de segurança LE do modo 1, um dispositivo deve ter recursos de entrada e saída para comparação numérica.

Aqui estão os modos compatíveis e suas propriedades associadas:

Modo 1, Nível 1 (sem segurança)


/* 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, Nível 2 (emparelhamento com criptografia não autenticada)


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

Modo 1, Nível 3 (emparelhamento com criptografia autenticada)

Esse modo não é compatível.

Modo 1, Nível 4 (emparelhamento com criptografia de conexões seguras LE autenticadas)

Esse modo é suportado por padrão.

Para obter informações sobre os modos de segurança LE, consulte a Bluetooth Core Specification v5.0, Vol. 3, Parte C, 10.2.1.

Inicialização

Se a aplicação interage com a pilha Bluetooth Low Energy por meio de middleware, só é necessário inicializar o middleware. O middleware cuida da inicialização das camadas inferiores da pilha.

Middleware

Para inicializar o middleware

Inicialize qualquer driver de hardware Bluetooth Low Energy antes de chamar a API de middleware da Bluetooth Low Energy.
Habilitar Bluetooth Low Energy.
Inicialize o middleware com IotBLE_Init().

nota
Essa etapa de inicialização não é necessária se você estiver executando as AWS demonstrações. A inicialização de demonstração é processada pelo gerenciador de rede, localizado em freertos/demos/network_manager.

Nível baixo APIs

Se você não quiser usar os serviços FreeRTOS Bluetooth Low Energy GATT, você pode ignorar o middleware e interagir diretamente com os de baixo nível para economizar recursos. APIs

Para inicializar o nível baixo APIs

Inicialize todos os drivers de hardware Bluetooth Low Energy antes de ligar para o. APIs A inicialização do driver não faz parte do nível baixo APIs do Bluetooth Low Energy.
A API de baixo nível da Bluetooth Low Energy fornece uma chamada de habilitação/desabilitação para a pilha Bluetooth Low Energy a fim de otimizar a potência e os recursos. Antes de ligar para o APIs, você deve ativar o Bluetooth Low Energy.
```
const BTInterface_t * pxIface = BTGetBluetoothInterface();
xStatus = pxIface->pxEnable( 0 );
```
O gerenciador de Bluetooth contém o APIs que é comum ao Bluetooth Low Energy e ao Bluetooth classic. Os retornos de chamada para o gerenciador comum devem ser inicializados depois.
```
xStatus = xBTInterface.pxBTInterface->pxBtManagerInit( &xBTManagerCb );
```

O adaptador Bluetooth Low Energy se encaixa em cima da API comum. É necessário inicializar os retornos de chamada da mesma forma que a API comum foi inicializada.


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

Registre a nova aplicação do usuário.


xBTInterface.pxBTLeAdapterInterface->pxRegisterBleApp( pxAppUuid );

Inicialize os retornos de chamada para os servidores GATT.


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

Depois de inicializar o adaptador Bluetooth Low Energy, você pode adicionar um servidor GATT. Só é possível registrar um servidor GATT por vez.


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

Defina as propriedades da aplicação, como somente conexão segura e tamanho da MTU.
```
xStatus = xBTInterface.pxBTInterface->pxSetDeviceProperty( &pxProperty[ usIndex ] );
```

Referência da API

Para obter uma referência completa de API, consulte Referência de API do Bluetooth Low Energy.

Exemplo de uso

Os exemplos a seguir demonstram como usar a biblioteca Bluetooth Low Energy para publicidade e criação de novos serviços. Para obter aplicações de demonstração da Bluetooth Low Energy do FreeRTOS completos, consulte Aplicações de demonstração de 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;
}

Esse retorno de chamada envia o UUID na mensagem de anúncio e o nome completo na resposta de verificação.

Abra vendors/vendor/boards/board/aws_demos/config_files/iot_ble_config.h e defina IOT_BLE_SET_CUSTOM_ADVERTISEMENT_MSG como 1. Isso dispara o retorno de chamada IotBle_SetCustomAdvCb.

Adição de um novo serviço

Para ver exemplos completos de serviços, consulte freertos/.../ble/services.

Crie UUIDs para as características e os descritores do serviço:


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

Crie um buffer para registrar as alças da característica e dos descritores:
```
static uint16_t usHandlesBuffer[egattDemoNbAttributes];
```

Crie a tabela de atributo. Para economizar RAM, defina a tabela como const.

Importante

Sempre crie os atributos em ordem, com o serviço como o primeiro 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 )
          }
     }
};

Crie uma matriz de retornos de chamada. Essa matriz de retornos de chamada deve seguir a mesma ordem que a matriz de tabela definida acima.

Por exemplo, se vReadCounter é acionado quando xCharCounterUUID_TYPE é acessado, e vWriteCommand é acionado quando xCharControlUUID_TYPE é acessado, defina a matriz da seguinte forma:
```
static const IotBleAttributeEventCallback_t pxCallBackArray[egattDemoNbAttributes] =
    {
  NULL,
  vReadCounter,
  vEnableNotification,
  vWriteCommand
};
```

Crie o serviço:


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

Chame a API IotBle_CreateService com a estrutura que você criou na etapa anterior. O middleware sincroniza a criação de todos os serviços e, portanto, é necessário que todos os novos serviços já tenham sido definidos quando o IotBle_AddCustomServicesCb retorno de chamada for acionado.
1. Defina IOT_BLE_ADD_CUSTOM_SERVICES como 1 em vendors/vendor/boards/board/aws_demos/config_files/iot_ble_config.h.
2. Crie IotBle _ AddCustomServicesCb em seu aplicativo:
```
void IotBle_AddCustomServicesCb(void)
{
    BTStatus_t xStatus;
    /* Select the handle buffer. */
    xStatus = IotBle_CreateService( (BTService_t *)&xGattDemoService, (IotBleAttributeEventCallback_t *)pxCallBackArray );
}
```

Portabilidade

Periférico de entrada e saída do usuário

Uma conexão segura requer entrada e saída para comparação numérica. O evento eBLENumericComparisonCallback pode ser registrado usando o gerenciador de eventos:


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

O periférico deve exibir a chave de acesso numérica e assumir o resultado da comparação como uma entrada.

Transferência de implementações da API

Para portar os FreeRTOS para um novo destino, você deve implementar APIs alguns para o serviço de provisionamento de Wi-Fi e a funcionalidade Bluetooth Low Energy.

Bluetooth de baixa energia APIs

Para usar o middleware FreeRTOS Bluetooth Low Energy, você deve implementar alguns. APIs

APIs comum entre GAP para Bluetooth Classic e GAP para Bluetooth Low Energy

pxBtManagerInit
pxEnable
pxDisable
pxGetDeviceProperty
pxSetDeviceProperty (Todas as opções são obrigatórias, exceto eBTpropertyRemoteRssi e eBTpropertyRemoteVersionInfo)
pxPair
pxRemoveBond
pxGetConnectionState
pxPinReply
pxSspReply
pxGetTxpower
pxGetLeAdapter
pxDeviceStateChangedCb
pxAdapterPropertiesCb
pxSspRequestCb
pxPairingStateChangedCb
pxTxPowerCb

APIs específico para GAP para Bluetooth Low Energy

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

Servidor 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 obter mais informações sobre a portabilidade da biblioteca Bluetooth Low Energy do FreeRTOS para sua plataforma, consulte Portabilidade da biblioteca Bluetooth Low Energy no Guia de portabilidade do FreeRTOS.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

backoffAlgorithm

Celular SDKs para dispositivos Bluetooth FreeRTOS

Biblioteca de Bluetooth Low Energy

Importante

Visão geral

Arquitetura

Serviços

Informações do dispositivo

Provisionamento de Wi-Fi

Abstração de rede

Transferência de objetos grandes

Middleware

Assinatura de retorno de chamada flexível

Wrappers de baixo nível

Dependências e requisitos

Arquivo de configuração da biblioteca

Otimização

Restrições de uso

Inicialização

Middleware

nota

Nível baixo APIs

Referência da API

Exemplo de uso

Publicidade

Adição de um novo serviço

Importante

Portabilidade

Periférico de entrada e saída do usuário

Transferência de implementações da API

Bluetooth de baixa energia APIs

APIs comum entre GAP para Bluetooth Classic e GAP para Bluetooth Low Energy

APIs específico para GAP para Bluetooth Low Energy

Servidor GATT