AIROC™: Bluetooth® LE Long Range Central

The following two examples, when executed in parallel on two separate boards, demonstrate the use of LE Long Range PHY with Infineon AIROC™ CYW20829/CYW89829 Bluetooth® devices.

1. LE Long Range Central application (GATT Client): This code example documented and demonstrated here, is designed to connect and access services of the 'Hello Sensor' device using LE LR PHY. Because handles of all the attributes of the Hello Sensor device are known beforehand, this GATT Client does not perform GATT discovery but uses them directly. The GATT Client assumes that the Hello Sensor device advertises a special UUID and connects to the device which publishes it.

2. LE Long Range Peripheral application (GATT Server): This complementary application implements the peer role as the peripheral GATT Server application. Use ModusToolbox™ software to create the project, or view the application README and download manually from: https://github.com/Infineon/mtb-example-btstack-freertos-le-lr-peripheral.

Bluetooth® LE Long Range (LR) feature is designed to provide extended range and improved robustness for LE devices. LR achieves this by using a new modulation scheme called Coded PHY, which uses Forward Error Correction (FEC) to improve the signal-to-noise ratio and increase the range of LE devices.

The coded PHY scheme has two different coding schemes: S2 and S8.

• S2 provides a higher data rate than S8 and is designed for applications that require a moderate range and data rate.
• S8 provides the longest range and highest robustness, but has a lower data rate than S2. It is designed for applications that require the longest possible range and the highest robustness, even at the cost of a lower data rate.

Note: Both code examples are set to S8 by default in order to showcase the longest range achievable with the Long Range feature. By setting the value of USE_S8_DEFAULT to 0 in the Makefile, the default coding scheme will be switched from S8 to S2.

This README covers the GATT Client application in detail.

View this README on GitHub.

Provide feedback on this code example.

Requirements

• ModusToolbox™ v3.0 or later (tested with v3.0)
• Board support package (BSP) minimum required version for:
  • CYW920829M2EVK-02: v1.0.2
  • CYW989829M2EVB-01: v1.0.1
• Programming language: C
• Associated parts: All AIROC™ CYW20829 Bluetooth® LE SoC

Supported toolchains (make variable 'TOOLCHAIN')

• GNU Arm® Embedded Compiler v10.3.1 (GCC_ARM) - Default value of TOOLCHAIN
• Arm® Compiler v6.16 (ARM)
• IAR C/C++ Compiler v9.30.1 (IAR)

Supported kits

• AIROC™ CYW920829M2EVK-02 (CYW920829M2EVK-02) – Default value of TARGET
• AIROC™ CYW89829 Bluetooth® LE Evaluation Kit (CYW989829M2EVB-01)

Note: CY8CKIT-028-SENSE is required when USE_OLED_DISP is enabled in the Makefile, by default OLED display flag is disabled.

Hardware setup

This example uses the kit’s default configuration. See the kit user guide to ensure that the kit is configured correctly.

The AIROC™ CYW20829 Bluetooth® Kit (CYW920829M2EVK-02) ships with KitProg3 version 2.21 installed. ModusToolbox™ requires KitProg3 with latest version 2.40. Before using this code example, make sure that the board is upgraded to KitProg3. The tool and instructions are available in the Firmware Loader GitHub repository. If you do not upgrade, you will see an error like "unable to find CMSIS-DAP device" or "KitProg firmware is out of date".

Software setup

See the ModusToolbox™ tools package installation guide for information about installing and configuring the tools package.

Install a terminal emulator if you don't have one. Instructions in this document use Tera Term.

Using the code example

Create the project

The ModusToolbox™ tools package provides the Project Creator as both a GUI tool and a command line tool.

Use Project Creator GUI

1. Open the Project Creator GUI tool.

   There are several ways to do this, including launching it from the dashboard or from inside the Eclipse IDE. For more details, see the Project Creator user guide (locally available at {ModusToolbox™ install directory}/tools_{version}/project-creator/docs/project-creator.pdf).

2. On the Choose Board Support Package (BSP) page, select a kit supported by this code example. See Supported kits.

   Note: To use this code example for a kit not listed here, you may need to update the source files. If the kit does not have the required resources, the application may not work.

3. On the Select Application page:

   a. Select the Applications(s) Root Path and the Target IDE.

   Note: Depending on how you open the Project Creator tool, these fields may be pre-selected for you.

   b. Select this code example from the list by enabling its check box.

   Note: You can narrow the list of displayed examples by typing in the filter box.

   c. (Optional) Change the suggested New Application Name and New BSP Name.

   d. Click Create to complete the application creation process.

Use Project Creator CLI

