RA Flexible Software Package Documentation  Release v5.6.0

 
GTL BLE Abstraction (rm_ble_abs_gtl)
Modules » Networking

Middleware for the Bluetooth peripheral on RA MCUs. This module implements the BLE ABS Interface.

Overview

This module provides BLE GAP functionality that complies with the Bluetooth Core Specification version 5.0 specified by the Bluetooth SIG. This module is configured via the QE for BLE. QE for BLE provides standard and custom services defined by the user.

The module supports the Renesas Electronics DA14531 and DA14535 Bluetooth® Low Energy 5 Modules. The rm_ble_abs_gtl driver interfaces with the DA14531/DA14535 module over UART.

Features

The Bluetooth® Low Energy Abstraction module with GTL supports the following features:

Configuration

Pin Configuration

Pins used by the BLE driver to control the DA14531/DA14535 module:

Usage Notes

Getting Started Guide

The below guide walks users through building a fully working solution that allows booting from the host via 1-wire UART in order to run a BLE application from the RA MCU using the GTL interface.

https://lpccs-docs.renesas.com/DA1453x-FSP_BLE_Framework/UM-B-172/index.html

Addresses

When using a public BD address the address pre-programmed into the DA14531/DA14535 will be used and can't be overridden.

A random address can be set by calling the R_BLE_VS_SetBdAddr function before the R_BLE_GAP_Init function is called.

Heap Requirements

Ensure the BSP heap size is set to at least 2K bytes.

When using FreeRTOS ensure the heap 4 size is set to a minimum of 2K bytes.

Module Firmware Compatibility

This middleware module is compatible with GTL binary version 6.0.22 and later. You must ensure that the DA14531/DA14535 Module (or PMOD) you are using contains this version (or later) firmware or that you use the boot from host feature and have the host MCU load the binary into the DA14531/DA14535. Note that DA14531 and DA14535 are not firmware compatible even though the GTL API is the same.

Instructions detailing how to upgrade the firmware in a DA14531 Module can be found here:

https://lpccs-docs.renesas.com/US159-DA14531EVZ_Firmware_Upgrade/index.html

The GTL binary file can be downloaded using the tool described in the above instructions, or by using the following link:

https://www.renesas.com/us/en/document/swo/fsp-gtl-binary-us159-da14531evz-pmod-programming?r=1564826

Limitations

Developers should be aware of the following limitations when using the BLE_ABS:

Following a power on reset, the R_BLE_VS_GetRand function always returns the same number. Subsequent calls to this function produce random numbers.

Service and characteristic write callback functions, created when using the QE Tool are not supported

The boot from host feature currently supports 1-wire and 2-wire UART operation. If using a 1-wire boot from host the UART RX and TX pins on the host RA MCU must be tied together using a 1K ohm resistor in order to boot the DA14531/DA14535 - this resistor can remain in place after the boot operation has been completed. Boot from host using 2-wire UART is not supported when using a DA14531MOD module because not all the required pins are exposed. Boot from host using 2-wire UART is supported when a DA14535PMOD with SmartBoot (UM-B-171) is already flashed in DA14535. In this case the same pins used for GTL communication are also used for 2-wire boot.

Legacy pairing functionality currently works with the DA14531/DA14535 module acting as a Peripheral. Bonding data supports only one connection. Bonding data is stored in RAM and not in Flash. Data will be lost after a reset.

The RI feature of attributes is controlled from the flag read_notify = 1. In case of a write request the local data base is automatically updated. The app will be notified by an BLE_GATTS_OP_PEER_XXX_WRITE_REQ. In case of a read request and read_notify==1 (read indication) the local data base is not automatically accessed to get the value. The user is responsible to provide the reply value from gatts_cb by using R_BLE_GTL_GATTS_ReadCfm after a BLE_GATTS_EVENT_DB_ACCESS_IND with BLE_GATTS_OP_PEER_XXX_READ_REQ. The CCC values are always treated as RI values. If the attribute is CCC and it is not marked as read_notify, then r_ble_gtl automatically handles it by using a cached value.

Currently supported rm_ble_abs_gtl interface functions:

Currently supported r_ble_api interface functions:

Currently supported callback events:

Examples

BLE_ABS_GTL Basic Example

This is a basic example of minimal use of the BLE_ABS_GTL in an application.

