Renesas RX23W Application Note

Application Note

RX23W Group

Bluetooth Low Energy Profile Developer's Guide

Introduction

This document guides you on how to generate and customize Bluetooth® Low Energy(LE) profiles for developer using the following target device.

Target Device

• RX23W Group

Related Documents

• Bluetooth Core Specification (https://www.bluetooth.com)

• RX23W Group User’s Manual: Hardware (R01UH0823)

• Firmware Integration Technology User's Manual (R01AN1833)

• RX Family Board Support Package Module Using Firmware Integration Technology (R01AN1685)

• Adding Firmware Integration Technology Modules to Projects (R01AN1723)

• Renesas Smart Configurator User Guide: e2 studio (R20AN0451)

• RX23W Group BLE Module Firmware Integration Technology(R01AN4860)

• RX23W Group BLE QE Utility Module Firmware Integration Technology(R01AN4907)

• QE for BLE[RX] V1.0.0 Release Note(R20UT4644)

• Bluetooth Low Energy Protocol Stack Basic Package: User's Manual (R01UW0205)

• RX23W Group Bluetooth Low Energy Application Developer’s Guide (R01AN5504)

The Bluetooth such marks by Renesas Electronics Corporation is under license. Other trademarks and registered trademarks are the property of their respective owners.

word mark and logos are registered trademarks owned by Bluetooth SIG, Inc. and any use of

R01AN4553EJ0110 Rev.1.10 Page 1 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Contents

1. Overview ................................................................................................................................. 4

1.1 Structure of profile ................................................................................................................................... 4

1.2 Flow of profile development .................................................................................................................... 6

2. Development environment ....................................................................................................... 7

2.1 Software Requirements ........................................................................................................................... 7

2.2 BLE QE Utility Module ............................................................................................................................. 7

2.3 QE for BLE ............................................................................................................................................ 10

2.4 Building development environment ....................................................................................................... 10

2.4.1 Install QE for BLE ................................................................................................................................ 10

2.4.2 Download FIT module ......................................................................................................................... 10

3. Profile Configuration in QE for BLE ........................................................................................ 11

3.1 Overview of profile configuration ........................................................................................................... 11

3.1.1 Create new project .............................................................................................................................. 11

3.1.2 Download FIT module ......................................................................................................................... 11

3.1.3 Addition of BLE QE Utility module ....................................................................................................... 15

3.1.4 Addition of QE for BLE ........................................................................................................................ 17

3.1.5 Addition of BLE FIT module ................................................................................................................ 18

3.1.6 Configuration of profile ........................................................................................................................ 18

3.1.7 Code generation .................................................................................................................................. 19

3.2 How to use QE for BLE ......................................................................................................................... 20

3.2.1 Addition of elements ............................................................................................................................ 21

3.2.2 Configuration of profile ........................................................................................................................ 23

3.2.3 Configuration of service ....................................................................................................................... 24

3.2.4 Configuration of characteristic ............................................................................................................. 27

3.2.5 Configuration of descriptor .................................................................................................................. 30

4. Implementation of program .................................................................................................... 32

4.1 Service API program ............................................................................................................................. 34

4.1.1 Function defined in service API program ............................................................................................ 34

4.1.2 Event defined in service API program ................................................................................................. 35

4.2 Implementation of custom service ......................................................................................................... 38

4.2.1 Implementing encode/decode function ............................................................................................... 38

4.2.2 Implementing callback in service API program ................................................................................... 42

4.3 Implementation of app_main.c .............................................................................................................. 47

4.3.1 Implementing callback in application framework ................................................................................. 47

4.4 Notice .................................................................................................................................................... 49

4.4.1 Implementation of multiple services .................................................................................................... 49

4.4.2 Implementation of same service.......................................................................................................... 49

4.4.3 Implementation of secondary service .................................................................................................. 51

4.4.4 Implementation of discovery operation about included service .......................................................... 55

4.4.5 Using GAT service and GAP service .................................................................................................. 58

4.4.6 Guide for Connection Update .............................................................................................................. 61

R01AN4553EJ0110 Rev.1.10 Page 2 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

5. Build and Run created profile ................................................................................................. 62

5.1 Build and Run for New Project .............................................................................................................. 62

5.2 Build and Run for Sample Project ......................................................................................................... 62

Revision History ............................................................................................................................ 64

R01AN4553EJ0110 Rev.1.10 Page 3 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

1. Overview

1.1 Structure of profile

In Bluetooth LE Communication, Generic Attribute Protocol (GATT) is primarily used. GATT defines client and server roles, and profile communication is performed between client and server. Profiles are protocols developed for many applications consisting of one or more services. Profile communication is allowed between devices that supports same profile. Server device has profile data in GATT database, and client device accesses the profile data. The server device can also notify profile data to the client device using. By using them, it is possible to transmit and receive in Bluetooth LE communication.

The server has the profile data in GATT database and the client accesses the profile data by Bluetooth LE communication.

Figure 1.1 Overview of profile communication

Figure 1.2 shows Structure of profile in Bluetooth LE software.

In this Bluetooth LE software, user application and profiles run on the BLE Protocol Stack. Profile consist of 3 types of program:

• Framework for using Bluetooth LE features and profiles from user application.

• GATT database that defines the data structure of the services configured in the profile.

• API program for accessing profile data.

R01AN4553EJ0110 Rev.1.10 Page 4 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Figure 1.2 Structure of profile

Bluetooth LE software defines the data structure of the profile as a GATT database and data accessing method as an API program for the service. The user application uses the API program for service to access the profile data to perform Bluetooth LE profile communication.

Bluetooth SIG Inc. defines specification of several services. In this document, those services are referred as SIG adopted services. On the other hand, if you want to achieve functionality that is not supported by SIG adopted service, you must define your own service. In this document, these are referred as custom service.

R01AN4553EJ0110 Rev.1.10 Page 5 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

1.2 Flow of profile development

Figure 1.3 shows flow of profile development.

Figure 1.3 Flow of profile development

The steps for profile development are as follows:

1) Configure profile with QE for BLE