The 'project-creator-cli' tool can be used to create applications from a CLI terminal or from within batch files or shell scripts. This tool is available in the {ModusToolbox™ install directory}/tools_{version}/project-creator/ directory.

Use a CLI terminal to invoke the 'project-creator-cli' tool. On Windows, use the command-line 'modus-shell' program provided in the ModusToolbox™ installation instead of a standard Windows command-line application. This shell provides access to all ModusToolbox™ tools. You can access it by typing "modus-shell" in the search box in the Windows menu. In Linux and macOS, you can use any terminal application.

The following example clones the "mtb-example-btstack-freertos-le-lr-central" application with the desired name "LeLrCentral" configured for the CYW920829M2EVK-02 BSP into the specified working directory, C:/mtb_projects:

project-creator-cli --board-id CYW920829M2EVK-02 --app-id mtb-example-btstack-freertos-le-lr-central --user-app-name LeLrCentral --target-dir "C:/mtb_projects"

The 'project-creator-cli' tool has the following arguments:

Argument	Description	Required/optional
--board-id	Defined in the field of the BSP manifest	Required
--app-id	Defined in the field of the CE manifest	Required
--target-dir	Specify the directory in which the application is to be created if you prefer not to use the default current working directory	Optional
--user-app-name	Specify the name of the application if you prefer to have a name other than the example's default name	Optional

Note: The project-creator-cli tool uses the git clone and make getlibs commands to fetch the repository and import the required libraries. For details, see the "Project creator tools" section of the ModusToolbox™ tools package user guide (locally available at {ModusToolbox™ install directory}/docs_{version}/mtb_user_guide.pdf).

Open the project

After the project has been created, you can open it in your preferred development environment.

Eclipse IDE

If you opened the Project Creator tool from the included Eclipse IDE, the project will open in Eclipse automatically.

For more details, see the Eclipse IDE for ModusToolbox™ user guide (locally available at {ModusToolbox™ install directory}/docs_{version}/mt_ide_user_guide.pdf).

Visual Studio (VS) Code

Launch VS Code manually, and then open the generated {project-name}.code-workspace file located in the project directory.

For more details, see the Visual Studio Code for ModusToolbox™ user guide (locally available at {ModusToolbox™ install directory}/docs_{version}/mt_vscode_user_guide.pdf).

Keil µVision

Double-click the generated {project-name}.cprj file to launch the Keil µVision IDE.

For more details, see the Keil µVision for ModusToolbox™ user guide (locally available at {ModusToolbox™ install directory}/docs_{version}/mt_uvision_user_guide.pdf).

IAR Embedded Workbench

Open IAR Embedded Workbench manually, and create a new project. Then select the generated {project-name}.ipcf file located in the project directory.

For more details, see the IAR Embedded Workbench for ModusToolbox™ user guide (locally available at {ModusToolbox™ install directory}/docs_{version}/mt_iar_user_guide.pdf).

Command line

If you prefer to use the CLI, open the appropriate terminal, and navigate to the project directory. On Windows, use the command-line 'modus-shell' program; on Linux and macOS, you can use any terminal application. From there, you can run various make commands.

For more details, see the ModusToolbox™ tools package user guide (locally available at {ModusToolbox™ install directory}/docs_{version}/mtb_user_guide.pdf).

Operation

1. Connect the two boards to your PC using the provided USB cable through the USB connector.

2. Open a terminal program and select the KitProg3 COM port. Set the serial port parameters to 8N1 and 115200 baud. You need two windows of the terminal application to view messages from both the peripheral and the central applications.

3. Program one board with the central application and the other with the peripheral application using one of the following:

   Using Eclipse IDE

   1. Select the application project in the Project Explorer.

   2. In the Quick Panel, scroll down, and click <Application Name> Program (KitProg3_MiniProg4).

   In other IDEs

   Follow the instructions in your preferred IDE.

   Using CLI

   From the terminal, execute the make program command to build and program the application using the default toolchain to the default target. The default toolchain is specified in the application's Makefile but you can override this value manually:

   make program TOOLCHAIN=<toolchain>
   

   Example:

   make program TOOLCHAIN=GCC_ARM
   

   After programming, the application starts automatically. RGB LED status color shows red.

4. Push the user button on the peripheral to start advertising.

5. Push the user button on the central board to start scanning and connect. RGB LED status color changes to blue during the scan.

6. After establishing a connection, the peripheral application will initiate the transmission of notifications to the client. RGB LED status color changes to green.

7. To switch between S2 and S8 coding schemes, press the user button on the central board. The default coding scheme is configured in makefile using USE_S8_DEFAULT

