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

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

RX23W Group Bluetooth Low Energy Profile Developer's Guide

3.2.1 Addition of elements

You can add elements to [Profile Tree] by clicking [ ] button in [Toolbar]. The elements that are added will change depending on current elements that are selected in [Profile Tree]. This section describes which elements are added by the selected elements.

You can add services by clicking [ ] button with the profile selected in [Profile Tree] (Figure 3.17). Select [New service] to add custom service or [Add service] to add a SIG adopted service. SIG adopted service that can be added is listed in Table 2.1. If you select [Add profile], you can select adding services by profile. The list of services that configure profile is listed in Table 2.2. Optional services in profile will not be added by selecting profile. For these services, add to [Profile Tree] individually.

Figure 3.17 Adding service

You can add a characteristic by clicking [ ] button with the service selected in [Profile Tree] (Figure 3.18). Select [New Characteristic] to add a custom characteristic or [Add Characteristic] to add SIG adopted characteristic.

Figure 3.18 Adding characteristic

R01AN4553EJ0110 Rev.1.10 Page 21 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

You can add a descriptor by clicking [ ] button with the characteristic selected in [Profile Tree] (Figure

3.19). Select [New Descriptor] to add a custom descriptor or [Add Descriptor] to add SIG adopted descriptor.

Figure 3.19 Adding descriptor

R01AN4553EJ0110 Rev.1.10 Page 22 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

3.2.2 Configuration of profile

When you select profile [ ] in [Profile Tree], profile configuration screen (Figure 3.20) will be shown in [Detail Settings Screen].

You can select GAP role on profile configuration screen. Use the radio button to choose whether to set profile to [Central] or [Peripheral]. Application framework is generated depending on this item. If you select [Peripheral], program which can advertise is generated. If you select [Central], program which can scan and issue connection request is generated.

[Applied Standard Profiles] shows profiles that applied based on services added to [Profile Tree]. Profile that are shown is listed in Table 2.2.

Figure 3.20 Profile configuration screen

R01AN4553EJ0110 Rev.1.10 Page 23 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

3.2.3 Configuration of service

When you select service [ ] in [Profile Tree], service configuration screen(Figure 3.21) will be shown in [Detail Settings Screen]. Table 3.1 describes each item on the configuration screen.

Note: The GAP service and GATT service are mandatory services. Do not delete these services.

Figure 3.21 Service configuration screen

R01AN4553EJ0110 Rev.1.10 Page 24 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Item

Description

Server [optional]

Set check on this item to generate service program as server. It also adds characteristic and [optional]

Name

Name of service.

Custom service

128bit : 96FE7990-2C76-89AB-DC49-AB7F123DEF9C

Abbreviation

Abbreviation of service.

This service used for sending sensor data.

Aux properties

AUX properties of service. Items below can be configured.

Encryption

Enable encryption.

Authorization

Enable authorization. Use function R_BLE_GAP_AuthorizeDev( ) to authorize.

Select appropriate security requirement stage from the following item

None

There are no requirements about security for accessing service.

Unauthentication

Requires pairing for accessing service.

Authentication

Requires pairing with MITM for accessing service.

Secure Connection

Requires pairing on secure connection for accessing service.

Included [optional]

Sets Included service. Select the service to be included from the list.

Error code added can be used by function R_BLE_GATTS_SendErrRsp( ).

Name

Name of error code.

Value not Supported

Select from value list.

Table 3.1 Service configuration

descriptors to GATT database.

Client

Set check on this item to generate service program as client.

[mandatory]

UUID [mandatory]

[mandatory]

Description [optional]

[optional]

Example)

UUID of service. Select 128bit if service is custom service. Initial value is entered randomly. Please modify if needed. Example) 16bit : 0xe237

This value is used in file name, function name and variable name. Beware not to conflict with other services.

Example)

Description of service. Explain usage if needed. This description will be used as comments in generated program. Example)

Error Codes [optional]

Adds error code of service.

Example)

Code Value of error code.

R01AN4553EJ0110 Rev.1.10 Page 25 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Figure 3.22 shows the service configuration screen for SIG adopted service. In this state, only [server], [client], and [Included] items can be configured. You can edit all items by clicking the [Customize] button. Please use it in case creating a custom service based on SIG adopted service.

Figure 3.22 SIG adopted service configuration screen

R01AN4553EJ0110 Rev.1.10 Page 26 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

3.2.4 Configuration of characteristic

When you select characteristic [ ] in [Profile Tree], characteristic configuration screen (Figure 3.23) will be shown in [Detail Settings Screen]. Table 3.2 and Table 3.3 describes each item on the configuration screen.

Figure 3.23 Characteristic configuration screen

R01AN4553EJ0110 Rev.1.10 Page 27 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Item

Description

Custom Characteristic

UUID

UUID of characteristic.

128bit: 96FE7990-2C76-89AB-DC49-AB7F123DEF9C

Description

Description of Characteristic.

This Characteristic is used for sending sensor data

Items below can be configured.

Read

Enable Read operation.

Write

Enable Write operation.

WriteWithoutResponse

Enable Write Without Response operation.

Notify

Enable Notify operation.

Indicate

Enable Indicate operation.

ReliableWrite

Enable Reliable Write operation.

Broadcast

Enable Broadcast operation.

Items below can be configured.

Const

Value will not be able to change.

Peer Specific

Value will be kept individually for each connection.

Variable Length

Value length will be variable.

Use function R_BLE_GAP_AuthorizeDev() to authorize.

Disable

Disable attribute.

For string: “example”

[mandatory]

Table 3.2 Characteristic configuration

Name [mandatory]

[mandatory]

Abbreviation [mandatory]

[optional]

Properties [mandatory]

Name of characteristic. Example)

Select 128bit if service is custom characteristic. Initial value is entered randomly. Please modify if needed. Example) 16bit: 0xe237

Abbreviation of characteristic. This value is used in function name and variable name. Beware not to conflict with other characteristics. Example)

Explain usage if needed. This description will be used as comment of generated program. Example)

Properties of characteristic which defines operation on Bluetooth LE communication. API and events will be generated for each item checked. [Broadcast] and [ReliableWrite] won’t generate API and events due to its method. Client Characteristic Configuration Descriptor will be added if [Notify] or [Indicate] is selected.

Aux Properties [optional]

DBSize [mandatory]

Value [optional]

Field

AUX properties of characteristic.

Authorization Enable authorization.

Size of characteristic. Unit of value is byte. Example)

Initial value of characteristic. If you want to enter a number, enter it separated by 8bit digit. If you want to enter string, you can easily enter it by enclosing it in “”. Example) For numbers: 0x12, 0x34, 56,78

Set value field used in application. Please refer Table 3.3 for configuration.

R01AN4553EJ0110 Rev.1.10 Page 28 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

New Field

Add new field. Items below can be configured

field_name

Format/Value

Format of field. Value can be selected from below.

bool

Boolean type

char

char type

uint8_t

unsigned 8bit data type

uint16_t

unsigned 16bit data type

uint32_t

unsigned 32bit data type

int8_t

signed 8bit data type

int16_t

signed 16bit data type

int32_t

signed 32bit data type

st_ble_ieee_11073_float_t

IEEE-11073 32bit FLOAT type

st_ble_ieee_11073_sfloat_ t

IEEE-11073 16bit SFLOAT type information.

st_ble_dev_addr_t

Structure for setting Bluetooth LE address data.

and length is set more than 2.

struct

Structure type. Select this when selecting [Add Field].

[mandatory]

Abbreviation [optional]

Abbreviation of field. [optional]

Explain usage if needed

Add Field

Adds a new Field inside the selected Field.

Added Field can be configured same items explained in [New Field].

Items below can be configured.

Name

Name of enumeration.

enable

0x01

Description [optional]

Description of enumeration.

Table 3.3 Field configuration

Name [mandatory]

[mandatory]

Name of field. Example)

st_ble_date_time_t Structure for setting date and time

st_ble_seq_data_t Structure for variable length data.

Length

Description

Please use it if you configure data that has hierarchy. The Format/Value of the selected Field is set to [struct].

Add Enumeration Defines enumeration usable for selected field.

[mandatory]

Format/Value [mandatory]

Data length of field.

Description of field.

Example)

Value code of enumeration. Example)

Select this when only one field is set,

Delete Delete selected field.

R01AN4553EJ0110 Rev.1.10 Page 29 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

3.2.5 Configuration of descriptor

When you select descriptor [ ] in [Profile Tree], descriptor configuration screen (Figure 3.24) will be shown in [Detail Settings Screen]. Table 3.4 describe each item on the configuration screen.