Configure profile by GUI provided from QE for BLE. Check [3 Profile Configuration in QE for BLE] for more information.

2)Generate profile from Smart Configurator

Smart Configurator generates API program of profile configured on QE for BLE, GATT database, application framework on user project created over user project. BLE Protocol Stack, which provides basic Bluetooth LE functionality, can also be generated from Smart Configurator if BLE FIT Module is added to it.

3) Implement application into generated program

You can implement the application on user project using program generated from Smart Configurator. For more information about implementing user application using generated program, refer [4 Implementation of program].

4)Build and Run implemented application

Implemented application can be built and runed on evaluation board. For running application and profile, BLE Protocol Stack is needed. For more information, refer [5 Build and Run created profile].

R01AN4553EJ0110 Rev.1.10 Page 6 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

2. Development environment

2.1 Software Requirements

To develop Bluetooth LE software for RX23W using QE for BLE, software below is required.

• e2 studio v7.6.0 or later (32bit) / 2020-01 or later (64bit)

• CC-RX compiler v2.08.00 or later

• BLE FIT module v1.0.0 or later

• BLE QE Utility module v1.1.0 or later

• QE for BLE[RX] v1.0.0 or later

For more information about BLE QE Utility module and QE for BLE[RX], refer [2.2 BLE QE Utility Module] and [2.3 QE for BLE]. For guide on building development environment, refer [2.4 Building development environment].

2.2 BLE QE Utility Module

BLE QE Utility Module is used by QE for BLE to generate profile program files. For SIG adopted services, QE for BLE generates API program made by Renesas. These programs are authenticated by Bluetooth SIG. Table 2.1 shows the list of SIG adopted service that are supported by BLE QE Utility Module. Also, T shows list of profile that are supported by BLE QE Utility module.

Specifications of each service is defined by Bluetooth SIG. Check Web page of Bluetooth SIG (https://www.bluetooth.com

) for more information.

R01AN4553EJ0110 Rev.1.10 Page 7 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Continuous Glucose Monitoring Service

CGMS

1.0.1

CTS

1.1

CPS

1.1

Cycling Speed and Cadence Service

CSCS

1.0 DIS

1.1

ESS

1.0

IDS

1.0

LLS

1.0.1

Service

UDS

1.0

WSS

1.0

Table 2.1 SIG adopted service supported by BLE QE Utility Module

Service name

Alert Notification Service

Battery Service

Body Composition Service

Cycling Power Service

Device Information Service

Fitness Machine Service

Health Thermometer Service

Human Interface Device Service

Insulin Delivery Service

Location and Navigation Service

Object Transfer Service