8. If OLED display option is enabled , the display shows the LE-LR connection status, RSSI values and coding schemes.

Notes:

1. Changing the S2/S8 coding scheme on the central board does not automatically change the coding scheme on the peripheral board. Therefore, to ensure that both boards are using the same coding scheme, the user must press the user button on the peripheral board to match the coding scheme for both boards.

2. At present, 100% scan duty cycle is used. The parameters may be fine tuned as per requirement.

Programming a CYW20829 board (when multiple boards are connected)

Get the board's serial number

1. Connect the board to your machine.

2. Go to {ModusToolbox™ install directory}/tools_{version}/fw-loader/bin and open the command prompt.

3. Run the following command:

   fw-loader.exe --device-list
   

4. On the text that appears, locate the following message starting with Connected supported devices:.

5. Note the 16-digit number that is listed. This is the serial number of the board.

   In this example, 0B0B03B803260400 is the serial number for the board.

From the CLI

1. Go to your application and open the Makefile.

2. Add the following to the Makefile (in the "Advanced Configuration" section):

   CY_OPENOCD_CUSTOM_COMMAND += cmsis_dap_serial <SERIAL_NUMBER>;
   

   Note: Ensure that a semicolon is added at the end of the line as shown above.

You can program the board using the make program command from the ModusToolbox™ terminal.

From the IDE (via launch configurations available in Quick Panel)

On Eclipse IDE for ModusToolbox™ software, you need to edit the 'Program' configurations to bind them with a specific CMSIS-DAP serial number. See the following sections of the ModusToolbox™ user guide:

• 5.1.6 "Select specific CMSIS-DAP device"
• 5.1.6.2 "Selecting by serial number"

1. Select Run > Debug Configurations, and then select GDB OpenOCD Debugging on the Create, manage, and run configurations window.

2. Select "Bluetooth_LE_Long_Range_Peripheral Program (KitProg3_MiniProg4)".

3. On the right pane, select the Debugger tab.

4. In Config options, insert the following line after -c "source [find interface/kitprog3.cfg]":

   -c "cmsis_dap_serial <serial_num_1>"

5. Select Apply and Debug for the change to take effect.

6. Similar to Step 2, select "Bluetooth_LE_Long_Range_Central Program (KitProg3_MiniProg4)".

7. On the right pane, select the Debugger tab.

8. In Config options, insert the following line after -c "source [find interface/kitprog3.cfg]":

   -c "cmsis_dap_serial <serial_num_2>"

9. Click Apply and Debug for the change to take effect.

BTSpy

BTSpy is a trace utility that can be used in the AIROC™ Bluetooth® platforms to view protocol and generic trace messages from the embedded device. BTSpy is available as part of the ModusToolbox™ installation. If not, download and install BTSpy.

Do the following to configure the use of BTSpy:

1. Add the ENABLE_BT_SPY_LOG macro in the Makefile or command-line DEFINES+=ENABLE_BT_SPY_LOG.

2. Call cybt_debug_uart_init(&debug_uart_configuration, NULL);

   The first argument is the debug_uart_configurations structure pointer, which has hardware pin configurations along with baud rate and flow control configurations. Recommended baud rate is 300,0000, although 115,200 is also supported by the BTSpy tool. The second argument is an optional callback function which can be set to NULL.

3. Ensure that retarget-io is not enabled on the same UART port as BTSpy. There is no need to initialize the retarget-io library if the application wants to send both application messages and Bluetooth® protocol traces to the same port through BTSpy.

4. Use compiler directives to either initialize the retarget-io library or BTSpy logs depending on the debug macro setting. '

   For example:

   #ifdef ENABLE_BT_SPY_LOG
      {
          #define DEBUG_UART_BAUDRATE 3000000
          #define DEBUG_UART_RTS        (P5_2)
          #define DEBUG_UART_CTS        (P5_3)
          cybt_debug_uart_config_t debug_uart_config = {
                  .uart_tx_pin = CYBSP_DEBUG_UART_TX,
                  .uart_rx_pin = CYBSP_DEBUG_UART_RX,
                  .uart_cts_pin = DEBUG_UART_CTS,
                  .uart_rts_pin = DEBUG_UART_RTS,
                  .baud_rate = DEBUG_UART_BAUDRATE,
                  .flow_control = TRUE
          };
          cybt_debug_uart_init(&debug_uart_config, NULL);
      }
   #else
      cy_retarget_io_init(CYBSP_DEBUG_UART_TX, CYBSP_DEBUG_UART_RX, CY_RETARGET_IO_BAUDRATE);
   #endif
   

Enable BTSpy logs