Figure 3.24 Descriptor configuration screen

R01AN4553EJ0110 Rev.1.10 Page 30 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Item

Description

Custom Descriptor

UUID

UUID of descriptor.

128bit: 96FE7990-2C76-89AB-DC49-AB7F123DEF9C

Description

Description of descriptor.

This descriptor is used for sending sensor data

Items below can be configured

Read

Enable Read operation.

Write

Enable Write operation.

Aux Properties

AUX properties of descriptor. Items below can be configured.

Const

Value will not be able to change.

Peer Specific

Value will be kept individually for each connection.

Variable Length

Value length will be variable.

Authorization

Enable authorization. Use function R_BLE_GAP_AuthorizeDev() to authorize.

Disable

Disable attribute.

DBSize

Size of descriptor. Unit of value is byte.

For string: “example”

Field

Set value field used in application. Please refer Table 3.3 for configuration.

Table 3.4 Descriptor configuration

Name [mandatory]

[mandatory]

Abbreviation [mandatory]

[optional]

Properties [mandatory]

Name of descriptor. Example)

Select 128bit if service is custom descriptor. Initial value is entered randomly. Please modify if needed. Example) 16bit: 0xe237

Abbreviation of descriptor. This value is used in function name and variable name. Beware not to conflict with other descriptors. Example)

Explain usage if needed. This description will be used as comment of generated program. Example)

Properties of descriptor which defines operation on Bluetooth LE communication. API and events will be generated for each item checked.

[optional]

[mandatory]

Value [optional]

[mandatory]

Example)

Initial value of descriptor. If you want to enter a number, enter it separated by 8bit digit. If you want to enter string, you can easily enter it by enclosing it in “”. Example) For numbers: 0x12, 0x34, 56,78

R01AN4553EJ0110 Rev.1.10 Page 31 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

/* Start user code for XXXX. Do not edit comment generated here */

/* End user code. Do not edit comment generated here */

4. Implementation of program

This chapter guides you on how to add user applications to programs generated from QE for BLE. Figure 4.1 shows an example of a program generated from QE for BLE.

Figure 4.1 Program generated from QE for BLE

Programs generated from QE for BLE are newly generated each time QE for BLE is used. If you are using version 1.10 or later of BLE QE Utility module, the application framework implements a comment line with code blocking capabilities to protect user-implemented code (Figure 4.2). User can leave code implemented to new application framework generated from QE for BLE by implementing code between this comment line.

Implement user code here

Figure 4.2 User code blocking comment

R01AN4553EJ0110 Rev.1.10 Page 32 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

When you re-generate code from QE for BLE, programs before regeneration will be copied to [trash] folder in the project (Figure 4.3). Therefore, if you cannot add user code between comment line, copy the required code accordingly.

Figure 4.3 trash folder

R01AN4553EJ0110 Rev.1.10 Page 33 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

operation

description

Get[characteristic][descriptor]

You can check GATT database value changed in write operation.

Set[characteristic] Set[characteristic][descriptor]

Set characteristic/descriptor value to GATT database. Value set in GATT database is used in operation such as read operation.

Characteristic value will not be stored to GATT database by calling this API.

Indicate[characteristic]

Start Indication operation by sending Handle Value Indication. Characteristic value will not be stored to GATT database by calling this API.

operation

description

Get[characteristic]AttrHdl

Get characteristic attribute handle discovered in Discovery operation.

Complete Discovery operation before calling this API.

Value operation by sending Write Prepare request.

Read[characteristic]

Start Read Characteristic Value operation by sending Read Request.

Value operation by sending Read Blob Request.

R_BLE_[service][S or C]_[operation]

4.1 Service API program

This section will guide you through common specifications in the API program of SIG adopted services and custom service.

4.1.1 Function defined in service API program

The APIｓ defined in SIG standard service API program and custom service API program are named according to certain rules. So, you can determine which API to use in user application just by checking the name of API. API for operation about value of characteristics and descriptor is named as follows.

[service] is the string set to [abbreviation] of the service in QE for BLE. For [S or C], S is set service is configured as server, C is set if service is configured as client. The string set to [operation] is operation of Bluetooth LE communication which is set to [properties] of characteristic or descriptor. [operation] section Bluetooth LE operation for characteristic and descriptor will be set. Table 4.1 lists [operation] generated in the server side API program and Table 4.2 lists [operation] generated in the client side API program. In both tables, [characteristic] is the string set to [abbreviation] of the characteristic in QE for BLE, [descriptor] is the string set to the [abbreviation] of the descriptor in QE for BLE.

Table 4.1 Server API

Get[characteristic]

Notify[characteristic] Start Notification operation by sending Handle Value Notification.

Get characteristic/descriptor value from GATT database.

Table 4.2 Client API

You can also get Attribute handle of descriptor included in characteristic.

Write[characteristic] Write[characteristic][descriptor]

Read[characteristic][descriptor]

Start Write Characteristic Value operation by sending Write Request. If value length exceeds MTU size, this function will start Write Long Characteristic

If value length exceeds MTU size, this function will start Write Long Characteristic

R01AN4553EJ0110 Rev.1.10 Page 34 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

API

description

R_BLE_[service][S or C]_Init

Initialization function for the service. Calling this function is necessary before using service API program.

This function is implemented only on client API program.

R_BLE_[service][S or C]_ServDiscCb

Function to operate discovery operation.

This function is implemented only on client API program.

BLE_[service][S or C]_EVENT_[characteristic]_[event type]

BLE_[service][S or C]_EVENT_[characteristic]_[descriptor]_[event type]

Each service generated from QE for BLE defines the function listed in Table 4.3, regardless of its configuration. In this table, [service] is sting set to [Abbreviation] of the service in QE for BLE, For [S or C], S is set service is configured as server, C is set if service is configured as client.

Table 4.3 API defined in each service API program

R_BLE_[service][S or C]_GetServAttrHdl Returns service attribute handle which is discovered in discovery

operation. Call this function after discovery operation is completed.

This function is used as callback function when using discovery library.

4.1.2 Event defined in service API program

API program for all services, including custom service, have events defined for sending and receiving data in Bluetooth LE communications. Users can develop applications by implementing behavior responding to defined events in callback functions.

Each defined event is named based on the type of data and behavior in communication.

Events about characteristic value are named as follows.

[service] is the string set to [abbreviation] of the service in QE for BLE, and [characteristic] is the string set to [abbreviation] of the characteristic in QE for BLE. [S or C] is S if the service is set to server, C if the service is set to client. [event type] is determined by the type of event described below.

Events about descriptor value are named as follows.

[service] is the string set to [abbreviation] of the service in QE for BLE, [characteristic] is the string set to [abbreviation] of the characteristic in QE for BLE, [descriptor] is the string set to [abbreviation] of the descriptor. [S or C] is S if the service is set to server, C if the service is set to client. [event type] is determined by the type of event described below.

The string set to [event type] is determined by sending and receiving events in Bluetooth LE communication. The type of event that occurs in Bluetooth LE communication is different on the server side and client side. Table 4.4 lists the events that occur on the server side, and Table 4.5 lists the event that occur on the client side.

R01AN4553EJ0110 Rev.1.10 Page 35 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Event

description

WRITE_REQ

Event that occurs when Write Request or Prepare Write Request is received.

BLE_GATTS_OP_CHAR_PEER_WRITE_REQ

BLE_GATTS_EVENT_EXE_WRITE_RSP_COMP

WRITE_CMD

Event that occurs when Write Command or Signed Write Command is received.

BLE_GATTS_OP_CHAR_PEER_WRITE_CMD

BLE_GATTS_OP_CHAR_PEER_READ_REQ

HDL_VAL_CNF

Event that occurs when Handle Value Confirmation is received.

BLE_GATTS_EVENT_HDL_VAL_CNF

event

description

BLE_GATTC_EVENT_LONG_CHAR_WRITE_COMP

READ_RSP

Event that occurs when Read Response or Read Blob Response is received.

BLE_GATTC_EVENT_LONG_CHAR_READ_COMP

BLE_GATTC_EVENT_HDL_VAL_NTF

HDL_VAL_IND

Event that occurs when Handle Value Indication is received.

BLE_GATTC_EVENT_HDL_VAL_IND

Table 4.4 Server event

It is used in Write Characteristic Value operation or Write Characteristic Long Value operation. GATT event:

WRITE_COMP Event that occurs when Write Response or Execute Write Response is sent.

It is used in Write Characteristic Value operation or Write Characteristic Long Value operation. GATT event: BLE_GATTS_EVENT_CHAR_WRITE_RSP_COMP

It is used in Write Characteristic Without Response operation or Signed Write operation. GATT event:

READ_REQ Event that occurs when Read Request is received.

It is used in Read Characteristic Value operation or Read Characteristic Long Value operation. GATT event:

It is used in Indication operation. GATT event:

Table 4.5 Client event

WRITE_RSP

HDL_VAL_NTF Event that occurs when Handle Value Notification is received.

Event that occurs when Write Response or Prepare Write Response is received. It is used in Write Characteristic Value operation or Write Characteristic Long Value operation. GATT event: BLE_GATTC_EVENT_CHAR_WRITE_RSP

It is used in Read Characteristic Value operation or Read Characteristic Long Value operation. GATT event: BLE_GATTC_EVENT_CHAR_READ_RSP

BLE_GATTC_EVENT_CHAR_PART_READ_RSP (If operation failed)

It is used in Notification operation. GATT event:

It is used in Indication operation. GATT event:

R01AN4553EJ0110 Rev.1.10 Page 36 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

/* LED Switch Service (Abbreviation:ls) Client Event Type Definition */

} e_ble_lsc_event_t;

Figure 4.4 shows the example of events defined in custom service. In this example, [Switch State (abbreviation: switch_state)] characteristic and [LED Blink Rate (abbreviation: blink_rate)] characteristic from client side of service [LED Switch Service (abbreviation: ls)] is shown. [LED Switch Service] is service used in sample project of BLE FIT module.

typedef enum {

/* Switch State Characteristic (Abbreviation:switch state) */

/* Handle Value Notification */

BLE_LSC_EVENT_SWITCH_STATE_HDL_VAL_NTF = BLE_SERVC_ATTR_EVENT(BLE_LSC_SWITCH_STATE_IDX, BLE_SERVC_HDL_VAL_NTF),

/* Client Characteristic Configuration Descriptor (Abbreviation:cli_cnfg) */ /* Read response */

BLE_LSC_EVENT_SWITCH_STATE_CLI_CNFG_READ_RSP

= BLE_SERVC_ATTR_EVENT(BLE_LSC_SWITCH_STATE_CLI_CNFG_IDX, BLE_SERVC_READ_RSP), /* Write response */ BLE_LSC_EVENT_SWITCH_STATE_CLI_CNFG_WRITE_RSP = BLE_SERVC_ATTR_EVENT(BLE_LSC_SWITCH_STATE_CLI_CNFG_IDX,

BLE_SERVC_WRITE_RSP),

/* LED Blink Rate Characteristic (Abbreviation:blink rate) */

/* Read Response */

BLE_LSC_EVENT_BLINK_RATE_READ_RSP = BLE_SERVC_ATTR_EVENT(BLE_LSC_BLINK_RATE_IDX, BLE_SERVC_READ_RSP), /* Write Response */ BLE_LSC_EVENT_BLINK_RATE_WRITE_RSP = BLE_SERVC_ATTR_EVENT(BLE_LSC_BLINK_RATE_IDX, BLE_SERVC_WRITE_RSP),

Figure 4.4 Example of event defined in custom service

R01AN4553EJ0110 Rev.1.10 Page 37 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Application

API Program

encode function

decode

function

GATT Database

BLE Protocol Stack

Ch ar ac teri s ti c / Des cr ip tor v al ue i s rep rens ent ed a s BYTE DATA ARRAY

e.g.)

uint8_t gatt_value[6];

Ch ar ac teri s ti c/Des cr ipto r va l ue i s rep res ented a s VAR IABLE or STRUC TURE

e.g.)

struct {

uint32_t field1; uint16_t field2;

} app_value;

4.2 Implementation of custom service

If you want to use features that are not defined in the SIG adopted service, you must create a custom service. This chapter guides you how to implement API programs for custom services generated from QE for BLE.

4.2.1 Implementing encode/decode function

The application layer handles characteristic and descriptor value in accordance with the format specified by the “Fields” of QE for BLE. On the other hand, the GATT database maintains characteristic and descriptor value in 8-bit data array which size is specified by the [Dbsize] of QE for BLE, and data in the array is sent and received as bit-stream by the BLE Protocol Stack. For this reason, the API program has to convert the value between structured data format for application and 8bit-serialized data for GATT Database and BLE Protocol Stack by using the encode/decode function.

Figure 4.5 shows the feature of encode/decode function.

The encode function is used by the API Program when API to send characteristic or descriptor value or to

Figure 4.5 Feature of encode/decode function

change characteristic or descriptor value of own GATT Database is called. Also, the decode function is used by the API Program before callback function to notify characteristic or descriptor value received.

Figure 4.6 shows a use-case of the encode/decode function that GATT Client writes new Characteristic value to peer GATT Server. The encode function is used by API Program of the client side and then the decode function is used by API Program of the server side.

R01AN4553EJ0110 Rev.1.10 Page 38 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

GATT Client

Application

API Program

BLE Protocol Stack

GATT Server Application

API Program

decode function

BLE Protocol Stack

VA RIABLE or S TRUCTURE of

Characte ristic v alue

BYTE DATA ARRA Y of

Characte ristic v alue

encode function

VA RIABLE or S TRUCTURE of

Characte ristic v alue

BYTE DATA ARRA Y of

Characte ristic v alue

Calling API to write Charasteristic value

Callback function is called and Write eve nt is notified

API Program

BLE P rotocol Stack

API Program

encode

function

BLE P rotocol Stack

VA RIABLE or STRUCTURE of

Characte ristic v alue

BYTE DATA ARRA Y of

Characte ristic v alue

decode function

VA RIABLE or STRUCTURE of

Characte ristic v alue

BYTE DATA ARRA Y of

Characte ristic v alue

Callback function is called and Notif y event is notified

Calli ng API to noti fy Charasteristic value

Figure 4.6 Use-Case of the encode/decode Function writing Characteristic value

Similarly, Figure 4.7 shows a use-case of the encode/decode function that GATT Server notifies new Characteristic value to peer GATT Client. The encode function is used by API Program of the server side and then the decode function is used by API Program of the client side.

Figure 4.7 Use-Case of the encode/decode Function notifying Characteristic value

R01AN4553EJ0110 Rev.1.10 Page 39 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Type of Field

encode

decode

int8_t

uint16_t int16_t

BT_PACK_LE_2_BYTE(*dst, *src)

BT_UNPACK_LE_2_BYTE(*dst, *src) int32_t

st_ble_ieee11073_sfloat_t

pack_st_ble_ieee11073_sfloat_t(*p_dst, *p_src)

unpack_st_ble_ieee11073_sfloat_t(*p_dst, *p_src)

st_ble_date_time_t

pack_st_ble_date_time_t(*p_dst, *p_src)

unpack_st_ble_date_time_t(*p_dst, *p_src)

In API program of custom service, encode/decode function is created but their contents are not implemented. Therefore, implementation of the encode/decode function for each data structure is needed. For basic data structures such as uint8_t type and commonly used data structures such as ieee11073 SFLOAT type, you can implement encode/decode function by calling appropriate encode/decode macros and functions. Table

4.6 describes the list of provided encode/decode macros and functions.

Table 4.6 encode/decode macro or function

char uint8_t

uint32_t

BT_PACK_LE_1_BYTE(*dst, *src) BT_UNPACK_LE_1_BYTE(*dst, *src)

BT_PACK_LE_4_BYTE(*dst, *src) BT_UNPACK_LE_4_BYTE(*dst, *src)

Figure 4.8 shows implementation of a encode function for characteristic which has field shown in Figure

4.9.In this encode function, encode macros and functions provided in Table 4.6 are used.

R01AN4553EJ0110 Rev.1.10 Page 40 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

typedef struct {

}

uint16_t field_u16; /**<field_u16 */ uint8_t field_u8; /**< field_u8 */ st_ble_date_time_t field_date; /**< field_date */ } st_ble_css_cc_t;

static ble_status_t encode_st_ble_css_cc_t(const st_ble_css_cc_t *p_app_value,

st_ble_gatt_value_t *p_gatt_value)