Pulse Oximeter Service

abbreviation version

ANS 1.0

BAS 1.0

BCS 1.0

FTMS 1.0

HTS 1.0

HIDS 1.0

LNS 1.0

OTS 1.0

PLXS 1.0

Service name

Automation IO Service

Blood Pressure Service

Bond Management Service

Current Time Service

Environmental Sensing Service

Glucose Service

Heart Rate Service

Immediate Alert Service

Link Loss Service

Next DST Change Service

Phone Alert Status Service

Reconnection Configuration

abbreviation version

AIOS 1.0

BLS 1.0

BMS 1.0

GLS 1.0

HRS 1.0

IAS 1.0

NDCS 1.0

PASS 1.0

RCS 1.0

Reference Time Update Service

Scan Parameters Service

User Data Service

GATT Service GATS - GAP Service GAPS -

RTUS 1.0

ScPS 1.0

Running Speed and Cadence

Tx Power Service

Weight Scale Service

RSCS 1.0

TPS 1.0

Note: Object Transfer Service is not authenticated. Please contact us when considering this service to be used in your product.

R01AN4553EJ0110 Rev.1.10 Page 8 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Profile

Service that configure profile

Table 2.2 Profile supported by BLE QE Utility Module

Blood Pressure Profile [BLP] BLS DIS

Health Thermometer Profile [HTP] HTS DIS

Heart Rate Profile [HRP] HRS DIS

Glucose Profile [GLP] GLS DIS

Pulse Oximeter Profile [PLXP]

Continuous Glucose Monitoring Profile [CGMP] CGMS DIS (BMS)

Reconnection Configuration Profile [RCP] RCS (BMS)

Insulin Delivery Profile [IDP]

Cycling Power Profile [CPP] CPS (DIS) (BAS)

Cycling Speed and Cadence Profile [CSCP] CSCS (DIS)

Running Speed and Cadence Profile [RSCP] RSCS (DIS)

Location and Navigation Profile [LNP] LNS (DIS) (BAS)

Weight Scale Profile [WSP]

Fitness Machine Profile [FTMP] FTMS (DIS) (UDS)

Environmental Sensing Profile [ESP] ESS (DIS) BAS)

Find Me Profile [FMP] IAS

Proximity Profile [PXP] IAS (LLS) (TPS)

Alert Notification Profile [ANP] ANS

PLXS DIS (BAS) (CTS)

(BMS)

IDS DIS (BAS) (CTS)

(BMS) (IAS)

WSS DIS (BCS) (BAS)

(CTS) (UDS)

Phone Alert Status Profile [PASP] PASS

Time Profile [TIP] CTS (NDCS) (RTUS)

HID over GATT Profile [HOGP] HIDS DIS BAS (ScPS)

Scan Parameters Profile [ScPP] ScPS

Automation IO Profile [AIOP] AIOS

Note: Services without () are mandatory services, and services with () are Optional services. If you add a profile in QE for BLE, only mandatory services are added to profile tree.

R01AN4553EJ0110 Rev.1.10 Page 9 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

file name

description

Skeleton program that is the basis of application/profile development.

gatt_db.h

Data structure of service which is checked on [server] in QE for BLE is defined.

[abbreviation]=[cus], [client]: r_ble_cusc.c, r_ble_cusc.h

2.3 QE for BLE

QE for BLE provides GUI to configure profile and generates program. Table 2.3 lists the program that QE for BLE generates.

Table 2.3 Programs generated by QE for BLE

app_main.c Application/Profile framework

gatt_db.c

r_ble_[abbreviation][s or c].c r_ble_[abbreviation][s or c].h

GATT database program

Profile API program API program for accessing and notifying profile data. File is generated for each service that configure profile. Each file name is determined based on the [abbreviation], [server], and [client] set in QE for BLE. [abbreviation][s] is the server program, [abbreviation][c] is the client program. Example) [abbreviation]=[sig], [server]: r_ble_sigs.c, r_ble_sigs.h

All program generated by QE for BLE is output in [Project Name]/src/smc_gen/Config_BLE_PROFILE.

Skeleton Programs are basis for profile and application development. Implementation of skeleton program is described in [4 Implementation of program].

2.4 Building development environment

2.4.1 Install QE for BLE

QE for BLE can be downloaded from the web page below.

https://www.renesas.com/qe-ble

For more information about installation, refer to the document below.