/* The callback is called when peripheral event occurs. */
void gap_peripheral_cb (uint16_t type, ble_status_t result, st_ble_evt_data_t * p_data)
{
FSP_PARAMETER_NOT_USED(result);
FSP_PARAMETER_NOT_USED(p_data);
switch (type)
{
case BLE_GAP_EVENT_STACK_ON:
{
g_ble_event_flag = g_ble_event_flag | BLE_ABS_EVENT_FLAG_STACK_ON;
break;
}
case BLE_GAP_EVENT_ADV_ON:
{
st_ble_gap_adv_set_evt_t * p_gap_adv_set_evt_param = (st_ble_gap_adv_set_evt_t *) p_data->p_param;
g_advertising_handle = p_gap_adv_set_evt_param->adv_hdl;
g_ble_event_flag |= BLE_ABS_EVENT_FLAG_ADV_ON;
break;
}
case BLE_GAP_EVENT_ADV_OFF:
{
g_ble_event_flag |= BLE_ABS_EVENT_FLAG_ADV_OFF;
break;
}
case BLE_GAP_EVENT_CONN_IND:
{
g_ble_event_flag |= BLE_ABS_EVENT_FLAG_CONN_IND;
break;
}
{
/* Do nothing. */
break;
}
default:
break;
}
}
#define BLE_ABS_EVENT_FLAG_STACK_ON (0x01 << 0)
#define BLE_ABS_EVENT_FLAG_CONN_IND (0x01 << 1)
#define BLE_ABS_EVENT_FLAG_ADV_ON (0x01 << 2)
#define BLE_ABS_EVENT_FLAG_ADV_OFF (0x01 << 3)
#define BLE_ABS_EVENT_FLAG_DISCONN_IND (0x01 << 4)
#define BLE_ABS_EVENT_FLAG_RSLV_LIST_CONF_COMP (0x01 << 5)
#define BLE_ABS_EXAMPLE_SHORTENED_LOCAL_NAME 'E', 'x', 'a', 'm', 'p', 'l', 'e'
#define BLE_ABS_EXAMPLE_COMPLETE_LOCAL_NAME 'T', 'E', 'S', 'T', '_', 'E', 'x', 'a', 'm', 'p', 'l', 'e'
#define BLE_ABS_EXAMPLE_SLOW_ADVERTISING_INTERVAL (0x00000640)
void ble_abs_peripheral_example (void)
{
fsp_err_t err = FSP_SUCCESS;
volatile uint32_t timeout = UINT16_MAX * UINT8_MAX * 8;
uint8_t advertising_data[] =
{
/* Flags */
0x02,
0x01,
(0x1a),
/* Shortened Local Name */
0x08,
0x08,
BLE_ABS_EXAMPLE_SHORTENED_LOCAL_NAME,
};
/* Scan Response Data */
uint8_t scan_response_data[] =
{
/* Complete Local Name */
0x0D,
0x09,
BLE_ABS_EXAMPLE_COMPLETE_LOCAL_NAME,
};
ble_abs_legacy_advertising_parameter_t legacy_advertising_parameter =
{
.p_peer_address = NULL,
.slow_advertising_interval = BLE_ABS_EXAMPLE_SLOW_ADVERTISING_INTERVAL,
.slow_advertising_period = 0x0000,
.p_advertising_data = advertising_data,
.advertising_data_length = sizeof(advertising_data),
.p_scan_response_data = scan_response_data,
.scan_response_data_length = sizeof(scan_response_data),
.advertising_filter_policy = BLE_ABS_ADVERTISING_FILTER_ALLOW_ANY,
.advertising_channel_map = (BLE_GAP_ADV_CH_37 | BLE_GAP_ADV_CH_38 | BLE_GAP_ADV_CH_39),
.own_bluetooth_address_type = BLE_GAP_ADDR_PUBLIC,
.own_bluetooth_address = {0},
};
g_ble_event_flag = 0;
/* Open the module. */
err = RM_BLE_ABS_Open(&g_ble_abs0_ctrl, &g_ble_abs0_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
/* Configure the Transmit Level */
err = (fsp_err_t) R_BLE_VS_SetTxPower(0, BLE_ABS_TRANSMIT_POWER);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
/* Wait BLE_GAP_EVENT_STACK_ON event is notified. */
while (!(BLE_ABS_EVENT_FLAG_STACK_ON & g_ble_event_flag) && (--timeout > 0U))
{
R_BLE_Execute();
}
time_out_handle_error(timeout);
g_ble_event_flag = 0;
timeout = UINT16_MAX * UINT8_MAX * 8;
/* Start advertising. */
err = RM_BLE_ABS_StartLegacyAdvertising(&g_ble_abs0_ctrl, &legacy_advertising_parameter);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
while (!(BLE_ABS_EVENT_FLAG_CONN_IND & g_ble_event_flag) && (--timeout > 0U))
{
if (BLE_ABS_EVENT_FLAG_ADV_OFF & g_ble_event_flag)
{
/* Restart advertise, when stop advertising. */
err = RM_BLE_ABS_StartLegacyAdvertising(&g_ble_abs0_ctrl, &legacy_advertising_parameter);
if (FSP_SUCCESS == err)
{
g_ble_event_flag &= (uint16_t) ~BLE_ABS_EVENT_FLAG_ADV_OFF;
}
else if (FSP_ERR_INVALID_STATE == err)
{
/* BLE driver state is busy. */
;
}
else
{
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
}
}
else if ((timeout % BLE_ABS_RETRY_INTERVAL) == 0U)
{
/* Stop advertising after a certain amount of time */
R_BLE_GAP_StopAdv(g_advertising_handle);
}
else
{
;
}
R_BLE_Execute();
}
time_out_handle_error(timeout);
/* Clean up & Close BLE driver */
g_ble_event_flag = 0;
/* Close BLE driver */
err = RM_BLE_ABS_Close(&g_ble_abs0_ctrl);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
}