{ /* Start user code for Custom Characteristic characteristic value encode function.

Do not edit comment generated here */

uint8_t pos = 0; BT_PACK_LE_2_BYTE(&p_gatt_value->p_value[pos], &p_app_value->field_u16); pos += 2;

BT_PACK_LE_1_BYTE(&p_gatt_value->p_value[pos], &p_app_value->field_u8); pos += 1;

pack_st_ble_date_time_t(&p_gatt_value->p_value[pos], &p_app_value->field_date); pos += 7

p_gatt_value->value_len = pos;

/* End user code. Do not edit comment generated here */

return BLE_SUCCESS;

Figure 4.8 Example of implementing encode function

Figure 4.9 Example of field

R01AN4553EJ0110 Rev.1.10 Page 41 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

static const st_ble_servs_char_info_t gs_nc_char = {

};

4.2.2 Implementing callback in service API program

Bluetooth LE software generates events when Bluetooth LE communication such as receiving data or establishing connection occurs. You can implement application by implementing callback for those events. Callback for events can be implemented in 2 ways.

• Callback in the application.

• Callback in the service.

Beware that if you implement callback in the service, callback in application won’t be called. This section guides you how to implement callback in the service. For callback in application, refer [4.3.1Implementing callback in application framework]

Depending on the specifications of the custom service you implement, you may be required to implement following operations:

• Returns an error when an incorrect value is written to a characteristic or descriptor.

• Returns another characteristic value when specific instruction is written to a characteristic or descriptor.

Implementing these features in custom service API program improves portability and can be used for various applications.

Each characteristic has a structure defined as shown in Figure 4.10.

.start_hdl = BLE_CSS_CC_DECL_HDL, .end_hdl = BLE_CSS_CC_CLI_CNFG_DESC_HDL, .char_idx = BLE_CSS_CC_IDX, .app_size = sizeof(st_ble_css_cc_t), .db_size = BLE_CSS_CC_LEN, .decode = (ble_servs_attr_decode_t)decode_st_ble_css_cc_t, .encode = (ble_servs_attr_encode_t)encode_st_ble_css_cc_t, .pp_descs = gspp_cc_descs, .num_of_descs = ARRAY_SIZE(gspp_cc_descs),

Figure 4.10 Characteristic structure in service API program

You can create a callback function for a characteristic event in a custom service by editing this structure as shown in Figure 4.11.

R01AN4553EJ0110 Rev.1.10 Page 42 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

static void css_cc_write_req_cb(const void *p_attr, uint16_t conn_hdl, ble_status_t

};

result, const void *p_app_value) {

/*........*/

}

static void css_cc_write_comp_cb(const void *p_attr, uint16_t conn_hdl, ble_status_t

result, const void *p_app_value) {

/*........*/

}

static const st_ble_servs_char_info_t gs_nc_char = {

Figure 4.11 Implementing callback function in service API program

The callbacks that can be registered are different in server program and client program. Table 4.7 shows callback functions that server program can register and Table 4.8 shows a callback functions that the client program can register. For more information about each event, refer the [R_BLE API Document (r_ble_api_spec.chm)] that is included in BLE FIT Module.

R01AN4553EJ0110 Rev.1.10 Page 43 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Callback

Event

write_req_cb

This callback occurs when Write Request or Prepare Write Request is received.

BLE_GATTS_OP_CHAR_PEER_WRITE_REQ

BLE_GATTS_EVENT_EXE_WRITE_RSP_COMP

write_cmd_cb

This callback occurs when Write Command or Signed Write Command is received.

BLE_GATTS_OP_CHAR_PEER_WRITE_CMD

BLE_GATTS_OP_CHAR_PEER_READ_REQ

hdl_val_cnf_cb

This callback occurs when Handle Value Confirmation is received.

BLE_GATTS_EVENT_HDL_VAL_CNF

BLE_VS_EVENT_TX_FLOW_STATE_CHG

Callback

Event

BLE_GATTC_EVENT_LONG_CHAR_WRITE_COMP

read_rsp_cb

This callback occurs when Read Response or Read Blob Response is received.

BLE_GATTC_EVENT_LONG_CHAR_READ_COMP

BLE_GATTC_EVENT_HDL_VAL_NTF

hdl_val_ind_cb

This callback occurs when Handle Value Indication is received.

BLE_GATTC_EVENT_HDL_VAL_IND

Table 4.7 Callback available for server characteristic

It is used in Write Characteristic Value operation or Write Characteristic Long Value operation. GATT event:

write_comp_cb This callback occurs when Write Response or Execute Write Response is sent.

It is used in Write Characteristic Value operation or Write Characteristic Long Value operation. GATT event: BLE_GATTS_EVENT_WRITE_RSP_COMP

It is used in Write Characteristic Without Response operation or Signed Write operation. GATT event:

read_req_cb This callback occurs when Read Request is received.

It is used in Read Characteristic Value operation or Read Characteristic Long Value operation. GATT event:

It is used in Indication operation. GATT event:

flow_control_cb This callback occurs when TX flow event is noticed.

VS event:

Table 4.8 Callback available for client characteristic

write_rsp_cb This callback occurs when Write Response or Prepare Write Response is received.

It is used in Write Characteristic Value operation or Write Characteristic Long Value operation.

GATT event: BLE_GATTC_EVENT_CHAR_WRITE_RSP

It is used in Read Characteristic Value operation or Read Characteristic Long Value operation. GATT event:

BLE_GATTC_EVENT_CHAR_READ_RSP

hdl_val_ntf_cb This callback occurs when Handle Value Notification is received.

It is used in Notification operation. GATT event:

It is used in Indication operation. GATT event:

R01AN4553EJ0110 Rev.1.10 Page 44 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Callback

Event

BLE_GATTS_OP_CHAR_PEER_HLD_CNFG_WRITE_REQ

BLE_GATTS_EVENT_EXE_WRITE_RSP_COMP

BLE_GATTS_OP_CHAR_PEER_HLD_CNFG_READ_REQ

static const st_ble_servs_desc_info_t gs_cc_cd = {

};

Similar to characteristic, each descriptor has structure defined as shown inFigure 4.12. By editing this structure, you can also register callback functions in the descriptor.

.attr_hdl = BLE_CSS_CC_CD_DESC_HDL, .app_size = sizeof(uint8_t), .desc_idx = BLE_CSS_CC_CD_IDX, .db_size = BLE_CSS_CC_CD_LEN, .decode = (ble_servs_attr_decode_t)decode_uint8_t, .encode = (ble_servs_attr_encode_t)encode_uint8_t,

Figure 4.12 Descriptor structure in service API program

Descriptors can register different types of callbacks than characteristics. Table 4.9 shows callbacks that can be registered on the server side, and Table 4.10 shows callbacks that can be registered on the client side. For more information about each event, refer [R_BLE API Document (r_ble_api_spec.chm)] that is included in BLE FIT Module.

Table 4.9 Callback available for server descriptor

write_req_cb This callback occurs when Write Request or Prepare Write Request is received.

It is used in Write Characteristic Value operation or Write Characteristic Long Value operation.

GATT event: BLE_GATTS_OP_CHAR_PEER_CLI_CNFG_WRITE_REQ BLE_GATTS_OP_CHAR_PEER_SER_CNFG_WRITE_REQ BLE_GATTS_OP_CHAR_PEER_USR_CNFG_WRITE_REQ

write_comp_cb This callback occurs when Write Response or Execute Write Response is sent.

It is used in Write Characteristic Value operation or Write Characteristic Long Value operation. GATT event: BLE_GATTS_EVENT_WRITE_RSP_COMP

read_req_cb This callback occurs when Read Request is received.

It is used in Read Characteristic Value operation or Read Characteristic Long Value operation. GATT event: BLE_GATTS_OP_CHAR_PEER_CLI_CNFG_READ_REQ

BLE_GATTS_OP_CHAR_PEER_SER_CNFG_READ_REQ BLE_GATTS_OP_CHAR_PEER_USR_CNFG_READ_REQ

R01AN4553EJ0110 Rev.1.10 Page 45 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Callback

Event

write_rsp_cb

This callback occurs when Write Response or Prepare Write Response is received.

BLE_GATTC_EVENT_LONG_CHAR_WRITE_RSP

BLE_GATTC_EVENT_LONG_CHAR_READ_COMP

Table 4.10 Callback available for client descriptor

It is used in Write Characteristic Value operation or Write Characteristic Long Value operation. GATT event:

BLE_GATTC_EVENT_CHAR_WRITE_RSP

read_rsp_cb This callback occurs when Read Response or Read Blob Response is received.

It is used in Read Characteristic Value operation or Read Characteristic Long Value operation. GATT event:

BLE_GATTC_EVENT_CHAR_READ_RSP

R01AN4553EJ0110 Rev.1.10 Page 46 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

[service][s or c]_cb

4.3 Implementation of app_main.c

app_main.c is the underlying framework for implementing user applications and profiles. This chapter guides you on how to implement user applications and profiles.

4.3.1 Implementing callback in application framework

• Callback in the application.

• Callback in the service.

Beware that if you implement callback in the service, callback in application won’t be called. This section guides you how to implement callback in the application.

Handling of basic events for Bluetooth LE communication is implemented in application.

For events that comply with Bluetooth specifications, such as the establishment of connection or the completion of pairing, please refer [3. How to implement user code] in Application Note [RX23W Group Bluetooth Low Energy Application Developer’s Guide (R01AN5504)].

For events that exchanges each data of characteristic or descriptor included in the profile is implemented in the callback function output as a skeleton program. Naming rule of callback function is follows.

[service] is the string set to [abbreviation] of the service in QE for BLE. [s or c] is s if the service is set to server, c if the service is set to client.

For information about the events that occur, refer [4.1.2 Event defined in service API program]. Figure 4.13 shows an example of implementing a custom service callback function. This example is server side of [LED switch service (abbreviation: ls)] used in sample program in [RX23W Group BLE Module Firmware Integration Technology(R01AN4860)]. The process of updating the software timer when receiving data sent by write data operation from client side is implemented. For software timer, refer [4.1 software timer] in [RX23W Group Bluetooth Low Energy Application Developer’s Guide (R01AN5504)].

R01AN4553EJ0110 Rev.1.10 Page 47 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

static void lss_cb(uint16_t type, ble_status_t result, st_ble_servs_evt_data_t

}

*p_data) { switch (type) { case BLE_LSS_EVENT_BLINK_RATE_WRITE_REQ: { uint8_t rate = *(uint8_t *)p_data->p_param; R_BLE_TIMER_UpdateTimeout(gs_timer_hdl, rate*100); } break;

default: break; }

Figure 4.13 Callback event of custom service

R01AN4553EJ0110 Rev.1.10 Page 48 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

4.4 Notice

4.4.1 Implementation of multiple services

When implementing multiple services, take care of the characteristic and descriptor code sizes contained in the service. If the code size exceeds the RAM/ROM size of target device, it cannot be compiled. Please refer [RX23W Group BLE Module Firmware Integration Technology(R01AN4860)] for ROM/RAM size that BLE Protocol Stack uses.

4.4.2 Implementation of same service

If you add multiple same SIG standard services to a profile, QE for BLE cannot correctly generate programs due to problem such as conflicts of file name. Therefore, if you want to implement multiple same services, you need to add only one service as SIG standard service and add the others as custom service on QE for BLE. For example, assume that you want to implement 2 Human Interface Device Service (HIDS), which is SIG standard service.

First, you need to add 2 HIDS as SIG standard service in QE for BLE. Change 1 of these HIDS from SIG standard service to custom service. To change from SIG standard service to custom service, click the customize button on the service setting screen. You need to make the following changes to the service that you changed to the custom service:

• Change [UUID] of service so that service UUID matches between the same service. If you want to treat the custom service as SIG standard service, set [UUID] to 16bit and change the value.

• Change [abbreviation] of service so that it does not conflict with other services. This is to prevent conflicts on file name, function name, and variable name because [abbreviation] is used for them. Similarly, set [abbreviation] of characteristic and descriptor to string which do not conflict with others.

Setting on QE for BLE is over. Figure 4.14 shows how to configure multiple SIG standard services on QE for BLE.

Figure 4.14 Configure multiple service on QE for BLE

R01AN4553EJ0110 Rev.1.10 Page 49 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

/* Human Interface Device Service UUID */

};