• QE for BLE[RX] V1.0.0 Release Note(R20UT4644)

2.4.2 Download FIT module

For using QE for BLE, FIT module shown below is needed for using QE for BLE.

• RX23W Group BLE QE Utility Module Firmware Integration Technology(R01AN4907)

Also, FIT modules shown below is needed for construction of BLE Protocol Stack which is needed for running BLE communication.

• RX23W Group BLE Module Firmware Integration Technology(R01AN4860)

These FIT modules can be downloaded using smart configurator. For more information, refer [3.1.2 Download FIT module].

R01AN4553EJ0110 Rev.1.10 Page 10 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

3. Profile Configuration in QE for BLE

This section guides how to configure profiles in QE for BLE.

3.1 Overview of profile configuration

To configure your profile, you must follow these steps.

①Create a new project that uses Smart Configurator. ②Download FIT module using Smart Configurator. ③Add FIT modules to Smart Configurator. ④Add QE for BLE to Smart Configurator. ⑤Configure Profile using QE for BLE. ⑥Generate code based on configured profile.

Each step of configuration is described here.

Note: e

3.1.1 Create new project

To create RX23W Bluetooth LE project that QE for BLE operate, you need to create project which has Smart Configurator. To create project which has Smart Configurator, refer [4.1create a new project] in application note [RX23W Group BLE Module Firmware Integration Technology(R01AN4860)].

studio V7.8.0 is used in figure of instruction.

3.1.2 Download FIT module

The FIT module can be downloaded not only from the Renesas web page, but also using smart configurator. This section describes how to download FIT module using smart configurator.

Launch Smart Configurator

Open ${project_name}.scfg file in the project explorer.

Figure 3.1 Launch Smart Configurator

R01AN4553EJ0110 Rev.1.10 Page 11 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

①

②

Click the tab at the bottom of the Smart Configurator on e [Components] tab, click [Add module].

studio to open the [Components] tab. On the

Figure 3.2 Add Module

Before downloading FIT module, folder for downloading FIT module should be specified. Click [Configure general setting] and open Preference window.

Figure 3.3 Click configure general setting

R01AN4553EJ0110 Rev.1.10 Page 12 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Verify

①

②

Click the [Browse] button in Location(RX) to specify folder. Verify that the path to specified folder is displayed. After verifying that the correct folder path is displayed, click [Apply and Close] button to close Preference Window.

Figure 3.4 Preference window

Click [Download more software components] on New Component window

Figure 3.5 Click Download more software components

R01AN4553EJ0110 Rev.1.10 Page 13 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Enter Verify

① ② ③

Select

When My Renesas login screen appears, enter the email address and password registered to My Renesas. After that, click [OK] button.

Figure 3.6 My Renesas login window

If region selection screen appears, select your region. Click [OK] button to close the window.

Figure 3.7 Region Setting window

Select the required FIT module on the FIT selection screen. Check the box for all FIT modules you want to download. Next make sure that the path of the Module Folder Path is the path specified on the Preference window. If it is incorrect, click [Browse] button to specify the correct folder path. After you have done all of this, click [Download] button.

Figure 3.8 FIT Module Download window

R01AN4553EJ0110 Rev.1.10 Page 14 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

3.1.3 Addition of BLE QE Utility module

BLE QE Utility module provide feature which generate code to QE for BLE.QE for BLE presume BLE QE Utility module when it is installed. Therefore, BLE QE Utility module should be added to component before QE for BLE is added. The following describe procedure for adding BLE QE Utility module to component.

Add to component

Open [component] tab. Tab is located in the bottom of smart configurator window. Click green plus button in component window and [Software Component Selection] window open.

Figure 3.9 Add button for component

BLE QE Utility Module is displayed as [r_ble_qe_utility] at component lists. Select [r_ble_qe_utility] and Click [Finish Button] to add module.

Figure 3.10 Window to add BLE QE Utility

R01AN4553EJ0110 Rev.1.10 Page 15 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Confirm component

Confirm that [r_ble_qe_utility] is added to Middleware - Generic folder in Component window. BLE QE Utility module don’t have the configure items.

Figure 3.11 Confirm BLE QE Utility module

R01AN4553EJ0110 Rev.1.10 Page 16 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

3.1.4 Addition of QE for BLE

