SPP BLE Abstraction (rm_ble_abs_spp)

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 RYZ012 Bluetooth® Low Energy 5 Module. The rm_ble_abs_spp driver interfaces with the RYZ012 module over UART or SPI.

Features

The Bluetooth Low Energy (BLE) Abstraction module with SPP supports the following features:

• Common functionality
  • Open/Close the BLE protocol stack.
  • Setting Transmit Power Level.
• The following GAP Role support
  • Peripheral: The device that accepts a connection request from Central and establishes a connection.
• GAP functionality
  • Initialize the Host stack.
  • Setting address.
  • Start/Stop Advertising.
  • Connect/Disconnect a link.
• GATT Common functionality
  • Get MTU Size.
• GATT Server functionality
  • Initialization of GATT Server.
  • Loading of Profile definition.
  • Notification of characteristics modification.
  • Read/Write of GATT Profile from host.
• Selectable Communication Interfaces
  • SPI Interface
  • UART Interface

Target Devices

The BLE Abstraction module supports the following devices.

• RA6 line of devices using the RYZ012 module
• RA4 Line of devices using the RYZ012 module

Configuration

Build Time Configurations for rm_ble_abs_spp

The following build time configurations are defined in fsp_cfg/rm_ble_abs_spp_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enable Disable	Default (BSP)	Specify whether to include code for API parameter checking.
Reset Port	Refer to the RA Configuration tool for available options.	03	Specify the module reset pin port for the MCU.
Reset Pin	Refer to the RA Configuration tool for available options.	10	Specify the module reset pin for the MCU.
UART/SPI Select Port (PB5)	Refer to the RA Configuration tool for available options.	03	Specify the module PB5 (UART/SPI select) port for the MCU.
UART/SPI Select Pin (PB5)	Refer to the RA Configuration tool for available options.	11	Specify the module PB5 (UART/SPI select) pin for the MCU.
SPI Software SSL Port	Refer to the RA Configuration tool for available options.	Disabled	Specify the port to use for controlling SSL using the ioport module.
SPI Software SSL Pin	Refer to the RA Configuration tool for available options.	Disabled	Specify the pin to use for controlling SSL using the ioport module.
Transmit Power Level (in dBm)	Refer to the RA Configuration tool for available options.	4.57	Specify the module transmit power in dBm.

Configurations for Networking > SPP BLE Abstraction (rm_ble_abs_spp)

This module can be added to the Stacks tab via New Stack > Networking > SPP BLE Abstraction (rm_ble_abs_spp).

Configuration	Options	Default	Description
General
Name	Name must be a valid C symbol	g_ble_abs0	Module name.
GAP callback	Name must be a valid C symbol	gap_cb	If QE is used, set to "gap_cb".
Vendor specific callback	Name must be a valid C symbol	vs_cb	If QE is used, set to "vs_cb".
GATT server callback parameter	Name must be a valid C symbol	gs_abs_gatts_cb_param	If QE is used, set to "gs_abs_gattc_cb_param".
GATT server callback number	Must be a valid number	2	The number of GATT Server callback functions.
GATT client callback parameter	Name must be a valid C symbol	gs_abs_gattc_cb_param	Set GATT client callback parameter. If QE is used, set to "gs_abs_gattc_cb_param".
GATT client callback number	Must be a valid number	2	The number of GATT Server callback functions.

Pin Configuration

Pins used by the BLE driver to control the RYZ012 module:

• Reset Pin : Active low reset line for RYZ012 module
• UART/SPI Select Pin : Allows selection between UART or SPI for module communication. UART is selected with output low and SPI with output high.
• UART Interface : RX/TX Pins
• SPI Interface : MOSI/MISO/SCK/SSL Pins
  • Data Ready Pin : When the SPI Interface is selected as the communication interface, the Data Ready pin is asserted in order to notify the MCU that there is data ready to be read.
  • Software SSL Pin : Can be optionally configured in order to drive the SSL Pin using software instead of hardware¹.

Note

1. The software SSL Pin is required when using the SPI (r_sci_spi) driver.

2. When using software SSL, the pin must be configured as "Output mode (Initial High)" in the pin configuration editor in addition to being configured in the "stacks" tab.

Usage Notes

Limitations

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

Currently supported rm_ble_abs_spp interface functions:

• RM_BLE_ABS_Open
• RM_BLE_ABS_Close
• RM_BLE_ABS_StartLegacyAdvertising

Currently supported r_ble_spp_api interface functions:

• R_BLE_Open
• R_BLE_Close
• R_BLE_SetEvent
• R_BLE_GAP_Init
• R_BLE_GAP_StopAdv
• R_BLE_GAP_SetAdvSresData
• R_BLE_GAP_StartAdv
• R_BLE_GAP_SetAdvParam
• R_BLE_GATT_GetMtu
• R_BLE_GATTS_SetDbInst
• R_BLE_GATTS_Init
• R_BLE_GATTS_GetAttr
• R_BLE_GATTS_SetAttr
• R_BLE_GATTS_Notification
• R_BLE_GATTS_Indication
• R_BLE_GATTS_RegisterCb
• R_BLE_GATTC_Init
• R_BLE_GATTC_RegisterCb
• R_BLE_VS_SetBdAddr
• R_BLE_VS_SetTxPower