1. In the Makefile, make ENABLE_SPY_TRACES=1.
2. Build and program the board.
3. Open ClientControl.
4. Set the baud rate to 3000000.
5. Deselect flow control.
6. Select the port and click Open port.
7. Launch BTSpy.
8. Press and release the reset button on the board to get BTSpy logs.
9. You should see all the application traces and the Bluetooth® HCI messages. These messages help debug the HCI commands issued to the Bluetooth® controller. Application traces indicate the start/stop of advertisements, connection/disconnection, and PHY updates.

Design and implementation

LE-LR

LE-LR represents LE Long Range PHY. The two mentioned CEs demonstrate the use of LE-LR PHY to advertise, scan for advertisements, and connect.

The mandatory symbol rate is 1 mega symbol per second (Msym/s), where 1 symbol represents 1-bit, therefore, supporting a bit rate of 1 megabit per second (Mb/s), which is referred to as the LE 1M PHY.

The 1 Msym/s symbol rate may optionally support error correction coding, which is referred to as the LE Coded PHY. This may use either of two coding schemes: S=2, where 2 symbols represent 1-bit, therefore, supporting a bit rate of 500 kb/s, and S=8, where 8 symbols represent 1-bit, therefore, supporting a bit rate of 125 kb/s.

Program

The LE Long Range Peripheral code example configures the device as Bluetooth® LE GAP Peripheral/GATT Server, and the LE Long Range Central application configures the device as Bluetooth® LE GAP Central/GATT Client.

The peripheral example implements a custom GATT profile that includes the following three services:

• Hello Sensor custom service
• Device Information service
• Battery Level service

The Hello Sensor service includes a custom characteristic - Notify. The Notify characteristic is used to send a notification or indication to the peer client device upon connection.

The application uses a UART resource from the hardware abstraction layer (HAL) to send debug messages on a UART terminal emulator. The UART resource initialization and re-targeting of standard I/O to the UART port are done using the retarget-io library.

Upon reset, the applications start automatically and initialize the Bluetooth® stack and other device peripherals. The peripheral device starts to advertise its presence to the peer central device using LE-LR PHY when a button press is detected. Similarly, central device scans for the peripheral device upon button press.

After a Bluetooth® LE connection is established, the peer central device registers for notifications to be received by using the CCCD handle of the Notify characteristic. Because the CCCD handle of the Notify characteristic requires write authentication, an attempt to enable notification/indication will trigger the pairing process at the central side.

After the pairing process completes, the peer device's link keys and addresses are stored in the device's flash memory and therefore bonded.

The user button on the peripheral board is configured to trigger an interrupt on the falling edge. When this button is pressed, the device will switch the coding algorithm between S=2 and S=8 and notify using the modified coding algorithm.

Related resources

Resources	Links
Application notes	AN228571 – Getting started with PSoC™ 6 MCU on ModusToolbox™ software AN215656 – PSoC™ 6 MCU: Dual-CPU system design
Code examples	Using ModusToolbox™ on GitHub Using Bluetooth® SDK
Device documentation	AIROC™ CYW20829 Bluetooth® LE SoC
Development kits	Select your kits from the Evaluation board finder.
Libraries on GitHub	mtb-pdl-cat1 – PSoC™ 6 Peripheral Driver Library (PDL) mtb-hal-cat1 – Hardware Abstraction Layer (HAL) library retarget-io – Utility library to retarget STDIO messages to a UART port
Middleware on GitHub	psoc6-middleware – Links to all PSoC™ 6 MCU middleware
Tools	ModusToolbox™ – ModusToolbox™ software is a collection of easy-to-use libraries and tools enabling rapid development with Infineon MCUs for applications ranging from wireless and cloud-connected systems, edge AI/ML, embedded sense and control, to wired USB connectivity using PSoC™ Industrial/IoT MCUs, AIROC™ Wi-Fi and Bluetooth® connectivity devices, XMC™ Industrial MCUs, and EZ-USB™/EZ-PD™ wired connectivity controllers. ModusToolbox™ incorporates a comprehensive set of BSPs, HAL, libraries, configuration tools, and provides support for industry-standard IDEs to fast-track your embedded application development.

Other resources

Infineon provides a wealth of data at www.infineon.com to help you select the right device, and quickly and effectively integrate it into your design.

Document history

Document title: CE236596 – *AIROC™: Bluetooth® LE Long Range Central

Version	Description of change
1.0.0	New code example that only supports MTB 3.0
1.1.0	Added support for CYW920829M2EVK-02 Removed CYW920829M2EVB-01 from supported kit
1.2.0	Set scan duty to %100
1.3.0	Setting adv_handle and sub_event to 0xFF in hello_client_app_init() Update README to reflect minimum BSP support for CYW920829M2EVK-02 : v1.0.1
2.0.0	Enabling OLED display and RGB LED to show LE-LR status information
2.1.0	Added support for CYW989829M2EVB-01

