RA Flexible Software Package Documentation  Release v6.0.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

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

Up to 3 concurrent connections are supported.

For DA1453x Sleep mode CTSRTS0 (EK-RA6M4) should be set to P413. Flow Control CTS/RTS Selection should be set to Hardware CTS. If RA is required to wake-up from DA453x P413 and P414 should be shorted and P414 should be se to interrupt mode.

For bonded devices Client Characteristic Configuration (CCC) values are not saved to flash memory. They are kept to RAM as long as reset does not take place. If the user wishes to save the CCC values to non-volatile memory, he should handle it from the application layer by marking them as Read Indicated (RI, please find the description bellow).

The CCC values are not kept per connection, the value of a CCC is the value of the last modification by a GATT Client. If the user wishes to keep CCC values per connection, he should handle it from the application layer by marking them as Read Indicated (RI, please find the description bellow).

Maximum bonded devices are limited to seven (7). Application must delete an entry before bonding with a new device. Saving bond data is supported with devices that use HP_Flash and boards RA6M4_EK, RA6M5_EK, RA4M3_EK, RA4M2_EK.

Role switching between Central and Peripheral is not supported after the devices have been bonded.

Out Of Band (OOB) paring is not supported.

GAP operations cannot overlap, e.g. you cannot initiate two connections concurrently

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.

The RI feature of attributes (values are not stored in DA1453x database) is controlled from the flag Enable Characteristic Value Read Callback of QE Tool. 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 Value Read Callback is enabled (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 Client Characteristic Configuration (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.

Service and characteristic write callback functions, are not generated by the QE Tool. Thus, R_BLE_GTL_GATTC_WRITE_REQ_IND always confirms with R_BLE_GTL_GAP_ERR_NO_ERROR. No value check is provided for incorrect value/range etc

R_BLE_GTL_GAP_StartScan supports only :

R_BLE_GTL_GAP_CreateConn supports only :

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