Currently supported callback events:

• BLE_GAP_EVENT_CONN_IND
• BLE_GAP_EVENT_DISCONN_IND
• BLE_GAP_EVENT_ADV_ON
• BLE_GAP_EVENT_ADV_OFF
• BLE_GATTC_EVENT_CONN_IND
• BLE_GATTS_EVENT_CONN_IND
• BLE_GATTC_EVENT_DISCONN_IND
• BLE_GATTS_EVENT_DISCONN_IND
• BLE_GATTS_EVENT_WRITE_RSP_COMP

Transmit Power

Specific Operational Use Conditions for RYZ012 BLE module:

Please consult the laws and regulations of the region(s) in which the device will be used to verify the information below before using this device.

North America (FCC) The module must not be operated at power levels above 10.0 dBm. Host devices that need higher output power may not be marketed without prior re-certification.

Europe (RED) The module must not be operated at power levels above 8.4 dBm. Host devices that need higher output power may not be marketed in regions covered by RED regulation without prior re-certification.

Japan (MIC) The module must be operated at power level 4.5 dBm. Host devices that need to change output power may not be marketed without prior re-certification.

The current default level used in the e² studio Configurator is 4.57 dBm for the transmit power level.

Examples

BLE_ABS_SPP Basic Example

This is a basic example of minimal use of the BLE_ABS_SPP 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 = 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);
}

BLE_ABS_SPP Firmware Update Example

This is a basic example of performing a firmware update.

void ble_abs_firmware_update_example (void)
{
    fsp_err_t err = FSP_SUCCESS;

    /* Open the module. */
    err = RM_BLE_ABS_Open(&g_ble_abs0_ctrl, &g_ble_abs0_cfg);
    assert(FSP_SUCCESS == err);

    /* Complete the firmware update (This function blocks until the procedure has completed). */
    ble_status_t status = R_BLE_VS_UpdateModuleFirmware(g_firmware_image, g_firmware_image_size);
    assert(BLE_SUCCESS == status);

    /* Close the module. */
    err = RM_BLE_ABS_Close(&g_ble_abs0_ctrl);
    assert(FSP_SUCCESS == err);

    /* The RYZ012 is now using the updated firmware. Call open to re-initialize the module using the new firmware. */
}

BLE_ABS_SPP Firmware Update Asynchronous Example

This is an example of performing a firmware update using the asynchronous API.

volatile uint32_t g_firmware_update_complete = 0;

void vs_cb (uint16_t type, ble_status_t result, st_ble_vs_evt_data_t * p_data)
{
    FSP_PARAMETER_NOT_USED(p_data);

    if (BLE_SUCCESS != result)
    {
        /* Stop the firmware update process if there was an error. */
        return;
    }

    static uint16_t index = 0;

    switch (type)
    {
        /* The response to the START_FW_UPDATE command was received (Fall through to send the next data frame). */
        case BLE_VS_EVENT_START_FW_UPDATE_COMP:

        /* The response to the SEND_FW_DATA command was received. */
        case BLE_VS_EVENT_SEND_FW_DATA_COMP:
        {
            if (BLE_VS_EVENT_START_FW_UPDATE_COMP == index)
            {
                index = 0;
            }

            uint16_t  length          = 0;
            uint8_t * p_firmware_data = NULL;

            /*
             * Get next firmware data frame.
             * Note that app_data_frame_get() is an application defined function.
             */
            app_data_frame_get(index, &p_firmware_data, &length);

            if (length > 0)
            {
                /* Send the firmware data frame. */
                R_BLE_VS_SendFirmwareData(index, length, p_firmware_data);
                index++;
            }
            else
            {
                /* The previously completed data frame was the last data frame. Send the firmware update end command. */
                R_BLE_VS_EndFirmwareUpdate(index - 1);
            }

            break;
        }

        /* The response to the END_FW_UPDATE command was received. */
        case BLE_VS_EVENT_END_FW_UPDATE_COMP:
        {
            /* After the BLE_VS_EVENT_END_FW_UPDATE_COMP command is sent, send the restart command. */
            R_BLE_VS_RestartModule();
            break;
        }

        /* The module has finished restarting and the MODULE_READY event has been received. */
        case BLE_VS_EVENT_MODULE_READY_COMP:
        {
            /* Firmware update process has completed. */
            g_firmware_update_complete = 1;
            break;
        }

        default:
        {
            break;
        }
    }
}

void ble_abs_firmware_update_async_example (void)
{
    fsp_err_t err = FSP_SUCCESS;

    /* Open the module. */
    err = RM_BLE_ABS_Open(&g_ble_abs0_ctrl, &g_ble_abs0_cfg);
    assert(FSP_SUCCESS == err);

    /* Start the firmware update process. */
    ble_status_t status = R_BLE_VS_StartFirmwareUpdate();
    assert(BLE_SUCCESS == status);

    /* main loop */
    while (0 == g_firmware_update_complete)
    {
        /* Process BLE Event */
        R_BLE_Execute();
    }

    /* Close the module. */
    err = RM_BLE_ABS_Close(&g_ble_abs0_ctrl);
    assert(FSP_SUCCESS == err);

    /* The RYZ012 is now using the updated firmware. Call open to re-initialize the module using the new firmware. */
}