Because the program generated from custom services are skeleton program, it is necessary to implement the actual state of process. Program generated from SIG standard services has same mechanism and is implemented according to the defined specification, so refer this program to implement skeleton program of custom service. The parts that must be implemented vary from service to service, but in many cases, following implementation is needed:

• Implements encode/decode function. Since the structure of the characteristic or descriptor remains the same, you can port many parts of implementation. Beware of differences in function name and variable name.

• Implements callback function in service. This is used when you want to automatically return error for invalid value written or automatically return certain value for specific value written. Implementation is needed according to functionality of each service.

In addition, if the profile has at least one service selected as a [client] except the GAP service, discovery operation program using discovery library is implemented in file app_main.c. Among them, the array gs_disc_entries[] defines UUID and discovery callback function for each service included in profile. To discover services those have same service UUID, you need to add element idx which is index number for them. The following is example of implementing a program with 2 HIDS.

static uint8_t HIDC_UUID[] = { 0x12, 0x18 }; //HIDS specific service UUID

/* Human Interface Device Service2 UUID */

static uint8_t HID2C_UUID[] = { 0x12, 0x18 }; //Same service UUID

/* Service discovery parameters */

static st_ble_disc_entry_t gs_disc_entries[] = {

{ .p_uuid = HIDC_UUID, .uuid_type = BLE_GATT_16_BIT_UUID_FORMAT, .serv_cb = R_BLE_HIDC_ServDiscCb, /* Add member [idx] */

.idx = 0, /* Set index number if service UUID is same */ }, { .p_uuid = HID2C_UUID, .uuid_type = BLE_GATT_16_BIT_UUID_FORMAT, .serv_cb = R_BLE_HID2C_ServDiscCb,

/* Add member [idx] */

.idx = 1, /* Set index number if service UUID is same */ },

R01AN4553EJ0110 Rev.1.10 Page 50 of 64 Mar.12.21

Figure 4.15 Example of implementing 2 HIDSs

RX23W Group Bluetooth Low Energy Profile Developer's Guide

static const st_ble_gatts_db_uuid_cfg_t gs_gatt_type_table[] =

}

4.4.3 Implementation of secondary service

QE for BLE treats all services as primary services. Therefore, if you want to use secondary service, you need to modify the generated program. How to change program is different on the server side and client side.

Server Side

QE for BLE generates GATT database which stores information of services which have check in [server]. Since QE for BLE treats all services as primary service, generated GATT database defines all services as primary service. You need to modify service information defined in GATT database.

Change the array gs_gatt_type_table[ ] defined in file gatt_db.c. In this array, following 2 point needs to be changed:

• Add definition for secondary service. Refer to the other elements of the array and create element that has [UUID_Offset] is 2 and correct attribute handles of secondary services.

• Change element which defines [Primary Service Declaration]. Change it to specify the correct attribute handle.

The following is the example of implementation on array gs_gatt_type_table[ ].

{ /* 0 : Primary Service Declaration */ { /* UUID Offset */ 0,

/* First Occurrence for type */

/* Change this value to proper handle */

0x000C,

/* Last Occurrence for type */

/* Change this value to proper handle */

0x0026, },

/* Add from here */

/* 2 : Secondary Service Declaration */ { /* UUID Offset */

/* set 2 for this value */

/* First Occurrence for type */

/* Change this value to proper handle */

0x0010,

/* Last Occurrence for type */

/* Change this value to proper handle */

0x0000, },

/* Add until here */

Figure 4.16 GATT database of secondary service (1)

R01AN4553EJ0110 Rev.1.10 Page 51 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Also, change array gs_gatt_db_attr_table[ ]. n this array, following 2 point needs to be changed:

• Change [UUID_Offset] section of service declaration which you want to change to secondary service. [UUID_offset] determines attribute type of data. In [UUID_Offset], 0 stands for primary service and 2 stands for secondary service. Set 2 for [UUID_Offset].

• change element [Next Attribute Type Index] to indicate correct attribute handle. [Next Attribute Type Index] holds attribute handle of next data which has same attribute type. If modified data was the last data with same attribute type, enter 0x0000 for [Next Attribute Type Index].

The example of implementation on array gs_gatt_type_table[ ] is shown on the next page.

Note: Make sure that the service which you changed to secondary service is included from at least one

primary service.

R01AN4553EJ0110 Rev.1.10 Page 52 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

static const st_ble_gatts_db_attr_cfg_t gs_gatt_db_attr_table[] =

}