All referenced product or service names and trademarks are the property of their respective owners.

The Bluetooth® word mark and logos are registered trademarks owned by Bluetooth SIG, Inc., and any use of such marks by Infineon is under license.

---

© Cypress Semiconductor Corporation, 2022-2023. This document is the property of Cypress Semiconductor Corporation, an Infineon Technologies company, and its affiliates ("Cypress"). This document, including any software or firmware included or referenced in this document ("Software"), is owned by Cypress under the intellectual property laws and treaties of the United States and other countries worldwide. Cypress reserves all rights under such laws and treaties and does not, except as specifically stated in this paragraph, grant any license under its patents, copyrights, trademarks, or other intellectual property rights. If the Software is not accompanied by a license agreement and you do not otherwise have a written agreement with Cypress governing the use of the Software, then Cypress hereby grants you a personal, non-exclusive, nontransferable license (without the right to sublicense) (1) under its copyright rights in the Software (a) for Software provided in source code form, to modify and reproduce the Software solely for use with Cypress hardware products, only internally within your organization, and (b) to distribute the Software in binary code form externally to end users (either directly or indirectly through resellers and distributors), solely for use on Cypress hardware product units, and (2) under those claims of Cypress’s patents that are infringed by the Software (as provided by Cypress, unmodified) to make, use, distribute, and import the Software solely for use with Cypress hardware products. Any other use, reproduction, modification, translation, or compilation of the Software is prohibited.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, CYPRESS MAKES NO WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, WITH REGARD TO THIS DOCUMENT OR ANY SOFTWARE OR ACCOMPANYING HARDWARE, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. No computing device can be absolutely secure. Therefore, despite security measures implemented in Cypress hardware or software products, Cypress shall have no liability arising out of any security breach, such as unauthorized access to or use of a Cypress product. CYPRESS DOES NOT REPRESENT, WARRANT, OR GUARANTEE THAT CYPRESS PRODUCTS, OR SYSTEMS CREATED USING CYPRESS PRODUCTS, WILL BE FREE FROM CORRUPTION, ATTACK, VIRUSES, INTERFERENCE, HACKING, DATA LOSS OR THEFT, OR OTHER SECURITY INTRUSION (collectively, "Security Breach"). Cypress disclaims any liability relating to any Security Breach, and you shall and hereby do release Cypress from any claim, damage, or other liability arising from any Security Breach. In addition, the products described in these materials may contain design defects or errors known as errata which may cause the product to deviate from published specifications. To the extent permitted by applicable law, Cypress reserves the right to make changes to this document without further notice. Cypress does not assume any liability arising out of the application or use of any product or circuit described in this document. Any information provided in this document, including any sample design information or programming code, is provided only for reference purposes. It is the responsibility of the user of this document to properly design, program, and test the functionality and safety of any application made of this information and any resulting product. "High-Risk Device" means any device or system whose failure could cause personal injury, death, or property damage. Examples of High-Risk Devices are weapons, nuclear installations, surgical implants, and other medical devices. "Critical Component" means any component of a High-Risk Device whose failure to perform can be reasonably expected to cause, directly or indirectly, the failure of the High-Risk Device, or to affect its safety or effectiveness. Cypress is not liable, in whole or in part, and you shall and hereby do release Cypress from any claim, damage, or other liability arising from any use of a Cypress product as a Critical Component in a High-Risk Device. You shall indemnify and hold Cypress, including its affiliates, and its directors, officers, employees, agents, distributors, and assigns harmless from and against all claims, costs, damages, and expenses, arising out of any claim, including claims for product liability, personal injury or death, or property damage arising from any use of a Cypress product as a Critical Component in a High-Risk Device. Cypress products are not intended or authorized for use as a Critical Component in any High-Risk Device except to the limited extent that (i) Cypress's published data sheet for the product explicitly states Cypress has qualified the product for use in a specific High-Risk Device, or (ii) Cypress has given you advance written authorization to use the product as a Critical Component in the specific High-Risk Device and you have signed a separate indemnification agreement.
Cypress, the Cypress logo, and combinations thereof, ModusToolbox, PSoC, CAPSENSE, EZ-USB, F-RAM, and TRAVEO are trademarks or registered trademarks of Cypress or a subsidiary of Cypress in the United States or in other countries. For a more complete list of Cypress trademarks, visit www.infineon.com. Other names and brands may be claimed as property of their respective owners.