Amazon FreeRTOS
Porting Guide

Porting the Bluetooth Low Energy Library

You can use the Amazon 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 Amazon FreeRTOS Bluetooth Low Energy Library in the Amazon FreeRTOS User Guide.

Note

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

Prerequisites

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

Porting

Three files in the <amazon-freertos>/libraries/abstractions/ble_hal/include folder define the Amazon 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:

bt_hal_manager.h

  • pxBtManagerInit

  • pxEnable

  • pxDisable

  • pxGetDeviceProperty

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

  • pxPair

  • pxRemoveBond

  • pxGetConnectionState

  • pxPinReply

  • pxSspReply

  • pxGetTxpower

  • pxGetLeAdapter

  • pxDeviceStateChangedCb

  • pxAdapterPropertiesCb

  • pxSspRequestCb

  • pxPairingStateChangedCb

  • pxTxPowerCb

bt_hal_manager_adapter_ble.h

  • pxRegisterBleApp

  • pxUnregisterBleApp

  • pxBleAdapterInit

  • pxStartAdv

  • pxStopAdv

  • pxSetAdvData

  • pxConnParameterUpdateRequest

  • pxRegisterBleAdapterCb

  • pxAdvStartCb

  • pxSetAdvDataCb

  • pxConnParameterUpdateRequestCb

  • pxCongestionCb

bt_hal_gatt_server.h

  • 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

Testing

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 Amazon 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.

Important

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 <amazon-freertos>/vendors/<vendor>/boards/<board>/ports/ble to your aws_tests IDE project.

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

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

  4. Open <amazon-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 Amazon FreeRTOS Portable Layers.

The CMakeLists.txt template list file under <amazon-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 <amazon-freertos>/tests/bleTestsScripts/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@192.168.1.4: ssh -t -t 192.168.1.4 -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. Build the test project, and then flash it to your device for execution.

  3. Check the test results in the UART console.

Validation

To officially qualify a device for Amazon 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 Amazon FreeRTOS in the Amazon 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 Amazon FreeRTOS qualification process. For more information, see the Amazon FreeRTOS Qualification Guide.