QE for BLE provide GUI for developing profile on the Smart Configurator. BLE QE Utility Module is necessary for QE for BLE to be used. Therefore, QE for BLE should be added to component after BLE QE Utility Module is added.

Add to component

Click green plus button in component window and [Software Component Selection] window open. QE for BLE is displayed as [BLE Profile Creation] at component lists. If the [BLE Profile Creation] is not displayed, you need to download QE for BLE referring to [2.4 Building development environment]. Select [BLE Profile Creation] and Click [Finish Button] to add module.

Figure 3.12 Window to add QE for BLE

R01AN4553EJ0110 Rev.1.10 Page 17 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Confirm component

Confirm that [Config_BLE_PROFILE] is added to Application - Communication folder in Component window. Confirm that BLE custom profile configuration screen is displayed when you select [Config_BLE_PROFILE]. In custom profile configuration screen, confirm that [GAP service] and [GATT service] is added. If these contents are not added, [r_ble_qe_utility] module might not be added to Smart Configurator.

Figure 3.13 Confirm BLE QE Utility module

3.1.5 Addition of BLE FIT module

By adding BLE FIT module to Smart Configurator in the created project, you can develop not only profile but also Bluetooth LE application by using created project. How to add BLE FIT module to smart configurator in a project is described at [4. BLE FIT Module Project] in application note [RX23W Group BLE Module Firmware Integration Technology(R01AN4860)] .

3.1.6 Configuration of profile

You can configure profile using custom profile configuration screen on QE for BLE. For detailed description of the custom profile configuration screen, refer [3.2 How to use QE for BLE].

R01AN4553EJ0110 Rev.1.10 Page 18 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

3.1.7 Code generation

After profile configuration using QE for BLE, you can generate program by clicking [Generate Code] button in Smart Configurator.

Figure 3.14 Generate Code button

Generated program can be divided into following 4 types:

• API program generated from SIG adopted service.

• API program generated from custom service.

• Application framework

• GATT database

User application will be created using these generated programs. Refer [4.2 Implementation of custom service] for modifying API program of custom service, and refer [4.3 Implementation of app_main.c] for modifying application framework.

Figure 3.15 shows an example of files generated from QE for BLE.

Figure 3.15 Files generated from QE for BLE

R01AN4553EJ0110 Rev.1.10 Page 19 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

3.2 How to use QE for BLE

You can configure profile using QE for BLE. Figure 3.16 shows configuration screen of QE for BLE.

Figure 3.16 QE for BLE configuration screen

Profile is a tree-like structure consisting of one or more services, service consisting of one or more characteristics, characteristic consisting of zero or more descriptors. You can check the configuration of the profile that you are currently designing from [Profile Tree].

When you select each element of [Profile Tree], the settings are displayed for each type of elements selected in [Detail Setting Area]. You can configure the functionality of elements added to [Profile Tree] by editing the items displayed in [Detail Setting Area]. Configured profile are stored in the smart configurator. If you want to save your profile to any folder, you can use [Export] to save it on a per-service basis.

[Toolbar] is used when you want to add or delete contents from [Profile Tree]. The icons on [Toolbar] and their behavior are as follows:

• [ ] : Adds an elements to [Profile Tree]. The elements added depends on the elements selected in [Profile Tree]

• [ ] : Deletes selected elements in [Profile Tree].

• [ ][ ] : Moves selected elements in [Profile Tree]. Use this to rearrange elements in [Profile Tree].

• [Export] : Outputs the configured service as JSON file.

• [Import] : Loads service defined JSON file and adds it to the profile.

R01AN4553EJ0110 Rev.1.10 Page 20 of 64 Mar.12.21

+ 46 hidden pages

Renesas RX23W Application Note

Specifications and Main Features

Frequently Asked Questions

User Manual

1. Overview

1.1 Structure of profile

1.2 Flow of profile development

2. Development environment

2.1 Software Requirements

2.2 BLE QE Utility Module

2.3 QE for BLE

2.4 Building development environment

2.4.1 Install QE for BLE

2.4.2 Download FIT module

3. Profile Configuration in QE for BLE

3.1 Overview of profile configuration

3.1.1 Create new project

3.1.2 Download FIT module

3.1.3 Addition of BLE QE Utility module

3.1.4 Addition of QE for BLE

3.1.5 Addition of BLE FIT module

3.1.6 Configuration of profile

3.1.7 Code generation

3.2 How to use QE for BLE