{

/* Handle: 0x000C */

/* GATT Service: Primary Service Declaration */ { /* Properties */ BLE_GATT_DB_READ, /* Auxiliary Properties */ BLE_GATT_DB_FIXED_LENGTH_PROPERTY, /* Value Size */ 2,

/* Next Attribute Type Index */

/* change this value to handle of next primary service declaration */

0x0026, /* 0x0010 → 0x0026 */

/* UUID Offset */ 0, /* Value */ (uint8_t *)(gs_gatt_const_uuid_arr + 20), },

/* Example: Secondary Service Declaration */

/* Handle: 0x0010 */

/* Human Interface Device Service: Primary Service Declaration */

{

/* Properties */

BLE_GATT_DB_READ,

/* Auxiliary Properties */

BLE_GATT_DB_FIXED_LENGTH_PROPERTY, /* Value Size */ 2,

/* Next Attribute Type Index */

/* Change this value to proper handle */

/* Last secondary service declared: 0x0000 */ /* Not last secondary service declared: handle of next secondary service

declaration */

0x0000, /* 0x0026 → 0x0000 */

/* UUID Offset */

/* Change this value to proper Attribute type */

/* Primary service declaration: 0 */ /* Secondary service declaration: 2 */ 2, /* 0 → 2 */

/* Value */ (uint8_t *)(gs_gatt_const_uuid_arr + 26), },

/* Handle: 0x0026 */ /* Human Interface Device Service2: Primary Service Declaration */

Figure 4.17 GATT database of secondary service (2)

R01AN4553EJ0110 Rev.1.10 Page 53 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Client Side

If the profile has at least one service selected as a [client] except the GAP service, QE for BLE generate the code to perform the discovery operation. Generated program performs discovery operation only to primary service using Discovery Library provided by BLE Protocol Stack. When you need to discovery secondary service, perform discovery operation as the included service because secondary service is included from other primary service, Refer to [4.4.4 Implementation of discovery operation about included service]. When you perform secondary service discovery operation to debug, call R_BLE_GATTC_DiscAllSecondServ() in GATT Client API provided by BLE Protocol Stack. For more information about GATT Client API, refer the [R_BLE API document (r_ble_api_spec.chm)] that is included in BLE FIT module.

R01AN4553EJ0110 Rev.1.10 Page 54 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

/*PRIMARY service entry */

};

4.4.4 Implementation of discovery operation about included service

Specifying included service

If service has specific service as an included service, you need to confirm its structure to perform discovery operation to specific service. Discovery library provide feature to perform discovery operation confirming this structure. Discovery library perform discovery operation to attribute handle range that included service declaration has if included service entries are registered in discovery entry of parent service. Modify the variable gs_disc_entries in the app_main.c as the following, in order to register included service entries to discovery entry of parent service.

static st_ble_disc_entry_t gs_disc_entries[] =

{ { /*Weight Scale service disc entry */ .p_uuid = (uint8_t *)BLE_WSC_UUID, .uuid_type = BLE_GATT_16_BIT_UUID_FORMAT, .serv_cb = R_BLE_WSC_ServDiscCb, }, { /*Body Composition service disc entry */ .p_uuid = (uint8_t *)BLE_BCC_UUID, .uuid_type = BLE_GATT_16_BIT_UUID_FORMAT, .serv_cb = R_BLE_BCC_ServDiscCb, },

Figure 4.18 Code generated by QE for BLE

R01AN4553EJ0110 Rev.1.10 Page 55 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

/*Add INCLUDE service entry*/

};

static st_ble_disc_entry_t gs_disc_wsc_inc_entries[] =

{

/*Body Composition service disc entry AS A INCLUDE SERVICE IN WSS*/

{ .p_uuid = (uint8_t *)BLE_BCC_UUID, .uuid_type = BLE_GATT_16_BIT_UUID_FORMAT,

.serv_cb = R_BLE_BCC_ServDiscCb, .num_of_inc_servs = 0, }, };

/*PRIMARY service entry */

static st_ble_disc_entry_t gs_disc_entries[] =

