Porting the Bluetooth Low Energy library - FreeRTOS

Porting the Bluetooth Low Energy library

You can use the FreeRTOS Bluetooth Low Energy library to provision Wi-Fi and send MQTT messages over Bluetooth Low Energy. The Bluetooth Low Energy library also includes higher-level APIs that you can use to communicate directly with the Bluetooth Low Energy stack. For more information, see FreeRTOS Bluetooth Low Energy Library in the FreeRTOS User Guide.


A port of the FreeRTOS Bluetooth Low Energy library is currently not required for qualification.


To port the Bluetooth Low Energy library, you need the following:


Three files in the freertos/libraries/abstractions/ble_hal/include folder define the FreeRTOS Bluetooth Low Energy APIs:

  • bt_hal_manager.h

  • bt_hal_manager_adapter_ble.h

  • bt_hal_gatt_server.h

Each file includes comments that describe the APIs. You must implement the following APIs:


  • pxBtManagerInit

  • pxEnable

  • pxDisable

  • pxGetDeviceProperty

  • pxSetDeviceProperty (All options are mandatory except eBTpropertyRemoteRssi and eBTpropertyRemoteVersionInfo)

  • pxPair

  • pxRemoveBond

  • pxGetConnectionState

  • pxPinReply

  • pxSspReply

  • pxGetTxpower

  • pxGetLeAdapter

  • pxDeviceStateChangedCb

  • pxAdapterPropertiesCb

  • pxSspRequestCb

  • pxPairingStateChangedCb

  • pxTxPowerCb


  • pxRegisterBleApp

  • pxUnregisterBleApp

  • pxBleAdapterInit

  • pxStartAdv

  • pxStopAdv

  • pxSetAdvData

  • pxConnParameterUpdateRequest

  • pxRegisterBleAdapterCb

  • pxAdvStartCb

  • pxSetAdvDataCb

  • pxConnParameterUpdateRequestCb

  • pxCongestionCb


  • 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


This diagram shows the Bluetooth Low Energy testing framework.

To test your Bluetooth Low Energy ports, your computer communicates with an external, Bluetooth-enabled device (a Raspberry Pi 3 Model B+) over SSH, and with your device over Bluetooth Low Energy.

The Bluetooth Low Energy porting and qualification tests target the low-level wrapper layer that lies just above the manufacturer's hardware stack in the FreeRTOS Bluetooth Low Energy architecture:

If you are using an IDE to build test projects, you need to set up your library port in the IDE project.

Setting up the IDE test project

If you are using an IDE for porting and testing, you need to add some source files to the IDE test project before you can test your ported code.


In the following steps, make sure that you add the source files to your IDE project from their on-disk location. Do not create duplicate copies of source files.

To set up the Bluetooth Low Energy library in the IDE project

  1. Add all of the files in freertos/vendors/vendor/boards/board/ports/ble to your aws_tests IDE project.

  2. Add all of the files in freertos/libraries/abstractions/ble_hal/include to your aws_tests IDE project.

  3. Add all of the files in freertos/libraries/c_sdk/standard/ble to your aws_tests IDE project.

  4. Open freertos/vendors/vendor/boards/board/aws_tests/application_code/main.c, and enable the required Bluetooth Low Energy drivers.

Configuring the CMakeLists.txt file

If you are using CMake to build your test project, you need to define a portable layer target for the library in your CMake list file.

To define a library's portable layer target in CMakeLists.txt, follow the instructions in FreeRTOS portable layers.

The CMakeLists.txt template list file under freertos/vendors/vendor/boards/board/CMakeLists.txt includes example portable layer target definitions. You can uncomment the definition for the library that you are porting, and modify it to fit your platform.

Setting up your local testing environment

To set up the Raspberry Pi for testing

  1. Follow the instructions in Setting up your Raspberry Pi to set up your Raspberry Pi with Raspbian OS.

  2. Download bluez 5.50 from the kernel.org repository.

  3. Follow the instructions in the README on the kernel.org repository to install bluez 5.50 on the Raspberry Pi.

  4. Enable SSH on the Raspberry Pi. For instructions, see the Raspberry Pi documentation.

  5. On your computer, open the freertos/libraries/abstractions/ble_hal/test/ble_test_scripts/runPI.sh script, and change the IP addresses in the first two lines to the IP address of your Raspberry Pi:

    #!/bin/sh scp * root@ ssh -t -t -l root << 'ENDSSH' rm -rf "/var/lib/bluetooth/*" hciconfig hci0 reset python test1.py sleep 1 ENDSSH

Running the tests

To execute the Bluetooth Low Energy tests

  1. Execute the runPI.sh script.

  2. Clear any existing BLE bonds stored in the device.

  3. Build the test project, and then flash it to your device for execution.

  4. Check the test results in the UART console.


To officially qualify a device for FreeRTOS, you need to validate the device's ported source code with AWS IoT Device Tester. Follow the instructions in Using AWS IoT Device Tester for FreeRTOS in the FreeRTOS User Guide to set up Device Tester for port validation. To test a specific library's port, the correct test group must be enabled in the device.json file in the Device Tester configs folder.

After you have ported the Bluetooth Low Energy library, you can start the FreeRTOS qualification process. For more information, see the FreeRTOS Qualification Guide.

If the device supports Over the Air Updates, then you should also validate Over the Air Updates over Bluetooth Low Energy using a companion device. For more details, see the next topic, Perform Over the Air Updates using Bluetooth Low Energy.