{

/*Weight Scale service disc entry as a primary service*/

{ .p_uuid = (uint8_t *)BLE_WSC_UUID, .uuid_type = BLE_GATT_16_BIT_UUID_FORMAT, .serv_cb = R_BLE_WSC_ServDiscCb, /* Register include service entry*/ .inc_servs = gs_disc_wsc_inc_entries, .num_of_inc_servs = 1

Store Attribute handle of included service

Discovered attribute handle of included service will be passed to parent service API program. But parent service API program don’t store attribute handle of included service. Therefore, in case Service YYY is discovered as included service that Service XXX has, you can’t get range of its attribute handle by calling service YYY’s API R_BLE_YYY_GetServAttrhdl().

If service YYY’s range of attribute handle is needed, modify service XXX’s API program (r_ble_xxx.c) so that the notification that service YYY is discovered as a include service is delivered to service YYY’s discovery callback function.

The following show example in case Service XXX have 16bit UUID and have service YYY as included service. Take care the data type is different in 128bit UUID and in 16bit UUID.

Figure 4.19 code modified to discover included service

R01AN4553EJ0110 Rev.1.10 Page 56 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

#include <string.h>

}

#include "r_ble_XXX.h" #include "profile_cmn/r_ble_servc_if.h"

/* ADD : including discovery library and include service yyy */

#include "discovery/r_ble_disc.h" #include "r_ble_yyy.h"

void R_BLE_XXX_ServDiscCb(uint16_t conn_hdl, uint8_t serv_idx, uint16_t type, void

*p_param) {

/* ADD : */

uint16_t YYY_UUID = 0x0000; if (type == BLE_DISC_INC_SERV_FOUND) { st_disc_inc_serv_param_t * evt_param =

if (evt_param->uuid_type == BLE_GATT_16_BIT_UUID_FORMAT) { if(YYY_UUID == evt_param->value.inc_serv_16.service.uuid_16)

st_disc_serv_param_t serv_param = { .uuid_type = BLE_GATT_16_BIT_UUID_FORMAT, .value.serv_16.range =

.value.serv_16.uuid_16 =

R_BLE_YYY_ServDiscCb(

} }

/* Generated code */

(st_disc_inc_serv_param_t *)p_param;

{

evt_param->value.inc_serv_16.service.range,

evt_param->value.inc_serv_16.service.uuid_16,

};

/* Connection handle */

conn_hdl,

/* idx */

/* Notify as a primary service */

BLE_DISC_PRIM_SERV_FOUND,

/* Service handle information */

&serv_param);

}

Figure 4.20 Discovery of included service

R01AN4553EJ0110 Rev.1.10 Page 57 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

4.4.5 Using GAT service and GAP service

QE for BLE won’t generate source code to use GAT service and GAP service in app_main.c. To use them, add following changes.

Adding include header

Add the header file of the GAT service and GAP service to app_main.c. Add files below depending on which API program to be used. Figure 4.21 shows example of adding server side of GAT service and client side of GAP service.

• Server side of GAT service API program: “r_ble_gats.h”

• Client side of GAT service API program: “r_ble_gatc.h”

• Server side of GAP service API program: “r_ble_gaps.h”

• Client side of GAP service API program: “r_ble_gapc.h”

/****************************************************************************** User file includes *******************************************************************************/

/* Start user code for file includes. Do not edit comment generated here */

#include “r_ble_gats.h” #include “r_ble_gapc.h”

/* End user code. Do not edit comment generated here */

Figure 4.21 Adding include header

Adding init function and callback function

Implement callback function for the GAT service and GAP service and add init function to enable them.

First, implement a prototype declaration of callback function (Figure 4.22).

Note: In app_main.c, function name [gap_cb], [gatts_cb], [gattc_cb] are used. Use other callback function name.

/****************************************************************************** User function prototype declarations *******************************************************************************/

/* Start user code for function prototype declarations. Do not edit comment generated here */

static void gats_cb(uint16_t type, ble_status_t result, st_ble_servs_evt_data_t

*p_data);

static void gapc_cb(uint16_t type, ble_status_t result, st_ble_servc_evt_data_t

*p_data);

/* End user code. Do not edit comment generated here */

Figure 4.22 Prototype declarations of callback function

R01AN4553EJ0110 Rev.1.10 Page 58 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Next, add init function in app_main function (Figure 4.23).

void app_main(void)

{ /* Initialize BLE */ R_BLE_Open();

/* Initialize host stack and profiles */ ble_init();

/* Hint: Input process that should be done before main loop such as calling initial function or variable definitions */ /* Start user code for process before main loop. Do not edit comment generated here */

ble_status_t status; status = R_BLE_GATS_Init(gats_cb); if (BLE_SUCCESS != status) { return BLE_ERR_INVALID_OPERATION; } status = R_BLE_GAPC_Init(gapc_cb); if (BLE_SUCCESS != status) { return BLE_ERR_INVALID_OPERATION; }

/* End user code. Do not edit comment generated here */

Figure 4.23 Adding init function

Finally, implement callback function (Figure 4.24).

/****************************************************************************** User function definitions *******************************************************************************/

/* Start user code for function definitions. Do not edit comment generated here */

static void gats_cb(uint16_t type, ble_status_t result, st_ble_servs_evt_data_t

*p_data) {

switch(type) { /* Please implement operation */ } };

static void gapc_cb(uint16_t type, ble_status_t result, st_ble_servc_evt_data_t

*p_data) {

switch(type) { /* Please implement operation */ } };

/* End user code. Do not edit comment generated here */

Figure 4.24 Implement callback function

R01AN4553EJ0110 Rev.1.10 Page 59 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Implement to discovery_entries

If you use client side API program, you must perform discovery operation before using the API. To perform the discovery operation for GAT service and GAP service, change array gs_disc_entries in the app_main.c as shown in Figure 4.25.

/* Battery Service UUID */

static uint8_t BAC_UUID[] = { 0x0F, 0x18 };

/* ADD HERE */ /* GATT Service UUID */

static uint8_t GATC_UUID[] = { 0x01, 0x18 };

/* GAP Service UUID */

static uint8_t GAPC_UUID[] = { 0x00, 0x18 };

/* ADD HERE */

/* Service discovery parameters */

static st_ble_disc_entry_t gs_disc_entries[] =

{ { .p_uuid = BAC_UUID, .uuid_type = BLE_GATT_16_BIT_UUID_FORMAT, .serv_cb = R_BLE_BAC_ServDiscCb, },

/* ADD HERE */

{ .p_uuid = GATC_UUID, .uuid_type = BLE_GATT_16_BIT_UUID_FORMAT, .serv_cb = R_BLE_GATC_ServDiscCb, }, { .p_uuid = GAPC_UUID, .uuid_type = BLE_GATT_16_BIT_UUID_FORMAT, .serv_cb = R _BLE_GAPC_ServDiscCb, },

/* ADD HERE */

};

Figure 4.25 Adding UUID for discovery

R01AN4553EJ0110 Rev.1.10 Page 60 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

4.4.6 Guide for Connection Update

In Bluetooth LE communication, you can change the communication frequency during communication by updating the connection. Connection update can be performed by using function [R_BLE_GAP_UpdConn]. To change frequency of communication, change the following parameters.

• Connection Interval  Sets frequency of communication. user can set maximum value and minimum value. Value is

calculated by (set value)×1.25ms.

 variable: conn_intv_min, conn_intv_max

• Slave latency  Ignores communications by the number of value set. If set to 5, communication until the 6th

reception will be ignored after first reception.

 variable: conn_latency

• Supervision Timeout  Connection will be disconnected after the time set here. If user want to reduce the frequency of

communication, this value needs to be changed accordingly. Value is calculated by (set value)× 10ms.

Figure 4.26 shows the example of implementing connection update function in function disc_comp_cb.

static void disc_comp_cb(uint16_t conn_hdl)

{

/* Hint: Input process such as GATT operation */ /* Start user code for Discovery Complete callback function. Do not edit comment generated here */

st_ble_gap_conn_param_t conn_param = { .conn_intv_min = 0x0100, .conn_intv_max = 0x0100, .conn_latency = 0x0010, .sup_to = 0x0200, .min_ce_length = 0xFFFF, .max_ce_length = 0xFFFF, }; R_BLE_GAP_UpdConn(conn_hdl, BLE_GAP_CONN_UPD_MODE_REQ, 0x00, conn_param);

/* End user code. Do not edit comment generated here */

return; }

Figure 4.26 Example of using Connection Update function

R01AN4553EJ0110 Rev.1.10 Page 61 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

5. Build and Run created profile

5.1 Build and Run for New Project

If you create a new project according [2.4 Building development environment] and [3.1 Overview of profile configuration], the program generated from QE for BLE is generated ate the appropriate location in the project. If BLE FIT module is added to smart configurator, the BLE Protocol Stack is also added to the project in correct position. Therefore, you can build and run project without changing location of file and directory.

5.2 Build and Run for Sample Project

The BLE FIT module ships sample project using Bluetooth LE function under the name of “FITDemos”.User can import sample project and develop based on them.

Sample project included in version 1.20 or later BLE FIT module are created in structure that uses QE for BLE. Therefore, user can build and run project without changing location of file and directory.

If user are developing with sample project included in version 1.10 or early BLE FIT module, following changes are needed.

When QE for BLE is used in a sample project, the program will be generated replacing the files in the sample project. Therefore, a new project needs to be created for QE for BLE to generate the program. Next, copy the program generated from the new project to the sample project.

Copy each of the following files:

• “app_main.c” generated from QE for BLE  Replace with original “app_main.c”.

• “gatt_db.c” and “gatt_db.h” generated from QE for BLE  Replace with original “gatt_db.c” and

“gatt_db.h”.

• “r_ble_[service]” generated from QE for BLE  Copy all files to folder “src”.

• “service” folder of sample project  Delete with all files inside.

R01AN4553EJ0110 Rev.1.10 Page 62 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

//void app_main(void)

}

Edit app_main.c as follows to use in the sample project:

 Change app_main() to main()

void main(void)

{ R_BLE_Open(); ble_app_init();

while (1) { R_BLE_Execute(); }

R_BLE_Close();

Figure 5.1 Copy generated program files to sample program

5.2 Change function app_main

R01AN4553EJ0110 Rev.1.10 Page 63 of 64 Mar.12.21

RX23W Group Bluetooth Low Energy Profile Developer's Guide

Rev.

Date

Description

Page

Summary

1.00

Nov.27.19

—

First edition issued.

(R01AN5504)

BLE FIT module.

•

characteristic and descriptor.

Added [2.1 Software Requirements].

Added list of profile in [2.2 BLE QE Utility Module].

Added [3.1.2 Download FIT module].

Added [3.2.1 Addition of elements].

Added [4.1 Service API program].

program] and [4.1.2Event defined in service API program].

Added [4.4.5 Using GAT service and GAP service].

Added [4.4.6 Guide for Connection Update].

Revision History

1.10 Mar.12.21

28, 31

Added following document to Related Document.

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

•

RX23W Group Bluetooth Low Energy Application Developer’s Guide

Added guide for using sample project included in version 1.20 or later

Added guide for function added in QE Utility V1.10

Added code blocking function to protect user code. Deleted “not supported” from Aux Properties of

changed section number of [4.1.1Function defined in service API

R01AN4553EJ0110 Rev.1.10 Page 64 of 64 Mar.12.21

General Precautions in the Handling of Microprocessing Unit and Microcontroller Unit Products

The following usage notes are applicable to all Microprocessing unit and Microcontroller unit products from Renesas. For detailed usage notes on the products covered by this document, refer to the relevant sections of the document as well as any technical updates that have been issued for the products.

1. Precaution against Electrostatic Discharge (ESD)

A strong electrical field, when exposed to a CMOS device, can cause destruction of the gate oxide and ultimately degrade the device operation. Steps

must be taken to stop the generation of static electricity as much as possible, and quickly dissipate it when it occurs. Environmental control must be

adequate. When it is dry, a humidifier should be used. This is recommended to avoid using insulators that can easily build up static electricity.

Semiconductor devices must be stored and transported in an anti-static container, static shielding bag or conductive material. All test and

measurement tools including work benches and floors must be grounded. The operator must also be grounded using a wrist strap. Semiconductor

devices must not be touched with bare hands. Similar precautions must be taken for printed circuit boards with mounted semiconductor devices.

2. Processing at power-on

The state of the product is undefined at the time when power is supplied. The states of internal circuits in the LSI are indeterminate and the states of

register settings and pins are undefined at the time when power is supplied. In a finished product where the reset signal is applied to the external reset

pin, the states of pins are not guaranteed from the time when power is supplied until the reset process is completed. In a similar way, the states of pins

in a product that is reset by an on-chip power-on reset function are not guaranteed from the time when power is supplied until the power reaches the

level at which resetting is specified.

3. Input of signal during power-off state

Do not input signals or an I/O pull-up power supply while the device is powered off. The current injection that results from input of such a signal or I/O

pull-up power supply may cause malfunction and the abnormal current that passes in the device at this time may cause degradation of internal

elements. Follow the guideline for input signal during power-off state as described in your product documentation.

4. Handling of unused pins

Handle unused pins in accordance with the directions given under handling of unused pins in the manual. The input pins of CMOS products are

generally in the high-impedance state. In operation with an unused pin in the open-circuit state, extra electromagnetic noise is induced in the vicinity of

the LSI, an associated shoot-through current flows internally, and malfunctions occur due to the false recognition of the pin state as an input signal

become possible.

5. Clock signals

After applying a reset, only release the reset line after the operating clock signal becomes stable. When switching the clock signal during program

execution, wait until the target clock signal is stabilized. When the clock signal is generated with an external resonator or from an external oscillator

during a reset, ensure that the reset line is only released after full stabilization of the clock signal. Additionally, when switching to a clock signal

produced with an external resonator or by an external oscillator while program execution is in progress, wait until the target clock signal is stable.

6. Voltage application waveform at input pin

Waveform distortion due to input noise or a reflected wave may cause malfunction. If the input of the CMOS device stays in the area between V

(Max.) and V

input level is fixed, and also in the transition period when the input level passes through the area between V

7. Prohibition of access to reserved addresses

Access to reserved addresses is prohibited. The reserved addresses are provided for possible future expansion of functions. Do not access these

addresses as the correct operation of the LSI is not guaranteed.

8. Differences between products

Before changing from one product to another, for example to a product with a different part number, confirm that the change will not lead to problems.

The characteristics of a microprocessing unit or microcontroller unit products in the same group but having a different part number might differ in terms

of internal memory capacity, layout pattern, and other factors, which can affect the ranges of electrical characteristics, such as characteristic values,

operating margins, immunity to noise, and amount of radiated noise. When changing to a product with a different part number, implement a system-

evaluation test for the given product.

(Min.) due to noise, for example, the device may malfunction. Take care to prevent chattering noise from entering the device when the

(Max.) and VIH (Min.).

Corporate Headquarters

Contact information

www.renesas.com

Trademarks

of their respective owners.

Notice

1. Descriptions of circuits, software and other related information in this document are provided only to illustrate the operation of semiconductor products

and application examples. You are fully responsible for the incorporation or any other use of the circuits, software, and information in the design of your product or system. Renesas Electronics disclaims any and all liability for any losses and damages incurred by you or third parties arising from the use of these circuits, software, or information.

2. Renesas Electronics hereby expressly disclaims any warranties against and liability for infringement or any other claims involving patents, copyrights,

or other intellectual property rights of third parties, by or arising from the use of Renesas Electronics products or technical information described in this document, including but not limited to, the product data, drawings, charts, programs, algorithms, and application examples.

3. No license, express, implied or otherwise, is granted hereby under any patents, copyrights or other intellectual property rights of Renesas Electronics

or others.

4. You shall be responsible for determining what licenses are required from any third parties, and obtaining such licenses for the lawful import, export,

manufacture, sales, utilization, distribution or other disposal of any products incorporating Renesas Electronics products, if required.

5. You shall not alter, modify, copy, or reverse engineer any Renesas Electronics product, whether in whole or in part. Renesas Electronics disclaims any

and all liability for any losses or damages incurred by you or third parties arising from such alteration, modification, copying or reverse engineering.

6. Renesas Electronics products are classified according to the following two quality grades: “Standard” and “High Quality”. The intended applications for

each Renesas Electronics product depends on the product’s quality grade, as indicated below. "Standard": Computers; office equipment; communications equipment; test and measurement equipment; audio and visual equipment; home

"High Quality": Transportation equipment (automobiles, trains, ships, etc.); traffic control (traffic lights); large-scale communication equipment; key

Unless expressly designated as a high reliability product or a product for harsh environments in a Renesas Electronics data sheet or other Renesas Electronics document, Renesas Electronics products are not intended or authorized for use in products or systems that may pose a direct threat to human life or bodily injury (artificial life support devices or systems; surgical implantations; etc.), or may cause serious property damage (space system; undersea repeaters; nuclear power control systems; aircraft control systems; key plant systems; military equipment; etc.). Renesas Electronics disclaims any and all liability for any damages or losses incurred by you or any third parties arising from the use of any Renesas Electronics product that is inconsistent with any Renesas Electronics data sheet, user’s manual or other Renesas Electronics document.

7. No semiconductor product is absolutely secure. Notwithstanding any security measures or features that may be implemented in Renesas Electronics

hardware or software products, Renesas Electronics shall have absolutely no liability arising out of any vulnerability or security breach, including but not limited to any unauthorized access to or use of a Renesas Electronics product or a system that uses a Renesas Electronics product. RENESAS ELECTRONICS DOES NOT WARRANT OR GUARANTEE THAT RENESAS ELECTRONICS PRODUCTS, OR ANY SYSTEMS CREATED USING RENESAS ELECTRONICS PRODUCTS WILL BE INVULNERABLE OR FREE FROM CORRUPTION, ATTACK, VIRUSES, INTERFERENCE, HACKING, DATA LOSS OR THEFT, OR OTHER SECURITY INTRUSION (“Vulnerability Issues”). RENESAS ELECTRONICS DISCLAIMS ANY AND ALL RESPONSIBILITY OR LIABILITY ARISING FROM OR RELATED TO ANY VULNERABILITY ISSUES. FURTHERMORE, TO THE EXTENT PERMITTED BY APPLICABLE LAW, RENESAS ELECTRONICS DISCLAIMS ANY AND ALL WARRANTIES, EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT AND ANY RELATED OR ACCOMPANYING SOFTWARE OR HARDWARE, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.

8. When using Renesas Electronics products, refer to the latest product information (data sheets, user’s manuals, application notes, “General Notes for

Handling and Using Semiconductor Devices” in the reliability handbook, etc.), and ensure that usage conditions are within the ranges specified by Renesas Electronics with respect to maximum ratings, operating power supply voltage range, heat dissipation characteristics, installation, etc. Renesas Electronics disclaims any and all liability for any malfunctions, failure or accident arising out of the use of Renesas Electronics products outside of such specified ranges.

9. Although Renesas Electronics endeavors to improve the quality and reliability of Renesas Electronics products, semiconductor products have specific

characteristics, such as the occurrence of failure at a certain rate and malfunctions under certain use conditions. Unless designated as a high reliability product or a product for harsh environments in a Renesas Electronics data sheet or other Renesas Electronics document, Renesas Electronics products are not subject to radiation resistance design. You are responsible for implementing safety measures to guard against the possibility of bodily injury, injury or damage caused by fire, and/or danger to the public in the event of a failure or malfunction of Renesas Electronics products, such as safety design for hardware and software, including but not limited to redundancy, fire control and malfunction prevention, appropriate treatment for aging degradation or any other appropriate measures. Because the evaluation of microcomputer software alone is very difficult and impractical, you are responsible for evaluating the safety of the final products or systems manufactured by you.

10. Please contact a Renesas Electronics sales office for details as to environmental matters such as the environmental compatibility of each Renesas

Electronics product. You are responsible for carefully and sufficiently investigating applicable laws and regulations that regulate the inclusion or use of controlled substances, including without limitation, the EU RoHS Directive, and using Renesas Electronics products in compliance with all these applicable laws and regulations. Renesas Electronics disclaims any and all liability for damages or losses occurring as a result of your noncompliance with applicable laws and regulations.

11. Renesas Electronics products and technologies shall not be used for or incorporated into any products or systems whose manufacture, use, or sale is

prohibited under any applicable domestic or foreign laws or regulations. You shall comply with any applicable export control laws and regulations promulgated and administered by the governments of any countries asserting jurisdiction over the parties or transactions.

12. It is the responsibility of the buyer or distributor of Renesas Electronics products, or any other party who distributes, disposes of, or otherwise sells or

transfers the product to a third party, to notify such third party in advance of the contents and conditions set forth in this document.

13. This document shall not be reprinted, reproduced or duplicated in any form, in whole or in part, without prior written consent of Renesas Electronics.

14. Please contact a Renesas Electronics sales office if you have any questions regarding the information contained in this document or Renesas

Electronics products.

(Note1) “Renesas Electronics” as used in this document means Renesas Electronics Corporation and also includes its directly or indirectly controlled

(Note2) “Renesas Electronics product(s)” means any product developed or manufactured by or for Renesas Electronics.

subsidiaries.

electronic appliances; machine tools; personal electronic equipment; industrial robots; etc.

financial terminal systems; safety control equipment; etc.

(Rev.5.0-1 October 2020)

TOYOSU FORESIA, 3-2-24 Toyosu, Koto-ku, Tokyo 135-0061, Japan

Renesas and the Renesas logo are trademarks of Renesas Electronics Corporation. All trademarks and registered tradem arks are the property

For further information on a product, technology, the most up-to-date version of a document, or your nearest sales office, please visit:

www.renesas.com/contact/

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

3.2.1 Addition of elements

3.2.2 Configuration of profile

3.2.3 Configuration of service

3.2.4 Configuration of characteristic

3.2.5 Configuration of descriptor

4. Implementation of program

4.1 Service API program

4.1.1 Function defined in service API program

4.1.2 Event defined in service API program

4.2 Implementation of custom service

4.2.1 Implementing encode/decode function

4.2.2 Implementing callback in service API program

4.3 Implementation of app_main.c

4.3.1 Implementing callback in application framework

4.4 Notice

4.4.1 Implementation of multiple services

4.4.2 Implementation of same service

4.4.3 Implementation of secondary service

4.4.4 Implementation of discovery operation about included service

4.4.5 Using GAT service and GAP service

4.4.6 Guide for Connection Update

5. Build and Run created profile

5.1 Build and Run for New Project

5.2 Build and Run for Sample Project

Revision History